@mathzetta/qblur 0.0.0-stage → 0.1.2

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 ADDED
@@ -0,0 +1,58 @@
1
+ # Changelog
2
+
3
+ ## 0.1.2
4
+
5
+ Fixes from a review before this release. Needs MathZetta 1.2 (the peer range is `^1.2.0`).
6
+
7
+ - **The CPU gives the shader's pixels again.** `round` takes a half away from zero (`round(-2.5)` is −3, as
8
+ MathZetta 1.2's shaders round), and `50%` is 0.5 on the CPU too (it was "unknown name").
9
+ - **Names every object has are ordinary names.** A knob, picture or graphic called `constructor`, `toString` or
10
+ `valueOf` works (a knob so named had the value NaN, and a picture was refused); an unknown name or function
11
+ so called is refused as unknown, not by a later error.
12
+ - **Text is not maths.** A quoted string in a filter is refused on the GPU as it was on the CPU (it was
13
+ written into the shader, which then failed to compile).
14
+ - **A filter built to stall the page is stopped.** At most 256 passes and 64 graphics; brush strokes stop
15
+ painting after a few hundred frames' worth of work in one call (a point far outside the frame, or the
16
+ largest brush crossing it thousands of times, froze the page for minutes); a very long `options` list no
17
+ longer overflows the stack.
18
+ - **`drawAsync`:** calls made before the workers are up share one pool (two pools were started, one was never
19
+ closed, and a call could fail); `dispose()` during a draw ends that draw with an error instead of leaving
20
+ it waiting for ever; a picture is copied to shared memory once, not on every draw.
21
+ - **WebGL:** shaders are freed once their program is linked, and when a pass does not compile the passes
22
+ compiled before it are freed too (each filter left two shader objects per pass behind).
23
+ - A font's CSS is fetched without cookies or a referrer. `encodePng` refuses a size that isn't whole pixels
24
+ or data too short for it.
25
+ - More npm keywords (image-processing, canvas, gif, web-component …).
26
+
27
+ ## 0.1.1
28
+
29
+ No change to the code. The licence names its holder (`Copyright (c) 2025-2026 Robert Wilcox`; 0.1.0's said
30
+ "MathZetta Contributors"), and every bundle's banner says whose it is and its licence, MathZetta's too.
31
+ The README has a Licence section, and it and docs/library.md no longer say the package isn't on npm yet.
32
+ ## 0.1.0 — first release
33
+
34
+ The filter format, its compiler and two runners that give the same pixels.
35
+
36
+ - **The format, `mathzetta-filter/1`** (frozen: later versions add, never change or remove): a filter is
37
+ maths over a pixel, or a JSON document with a name, an author, knobs (`params`: numbers, colours, menus,
38
+ boxes), notes, other pictures (`images`, each placed), text and shapes and brush strokes (`graphics`), a
39
+ colour space, or `steps` — a chain of other filters with their own settings and opacity, which nests and
40
+ keeps its authors' names. `normalizeFilter`, `validateFilter`, `compileFilter`; sharing as JSON or a link
41
+ (`filterToJSON`, `filterToLink`, `readFilter`). A filter is only maths: running someone else's is safe (a text's font, if it names one, is fetched).
42
+ - **`applyFilter(picture, filter, { params, t, images, engine, canvas, maxSize })`** (`@mathzetta/qblur/apply`, `dist/qblur-apply.js`): the one call — a filter in any
43
+ form (maths, a document, JSON, a link, a compiled filter, or a built-in filter's name) on an `<img>`,
44
+ `<video>`, canvas, ImageData or `{ data, width, height }`; a 2D canvas back in a page, the picture in Node. Pictures over 4096 px on the long side (2048 on the CPU)
45
+ are scaled down first; `maxSize` sets the limit.
46
+ - **`<qblur-image>`** (`@mathzetta/qblur/element`, `dist/qblur-element.js`): a picture with a filter on it as an HTML
47
+ element; attributes `src`, `filter`, `params`, `t`, `animate`, `engine`, `alt`, `crossorigin`.
48
+ - **Runners**: WebGL 1 and 2 (`createFilterRunner`; 8-bit, half or float textures between passes) and plain
49
+ JavaScript (`createCpuRunner`; browsers and Node, `drawAsync` over workers for big pictures, generated
50
+ code checked before it runs); `createRunner` picks the GPU when it can.
51
+ - **Saving**: `toBlob` (PNG written by the package — indexed when there are few colours — so it works in
52
+ Node; JPEG and WebP in a browser), `encodeGif` (with gifenc passed in), `encodePng` — in `@mathzetta/qblur/apply`.
53
+ - **79 built-in filters** in `LIBRARY`, in seven `GROUPS`.
54
+ - **Text, shapes and brush strokes** drawn into frame-sized pictures (`renderGraphics`, `rasterizeStrokes`),
55
+ with web fonts and separate shadow layers.
56
+ - **Builds** on jsDelivr/unpkg: an ES module and a classic script, each with MathZetta inside or without
57
+ it, a GPU-only core, the element, and the CPU worker. TypeScript declarations for the package and the
58
+ element. MIT; no dependencies (MathZetta 1.x is a peer).
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-2026 Robert Wilcox
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,153 @@
1
- # Temporary Holding Version
1
+ # qblur
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Image filters written as maths — the site is **qblur** (qblur.com). A filter is an expression over a pixel —
4
+ `1 - rgb`, `if gray > 0.5 then (1, 0, 0)`, `gaussian(3)`,
5
+ `mix(source, rgb, luma(mask))` — or a JSON document with parameters, extra
6
+ pictures (masks, overlays) and chains of other people's filters. The
7
+ package turns one into WebGL shaders (through MathZetta's GLSL output) and
8
+ runs it on a picture.
9
+
10
+ ```js
11
+ import { applyFilter, toBlob } from '@mathzetta/qblur/apply'; // one call, and saving: its own entry
12
+
13
+ const canvas = await applyFilter(img, 'Sepia'); // a built-in filter, by name
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 maths
16
+ const png = await toBlob(mine); // PNG (JPEG, WebP in a browser)
17
+ // pictures over 4096 px on the long side (2048 on the CPU) are scaled down first: { maxSize } changes it
18
+ ```
19
+
20
+ ```html
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.1/dist/qblur-element.js"></script>
23
+ ```
24
+
25
+ For live knobs and video, a runner of your own:
26
+
27
+ ```js
28
+ import { compileFilter, createRunner, filterToLink } from '@mathzetta/qblur';
29
+
30
+ const compiled = compileFilter({ name: 'Old film', params: { strength: 1 }, color: 'gray + strength * 0.1 * sin(py)' });
31
+ const { runner } = createRunner(compiled, { gl: canvas.getContext('webgl') });
32
+ runner.setImage(img).draw({ t: 0, canvas });
33
+ filterToLink(compiled); // a URL anyone can open
34
+ ```
35
+
36
+ Needs `mathzetta` 1.x (a peer dependency: `npm install @mathzetta/qblur mathzetta`). TypeScript types are included.
37
+ Three entries: `@mathzetta/qblur` (the filters, the runners, the library), `@mathzetta/qblur/apply` (`applyFilter` and saving) and
38
+ `@mathzetta/qblur/element` (`<qblur-image>`).
39
+ Saving: `toBlob` (PNG anywhere, JPEG/WebP in a browser) and `encodeGif` (bring
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
+ 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 maths: what an expression can use, animation, neighbourhoods,
43
+ geometry, several pictures, sharing and the API.
44
+
45
+ It runs on the GPU (WebGL) or the CPU (plain JavaScript, also in Node):
46
+ `createRunner(compiled, { gl })` uses the GPU whenever WebGL is there (a
47
+ filter's shaders compile once, then serve every picture and frame) and the
48
+ CPU without it — both give the same pixels. See "Running it" in the guide.
49
+
50
+ ```bash
51
+ npm install # links ../mathzetta/packages/mathzetta (the public repo, checked out beside this one) for development
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)
54
+ npm run check # every library filter through real WebGL in headless Chrome
55
+ npm run check:cpu # …and the CPU runner on the same pictures, compared pixel by pixel
56
+ npm run check:nowebgl # Chrome without WebGL: the editor must fall back to the CPU
57
+ npm run build # site/ — the editor bundled for any static host (no node_modules, no import map)
58
+ npm run check:site # build, then run the checks against site/
59
+ ```
60
+
61
+ Before building for a real address, set `SITE_URL=https://…/` (or
62
+ `"homepage"` in package.json) so pages get absolute canonical, `og:url` and
63
+ `og:image` addresses; the preview cards are `demo/share/*.jpg` (`node tools/share-cards.mjs` remakes them).
64
+
65
+ `site/` is the deployable editor: `index.html`, `app.js` (the page with
66
+ MathZetta and this package bundled in), `cpu-worker.js`, `guide.html` (the
67
+ guide rendered, heading ids as on GitHub) and `photos/`. Default photos go
68
+ in `demo/photos/` with an `index.json` — see the README there.
69
+ Serve the folder from anywhere (GitHub Pages, S3, a CDN); share links are
70
+ `#…` fragments, so nothing else is needed.
71
+
72
+ ## From a CDN
73
+
74
+ Every npm release's `dist/` is on jsDelivr (and unpkg), MathZetta's GLSL output bundled in —
75
+ [docs/library.md](docs/library.md) has working examples of each way in:
76
+
77
+ ```html
78
+ <script type="module">
79
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
80
+ </script>
81
+ <!-- or a classic script: window.QBlur -->
82
+ <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.global.min.js"></script>
83
+ ```
84
+
85
+ Every build comes **with MathZetta inside or without it** (`*.external.*`). Sizes as the CDN sends them (compressed):
86
+
87
+ | | ES module | classic `<script>` (`window.QBlur`) |
88
+ |---|---|---|
89
+ | everything, MathZetta inside (the classic script: `@mathzetta/qblur/apply` too) | `qblur.js` 54 KB | `qblur.global.min.js` 58 KB |
90
+ | `@mathzetta/qblur/apply`: applyFilter and saving, MathZetta inside | `qblur-apply.js` 56 KB | |
91
+ | the `<qblur-image>` element (applyFilter and MathZetta inside) | `qblur-element.js` 56 KB | |
92
+ | everything, without MathZetta | `qblur.external.js` 26 KB | `qblur.external.global.min.js` 30 KB |
93
+ | compile + run on the GPU only (no CPU runner, strokes, graphics, library) | `qblur.core.js` 33 KB | |
94
+ | the CPU runner's worker (`drawAsync` on big pictures), found beside the bundle | `cpu-worker.js` 31 KB | |
95
+
96
+ MathZetta (its GLSL output and the parser) is about half of a full build. Without it, the page
97
+ loads MathZetta once itself: a classic page puts a MathZetta `<script>` first — `mathzetta.min.js`
98
+ or the `glsl` flavour (GLSL + formulas is what the filters use) — and the external classic build
99
+ reads `window.MathZetta`; a module page maps `mathzetta`, `mathzetta/glsl` and `mathzetta/formulas`
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
101
+ `models/`, `ort/`) are not in the package: they belong to the editor at qblur.com.
102
+ Publishing is `npm publish` (`prepublishOnly` runs the tests and the build).
103
+
104
+ ## Files
105
+
106
+ | | |
107
+ | --- | --- |
108
+ | `src/format.js` | the filter document: normalize, validate, compile to passes, JSON and share links |
109
+ | `src/runtime.js` | the WebGL runner: textures, passes, live parameters |
110
+ | `src/cpu.js` | filter expressions → typed, straight-line JavaScript per pass (through the whitelist gate) |
111
+ | `src/cpu-helpers.js` | what that code calls: texture-like sampling, neighbourhood planes (separable, by bands of rows) |
112
+ | `src/cpu-runner.js`, `src/cpu-worker.js` | the CPU runner (draw / drawAsync over workers) |
113
+ | `src/auto.js` | `createRunner` / `chooseEngine`: GPU or CPU, and why |
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 |
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 colour splash (click colours to keep), a photo that moves (saved as a GIF or video), fancy text (letters and border each coloured 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` |
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 |
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" |
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 colours, RGB when nothing is transparent, forced palettes with dithering |
119
+ | `demo/export.js` | the Export panel: format with estimated sizes (auto picks the smallest sensible), quality / colours, 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 colour-fill wand; the mask is `selected` in the maths |
121
+ | `src/graphics.js` | text and shapes: `normalizeGraphic` (validation), `drawGraphic` onto any 2D canvas, `loadGraphicFonts`, `renderGraphics(compiled, w, h)` for the runner |
122
+ | `tools/shot.mjs` | a screenshot of a page of this repo after running some JavaScript in it (headless Chrome) |
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 |
124
+ | `demo/tracker.js` | tracking an object through a clip: patch-matched outline points held to the group's move/scale/turn, a colour 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 top of the editor: each example's filter, picture, features and step-by-step explanation (tested to compile; the checker runs each) |
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 |
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) |
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 |
129
+ | `tools/export-model.py` | remakes the ONNX models in demo/models/ (RF-DETR Small and Nano, MobileSAM; Python `rfdetr`) |
130
+ | `tools/compare-ai.mjs` | every object model on the same things in a photo, drawn side by side with timings (built site, headless Chrome) |
131
+ | `demo/app.js` | the editor's script; `tools/build.mjs` bundles it (resolving the page's import map) into `site/` |
132
+ | `demo/help.js` | the in-page cheat sheet, and `explain()`: an error → a hint and the help section / guide heading for it |
133
+ | `demo/photos/` | default photos (`index.json` lists them); the editor opens on the first |
134
+ | `tools/markdown.mjs` | the small Markdown renderer behind `site/guide.html` |
135
+ | `demo/index.html` | editor, library, share links; what `npm run check` drives |
136
+ | `docs/filters.md` | the guide |
137
+
138
+ This was `src/filters/` and `demos/filters.html` in MathZetta until
139
+ 2026-10-16; the GLSL expression output (`toGLSL`, `filterShader`) stayed
140
+ there as `mathzetta/glsl`.
141
+
142
+ ## Licence
143
+
144
+ MIT — [LICENSE](LICENSE), Copyright (c) 2025-2026 Robert Wilcox: the package, the editor, the apps, the
145
+ built-in filters and the site's own files. In this repository but under their own licences:
146
+
147
+ - `demo/models/` and `site/models/`: the object models, Apache License 2.0 (`LICENSE` and `NOTICE` there);
148
+ none of them is in the npm package.
149
+ - `demo/photos/` and `site/photos/`: the sample photos and videos, from Unsplash and Pexels under their own
150
+ licences (the Unsplash License, the Pexels License), credited in `photos/index.json` and under each on the page.
151
+ - `site/ort/`: ONNX Runtime Web, MIT, Copyright (c) Microsoft Corporation (`site/ort/LICENSE`).
152
+ - The site's bundles include gifenc (MIT, Copyright (c) 2017 Matt DesLauriers). `site/THIRD-PARTY-NOTICES.txt`
153
+ lists all of these for the deployed site.