@mathzetta/qblur 0.1.2 → 0.3.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 +45 -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 +110 -88
- package/docs/library.md +57 -52
- 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-runner.js +3 -1
- package/src/cpu.js +55 -23
- package/src/distance.js +145 -0
- package/src/element.d.ts +1 -1
- package/src/element.js +3 -3
- package/src/format.js +15 -14
- package/src/graphics.js +11 -11
- package/src/index.d.ts +26 -11
- package/src/index.js +1 -0
- package/src/library.js +35 -29
- package/src/png.js +18 -17
- package/src/runtime.js +2 -1
- package/src/save.js +7 -7
- package/src/strokes.js +4 -4
package/docs/library.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# qblur on your own pages
|
|
2
2
|
|
|
3
|
-
qblur is the library behind [the editor](https://qblur.com/): image filters written as
|
|
3
|
+
qblur is the library behind [the editor](https://qblur.com/editor.html): image filters written as math, compiled to
|
|
4
4
|
WebGL shaders, with the same pixels from plain JavaScript where there is no GPU. Put it on any page
|
|
5
5
|
with one `<script>` from a CDN — no build step, no server, nothing uploaded: the pictures stay in the
|
|
6
6
|
visitor's browser.
|
|
@@ -8,30 +8,30 @@ visitor's browser.
|
|
|
8
8
|
## What you can do with it
|
|
9
9
|
|
|
10
10
|
- **Filters on your pictures, live.** Any `<img>`, `<canvas>`, `<video>` or webcam — sepia, blur,
|
|
11
|
-
comic, tilt-shift, a
|
|
11
|
+
comic, tilt-shift, a color splash, or one of your own in a line of math: `1 - rgb`,
|
|
12
12
|
`if gray > 0.5 then (1, 0, 0) else rgb`, `mix(rgb, gaussian(4), y)`.
|
|
13
13
|
- **Knobs.** A filter declares its parameters (`strength`, `tint`, …) with ranges; your sliders set them
|
|
14
14
|
and the picture redraws at once, without recompiling.
|
|
15
|
-
- **79 ready-made filters** in `LIBRARY`, in seven groups (
|
|
16
|
-
motion, text, brushes, other pictures, chains) — use them as they are, chain them, or read their
|
|
15
|
+
- **79 ready-made filters** in `LIBRARY`, in seven groups (color and tone, blur and edges, shape and
|
|
16
|
+
motion, text, brushes, other pictures, chains) — use them as they are, chain them, or read their math.
|
|
17
17
|
- **Chains.** Filters run one after another, each with its own settings and opacity; a chain is a filter
|
|
18
18
|
too, so published chains nest and keep their authors' names.
|
|
19
19
|
- **Animation.** `t` counts frames: `pixel(px + 8 sin(py / 10 + t / 5), py)` is a wave. On a video, the
|
|
20
20
|
filter runs on every frame.
|
|
21
21
|
- **Several pictures.** Masks, overlays, a second photo to blend in, a background for a green screen —
|
|
22
22
|
each placed (cover, fit, tile, zoomed, turned) and set by name.
|
|
23
|
-
- **Text and shapes** drawn into the picture and
|
|
24
|
-
- **Share a filter as a link** or a small JSON document; reading one is safe — a filter is only
|
|
25
|
-
it can read the picture and write
|
|
23
|
+
- **Text and shapes** drawn into the picture and colored, shadowed, frosted or animated by the math.
|
|
24
|
+
- **Share a filter as a link** or a small JSON document; reading one is safe — a filter is only math:
|
|
25
|
+
it can read the picture and write colors, nothing else.
|
|
26
26
|
- **Save the result** as PNG (in Node too), JPEG, WebP or an animated GIF.
|
|
27
27
|
- **GPU or CPU, the same pixels.** WebGL when it is there (fast: the shaders are compiled once), plain
|
|
28
28
|
JavaScript when it isn't — old browsers, locked-down machines, **Node** (thumbnails on a server, tests).
|
|
29
29
|
|
|
30
30
|
Some things people build with it: filters on upload in a photo or social app; effects on a `<video>` or a
|
|
31
|
-
webcam stream; a product page that
|
|
32
|
-
animated backgrounds; previews in a CMS; high-contrast or
|
|
31
|
+
webcam stream; a product page that recolors an item as the customer picks; generative art and
|
|
32
|
+
animated backgrounds; previews in a CMS; high-contrast or color-blindness views for accessibility; a
|
|
33
33
|
lesson on how pictures are just numbers. The [small apps](https://qblur.com/avatar/) on qblur.com —
|
|
34
|
-
profile picture,
|
|
34
|
+
profile picture, make it move, fancy text — are each a page of this library and a few
|
|
35
35
|
controls.
|
|
36
36
|
|
|
37
37
|
## Start here
|
|
@@ -41,14 +41,14 @@ controls.
|
|
|
41
41
|
```html runnable
|
|
42
42
|
<img id="photo" src="photo.jpg" alt="" hidden>
|
|
43
43
|
<canvas id="out"></canvas>
|
|
44
|
-
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
44
|
+
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.global.min.js"></script>
|
|
45
45
|
<script>
|
|
46
46
|
const img = document.getElementById('photo');
|
|
47
47
|
img.decode().then(() => QBlur.applyFilter(img, 'Sepia', { canvas: document.getElementById('out') }));
|
|
48
48
|
</script>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
`applyFilter(picture, filter, options)` takes the filter in any form —
|
|
51
|
+
`applyFilter(picture, filter, options)` takes the filter in any form — math (`'1 - rgb'`), a built-in
|
|
52
52
|
filter's name (`'Sepia'`, `'Gaussian blur'`), a filter document, JSON, a share link or a compiled filter —
|
|
53
53
|
and resolves with the result at the picture's size: a 2D canvas (yours, given as `canvas`, or a new one) in a
|
|
54
54
|
page, `{ data, width, height }` in Node. A picture longer than 4096 px on its long side (2048 on the CPU) is
|
|
@@ -69,8 +69,8 @@ picture that redraws many times a second as a knob moves, a runner of your own (
|
|
|
69
69
|
### As an HTML element
|
|
70
70
|
|
|
71
71
|
```html runnable
|
|
72
|
-
<qblur-image id="out" src="photo.jpg" filter="Vignette" params='{"strength": 2.5}' alt="A street of
|
|
73
|
-
<script type="module" src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
72
|
+
<qblur-image id="out" src="photo.jpg" filter="Vignette" params='{"strength": 2.5}' alt="A street of colored houses"></qblur-image>
|
|
73
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur-element.js"></script>
|
|
74
74
|
```
|
|
75
75
|
|
|
76
76
|
`<qblur-image>` draws its picture with the filter on it, and again whenever an attribute changes:
|
|
@@ -85,13 +85,13 @@ picture from another site must allow CORS). It fires `load` after each drawing a
|
|
|
85
85
|
```html runnable
|
|
86
86
|
<img id="photo" src="photo.jpg" alt="">
|
|
87
87
|
<canvas id="out"></canvas>
|
|
88
|
-
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
88
|
+
<script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.global.min.js"></script>
|
|
89
89
|
<script>
|
|
90
90
|
const img = document.getElementById('photo'), canvas = document.getElementById('out');
|
|
91
91
|
img.decode().then(() => {
|
|
92
92
|
canvas.width = img.naturalWidth; // the result is the canvas's size: make it the picture's
|
|
93
93
|
canvas.height = img.naturalHeight;
|
|
94
|
-
const compiled = QBlur.compileFilter('1 - rgb'); // a filter: here, one line of
|
|
94
|
+
const compiled = QBlur.compileFilter('1 - rgb'); // a filter: here, one line of math
|
|
95
95
|
const { runner } = QBlur.createRunner(compiled, { gl: canvas.getContext('webgl') });
|
|
96
96
|
runner.setImage(img).draw({ canvas }); // the GPU draws on gl's canvas; without WebGL, the CPU draws on `canvas`
|
|
97
97
|
});
|
|
@@ -107,7 +107,7 @@ a WebGL context and the CPU when it doesn't; pass the same canvas to `draw` eith
|
|
|
107
107
|
<canvas id="out"></canvas>
|
|
108
108
|
<label>Vignette <input id="strength" type="range" min="0" max="4" step="0.01" value="1.6"></label>
|
|
109
109
|
<script type="module">
|
|
110
|
-
import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
110
|
+
import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
111
111
|
|
|
112
112
|
const img = new Image();
|
|
113
113
|
img.src = 'photo.jpg';
|
|
@@ -132,7 +132,7 @@ a WebGL context and the CPU when it doesn't; pass the same canvas to `draw` eith
|
|
|
132
132
|
### From npm
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
|
-
npm install @mathzetta/qblur mathzetta # mathzetta is a peer dependency: qblur uses its
|
|
135
|
+
npm install @mathzetta/qblur mathzetta # mathzetta is a peer dependency: qblur uses its math parser and GLSL output
|
|
136
136
|
```
|
|
137
137
|
|
|
138
138
|
```js
|
|
@@ -173,7 +173,7 @@ at one file:
|
|
|
173
173
|
} }
|
|
174
174
|
</script>
|
|
175
175
|
<script type="module">
|
|
176
|
-
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
176
|
+
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.external.js';
|
|
177
177
|
const img = new Image();
|
|
178
178
|
img.src = 'photo.jpg';
|
|
179
179
|
await img.decode();
|
|
@@ -185,21 +185,21 @@ at one file:
|
|
|
185
185
|
</script>
|
|
186
186
|
```
|
|
187
187
|
|
|
188
|
-
With classic scripts: `<script src="…/mathzetta@1/build/mathzetta.glsl.min.js">` (the GLSL
|
|
189
|
-
is what filters use) and then `…/@mathzetta/qblur@0.
|
|
188
|
+
With classic scripts: `<script src="…/mathzetta@1/build/mathzetta.glsl.min.js">` (the GLSL flavor, which
|
|
189
|
+
is what filters use) and then `…/@mathzetta/qblur@0.3/dist/qblur.external.global.min.js`.
|
|
190
190
|
|
|
191
|
-
Pin a version (`@0.
|
|
191
|
+
Pin a version (`@0.3` follows fixes, `@0.3.0` never changes) and, for a fixed version, add an `integrity`
|
|
192
192
|
hash so the browser checks the file. jsDelivr shows each file's hash on its package page, or make it
|
|
193
|
-
yourself: `curl -s https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
193
|
+
yourself: `curl -s https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3.0/dist/qblur.js | openssl dgst -sha384 -binary | openssl base64 -A`
|
|
194
194
|
gives the part after `sha384-`.
|
|
195
195
|
|
|
196
196
|
## Filters
|
|
197
197
|
|
|
198
|
-
A filter is
|
|
199
|
-
can use, animation,
|
|
198
|
+
A filter is math run on every pixel. The [guide](filters.md) is the full language — what an expression
|
|
199
|
+
can use, animation, neighboring pixels, geometry, several pictures, color spaces, text and brushes. In
|
|
200
200
|
short: `r g b a` (or `rgb`) is the pixel, `x y` its position from 0 to 1, `px py` in pixels, `w h` the
|
|
201
201
|
picture's size, `t` the frame, `gray` its brightness, `source` the original picture, and
|
|
202
|
-
`pixel(px, py)` reads another pixel. The result is a
|
|
202
|
+
`pixel(px, py)` reads another pixel. The result is a color `(r, g, b)` or a number (gray).
|
|
203
203
|
|
|
204
204
|
What you pass to `compileFilter`:
|
|
205
205
|
|
|
@@ -227,9 +227,9 @@ The fields of a filter document:
|
|
|
227
227
|
| --- | --- |
|
|
228
228
|
| `format` | `"mathzetta-filter/1"` — optional when writing one; `filterToJSON` adds it. The format is frozen: later versions add, never change |
|
|
229
229
|
| `name`, `author`, `description` | shown in credits and the editor's library |
|
|
230
|
-
| `params` | knobs: `{ name: { default, min, max, step?, label? } }`; a
|
|
231
|
-
| `color` | the
|
|
232
|
-
| `space` | the
|
|
230
|
+
| `params` | knobs: `{ name: { default, min, max, step?, label? } }`; a color is `[r, g, b]` (0–1) or `{ type: 'color', default: [r, g, b] }`; a bare number is a default |
|
|
231
|
+
| `color` | the math: a string, or by channel — `{ rgb: '…', a: '…' }`, `{ r, g, b, a }`, `{ rgba: '…' }` |
|
|
232
|
+
| `space` | the color space the math works in: `'hsv'`, `'hsl'`, `'lab'`, `'oklab'`, `'linear'`, `'ycbcr'`, or `{ in, out }` |
|
|
233
233
|
| `images` | other pictures it reads, by name: `{ mask: { description: 'light where the effect shows' } }` |
|
|
234
234
|
| `graphics` | text, rectangles, ovals or brush strokes drawn into pictures it reads ([Text and shapes](#text-and-shapes)) |
|
|
235
235
|
| `steps` | a chain instead of `color`: each step a filter (or an expression), with `with`, `opacity` and `skip` |
|
|
@@ -246,8 +246,8 @@ compiled.graphics; // every graphic, by name
|
|
|
246
246
|
compiled.credits; // [{ name: 'Sepia', author: '' }, …] — the filters it is made of
|
|
247
247
|
```
|
|
248
248
|
|
|
249
|
-
It throws when the filter is malformed or its
|
|
250
|
-
`the filter: Failed to parse expression "rgb * (1, 2": …`. A name the
|
|
249
|
+
It throws when the filter is malformed or its math doesn't parse:
|
|
250
|
+
`the filter: Failed to parse expression "rgb * (1, 2": …`. A name the math doesn't know (`rgb * nope`) is
|
|
251
251
|
found when a runner is made: `unknown name "nope"`. `validateFilter(def)` lists every problem with the
|
|
252
252
|
document itself, as messages naming the filter (`"Vignette": "with" sets "nope", but there is no parameter
|
|
253
253
|
called that`), without throwing.
|
|
@@ -334,14 +334,14 @@ await sharp(Buffer.from(out.data), { raw: { width: out.width, height: out.height
|
|
|
334
334
|
## Knobs
|
|
335
335
|
|
|
336
336
|
`filterParams(normalizeFilter(def))` lists every knob a filter or chain has —
|
|
337
|
-
`{ strength: { type: 'number', default: 1.6, min: 0, max: 4 } }`,
|
|
337
|
+
`{ strength: { type: 'number', default: 1.6, min: 0, max: 4 } }`, colors as `{ type: 'color', default: [r, g, b] }` —
|
|
338
338
|
so a page can build its controls from the filter:
|
|
339
339
|
|
|
340
340
|
```html runnable
|
|
341
341
|
<canvas id="out"></canvas>
|
|
342
342
|
<form id="knobs"></form>
|
|
343
343
|
<script type="module">
|
|
344
|
-
import { compileFilter, createRunner, normalizeFilter, filterParams } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
344
|
+
import { compileFilter, createRunner, normalizeFilter, filterParams } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
345
345
|
|
|
346
346
|
const def = {
|
|
347
347
|
name: 'Duotone',
|
|
@@ -384,7 +384,7 @@ In a chain, `filterParams` gives each knob's own default; the values a chain set
|
|
|
384
384
|
```html runnable
|
|
385
385
|
<canvas id="out"></canvas>
|
|
386
386
|
<script type="module">
|
|
387
|
-
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
387
|
+
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
388
388
|
const img = new Image();
|
|
389
389
|
img.src = 'photo.jpg';
|
|
390
390
|
await img.decode();
|
|
@@ -404,7 +404,7 @@ A video is a picture that changes: give the runner each frame.
|
|
|
404
404
|
<video id="clip" src="clip.mp4" muted loop playsinline autoplay hidden></video>
|
|
405
405
|
<canvas id="out"></canvas>
|
|
406
406
|
<script type="module">
|
|
407
|
-
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
407
|
+
import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
408
408
|
const video = document.getElementById('clip'), canvas = document.getElementById('out');
|
|
409
409
|
await new Promise((r) => { video.onloadeddata = r; if (video.readyState >= 2) r(); });
|
|
410
410
|
canvas.width = video.videoWidth;
|
|
@@ -424,14 +424,14 @@ To save what is shown as a video: `new MediaRecorder(canvas.captureStream(30))`.
|
|
|
424
424
|
|
|
425
425
|
## Other pictures: masks, overlays, backgrounds
|
|
426
426
|
|
|
427
|
-
A filter names the pictures it reads in `images`; the
|
|
427
|
+
A filter names the pictures it reads in `images`; the math uses them by name — `mask` is its color at
|
|
428
428
|
this pixel, `luma(mask)` its brightness, `alpha(mask)` its transparency — and you give them with
|
|
429
429
|
`setImage(name, picture)`. A picture not given is white.
|
|
430
430
|
|
|
431
431
|
```html runnable
|
|
432
432
|
<canvas id="out"></canvas>
|
|
433
433
|
<script type="module">
|
|
434
|
-
import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
434
|
+
import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
435
435
|
const img = new Image();
|
|
436
436
|
img.src = 'photo.jpg';
|
|
437
437
|
await img.decode();
|
|
@@ -445,7 +445,7 @@ this pixel, `luma(mask)` its brightness, `alpha(mask)` its transparency — and
|
|
|
445
445
|
grad.addColorStop(0, '#fff'); grad.addColorStop(1, '#000');
|
|
446
446
|
g.fillStyle = grad; g.fillRect(0, 0, 256, 256);
|
|
447
447
|
|
|
448
|
-
//
|
|
448
|
+
// gray everywhere, color where the mask is light ("Through a mask" is mix(source, rgb, luma(mask)))
|
|
449
449
|
const byName = (name) => LIBRARY.find((f) => f.name === name);
|
|
450
450
|
const { runner } = createRunner(compileFilter({ steps: [byName('Grayscale'), byName('Through a mask')] }), { gl: canvas.getContext('webgl') });
|
|
451
451
|
runner.setImage(img).setImage('mask', mask).draw({ canvas });
|
|
@@ -456,18 +456,21 @@ A picture of another shape is placed over the frame: `cover` (the default), `fit
|
|
|
456
456
|
with `zoom`, `x`, `y` and `angle` — set per step (`{ filter, with: { overlay: { place: 'fit', zoom: 0.5 } } }`)
|
|
457
457
|
or live (`runner.passes[i].placements.overlay.x = 0.2`; changing `place` needs a new compile).
|
|
458
458
|
`selected` is the picture named `selection` (the editor's selection): give it a mask to limit a filter to
|
|
459
|
-
part of the picture.
|
|
459
|
+
part of the picture. `away` is how many pixels a pixel is from that selection (0 inside it, and everywhere
|
|
460
|
+
without one): the runner works it out from the `selection` you give, only for a filter that uses it
|
|
461
|
+
(`mix((1, 0.8, 0.3), rgb, smoothstep(0, 60, away))` is a glow round the selection). To give distances of your own,
|
|
462
|
+
`setImage('away', awayPicture(mask))` — or any picture in that encoding.
|
|
460
463
|
|
|
461
464
|
## Text and shapes
|
|
462
465
|
|
|
463
|
-
A filter's `graphics` are drawn into pictures of the frame's size, which the
|
|
466
|
+
A filter's `graphics` are drawn into pictures of the frame's size, which the math reads like any other
|
|
464
467
|
picture. `renderGraphics` draws them (loading web fonts first); positions and sizes are fractions of the
|
|
465
468
|
frame, so they are crisp at any size.
|
|
466
469
|
|
|
467
470
|
```html runnable
|
|
468
471
|
<canvas id="out"></canvas>
|
|
469
472
|
<script type="module">
|
|
470
|
-
import { compileFilter, createRunner, renderGraphics } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.
|
|
473
|
+
import { compileFilter, createRunner, renderGraphics } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.3/dist/qblur.js';
|
|
471
474
|
const img = new Image();
|
|
472
475
|
img.src = 'photo.jpg';
|
|
473
476
|
await img.decode();
|
|
@@ -487,7 +490,7 @@ frame, so they are crisp at any size.
|
|
|
487
490
|
```
|
|
488
491
|
|
|
489
492
|
Text has `text`, `font` (a CSS family, or `fontUrl` for a web font), `weight`, `style`, `size`, `x`, `y`,
|
|
490
|
-
`align`, `angle`, `color`, `outline` and shadows; `rect` and `ellipse` have `x`, `y` (the
|
|
493
|
+
`align`, `angle`, `color`, `outline` and shadows; `rect` and `ellipse` have `x`, `y` (the center), `w`, `h`,
|
|
491
494
|
`angle`, `color`, `outline` and shadows, and a rectangle a corner `radius`. Brush strokes (`type: 'strokes'`) are recorded drawings that play out over `t`; draw them
|
|
492
495
|
for each frame with `renderGraphics(compiled, w, h, { t })` or `rasterizeStrokes`. The guide's
|
|
493
496
|
"Text and shapes" and "Brushes" have every field.
|
|
@@ -495,7 +498,7 @@ for each frame with `renderGraphics(compiled, w, h, { t })` or `rasterizeStrokes
|
|
|
495
498
|
## Saving the result
|
|
496
499
|
|
|
497
500
|
```js
|
|
498
|
-
const png = await toBlob(canvas); // a PNG: indexed when there are ≤ 256
|
|
501
|
+
const png = await toBlob(canvas); // a PNG: indexed when there are ≤ 256 colors, RGB when opaque
|
|
499
502
|
const jpeg = await toBlob(canvas, { type: 'image/jpeg', quality: 0.9 }); // JPEG and WebP: the browser's encoder
|
|
500
503
|
const { data, width, height } = cpuRunner.draw(); // CPU: the bytes themselves
|
|
501
504
|
```
|
|
@@ -505,7 +508,7 @@ PNG itself, so it works in Node as well; JPEG and WebP need a browser. A WebGL c
|
|
|
505
508
|
with a 2D context: pass the canvas `applyFilter` gave you, or call the canvas's own `toBlob` right after
|
|
506
509
|
`draw()` (or create the context with `preserveDrawingBuffer: true`).
|
|
507
510
|
|
|
508
|
-
An animated GIF needs a
|
|
511
|
+
An animated GIF needs a color quantizer and an LZW encoder. The package has no dependencies, so bring
|
|
509
512
|
[gifenc](https://www.npmjs.com/package/gifenc) (`npm i gifenc`, 9 KB) and pass it in:
|
|
510
513
|
|
|
511
514
|
```js node
|
|
@@ -527,14 +530,14 @@ of that size, or with the CPU runner on a picture of that size.
|
|
|
527
530
|
## Sharing filters
|
|
528
531
|
|
|
529
532
|
```js
|
|
530
|
-
const link = filterToLink(def, 'https://qblur.com/'); // https://qblur.com
|
|
533
|
+
const link = filterToLink(def, 'https://qblur.com/editor.html'); // https://qblur.com/editor.html#eyJmb3Jt… — opens in the editor
|
|
531
534
|
const json = filterToJSON(def); // the document, defaults left out
|
|
532
535
|
readFilter(text); // whatever was pasted: a link, JSON, or an expression
|
|
533
536
|
filterFromLink(location.hash); // a filter from your own page's address
|
|
534
537
|
validateFilter(readFilter(text)); // [] when it is fine
|
|
535
538
|
```
|
|
536
539
|
|
|
537
|
-
A filter from someone else is safe to run: it is
|
|
540
|
+
A filter from someone else is safe to run: it is math over the picture, compiled by qblur into shaders (or
|
|
538
541
|
checked JavaScript on the CPU), with no access to the page, the network or anything else. One thing does reach
|
|
539
542
|
the network: a filter with text may name a font (a Google Fonts family or an https address), which the page
|
|
540
543
|
then fetches to draw it — so whoever serves that font sees the request.
|
|
@@ -544,12 +547,12 @@ then fetches to draw it — so whoever serves that font sees the request.
|
|
|
544
547
|
`LIBRARY` is an array of filter documents (79), each with a `group` from `GROUPS`:
|
|
545
548
|
|
|
546
549
|
```js
|
|
547
|
-
GROUPS; // ['
|
|
550
|
+
GROUPS; // ['Color & tone', 'Blur & edges', 'Shape & motion', 'Text & shapes', 'Brushes', 'Other pictures', 'Chains']
|
|
548
551
|
LIBRARY.filter((f) => f.group === 'Blur & edges').map((f) => f.name);
|
|
549
552
|
const comic = LIBRARY.find((f) => f.name === 'Comic'); // a chain of four
|
|
550
553
|
```
|
|
551
554
|
|
|
552
|
-
The editor's [
|
|
555
|
+
The editor's library (*From the library*, in its [Filter tab](https://qblur.com/editor.html)) puts any of them on your own photo, with its knobs; the [filters page](https://qblur.com/filters.html) shows their math.
|
|
553
556
|
|
|
554
557
|
## Reference
|
|
555
558
|
|
|
@@ -562,11 +565,11 @@ Everything the package exports — from `@mathzetta/qblur/apply`, the first seve
|
|
|
562
565
|
| `MAX_SIZE`, `MAX_SIZE_CPU` | the default `maxSize`: 4096 on the GPU, 2048 on the CPU |
|
|
563
566
|
| `toCompiled(filter)` | any form `applyFilter` takes → the compiled filter |
|
|
564
567
|
| `toBlob(canvasOrPicture, { type, quality, palette })` | the result as a file: PNG anywhere, JPEG and WebP in a browser |
|
|
565
|
-
| `encodeGif(frames, { gifenc, delay, repeat,
|
|
566
|
-
| `encodePng({ width, height, data, palette,
|
|
568
|
+
| `encodeGif(frames, { gifenc, delay, repeat, colors })` | an animated GIF, with gifenc passed in |
|
|
569
|
+
| `encodePng({ width, height, data, palette, colors, quantize })` | the PNG writer `toBlob` uses (indexed, RGB or RGBA) |
|
|
567
570
|
| `pictureData(canvasOrPicture)` | its RGBA bytes |
|
|
568
571
|
| `QBlurImage` (from `@mathzetta/qblur/element`) | the `<qblur-image>` element's class; importing the entry defines the element |
|
|
569
|
-
| `compileFilter(def, { version })` | a filter (expression, document or chain) → `{ passes, images, graphics, credits, … }`; throws on a malformed filter or
|
|
572
|
+
| `compileFilter(def, { version })` | a filter (expression, document or chain) → `{ passes, images, graphics, credits, … }`; throws on a malformed filter or math that doesn't parse |
|
|
570
573
|
| `createRunner(compiled, { gl, prefer, precision, workers })` | `{ runner, engine, reason }`: the GPU when `gl` is a WebGL context, else the CPU |
|
|
571
574
|
| `createFilterRunner(gl, compiled, { precision })` | the WebGL runner |
|
|
572
575
|
| `createCpuRunner(compiled, { precision, workers, parallelFrom, workerUrl })` | the JavaScript runner (browsers and Node); `draw()` and `drawAsync()` |
|
|
@@ -587,6 +590,8 @@ Everything the package exports — from `@mathzetta/qblur/apply`, the first seve
|
|
|
587
590
|
| `normalizeStrokes`, `strokeTimeline`, `rasterizeStrokes(spec, w, h, t, { mask })` | brush strokes, frame by frame |
|
|
588
591
|
| `BRUSHES`, `TIMINGS`, `WIDTH_FROM`, `CLIPS`, `FPS`, `STROKES_DEFAULTS` | brush options |
|
|
589
592
|
| `traceContours(mask, w, h)`, `simplify`, `simplifyLoop` | the outlines of a mask, as polylines |
|
|
593
|
+
| `awayPicture(selection, { size })` | the picture `away` is read from, for a selection mask (white = in): its distances measured at most `size` (`AWAY_SIZE`, 512) across; the runners make it themselves |
|
|
594
|
+
| `encodeAway(data, w, h, { channel, scale })`, `distanceTo(inside, w, h)`, `awayFromChannels(red, green)`, `usesAway(compiled)` | the same from a mask's pixels; the exact distance transform; decoding; whether a filter reads `away` |
|
|
590
595
|
| `compileCpuPass(pass)` | one pass as checked JavaScript (what the CPU runner runs; `.uses` says if it reads `t`, other pictures, `random`) |
|
|
591
596
|
|
|
592
597
|
## Good to know
|
|
@@ -597,5 +602,5 @@ Everything the package exports — from `@mathzetta/qblur/apply`, the first seve
|
|
|
597
602
|
more where the effect needs it (bloom, edge strengths).
|
|
598
603
|
- **Big pictures.** WebGL limits a texture to `gl.getParameter(gl.MAX_TEXTURE_SIZE)` (often 4096 or more);
|
|
599
604
|
the CPU has no limit but takes longer — `drawAsync` uses every core.
|
|
600
|
-
- **
|
|
605
|
+
- **License.** MIT ([LICENSE](https://github.com/triplelog/qblur/blob/main/LICENSE), Copyright (c) 2025-2026 Robert Wilcox), and so is
|
|
601
606
|
MathZetta, which the bundles include. The object models used by the editor's "find objects" are not in the package.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mathzetta/qblur",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Shareable image filters written as
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Shareable image filters written as math: a JSON format with params, pictures and chains, compiled to WebGL shaders by MathZetta.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.js",
|
|
7
7
|
"types": "./src/index.d.ts",
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
"check:docs": "node tools/check-docs.mjs"
|
|
68
68
|
},
|
|
69
69
|
"peerDependencies": {
|
|
70
|
-
"mathzetta": "^1.
|
|
70
|
+
"mathzetta": "^1.5.0"
|
|
71
71
|
},
|
|
72
72
|
"devDependencies": {
|
|
73
73
|
"@mathzetta/inlinemath": "file:../mathzetta/packages/inlinemath",
|
|
@@ -114,7 +114,7 @@
|
|
|
114
114
|
"canvas",
|
|
115
115
|
"gif",
|
|
116
116
|
"web-component",
|
|
117
|
-
"
|
|
117
|
+
"math",
|
|
118
118
|
"mathzetta"
|
|
119
119
|
]
|
|
120
120
|
}
|
package/src/apply-filter.js
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* One call: a picture and a filter in, the filtered picture out.
|
|
3
3
|
*
|
|
4
|
-
* const canvas = await applyFilter(img, '1 - rgb'); //
|
|
4
|
+
* const canvas = await applyFilter(img, '1 - rgb'); // math
|
|
5
5
|
* const canvas = await applyFilter(img, 'Sepia'); // a built-in filter, by name
|
|
6
6
|
* const canvas = await applyFilter(img, 'Threshold', { params: { cutoff: 0.3 } });
|
|
7
7
|
* const picture = await applyFilter(imageData, filterDoc); // in Node: { data, width, height }
|
|
8
8
|
*
|
|
9
|
-
* `filter` is
|
|
9
|
+
* `filter` is math, a filter document, JSON or a share link (readFilter), a
|
|
10
10
|
* compiled filter (compileFilter), or the name of a filter in LIBRARY. The
|
|
11
11
|
* result is the picture's size — up to a limit: a picture longer than
|
|
12
12
|
* `maxSize` on its long side (MAX_SIZE, 4096 px, on the GPU; MAX_SIZE_CPU,
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
* same pixels either way. The GPU work happens on one hidden WebGL canvas the
|
|
22
22
|
* module keeps (browsers allow only a few contexts), and a filter's shaders
|
|
23
23
|
* are compiled once and kept for the next call with the same filter (the
|
|
24
|
-
* same
|
|
24
|
+
* same math or document — by what it says, so a changed document is a new
|
|
25
25
|
* filter — or the same compiled filter, whose knob values are read again on
|
|
26
26
|
* every call). Calls run one at a time, in the order they were made.
|
|
27
27
|
*/
|
|
@@ -40,7 +40,8 @@ const newCanvas = (width, height) => (typeof document !== 'undefined'
|
|
|
40
40
|
export function toCompiled(filter) {
|
|
41
41
|
if (filter && typeof filter === 'object' && Array.isArray(filter.passes)) return filter; // (isCompiled, below)
|
|
42
42
|
if (typeof filter === 'string') {
|
|
43
|
-
const
|
|
43
|
+
const wanted = filter.trim().toLowerCase();
|
|
44
|
+
const named = LIBRARY.find((f) => f.name.toLowerCase() === wanted);
|
|
44
45
|
return compileFilter(named ?? readFilter(filter));
|
|
45
46
|
}
|
|
46
47
|
return compileFilter(filter);
|
|
@@ -153,9 +154,9 @@ let queue = Promise.resolve(); // one drawing at a time: they share the
|
|
|
153
154
|
|
|
154
155
|
/**
|
|
155
156
|
* @param {CanvasImageSource|ImageData|{ data, width, height }} image the picture (loaded)
|
|
156
|
-
* @param {string|object} filter
|
|
157
|
+
* @param {string|object} filter math, a filter document, JSON, a link, a compiled filter, or a LIBRARY name
|
|
157
158
|
* @param {object} [options]
|
|
158
|
-
* params { name: value } — knob values (a
|
|
159
|
+
* params { name: value } — knob values (a color is [r, g, b], 0–1); the rest keep their defaults.
|
|
159
160
|
* In a chain, every step with a knob of that name takes it.
|
|
160
161
|
* t the frame, for filters that move (default 0)
|
|
161
162
|
* images { name: picture } — the other pictures the filter asks for (compiled.images)
|
|
@@ -192,7 +193,7 @@ async function apply(picture, filter, { params = {}, t = 0, images = {}, engine
|
|
|
192
193
|
for (const [name, value] of Object.entries(params)) {
|
|
193
194
|
if (!known.has(name)) throw new Error(`applyFilter: the filter has no knob called "${name}" (it has ${[...known.keys()].join(', ') || 'none'})`);
|
|
194
195
|
if (known.get(name).type === 'color' ? !isColor(value) : !Number.isFinite(Number(value)) || typeof value === 'object' || value === '') {
|
|
195
|
-
throw new Error(`applyFilter: the knob "${name}" needs ${known.get(name).type === 'color' ? 'a
|
|
196
|
+
throw new Error(`applyFilter: the knob "${name}" needs ${known.get(name).type === 'color' ? 'a color, [r, g, b] with each 0–1' : 'a number'}, not ${JSON.stringify(value)}`);
|
|
196
197
|
}
|
|
197
198
|
}
|
|
198
199
|
// the filter's graphics (text, shapes, strokes) are drawn first: nothing below waits, so a kept runner is set and drawn in one go
|
package/src/apply.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
/** `import { applyFilter, toBlob } from '@mathzetta/qblur/apply'` — one call to filter a picture, and the ways to save the result. */
|
|
2
|
-
import type { CompiledFilter, FilterInput, Picture, Picture8, PictureSource,
|
|
2
|
+
import type { CompiledFilter, FilterInput, Picture, Picture8, PictureSource, Color, Engine } from './index.js';
|
|
3
3
|
|
|
4
4
|
// ---- one call ------------------------------------------------------------------------------
|
|
5
5
|
|
|
6
6
|
export interface ApplyOptions {
|
|
7
|
-
/** Knob values; a
|
|
8
|
-
params?: Record<string, number |
|
|
7
|
+
/** Knob values; a color is [r, g, b], 0–1. The rest keep their defaults. */
|
|
8
|
+
params?: Record<string, number | Color>;
|
|
9
9
|
/** The frame, for filters that move. */
|
|
10
10
|
t?: number;
|
|
11
11
|
/** The other pictures the filter asks for (compiled.images). */
|
|
@@ -25,7 +25,7 @@ export const MAX_SIZE_CPU: number;
|
|
|
25
25
|
/**
|
|
26
26
|
* A picture and a filter in, the filtered picture out (the picture's size, up to `maxSize`): a 2D canvas in a page,
|
|
27
27
|
* an OffscreenCanvas in a worker, a picture { data, width, height } in Node.
|
|
28
|
-
* `filter`:
|
|
28
|
+
* `filter`: math, a document, JSON, a share link, a compiled filter, or a LIBRARY filter's name.
|
|
29
29
|
*/
|
|
30
30
|
export function applyFilter(image: PictureSource, filter: FilterInput | CompiledFilter, options?: ApplyOptions): Promise<HTMLCanvasElement | OffscreenCanvas | Picture8>;
|
|
31
31
|
/** A filter in any of the forms applyFilter takes → compiled. */
|
|
@@ -37,7 +37,7 @@ export function toCompiled(filter: FilterInput | CompiledFilter): CompiledFilter
|
|
|
37
37
|
export function toBlob(what: HTMLCanvasElement | OffscreenCanvas | Picture, options?: {
|
|
38
38
|
type?: 'image/png' | 'image/jpeg' | 'image/webp' | string;
|
|
39
39
|
quality?: number;
|
|
40
|
-
/** PNG: 'auto' writes an indexed PNG when there are at most 256
|
|
40
|
+
/** PNG: 'auto' writes an indexed PNG when there are at most 256 colors. */
|
|
41
41
|
palette?: 'auto' | 'none';
|
|
42
42
|
}): Promise<Blob>;
|
|
43
43
|
/** An animated GIF; pass gifenc (`import * as gifenc from 'gifenc'`). */
|
|
@@ -47,18 +47,19 @@ export function encodeGif(frames: Iterable<HTMLCanvasElement | OffscreenCanvas |
|
|
|
47
47
|
delay?: number;
|
|
48
48
|
/** 0: loop for ever (the default); -1: play once. */
|
|
49
49
|
repeat?: number;
|
|
50
|
-
|
|
50
|
+
/** Colors per frame's palette (256). */
|
|
51
|
+
colors?: number;
|
|
51
52
|
}): Promise<Blob>;
|
|
52
53
|
/** The RGBA bytes of a 2D canvas or a picture. */
|
|
53
54
|
export function pictureData(what: HTMLCanvasElement | OffscreenCanvas | Picture): Picture8 | ImageData;
|
|
54
|
-
/** The PNG writer: indexed when few
|
|
55
|
+
/** The PNG writer: indexed when few colors, RGB when opaque; null without CompressionStream. */
|
|
55
56
|
export function encodePng(options: {
|
|
56
57
|
width: number;
|
|
57
58
|
height: number;
|
|
58
59
|
data: Uint8ClampedArray | Uint8Array;
|
|
59
60
|
palette?: 'auto' | 'none' | 'force';
|
|
60
|
-
|
|
61
|
+
colors?: number;
|
|
61
62
|
dither?: boolean;
|
|
62
|
-
/** Needed for palette 'force' on a picture with more than `
|
|
63
|
-
quantize?: (data: Uint8ClampedArray | Uint8Array,
|
|
64
|
-
}): Promise<{ blob: Blob; kind: 'palette' | 'rgb' | 'rgba';
|
|
63
|
+
/** Needed for palette 'force' on a picture with more than `colors` colors. */
|
|
64
|
+
quantize?: (data: Uint8ClampedArray | Uint8Array, colors: number, options: { dither: boolean; width: number }) => { palette: number[][]; indices: Uint8Array };
|
|
65
|
+
}): Promise<{ blob: Blob; kind: 'palette' | 'rgb' | 'rgba'; colors: number; bits: number } | null>;
|
package/src/cpu-helpers.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* What the generated CPU filter code calls: sampling the picture the way a
|
|
3
|
-
* WebGL texture does, and the
|
|
3
|
+
* WebGL texture does, and the neighborhood functions as whole planes.
|
|
4
4
|
*
|
|
5
5
|
* Pictures are { data: Float32Array RGBA 0–1, width, height }, rows top
|
|
6
|
-
* down. Positions are pixel
|
|
6
|
+
* down. Positions are pixel centers in that frame: (px, py) is pixel px of
|
|
7
7
|
* row py, so sampling there returns that pixel exactly and a fractional
|
|
8
8
|
* position blends the four around it (bilinear, edges clamped) — what
|
|
9
9
|
* texture2D does with LINEAR filtering and CLAMP_TO_EDGE.
|
|
@@ -21,7 +21,7 @@ const PLACE = { cover: 0, fit: 1, stretch: 2, tile: 3 };
|
|
|
21
21
|
export function placeCode(place) { return PLACE[place ?? 'cover'] ?? 0; }
|
|
22
22
|
|
|
23
23
|
export function scratch() { return new Float64Array(4); }
|
|
24
|
-
/** P[i][k], for
|
|
24
|
+
/** P[i][k], for color params (the generated code may not index twice). */
|
|
25
25
|
export function at(P, i, k) { return Number(P[i][k]); }
|
|
26
26
|
|
|
27
27
|
export function fmod(a, b) { return a - b * Math.floor(a / b); }
|
|
@@ -42,7 +42,7 @@ export function random(px, py, h, seed) {
|
|
|
42
42
|
|
|
43
43
|
const clampi = (v, max) => (v < 0 ? 0 : v > max ? max : v);
|
|
44
44
|
|
|
45
|
-
/** Bilinear sample of picture data at pixel-
|
|
45
|
+
/** Bilinear sample of picture data at pixel-center position (X, Y), edges clamped, into out[0..3]. */
|
|
46
46
|
export function sample(D, w, h, X, Y, out) {
|
|
47
47
|
const x0f = Math.floor(X);
|
|
48
48
|
const y0f = Math.floor(Y);
|
|
@@ -69,7 +69,7 @@ export function sampleOrZero(D, w, h, X, Y, out) {
|
|
|
69
69
|
|
|
70
70
|
/**
|
|
71
71
|
* A named picture laid over the frame (the shader's mz_sample_<name>): scaled by `place`
|
|
72
|
-
* (0 cover, 1 fit, 2 stretch, 3 tile) times zoom,
|
|
72
|
+
* (0 cover, 1 fit, 2 stretch, 3 tile) times zoom, centered at (x, y) of the frame, turned by
|
|
73
73
|
* angle; transparent outside unless tiled.
|
|
74
74
|
*/
|
|
75
75
|
export function picture(Q, qw, qh, w, h, zoom, x, y, angle, mode, X, Y, out) {
|
|
@@ -91,7 +91,7 @@ export function picture(Q, qw, qh, w, h, zoom, x, y, angle, mode, X, Y, out) {
|
|
|
91
91
|
return sample(Q, qw, qh, qx - 0.5, qy - 0.5, out);
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
-
// ----
|
|
94
|
+
// ---- neighborhoods: whole planes, computed once per pass ------------------------------
|
|
95
95
|
//
|
|
96
96
|
// Taps are whole-pixel offsets, edges clamped; dy runs downwards. Square windows are done as a
|
|
97
97
|
// horizontal pass then a vertical one — the same sums, maxima and weights as the shader's
|
|
@@ -341,7 +341,7 @@ export function convolve(I, w, h, px, py, k00, k01, k02, k10, k11, k12, k20, k21
|
|
|
341
341
|
return out;
|
|
342
342
|
}
|
|
343
343
|
|
|
344
|
-
// ----
|
|
344
|
+
// ---- color spaces: the shader's to<space> / from<space> (mathzetta render/glsl.js colorGlsl), sRGB on the other side ----
|
|
345
345
|
const toLin = (c) => (c < 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
|
|
346
346
|
const fromLin = (c) => { c = Math.max(c, 0); return c < 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055; };
|
|
347
347
|
const hue = (r, g, b, v, d) => { const h = v === r ? (g - b) / d : v === g ? 2 + (b - r) / d : 4 + (r - g) / d; return h / 6 - Math.floor(h / 6); };
|
package/src/cpu-runner.js
CHANGED
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
29
|
import { compileCpuPass } from './cpu.js';
|
|
30
|
+
import { deriveAway } from './distance.js';
|
|
30
31
|
|
|
31
32
|
export function createCpuRunner(compiled, options = {}) {
|
|
32
33
|
const precision = options.precision === 'float' || options.precision === 'half' ? 'float' : 'byte';
|
|
@@ -47,6 +48,7 @@ export function createCpuRunner(compiled, options = {}) {
|
|
|
47
48
|
|
|
48
49
|
setImage(name, image) {
|
|
49
50
|
if (typeof name !== 'string') { image = name; name = null; }
|
|
51
|
+
if (name && name !== 'source' && image == null) { delete pictures[name]; return runner; } // back to "not given" (white)
|
|
50
52
|
const picture = toPicture(image);
|
|
51
53
|
if (!name || name === 'source') source = picture;
|
|
52
54
|
else pictures[name] = picture;
|
|
@@ -158,7 +160,7 @@ export function createCpuRunner(compiled, options = {}) {
|
|
|
158
160
|
sent = new Map();
|
|
159
161
|
},
|
|
160
162
|
};
|
|
161
|
-
return runner;
|
|
163
|
+
return deriveAway(runner, compiled);
|
|
162
164
|
}
|
|
163
165
|
|
|
164
166
|
/** Clamp to 0–1 and round to 1/255: what an 8-bit texture keeps. */
|