@mathzetta/qblur 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +63 -0
- package/LICENSE +1 -1
- package/README.md +34 -22
- package/dist/cpu-worker.js +2 -2
- package/dist/qblur-apply.js +2 -2
- package/dist/qblur-element.js +2 -2
- package/dist/qblur.core.js +2 -2
- package/dist/qblur.external.global.min.js +2 -2
- package/dist/qblur.external.js +2 -2
- package/dist/qblur.global.min.js +2 -2
- package/dist/qblur.js +2 -2
- package/docs/filters.md +92 -89
- package/docs/library.md +52 -55
- package/package.json +9 -3
- package/src/apply-filter.js +8 -7
- package/src/apply.d.ts +12 -11
- package/src/cpu-helpers.js +9 -7
- package/src/cpu-runner.js +26 -12
- package/src/cpu.js +65 -32
- package/src/element.d.ts +1 -1
- package/src/element.js +3 -3
- package/src/format.js +36 -27
- package/src/graphics.js +12 -12
- package/src/index.d.ts +11 -11
- package/src/library.js +29 -29
- package/src/png.js +21 -17
- package/src/runtime.js +25 -6
- package/src/save.js +7 -7
- package/src/strokes.js +15 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,68 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
- American spelling everywhere people read it (color, gray, center, neighborhood, math, license…): the docs, the
|
|
6
|
+
site's pages, messages and errors, and the built-in filters' names and groups (`Color & tone`, "Color circle",
|
|
7
|
+
"Color reveal brush", "Color spotlight"). **Breaking:** the British names are gone, not aliased: `encodePng`
|
|
8
|
+
and `encodeGif` take `colors` only (`colours` is ignored) and `encodePng`'s result has `colors` only; the types
|
|
9
|
+
`Colour` / `ColourSpace` are `Color` / `ColorSpace`; a built-in filter asked for by name (`applyFilter`,
|
|
10
|
+
`<qblur-image filter>`) needs its new name ("Color circle"). The filter format is unchanged (its keys were
|
|
11
|
+
already `color`).
|
|
12
|
+
- The CPU runner reads what the next MathZetta's shaders read: `arcsec`, `arccsc` and `arccot` (as `acos(1/x)`,
|
|
13
|
+
`asin(1/x)` and `π/2 − atan x`), degrees (`30°`, which the GPU already took and the CPU called an unknown name),
|
|
14
|
+
and evaluation bars (`\left[F\right]_a^b`, F at b minus F at a).
|
|
15
|
+
- …and `⇒` / `⇔` (`\Rightarrow`, `\iff`), and membership in set-builder notation (`r \in \{x \mid x > 0.4\}`).
|
|
16
|
+
- The CPU runner takes the empty set: `r ∈ ∅` is false and `r ∉ ∅` true, as on the GPU (it built `()` and threw a
|
|
17
|
+
SyntaxError).
|
|
18
|
+
- The site: Copy link / Copy JSON are off while there are no steps (they threw); where the clipboard is refused, the
|
|
19
|
+
text shows in a box to copy by hand on both pages; play / pause also pauses a GIF, and its label (and the tracking
|
|
20
|
+
panel's) follows; a video or picture that can't be read says so, and the old one's object URL is let go; the file
|
|
21
|
+
choosers are reachable by keyboard; the home page's handlers wait for its photo, and only a filter's link
|
|
22
|
+
(`#…`, not `#main`) is sent on to the editor; storage blocked by the browser no longer stops the editor.
|
|
23
|
+
- The site (not the package): the editor has its own page, `editor.html`, laid out as a dashboard — the pictures on a
|
|
24
|
+
stage that takes the room the window has (Result / Both / Original, **Expand** over the whole window, a sharper
|
|
25
|
+
preview: up to 960 × 720, or 1440 × 1080 when asked), beside the controls as tabs. The home page is now one small
|
|
26
|
+
example that opens in the editor; a filter's old link (`qblur.com/#…`) is sent on to the editor.
|
|
27
|
+
- The site: writing filters has its own page, `filters.html` (the steps' math, knobs and notes, a smaller preview,
|
|
28
|
+
saving, importing, the library and the cheat sheet), and the editor is for using them: choose one (saved or from
|
|
29
|
+
the library), tune its knobs, select and draw, download — "Edit this filter" and "Use it in the editor" carry the
|
|
30
|
+
filter (and the sample picture) between the two. Both pages are the same editor (`demo/app.js`, `data-mode`);
|
|
31
|
+
`filters.html` is made from `editor.html` by `tools/filters-page.mjs`. They have no sidebar column (the site's nav is
|
|
32
|
+
a bar across the top), so the pictures get the width. **Expand** fills the window again (the pictures were held to
|
|
33
|
+
the 200 px minimum: an expanded stage's height was counted as its bars). The home page's example takes your own photo
|
|
34
|
+
or video (or a file dropped on it), and Download saves a photo's result. New branding: the logo in the sidebar and
|
|
35
|
+
on the link-preview cards, new icons; the profile-picture sample is a photo now, not a painting.
|
|
36
|
+
|
|
37
|
+
## 0.1.2
|
|
38
|
+
|
|
39
|
+
Fixes from a review before this release. Needs MathZetta 1.2 (the peer range is `^1.2.0`).
|
|
40
|
+
|
|
41
|
+
- **The CPU gives the shader's pixels again.** `round` takes a half away from zero (`round(-2.5)` is −3, as
|
|
42
|
+
MathZetta 1.2's shaders round), and `50%` is 0.5 on the CPU too (it was "unknown name").
|
|
43
|
+
- **Names every object has are ordinary names.** A knob, picture or graphic called `constructor`, `toString` or
|
|
44
|
+
`valueOf` works (a knob so named had the value NaN, and a picture was refused); an unknown name or function
|
|
45
|
+
so called is refused as unknown, not by a later error.
|
|
46
|
+
- **Text is not maths.** A quoted string in a filter is refused on the GPU as it was on the CPU (it was
|
|
47
|
+
written into the shader, which then failed to compile).
|
|
48
|
+
- **A filter built to stall the page is stopped.** At most 256 passes and 64 graphics; brush strokes stop
|
|
49
|
+
painting after a few hundred frames' worth of work in one call (a point far outside the frame, or the
|
|
50
|
+
largest brush crossing it thousands of times, froze the page for minutes); a very long `options` list no
|
|
51
|
+
longer overflows the stack.
|
|
52
|
+
- **`drawAsync`:** calls made before the workers are up share one pool (two pools were started, one was never
|
|
53
|
+
closed, and a call could fail); `dispose()` during a draw ends that draw with an error instead of leaving
|
|
54
|
+
it waiting for ever; a picture is copied to shared memory once, not on every draw.
|
|
55
|
+
- **WebGL:** shaders are freed once their program is linked, and when a pass does not compile the passes
|
|
56
|
+
compiled before it are freed too (each filter left two shader objects per pass behind).
|
|
57
|
+
- A font's CSS is fetched without cookies or a referrer. `encodePng` refuses a size that isn't whole pixels
|
|
58
|
+
or data too short for it.
|
|
59
|
+
- More npm keywords (image-processing, canvas, gif, web-component …).
|
|
60
|
+
|
|
61
|
+
## 0.1.1
|
|
62
|
+
|
|
63
|
+
No change to the code. The licence names its holder (`Copyright (c) 2025-2026 Robert Wilcox`; 0.1.0's said
|
|
64
|
+
"MathZetta Contributors"), and every bundle's banner says whose it is and its licence, MathZetta's too.
|
|
65
|
+
The README has a Licence section, and it and docs/library.md no longer say the package isn't on npm yet.
|
|
3
66
|
## 0.1.0 — first release
|
|
4
67
|
|
|
5
68
|
The filter format, its compiler and two runners that give the same pixels.
|
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# qblur
|
|
2
2
|
|
|
3
|
-
Image filters written as
|
|
3
|
+
Image filters written as math — the site is **qblur** (qblur.com). A filter is an expression over a pixel —
|
|
4
4
|
`1 - rgb`, `if gray > 0.5 then (1, 0, 0)`, `gaussian(3)`,
|
|
5
5
|
`mix(source, rgb, luma(mask))` — or a JSON document with parameters, extra
|
|
6
6
|
pictures (masks, overlays) and chains of other people's filters. The
|
|
@@ -12,14 +12,14 @@ import { applyFilter, toBlob } from '@mathzetta/qblur/apply'; // one call,
|
|
|
12
12
|
|
|
13
13
|
const canvas = await applyFilter(img, 'Sepia'); // a built-in filter, by name
|
|
14
14
|
const sharp = await applyFilter(img, 'Threshold', { params: { cutoff: 0.3 } }); // …with a knob set
|
|
15
|
-
const mine = await applyFilter(img, 'if gray > 0.5 then (1, 0, 0) else rgb'); // or
|
|
15
|
+
const mine = await applyFilter(img, 'if gray > 0.5 then (1, 0, 0) else rgb'); // or math
|
|
16
16
|
const png = await toBlob(mine); // PNG (JPEG, WebP in a browser)
|
|
17
17
|
// pictures over 4096 px on the long side (2048 on the CPU) are scaled down first: { maxSize } changes it
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
```html
|
|
21
21
|
<qblur-image src="photo.jpg" filter="Vignette" params='{"strength": 2}' alt="…"></qblur-image>
|
|
22
|
-
<script type="module" src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
22
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur-element.js"></script>
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
For live knobs and video, a runner of your own:
|
|
@@ -39,7 +39,7 @@ Three entries: `@mathzetta/qblur` (the filters, the runners, the library), `@mat
|
|
|
39
39
|
Saving: `toBlob` (PNG anywhere, JPEG/WebP in a browser) and `encodeGif` (bring
|
|
40
40
|
[gifenc](https://www.npmjs.com/package/gifenc): the package has no dependencies of its own). See [CHANGELOG.md](CHANGELOG.md). [docs/library.md](docs/library.md) is how to use the
|
|
41
41
|
library on your own pages — the CDN, the builds, the API, with examples that `npm run check:docs` runs.
|
|
42
|
-
[docs/filters.md](docs/filters.md) is the full guide to the
|
|
42
|
+
[docs/filters.md](docs/filters.md) is the full guide to the math: what an expression can use, animation, neighborhoods,
|
|
43
43
|
geometry, several pictures, sharing and the API.
|
|
44
44
|
|
|
45
45
|
It runs on the GPU (WebGL) or the CPU (plain JavaScript, also in Node):
|
|
@@ -50,7 +50,7 @@ CPU without it — both give the same pixels. See "Running it" in the guide.
|
|
|
50
50
|
```bash
|
|
51
51
|
npm install # links ../mathzetta/packages/mathzetta (the public repo, checked out beside this one) for development
|
|
52
52
|
npm test # format, compiler, sharing, the CPU runner (pixels, bands, workers, safety) — no browser
|
|
53
|
-
npm run serve # http://localhost:8016/demo/ — the editor and library ("runs on": auto / GPU / CPU)
|
|
53
|
+
npm run serve # http://localhost:8016/demo/ — the home page; the editor and library are demo/editor.html ("runs on": auto / GPU / CPU)
|
|
54
54
|
npm run check # every library filter through real WebGL in headless Chrome
|
|
55
55
|
npm run check:cpu # …and the CPU runner on the same pictures, compared pixel by pixel
|
|
56
56
|
npm run check:nowebgl # Chrome without WebGL: the editor must fall back to the CPU
|
|
@@ -62,8 +62,8 @@ Before building for a real address, set `SITE_URL=https://…/` (or
|
|
|
62
62
|
`"homepage"` in package.json) so pages get absolute canonical, `og:url` and
|
|
63
63
|
`og:image` addresses; the preview cards are `demo/share/*.jpg` (`node tools/share-cards.mjs` remakes them).
|
|
64
64
|
|
|
65
|
-
`site/` is the deployable
|
|
66
|
-
|
|
65
|
+
`site/` is the deployable site: `index.html` and `home.js` (the home page, one small example), `editor.html`,
|
|
66
|
+
`filters.html` and `app.js` (the editor and the filters page, one bundle with this package in it; MathZetta loads from jsDelivr), `cpu-worker.js`, `guide.html` (the
|
|
67
67
|
guide rendered, heading ids as on GitHub) and `photos/`. Default photos go
|
|
68
68
|
in `demo/photos/` with an `index.json` — see the README there.
|
|
69
69
|
Serve the folder from anywhere (GitHub Pages, S3, a CDN); share links are
|
|
@@ -71,19 +71,15 @@ Serve the folder from anywhere (GitHub Pages, S3, a CDN); share links are
|
|
|
71
71
|
|
|
72
72
|
## From a CDN
|
|
73
73
|
|
|
74
|
-
> Not on npm yet: the addresses below are where releases will be (placeholders until the first one).
|
|
75
|
-
> Search for `cdn.jsdelivr.net/npm/@mathzetta/qblur` to find every place they are written: this README,
|
|
76
|
-
> docs/library.md (and the site's library.html built from it).
|
|
77
|
-
|
|
78
74
|
Every npm release's `dist/` is on jsDelivr (and unpkg), MathZetta's GLSL output bundled in —
|
|
79
75
|
[docs/library.md](docs/library.md) has working examples of each way in:
|
|
80
76
|
|
|
81
77
|
```html
|
|
82
78
|
<script type="module">
|
|
83
|
-
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
79
|
+
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
|
|
84
80
|
</script>
|
|
85
81
|
<!-- or a classic script: window.QBlur -->
|
|
86
|
-
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
82
|
+
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.global.min.js"></script>
|
|
87
83
|
```
|
|
88
84
|
|
|
89
85
|
Every build comes **with MathZetta inside or without it** (`*.external.*`). Sizes as the CDN sends them (compressed):
|
|
@@ -99,7 +95,7 @@ Every build comes **with MathZetta inside or without it** (`*.external.*`). Size
|
|
|
99
95
|
|
|
100
96
|
MathZetta (its GLSL output and the parser) is about half of a full build. Without it, the page
|
|
101
97
|
loads MathZetta once itself: a classic page puts a MathZetta `<script>` first — `mathzetta.min.js`
|
|
102
|
-
or the `glsl`
|
|
98
|
+
or the `glsl` flavor (GLSL + formulas is what the filters use) — and the external classic build
|
|
103
99
|
reads `window.MathZetta`; a module page maps `mathzetta`, `mathzetta/glsl` and `mathzetta/formulas`
|
|
104
100
|
to MathZetta's bundle with an import map (every name can point at the one file). The object models and their runtimes (the site's
|
|
105
101
|
`models/`, `ort/`) are not in the package: they belong to the editor at qblur.com.
|
|
@@ -112,21 +108,21 @@ Publishing is `npm publish` (`prepublishOnly` runs the tests and the build).
|
|
|
112
108
|
| `src/format.js` | the filter document: normalize, validate, compile to passes, JSON and share links |
|
|
113
109
|
| `src/runtime.js` | the WebGL runner: textures, passes, live parameters |
|
|
114
110
|
| `src/cpu.js` | filter expressions → typed, straight-line JavaScript per pass (through the whitelist gate) |
|
|
115
|
-
| `src/cpu-helpers.js` | what that code calls: texture-like sampling,
|
|
111
|
+
| `src/cpu-helpers.js` | what that code calls: texture-like sampling, neighborhood planes (separable, by bands of rows) |
|
|
116
112
|
| `src/cpu-runner.js`, `src/cpu-worker.js` | the CPU runner (draw / drawAsync over workers) |
|
|
117
113
|
| `src/auto.js` | `createRunner` / `chooseEngine`: GPU or CPU, and why |
|
|
118
114
|
| `src/library.js` | `LIBRARY`: the built-in filters, each with a `group` (`GROUPS`); every one validated, compiled and round-tripped by `npm test`. Canny edges is a nine-pass chain of plain expressions |
|
|
119
|
-
| `demo/avatar/`, `demo/splash/`, `demo/move/`, `demo/text/` | the small apps: a profile picture (framed on the person, a style, the background blurred, replaced or removed; a circle, a square or a cut-out sticker), a
|
|
115
|
+
| `demo/avatar/`, `demo/splash/`, `demo/move/`, `demo/text/` | the small apps: a profile picture (framed on the person, a style, the background blurred, replaced or removed; a circle, a square or a cut-out sticker), a color splash (click colors to keep), a photo that moves (saved as a GIF or video), fancy text (letters and border each colored by a formula — gold, chrome, fire, a picture, or your own — as a transparent PNG or a GIF) — a few choices each; `npm run check:apps` |
|
|
120
116
|
| `demo/kit.js`, `demo/apps.css` | what the small apps share: open a picture, the sample photos, a filter on the GPU or CPU (`createView`), download, GIF |
|
|
121
117
|
| `demo/gif.js` | a GIF decoder (all frames, delays, disposal) so GIFs play and filter frame by frame; `gifenc` (a dev dependency, bundled) writes "Save as GIF" |
|
|
122
|
-
| `demo/png.js` | a PNG writer for what the browser's cannot do: indexed (1/2/4/8-bit) when the picture has few
|
|
123
|
-
| `demo/export.js` | the
|
|
124
|
-
| `demo/livewire.js` | selecting an object: intelligent scissors (a cost map from the gradient, Dijkstra once per clicked point, the wire to the cursor walked back in real time, snapping, path cooling) and a
|
|
118
|
+
| `demo/png.js` | a PNG writer for what the browser's cannot do: indexed (1/2/4/8-bit) when the picture has few colors, RGB when nothing is transparent, forced palettes with dithering |
|
|
119
|
+
| `demo/export.js` | the editor's Download tab: format with estimated sizes (auto picks the smallest sensible), quality / colors, size, a crop dragged on the picture, background for JPEG |
|
|
120
|
+
| `demo/livewire.js` | selecting an object: intelligent scissors (a cost map from the gradient, Dijkstra once per clicked point, the wire to the cursor walked back in real time, snapping, path cooling) and a color-fill wand; the mask is `selected` in the math |
|
|
125
121
|
| `src/graphics.js` | text and shapes: `normalizeGraphic` (validation), `drawGraphic` onto any 2D canvas, `loadGraphicFonts`, `renderGraphics(compiled, w, h)` for the runner |
|
|
126
122
|
| `tools/shot.mjs` | a screenshot of a page of this repo after running some JavaScript in it (headless Chrome) |
|
|
127
123
|
| `src/strokes.js` | brushes: recorded strokes drawn again for every frame (round, soft, marker, chalk, spray; pressure or speed; timing; passes; clip to a mask) into a picture of coverage, age, passes and progress; `traceContours` for outlining a selection |
|
|
128
|
-
| `demo/tracker.js` | tracking an object through a clip: patch-matched outline points held to the group's move/scale/turn, a
|
|
129
|
-
| `demo/examples.js` | the Examples tour at the
|
|
124
|
+
| `demo/tracker.js` | tracking an object through a clip: patch-matched outline points held to the group's move/scale/turn, a color model per keyframe so the outline follows the object's edge, a confidence per frame, keyframes propagated both ways |
|
|
125
|
+
| `demo/examples.js` | the Examples tour (at the end of the Filter tab, on the editor and the filters page): each example's filter, picture, features and step-by-step explanation (tested to compile; the checker runs each) |
|
|
130
126
|
| `demo/ai.js` | finding objects: MobileSAM on the site (`SHIPPED_MODELS`, run by ONNX Runtime Web in `ort/`; every site file stays under 25 MiB for Cloudflare Pages); in development a menu also offers RF-DETR Small and Nano and MagicTouch 1 and 2 (`demo/models/`, Apache-2.0) to compare; nothing loads until asked |
|
|
131
127
|
| `demo/rfdetr.js` | the model's input (stretched, normalized) and its decoding (boxes, labels, outlines); used by the page and by Node (test/ai.test.js) |
|
|
132
128
|
| `demo/sam.js` | MobileSAM: the picture scaled for its encoder, the decoder's prompt (points, box), the surest of its masks; used by the page and by Node |
|
|
@@ -136,9 +132,25 @@ Publishing is `npm publish` (`prepublishOnly` runs the tests and the build).
|
|
|
136
132
|
| `demo/help.js` | the in-page cheat sheet, and `explain()`: an error → a hint and the help section / guide heading for it |
|
|
137
133
|
| `demo/photos/` | default photos (`index.json` lists them); the editor opens on the first |
|
|
138
134
|
| `tools/markdown.mjs` | the small Markdown renderer behind `site/guide.html` |
|
|
139
|
-
| `demo/
|
|
135
|
+
| `demo/editor.html` | the editor — filters on your picture: choosing one, its knobs, selecting and drawing, downloads — a dashboard: the stage — original and result as large as the window allows, expandable — beside the tabbed controls; what `npm run check` drives |
|
|
136
|
+
| `demo/workspace.js` | the editor's stage and tabs: what is shown (Result / Both / Original), the pictures' size on screen, Expand, the preview's sharpness |
|
|
137
|
+
| `demo/filters.html` | the filters page — writing, changing and saving filters beside a smaller preview: the same editor (`data-mode="write"`), made from editor.html by `tools/filters-page.mjs` (don't edit it) |
|
|
138
|
+
| `demo/index.html`, `demo/home.js` | the home page: one small example (a 50 KB photo — or your own photo or video —, a line of math, a few filters to try) that opens in the editor |
|
|
140
139
|
| `docs/filters.md` | the guide |
|
|
141
140
|
|
|
142
141
|
This was `src/filters/` and `demos/filters.html` in MathZetta until
|
|
143
142
|
2026-10-16; the GLSL expression output (`toGLSL`, `filterShader`) stayed
|
|
144
143
|
there as `mathzetta/glsl`.
|
|
144
|
+
|
|
145
|
+
## License
|
|
146
|
+
|
|
147
|
+
MIT — [LICENSE](LICENSE), Copyright (c) 2025-2026 Robert Wilcox: the package, the editor, the apps, the
|
|
148
|
+
built-in filters and the site's own files. In this repository but under their own licenses:
|
|
149
|
+
|
|
150
|
+
- `demo/models/` and `site/models/`: the object models, Apache License 2.0 (`LICENSE` and `NOTICE` there);
|
|
151
|
+
none of them is in the npm package.
|
|
152
|
+
- `demo/photos/` and `site/photos/`: the sample photos and videos, from Unsplash and Pexels under their own
|
|
153
|
+
licenses (the Unsplash License, the Pexels License), credited in `photos/index.json` and under each on the page.
|
|
154
|
+
- `site/ort/`: ONNX Runtime Web, MIT, Copyright (c) Microsoft Corporation (`site/ort/LICENSE`).
|
|
155
|
+
- The site's bundles include gifenc (MIT, Copyright (c) 2017 Matt DesLauriers). `site/THIRD-PARTY-NOTICES.txt`
|
|
156
|
+
lists all of these for the deployed site.
|