@mathzetta/qblur 0.1.2 → 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 +34 -0
- package/README.md +24 -21
- 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 +91 -88
- package/docs/library.md +51 -51
- package/package.json +4 -4
- package/src/apply-filter.js +8 -7
- package/src/apply.d.ts +12 -11
- package/src/cpu-helpers.js +7 -7
- package/src/cpu.js +51 -23
- package/src/element.d.ts +1 -1
- package/src/element.js +3 -3
- package/src/format.js +14 -14
- package/src/graphics.js +11 -11
- package/src/index.d.ts +11 -11
- package/src/library.js +29 -29
- package/src/png.js +18 -17
- package/src/save.js +7 -7
- package/src/strokes.js +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,39 @@
|
|
|
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
|
+
|
|
3
37
|
## 0.1.2
|
|
4
38
|
|
|
5
39
|
Fixes from a review before this release. Needs MathZetta 1.2 (the peer range is `^1.2.0`).
|
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
|
|
@@ -76,10 +76,10 @@ Every npm release's `dist/` is on jsDelivr (and unpkg), MathZetta's GLSL output
|
|
|
76
76
|
|
|
77
77
|
```html
|
|
78
78
|
<script type="module">
|
|
79
|
-
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';
|
|
80
80
|
</script>
|
|
81
81
|
<!-- or a classic script: window.QBlur -->
|
|
82
|
-
<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>
|
|
83
83
|
```
|
|
84
84
|
|
|
85
85
|
Every build comes **with MathZetta inside or without it** (`*.external.*`). Sizes as the CDN sends them (compressed):
|
|
@@ -95,7 +95,7 @@ Every build comes **with MathZetta inside or without it** (`*.external.*`). Size
|
|
|
95
95
|
|
|
96
96
|
MathZetta (its GLSL output and the parser) is about half of a full build. Without it, the page
|
|
97
97
|
loads MathZetta once itself: a classic page puts a MathZetta `<script>` first — `mathzetta.min.js`
|
|
98
|
-
or the `glsl`
|
|
98
|
+
or the `glsl` flavor (GLSL + formulas is what the filters use) — and the external classic build
|
|
99
99
|
reads `window.MathZetta`; a module page maps `mathzetta`, `mathzetta/glsl` and `mathzetta/formulas`
|
|
100
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
101
|
`models/`, `ort/`) are not in the package: they belong to the editor at qblur.com.
|
|
@@ -108,21 +108,21 @@ Publishing is `npm publish` (`prepublishOnly` runs the tests and the build).
|
|
|
108
108
|
| `src/format.js` | the filter document: normalize, validate, compile to passes, JSON and share links |
|
|
109
109
|
| `src/runtime.js` | the WebGL runner: textures, passes, live parameters |
|
|
110
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,
|
|
111
|
+
| `src/cpu-helpers.js` | what that code calls: texture-like sampling, neighborhood planes (separable, by bands of rows) |
|
|
112
112
|
| `src/cpu-runner.js`, `src/cpu-worker.js` | the CPU runner (draw / drawAsync over workers) |
|
|
113
113
|
| `src/auto.js` | `createRunner` / `chooseEngine`: GPU or CPU, and why |
|
|
114
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
|
|
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` |
|
|
116
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
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
|
|
119
|
-
| `demo/export.js` | the
|
|
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
|
|
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 |
|
|
121
121
|
| `src/graphics.js` | text and shapes: `normalizeGraphic` (validation), `drawGraphic` onto any 2D canvas, `loadGraphicFonts`, `renderGraphics(compiled, w, h)` for the runner |
|
|
122
122
|
| `tools/shot.mjs` | a screenshot of a page of this repo after running some JavaScript in it (headless Chrome) |
|
|
123
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
|
|
125
|
-
| `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) |
|
|
126
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
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
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 |
|
|
@@ -132,22 +132,25 @@ Publishing is `npm publish` (`prepublishOnly` runs the tests and the build).
|
|
|
132
132
|
| `demo/help.js` | the in-page cheat sheet, and `explain()`: an error → a hint and the help section / guide heading for it |
|
|
133
133
|
| `demo/photos/` | default photos (`index.json` lists them); the editor opens on the first |
|
|
134
134
|
| `tools/markdown.mjs` | the small Markdown renderer behind `site/guide.html` |
|
|
135
|
-
| `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 |
|
|
136
139
|
| `docs/filters.md` | the guide |
|
|
137
140
|
|
|
138
141
|
This was `src/filters/` and `demos/filters.html` in MathZetta until
|
|
139
142
|
2026-10-16; the GLSL expression output (`toGLSL`, `filterShader`) stayed
|
|
140
143
|
there as `mathzetta/glsl`.
|
|
141
144
|
|
|
142
|
-
##
|
|
145
|
+
## License
|
|
143
146
|
|
|
144
147
|
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
|
|
148
|
+
built-in filters and the site's own files. In this repository but under their own licenses:
|
|
146
149
|
|
|
147
150
|
- `demo/models/` and `site/models/`: the object models, Apache License 2.0 (`LICENSE` and `NOTICE` there);
|
|
148
151
|
none of them is in the npm package.
|
|
149
152
|
- `demo/photos/` and `site/photos/`: the sample photos and videos, from Unsplash and Pexels under their own
|
|
150
|
-
|
|
153
|
+
licenses (the Unsplash License, the Pexels License), credited in `photos/index.json` and under each on the page.
|
|
151
154
|
- `site/ort/`: ONNX Runtime Web, MIT, Copyright (c) Microsoft Corporation (`site/ort/LICENSE`).
|
|
152
155
|
- The site's bundles include gifenc (MIT, Copyright (c) 2017 Matt DesLauriers). `site/THIRD-PARTY-NOTICES.txt`
|
|
153
156
|
lists all of these for the deployed site.
|