@mathzetta/qblur 0.0.0-stage → 0.1.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.
@@ -0,0 +1,604 @@
1
+ # qblur on your own pages
2
+
3
+ qblur is the library behind [the editor](https://qblur.com/): image filters written as maths, compiled to
4
+ WebGL shaders, with the same pixels from plain JavaScript where there is no GPU. Put it on any page
5
+ with one `<script>` from a CDN — no build step, no server, nothing uploaded: the pictures stay in the
6
+ visitor's browser.
7
+
8
+ > **Not on npm yet.** The CDN addresses below (`cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/…`) are where every
9
+ > release will be, and start working with the first one. Until then, `npm run build` in the repository
10
+ > writes the same files to `dist/`: serve them yourself and change the address.
11
+
12
+ ## What you can do with it
13
+
14
+ - **Filters on your pictures, live.** Any `<img>`, `<canvas>`, `<video>` or webcam — sepia, blur,
15
+ comic, tilt-shift, a colour splash, or one of your own in a line of maths: `1 - rgb`,
16
+ `if gray > 0.5 then (1, 0, 0) else rgb`, `mix(rgb, gaussian(4), y)`.
17
+ - **Knobs.** A filter declares its parameters (`strength`, `tint`, …) with ranges; your sliders set them
18
+ and the picture redraws at once, without recompiling.
19
+ - **79 ready-made filters** in `LIBRARY`, in seven groups (colour and tone, blur and edges, shape and
20
+ motion, text, brushes, other pictures, chains) — use them as they are, chain them, or read their maths.
21
+ - **Chains.** Filters run one after another, each with its own settings and opacity; a chain is a filter
22
+ too, so published chains nest and keep their authors' names.
23
+ - **Animation.** `t` counts frames: `pixel(px + 8 sin(py / 10 + t / 5), py)` is a wave. On a video, the
24
+ filter runs on every frame.
25
+ - **Several pictures.** Masks, overlays, a second photo to blend in, a background for a green screen —
26
+ each placed (cover, fit, tile, zoomed, turned) and set by name.
27
+ - **Text and shapes** drawn into the picture and coloured, shadowed, frosted or animated by the maths.
28
+ - **Share a filter as a link** or a small JSON document; reading one is safe — a filter is only maths:
29
+ it can read the picture and write colours, nothing else.
30
+ - **Save the result** as PNG (in Node too), JPEG, WebP or an animated GIF.
31
+ - **GPU or CPU, the same pixels.** WebGL when it is there (fast: the shaders are compiled once), plain
32
+ JavaScript when it isn't — old browsers, locked-down machines, **Node** (thumbnails on a server, tests).
33
+
34
+ Some things people build with it: filters on upload in a photo or social app; effects on a `<video>` or a
35
+ webcam stream; a product page that recolours an item as the customer picks; generative art and
36
+ animated backgrounds; previews in a CMS; high-contrast or colour-blindness views for accessibility; a
37
+ lesson on how pictures are just numbers. The [small apps](https://qblur.com/avatar/) on qblur.com —
38
+ profile picture, colour splash, make it move, fancy text — are each a page of this library and a few
39
+ controls.
40
+
41
+ ## Start here
42
+
43
+ ### One line: applyFilter
44
+
45
+ ```html runnable
46
+ <img id="photo" src="photo.jpg" alt="" hidden>
47
+ <canvas id="out"></canvas>
48
+ <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.global.min.js"></script>
49
+ <script>
50
+ const img = document.getElementById('photo');
51
+ img.decode().then(() => QBlur.applyFilter(img, 'Sepia', { canvas: document.getElementById('out') }));
52
+ </script>
53
+ ```
54
+
55
+ `applyFilter(picture, filter, options)` takes the filter in any form — maths (`'1 - rgb'`), a built-in
56
+ filter's name (`'Sepia'`, `'Gaussian blur'`), a filter document, JSON, a share link or a compiled filter —
57
+ and resolves with the result at the picture's size: a 2D canvas (yours, given as `canvas`, or a new one) in a
58
+ page, `{ data, width, height }` in Node. A picture longer than 4096 px on its long side (2048 on the CPU) is
59
+ scaled down to that first, keeping its shape — `maxSize` sets the limit, up to what the GPU can hold. Knobs go in `params` (in a chain, every step with a knob of that
60
+ name takes it), the frame in `t`. Calls run one at a time, in the order they were made:
61
+
62
+ ```js
63
+ import { applyFilter, toBlob } from '@mathzetta/qblur/apply'; // its own entry; the classic scripts have it on window.QBlur
64
+
65
+ const canvas = await applyFilter(img, 'Threshold', { params: { cutoff: 0.3 } });
66
+ const frame = await applyFilter(video, 'pixel(px + 8 sin(py / 10 + t / 5), py)', { t: 12 });
67
+ ```
68
+
69
+ It uses the GPU when WebGL is there and the CPU when it isn't (`engine: 'gpu' | 'cpu'` to choose), keeps
70
+ one hidden WebGL canvas for every call, and compiles a filter once for all the calls that use it. For a
71
+ picture that redraws many times a second as a knob moves, a runner of your own (below) skips the copy.
72
+
73
+ ### As an HTML element
74
+
75
+ ```html runnable
76
+ <qblur-image id="out" src="photo.jpg" filter="Vignette" params='{"strength": 2.5}' alt="A street of coloured houses"></qblur-image>
77
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur-element.js"></script>
78
+ ```
79
+
80
+ `<qblur-image>` draws its picture with the filter on it, and again whenever an attribute changes:
81
+ `src`, `filter` (any form `applyFilter` takes), `params` (JSON, or set the `params` property to an object: whichever was set last counts),
82
+ `t`, `animate` (present: `t` counts up, 30 a second, while the element is in view), `engine`, `alt` and `crossorigin` (as on `<img>`: a
83
+ picture from another site must allow CORS). It fires `load` after each drawing and `error` (the Error in
84
+ `event.detail`) when the picture or the filter fails; `element.canvas` is the drawing, for
85
+ [saving](#saving-the-result). From npm: `import '@mathzetta/qblur/element'`.
86
+
87
+ ### One script tag, a runner of your own
88
+
89
+ ```html runnable
90
+ <img id="photo" src="photo.jpg" alt="">
91
+ <canvas id="out"></canvas>
92
+ <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.global.min.js"></script>
93
+ <script>
94
+ const img = document.getElementById('photo'), canvas = document.getElementById('out');
95
+ img.decode().then(() => {
96
+ canvas.width = img.naturalWidth; // the result is the canvas's size: make it the picture's
97
+ canvas.height = img.naturalHeight;
98
+ const compiled = QBlur.compileFilter('1 - rgb'); // a filter: here, one line of maths
99
+ const { runner } = QBlur.createRunner(compiled, { gl: canvas.getContext('webgl') });
100
+ runner.setImage(img).draw({ canvas }); // the GPU draws on gl's canvas; without WebGL, the CPU draws on `canvas`
101
+ });
102
+ </script>
103
+ ```
104
+
105
+ The classic build puts everything on `window.QBlur`. `createRunner` picks the GPU when the canvas gives
106
+ a WebGL context and the CPU when it doesn't; pass the same canvas to `draw` either way.
107
+
108
+ ### An ES module, a library filter and a slider
109
+
110
+ ```html runnable
111
+ <canvas id="out"></canvas>
112
+ <label>Vignette <input id="strength" type="range" min="0" max="4" step="0.01" value="1.6"></label>
113
+ <script type="module">
114
+ import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
115
+
116
+ const img = new Image();
117
+ img.src = 'photo.jpg';
118
+ await img.decode();
119
+ const canvas = document.getElementById('out');
120
+ canvas.width = img.naturalWidth;
121
+ canvas.height = img.naturalHeight;
122
+
123
+ const byName = (name) => LIBRARY.find((f) => f.name === name);
124
+ const compiled = compileFilter({ steps: [byName('Sepia'), byName('Vignette')] }); // a chain of two
125
+ const { runner } = createRunner(compiled, { gl: canvas.getContext('webgl') });
126
+ runner.setImage(img).draw({ canvas });
127
+
128
+ // knobs change live: set the value on every pass that has it, and draw again (no recompiling)
129
+ document.getElementById('strength').oninput = (e) => {
130
+ for (const pass of runner.passes) if ('strength' in pass.params) pass.values.strength = Number(e.target.value);
131
+ runner.draw({ canvas });
132
+ };
133
+ </script>
134
+ ```
135
+
136
+ ### From npm
137
+
138
+ ```bash
139
+ npm install @mathzetta/qblur mathzetta # mathzetta is a peer dependency: qblur uses its maths parser and GLSL output
140
+ ```
141
+
142
+ ```js
143
+ import { compileFilter, createRunner } from '@mathzetta/qblur'; // the filters, the runners, the library
144
+ import { applyFilter, toBlob } from '@mathzetta/qblur/apply'; // one call, and saving
145
+ import '@mathzetta/qblur/element'; // defines <qblur-image>
146
+ ```
147
+
148
+ A bundler (Vite, esbuild, webpack, rollup) handles the rest. TypeScript types come with the package (`src/index.d.ts`, `src/apply.d.ts`, `src/element.d.ts`). In Node the CPU runner works as it is (see
149
+ [In Node](#in-node)).
150
+
151
+ ### Which file
152
+
153
+ Every release has these in `dist/` (sizes compressed, as the CDN sends them):
154
+
155
+ | File | Size | What |
156
+ | --- | --- | --- |
157
+ | `qblur.js` | 54 KB | ES module, everything but `@mathzetta/qblur/apply`, MathZetta inside |
158
+ | `qblur.global.min.js` | 58 KB | a classic script: `window.QBlur`, everything — `applyFilter` and saving too |
159
+ | `qblur-apply.js` | 56 KB | ES module: `@mathzetta/qblur/apply` (`applyFilter`, `toBlob`, `encodeGif`…), MathZetta inside |
160
+ | `qblur.core.js` | 33 KB | compile and run on the GPU only: `compileFilter`, `createFilterRunner`, `readFilter`, `filterToLink`, `normalizeFilter` — no CPU runner, library, text or brushes |
161
+ | `qblur.external.js` | 26 KB | `qblur.js` with MathZetta left out: the page provides it (an import map) |
162
+ | `qblur.external.global.min.js` | 30 KB | `qblur.global.min.js` without MathZetta: reads `window.MathZetta`, so a MathZetta script goes first |
163
+ | `qblur-element.js` | 56 KB | `<qblur-image>`, with `applyFilter` and MathZetta inside |
164
+ | `cpu-worker.js` | 31 KB | the CPU runner's helper for big pictures (`drawAsync`), loaded only when used; it must sit beside the bundle (it does on the CDN) |
165
+
166
+ MathZetta is about half of a full build. A page that already uses MathZetta, or several libraries built on
167
+ it, loads it once and takes the `external` build. With modules, an import map points every MathZetta name
168
+ at one file:
169
+
170
+ ```html runnable
171
+ <canvas id="out"></canvas>
172
+ <script type="importmap">
173
+ { "imports": {
174
+ "mathzetta": "https://cdn.jsdelivr.net/npm/mathzetta@1/build/mathzetta.esm.min.js",
175
+ "mathzetta/glsl": "https://cdn.jsdelivr.net/npm/mathzetta@1/build/mathzetta.esm.min.js",
176
+ "mathzetta/formulas": "https://cdn.jsdelivr.net/npm/mathzetta@1/build/mathzetta.esm.min.js"
177
+ } }
178
+ </script>
179
+ <script type="module">
180
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.external.js';
181
+ const img = new Image();
182
+ img.src = 'photo.jpg';
183
+ await img.decode();
184
+ const canvas = document.getElementById('out');
185
+ canvas.width = img.naturalWidth;
186
+ canvas.height = img.naturalHeight;
187
+ const { runner } = createRunner(compileFilter('(gray, gray, gray)'), { gl: canvas.getContext('webgl') });
188
+ runner.setImage(img).draw({ canvas });
189
+ </script>
190
+ ```
191
+
192
+ With classic scripts: `<script src="…/mathzetta@1/build/mathzetta.glsl.min.js">` (the GLSL flavour, which
193
+ is what filters use) and then `…/qblur@0.1/dist/qblur.external.global.min.js`.
194
+
195
+ Pin a version (`@0.1` follows fixes, `@0.1.0` never changes) and, for a fixed version, add an `integrity`
196
+ hash so the browser checks the file. jsDelivr shows each file's hash on its package page, or make it
197
+ yourself: `curl -s https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1.0/dist/qblur.js | openssl dgst -sha384 -binary | openssl base64 -A`
198
+ gives the part after `sha384-`.
199
+
200
+ ## Filters
201
+
202
+ A filter is maths run on every pixel. The [guide](filters.md) is the full language — what an expression
203
+ can use, animation, neighbouring pixels, geometry, several pictures, colour spaces, text and brushes. In
204
+ 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
205
+ picture's size, `t` the frame, `gray` its brightness, `source` the original picture, and
206
+ `pixel(px, py)` reads another pixel. The result is a colour `(r, g, b)` or a number (grey).
207
+
208
+ What you pass to `compileFilter`:
209
+
210
+ ```js
211
+ compileFilter('1 - rgb'); // an expression
212
+ compileFilter({ // a filter document
213
+ name: 'Threshold', author: 'Ada', description: 'Black or white',
214
+ params: { cutoff: { default: 0.5, min: 0, max: 1 } }, // a knob
215
+ color: 'if gray > cutoff then 1 else 0',
216
+ });
217
+ compileFilter({ // a chain: steps run top to bottom
218
+ name: 'Old photo',
219
+ steps: [
220
+ LIBRARY.find((f) => f.name === 'Sepia'), // a filter as it is
221
+ { filter: LIBRARY.find((f) => f.name === 'Vignette'), with: { strength: 1.2 } }, // with its knob set
222
+ { filter: 'rgb * 1.1', opacity: 0.5 }, // half strength
223
+ { filter: 'gaussian(2)', skip: true }, // left out for now
224
+ ],
225
+ });
226
+ ```
227
+
228
+ The fields of a filter document:
229
+
230
+ | Field | What |
231
+ | --- | --- |
232
+ | `format` | `"mathzetta-filter/1"` — optional when writing one; `filterToJSON` adds it. The format is frozen: later versions add, never change |
233
+ | `name`, `author`, `description` | shown in credits and the editor's library |
234
+ | `params` | knobs: `{ name: { default, min, max, step?, label? } }`; a colour is `[r, g, b]` (0–1) or `{ type: 'color', default: [r, g, b] }`; a bare number is a default |
235
+ | `color` | the maths: a string, or by channel — `{ rgb: '…', a: '…' }`, `{ r, g, b, a }`, `{ rgba: '…' }` |
236
+ | `space` | the colour space the maths works in: `'hsv'`, `'hsl'`, `'lab'`, `'oklab'`, `'linear'`, `'ycbcr'`, or `{ in, out }` |
237
+ | `images` | other pictures it reads, by name: `{ mask: { description: 'light where the effect shows' } }` |
238
+ | `graphics` | text, rectangles, ovals or brush strokes drawn into pictures it reads ([Text and shapes](#text-and-shapes)) |
239
+ | `steps` | a chain instead of `color`: each step a filter (or an expression), with `with`, `opacity` and `skip` |
240
+
241
+ ## Running a filter
242
+
243
+ ### compileFilter
244
+
245
+ ```js
246
+ const compiled = compileFilter(def, { version: 100 }); // 100: WebGL 1 (the default); 300: WebGL 2
247
+ compiled.passes; // one shader pass per filter in the chain, in order; each has params, values, images, placements
248
+ compiled.images; // every picture it needs, by name
249
+ compiled.graphics; // every graphic, by name
250
+ compiled.credits; // [{ name: 'Sepia', author: '' }, …] — the filters it is made of
251
+ ```
252
+
253
+ It throws when the filter is malformed or its maths doesn't parse:
254
+ `the filter: Failed to parse expression "rgb * (1, 2": …`. A name the maths doesn't know (`rgb * nope`) is
255
+ found when a runner is made: `unknown name "nope"`. `validateFilter(def)` lists every problem with the
256
+ document itself, as messages naming the filter (`"Vignette": "with" sets "nope", but there is no parameter
257
+ called that`), without throwing.
258
+
259
+ ### createRunner: the GPU, or the CPU
260
+
261
+ ```js
262
+ const { runner, engine, reason } = createRunner(compiled, {
263
+ gl: canvas.getContext('webgl'), // null or missing: the CPU
264
+ prefer: 'auto', // 'gpu' or 'cpu' to insist
265
+ precision: 'byte', // 'half' or 'float' keeps values over 1 between passes (bloom, edges)
266
+ });
267
+ engine; // 'gpu' or 'cpu'
268
+ reason; // why: 'WebGL is here', 'no WebGL here', 'the GPU refused the shader (…)', 'asked for the CPU'
269
+ ```
270
+
271
+ Both runners have the same methods:
272
+
273
+ | | |
274
+ | --- | --- |
275
+ | `runner.setImage(picture)` | the picture to filter: `<img>`, `<canvas>`, `<video>`, `ImageData`, `ImageBitmap`, or `{ data, width, height }`. Call it again for each new picture or video frame. Returns the runner |
276
+ | `runner.setImage(name, picture)` | another picture the filter names (`compiled.images`, graphics) |
277
+ | `runner.draw({ t, canvas })` | runs every pass. The GPU draws on the canvas `gl` belongs to; the CPU draws on `canvas` when given, and returns `{ data, width, height }` (RGBA bytes) |
278
+ | `runner.passes` | `compiled.passes`, live: `passes[i].values.cutoff = 0.3`, then `draw()` |
279
+ | `runner.dispose()` | frees the textures and programs (or the CPU's workers) |
280
+
281
+ The output is the canvas's size (GPU) or the picture's size (CPU), and the picture is stretched to it — so
282
+ **size the canvas to the picture**, or to the size you want to save.
283
+
284
+ ### On the GPU: createFilterRunner
285
+
286
+ ```js
287
+ const gl = canvas.getContext('webgl', { preserveDrawingBuffer: true, premultipliedAlpha: false });
288
+ const runner = createFilterRunner(gl, compiled, { precision: 'half' });
289
+ runner.precision; // what the GPU gave: 'byte', 'half' or 'float'
290
+ ```
291
+
292
+ - `preserveDrawingBuffer: true` keeps the result on the canvas after the frame, so `canvas.toBlob()` can save
293
+ it later (otherwise call it straight after `draw()`).
294
+ - `premultipliedAlpha: false` keeps transparent results (`a` below 1) as they are.
295
+ - WebGL 2: `canvas.getContext('webgl2')` and `compileFilter(def, { version: 300 })`.
296
+ - The browser can take the context away (a GPU reset, a sleeping laptop): listen for `webglcontextlost`
297
+ (call `preventDefault()`), and on `webglcontextrestored` make a new runner.
298
+ - Pictures from another site need `img.crossOrigin = 'anonymous'` **and** that site's CORS header, or WebGL
299
+ refuses them (the same rule as reading a canvas's pixels).
300
+
301
+ ### On the CPU: createCpuRunner
302
+
303
+ ```js
304
+ const runner = createCpuRunner(compiled, { precision: 'byte', workers: 'auto', parallelFrom: 250000 });
305
+ const out = runner.setImage(img).draw({ t: 0, canvas }); // on this thread
306
+ const out2 = await runner.drawAsync({ t: 0, canvas }); // big pictures: rows shared among workers
307
+ ```
308
+
309
+ `drawAsync` splits each pass's rows among workers (`cpu-worker.js` beside the bundle — on the CDN it is;
310
+ `workerUrl` puts it elsewhere) when the picture has at least `parallelFrom` pixels, and draws on the calling
311
+ thread when it doesn't or when workers can't start. Both give the same pixels, and the same as the GPU.
312
+
313
+ ### In Node
314
+
315
+ The CPU runner needs no browser:
316
+
317
+ ```js node
318
+ import { compileFilter, createCpuRunner, LIBRARY } from '@mathzetta/qblur';
319
+
320
+ // a 64 × 64 picture as RGBA bytes — in practice, decoded from a file (sharp, pngjs, …)
321
+ const width = 64, height = 64, data = new Uint8ClampedArray(width * height * 4);
322
+ for (let i = 0; i < width * height; i++) data.set([(i % width) * 4, 120, 200, 255], i * 4);
323
+
324
+ const sepia = LIBRARY.find((f) => f.name === 'Sepia');
325
+ const runner = createCpuRunner(compileFilter(sepia));
326
+ const out = runner.setImage({ data, width, height }).draw();
327
+ console.log(out.width, out.height, out.data.slice(0, 4)); // 64 64 Uint8ClampedArray [ … ]
328
+ ```
329
+
330
+ With [sharp](https://sharp.pixelplumbing.com/) for the files:
331
+
332
+ ```js
333
+ const { data, info } = await sharp('in.jpg').ensureAlpha().raw().toBuffer({ resolveWithObject: true });
334
+ const out = createCpuRunner(compileFilter('1 - rgb')).setImage({ data: new Uint8ClampedArray(data), width: info.width, height: info.height }).draw();
335
+ await sharp(Buffer.from(out.data), { raw: { width: out.width, height: out.height, channels: 4 } }).toFile('out.png');
336
+ ```
337
+
338
+ ## Knobs
339
+
340
+ `filterParams(normalizeFilter(def))` lists every knob a filter or chain has —
341
+ `{ strength: { type: 'number', default: 1.6, min: 0, max: 4 } }`, colours as `{ type: 'color', default: [r, g, b] }` —
342
+ so a page can build its controls from the filter:
343
+
344
+ ```html runnable
345
+ <canvas id="out"></canvas>
346
+ <form id="knobs"></form>
347
+ <script type="module">
348
+ import { compileFilter, createRunner, normalizeFilter, filterParams } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
349
+
350
+ const def = {
351
+ name: 'Duotone',
352
+ params: { dark: [0.1, 0.05, 0.3], light: [1, 0.8, 0.4], contrast: { default: 1, min: 0.5, max: 2, label: 'Contrast' } },
353
+ color: 'mix(dark, light, clamp((gray - 0.5) contrast + 0.5, 0, 1))',
354
+ };
355
+ const img = new Image();
356
+ img.src = 'photo.jpg';
357
+ await img.decode();
358
+ const canvas = document.getElementById('out');
359
+ canvas.width = img.naturalWidth;
360
+ canvas.height = img.naturalHeight;
361
+ const { runner } = createRunner(compileFilter(def), { gl: canvas.getContext('webgl') });
362
+ runner.setImage(img).draw({ canvas });
363
+
364
+ const set = (name, value) => {
365
+ for (const pass of runner.passes) if (name in pass.params) pass.values[name] = value;
366
+ runner.draw({ canvas });
367
+ };
368
+ const hex = (rgb) => '#' + rgb.map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('');
369
+ const rgb = (h) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
370
+ for (const [name, p] of Object.entries(filterParams(normalizeFilter(def)))) {
371
+ const input = document.createElement('input');
372
+ if (p.type === 'color') { input.type = 'color'; input.value = hex(p.default); input.oninput = () => set(name, rgb(input.value)); }
373
+ else Object.assign(input, { type: 'range', min: p.min, max: p.max, step: p.step ?? (p.max - p.min) / 200, value: p.default, oninput: () => set(name, Number(input.value)) });
374
+ const label = document.createElement('label');
375
+ label.append(p.label ?? name, ' ', input);
376
+ document.getElementById('knobs').append(label);
377
+ }
378
+ </script>
379
+ ```
380
+
381
+ In a chain, `filterParams` gives each knob's own default; the values a chain sets with `with` are in
382
+ `compiled.passes[i].values`.
383
+
384
+ ## Animation, video and the webcam
385
+
386
+ `t` is whatever you pass to `draw`. Count frames for an animation:
387
+
388
+ ```html runnable
389
+ <canvas id="out"></canvas>
390
+ <script type="module">
391
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
392
+ const img = new Image();
393
+ img.src = 'photo.jpg';
394
+ await img.decode();
395
+ const canvas = document.getElementById('out');
396
+ canvas.width = img.naturalWidth;
397
+ canvas.height = img.naturalHeight;
398
+ const { runner } = createRunner(compileFilter('pixel(px + 6 sin(py / 12 + t / 5), py)'), { gl: canvas.getContext('webgl') });
399
+ runner.setImage(img); // a still picture: set it once
400
+ let t = 0;
401
+ (function frame() { runner.draw({ t: t++, canvas }); requestAnimationFrame(frame); })();
402
+ </script>
403
+ ```
404
+
405
+ A video is a picture that changes: give the runner each frame.
406
+
407
+ ```html runnable
408
+ <video id="clip" src="clip.mp4" muted loop playsinline autoplay hidden></video>
409
+ <canvas id="out"></canvas>
410
+ <script type="module">
411
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
412
+ const video = document.getElementById('clip'), canvas = document.getElementById('out');
413
+ await new Promise((r) => { video.onloadeddata = r; if (video.readyState >= 2) r(); });
414
+ canvas.width = video.videoWidth;
415
+ canvas.height = video.videoHeight;
416
+ const { runner } = createRunner(compileFilter('(red(px + 6, py), g, blue(px - 6, py))'), { gl: canvas.getContext('webgl') });
417
+ let t = 0;
418
+ const frame = () => {
419
+ runner.setImage(video).draw({ t: t++, canvas });
420
+ video.requestVideoFrameCallback ? video.requestVideoFrameCallback(frame) : requestAnimationFrame(frame);
421
+ };
422
+ frame();
423
+ </script>
424
+ ```
425
+
426
+ The webcam is the same with `video.srcObject = await navigator.mediaDevices.getUserMedia({ video: true })`.
427
+ To save what is shown as a video: `new MediaRecorder(canvas.captureStream(30))`.
428
+
429
+ ## Other pictures: masks, overlays, backgrounds
430
+
431
+ A filter names the pictures it reads in `images`; the maths uses them by name — `mask` is its colour at
432
+ this pixel, `luma(mask)` its brightness, `alpha(mask)` its transparency — and you give them with
433
+ `setImage(name, picture)`. A picture not given is white.
434
+
435
+ ```html runnable
436
+ <canvas id="out"></canvas>
437
+ <script type="module">
438
+ import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
439
+ const img = new Image();
440
+ img.src = 'photo.jpg';
441
+ await img.decode();
442
+ const canvas = document.getElementById('out');
443
+ canvas.width = img.naturalWidth;
444
+ canvas.height = img.naturalHeight;
445
+
446
+ // a spotlight mask: light in the middle, dark at the edges
447
+ const mask = Object.assign(document.createElement('canvas'), { width: 256, height: 256 });
448
+ const g = mask.getContext('2d'), grad = g.createRadialGradient(128, 128, 20, 128, 128, 128);
449
+ grad.addColorStop(0, '#fff'); grad.addColorStop(1, '#000');
450
+ g.fillStyle = grad; g.fillRect(0, 0, 256, 256);
451
+
452
+ // grey everywhere, colour where the mask is light ("Through a mask" is mix(source, rgb, luma(mask)))
453
+ const byName = (name) => LIBRARY.find((f) => f.name === name);
454
+ const { runner } = createRunner(compileFilter({ steps: [byName('Grayscale'), byName('Through a mask')] }), { gl: canvas.getContext('webgl') });
455
+ runner.setImage(img).setImage('mask', mask).draw({ canvas });
456
+ </script>
457
+ ```
458
+
459
+ A picture of another shape is placed over the frame: `cover` (the default), `fit`, `stretch` or `tile`,
460
+ with `zoom`, `x`, `y` and `angle` — set per step (`{ filter, with: { overlay: { place: 'fit', zoom: 0.5 } } }`)
461
+ or live (`runner.passes[i].placements.overlay.x = 0.2`; changing `place` needs a new compile).
462
+ `selected` is the picture named `selection` (the editor's selection): give it a mask to limit a filter to
463
+ part of the picture.
464
+
465
+ ## Text and shapes
466
+
467
+ A filter's `graphics` are drawn into pictures of the frame's size, which the maths reads like any other
468
+ picture. `renderGraphics` draws them (loading web fonts first); positions and sizes are fractions of the
469
+ frame, so they are crisp at any size.
470
+
471
+ ```html runnable
472
+ <canvas id="out"></canvas>
473
+ <script type="module">
474
+ import { compileFilter, createRunner, renderGraphics } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
475
+ const img = new Image();
476
+ img.src = 'photo.jpg';
477
+ await img.decode();
478
+ const canvas = document.getElementById('out');
479
+ canvas.width = img.naturalWidth;
480
+ canvas.height = img.naturalHeight;
481
+
482
+ const compiled = compileFilter({
483
+ graphics: { title: { type: 'text', text: 'Hello!', size: 0.16, y: 0.5, color: '#ffd23f' } },
484
+ color: 'mix(rgb * 0.6, title, alpha(title))', // the picture darkened, the words laid on it
485
+ });
486
+ const { runner } = createRunner(compiled, { gl: canvas.getContext('webgl') });
487
+ runner.setImage(img);
488
+ for (const [key, picture] of Object.entries(await renderGraphics(compiled, canvas.width, canvas.height))) runner.setImage(key, picture);
489
+ runner.draw({ canvas });
490
+ </script>
491
+ ```
492
+
493
+ Text has `text`, `font` (a CSS family, or `fontUrl` for a web font), `weight`, `style`, `size`, `x`, `y`,
494
+ `align`, `angle`, `color`, `outline` and shadows; `rect` and `ellipse` have `x`, `y` (the centre), `w`, `h`,
495
+ `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
496
+ for each frame with `renderGraphics(compiled, w, h, { t })` or `rasterizeStrokes`. The guide's
497
+ "Text and shapes" and "Brushes" have every field.
498
+
499
+ ## Saving the result
500
+
501
+ ```js
502
+ const png = await toBlob(canvas); // a PNG: indexed when there are ≤ 256 colours, RGB when opaque
503
+ const jpeg = await toBlob(canvas, { type: 'image/jpeg', quality: 0.9 }); // JPEG and WebP: the browser's encoder
504
+ const { data, width, height } = cpuRunner.draw(); // CPU: the bytes themselves
505
+ ```
506
+
507
+ `toBlob` takes a 2D canvas (what `applyFilter` returns) or a picture `{ data, width, height }`, and writes
508
+ PNG itself, so it works in Node as well; JPEG and WebP need a browser. A WebGL canvas can't be read back
509
+ with a 2D context: pass the canvas `applyFilter` gave you, or call the canvas's own `toBlob` right after
510
+ `draw()` (or create the context with `preserveDrawingBuffer: true`).
511
+
512
+ An animated GIF needs a colour quantizer and an LZW encoder. The package has no dependencies, so bring
513
+ [gifenc](https://www.npmjs.com/package/gifenc) (`npm i gifenc`, 9 KB) and pass it in:
514
+
515
+ ```js node
516
+ import * as gifenc from 'gifenc';
517
+ import { applyFilter, encodeGif, toBlob } from '@mathzetta/qblur/apply';
518
+
519
+ const picture = { width: 64, height: 48, data: new Uint8ClampedArray(64 * 48 * 4).fill(200) };
520
+ const frames = [];
521
+ for (let t = 0; t < 10; t++) frames.push(await applyFilter(picture, '(x, y, 0.5 + 0.5 sin(t / 2))', { t }));
522
+ const gif = await encodeGif(frames, { gifenc, delay: 50 }); // 50 ms a frame, looping
523
+ const png = await toBlob(frames[0]); // PNG in Node: no canvas needed
524
+ console.log(gif.type, gif.size, png.type);
525
+ ```
526
+
527
+ Frames can be canvases or pictures, all one size, in an array or an async iterable (each frame drawn as it
528
+ is needed); `repeat: -1` plays once. To save at a different size than you show, draw into a second canvas
529
+ of that size, or with the CPU runner on a picture of that size.
530
+
531
+ ## Sharing filters
532
+
533
+ ```js
534
+ const link = filterToLink(def, 'https://qblur.com/'); // https://qblur.com/#eyJmb3Jt… — opens in the editor
535
+ const json = filterToJSON(def); // the document, defaults left out
536
+ readFilter(text); // whatever was pasted: a link, JSON, or an expression
537
+ filterFromLink(location.hash); // a filter from your own page's address
538
+ validateFilter(readFilter(text)); // [] when it is fine
539
+ ```
540
+
541
+ A filter from someone else is safe to run: it is maths over the picture, compiled by qblur into shaders (or
542
+ checked JavaScript on the CPU), with no access to the page, the network or anything else. One thing does reach
543
+ the network: a filter with text may name a font (a Google Fonts family or an https address), which the page
544
+ then fetches to draw it — so whoever serves that font sees the request.
545
+
546
+ ## The built-in library
547
+
548
+ `LIBRARY` is an array of filter documents (79), each with a `group` from `GROUPS`:
549
+
550
+ ```js
551
+ GROUPS; // ['Colour & tone', 'Blur & edges', 'Shape & motion', 'Text & shapes', 'Brushes', 'Other pictures', 'Chains']
552
+ LIBRARY.filter((f) => f.group === 'Blur & edges').map((f) => f.name);
553
+ const comic = LIBRARY.find((f) => f.name === 'Comic'); // a chain of four
554
+ ```
555
+
556
+ The editor's [library](https://qblur.com/) shows them all on your own photo, with their maths.
557
+
558
+ ## Reference
559
+
560
+ Everything the package exports — from `@mathzetta/qblur/apply`, the first seven; from `@mathzetta/qblur/element`, `QBlurImage`; from
561
+ `@mathzetta/qblur`, the rest:
562
+
563
+ | Export | What |
564
+ | --- | --- |
565
+ | `applyFilter(picture, filter, { params, t, images, engine, canvas, maxSize })` | the one call: the filtered picture (a 2D canvas, or `{ data, width, height }` in Node), at most `maxSize` on its long side; the filter in any form, or a `LIBRARY` name |
566
+ | `MAX_SIZE`, `MAX_SIZE_CPU` | the default `maxSize`: 4096 on the GPU, 2048 on the CPU |
567
+ | `toCompiled(filter)` | any form `applyFilter` takes → the compiled filter |
568
+ | `toBlob(canvasOrPicture, { type, quality, palette })` | the result as a file: PNG anywhere, JPEG and WebP in a browser |
569
+ | `encodeGif(frames, { gifenc, delay, repeat, colours })` | an animated GIF, with gifenc passed in |
570
+ | `encodePng({ width, height, data, palette, colours, quantize })` | the PNG writer `toBlob` uses (indexed, RGB or RGBA) |
571
+ | `pictureData(canvasOrPicture)` | its RGBA bytes |
572
+ | `QBlurImage` (from `@mathzetta/qblur/element`) | the `<qblur-image>` element's class; importing the entry defines the element |
573
+ | `compileFilter(def, { version })` | a filter (expression, document or chain) → `{ passes, images, graphics, credits, … }`; throws on a malformed filter or maths that doesn't parse |
574
+ | `createRunner(compiled, { gl, prefer, precision, workers })` | `{ runner, engine, reason }`: the GPU when `gl` is a WebGL context, else the CPU |
575
+ | `createFilterRunner(gl, compiled, { precision })` | the WebGL runner |
576
+ | `createCpuRunner(compiled, { precision, workers, parallelFrom, workerUrl })` | the JavaScript runner (browsers and Node); `draw()` and `drawAsync()` |
577
+ | `chooseEngine({ webgl, prefer })` | which runner `createRunner` would use, and why |
578
+ | `toPicture(image)` | any picture as `{ data: Float32Array, width, height }` (what the CPU works on) |
579
+ | `normalizeFilter(def)` | the full form: types and ranges on params, `with` and `opacity` on steps; throws on a bad shape |
580
+ | `validateFilter(def)` | every problem, as messages naming the filter; `[]` when it will compile |
581
+ | `filterParams(filter)` / `filterImages(filter)` / `filterGraphics(filter)` | a normalized filter's knobs, pictures, graphics (a chain's included) |
582
+ | `filterToJSON(def)` / `filterFromJSON(text)` | the document as JSON, and back |
583
+ | `filterToLink(def, pageUrl)` / `filterFromLink(text)` | the filter in a URL's `#…`, and back |
584
+ | `readFilter(text)` | a link, JSON or a bare expression → a filter |
585
+ | `FILTER_FORMAT`, `PLACEMENT` | `'mathzetta-filter/1'`; the default placement `{ place: 'cover', zoom: 1, x: 0.5, y: 0.5, angle: 0 }` |
586
+ | `LIBRARY`, `GROUPS` | the built-in filters and their groups |
587
+ | `renderGraphics(compiled, w, h, { t, mask })` | every graphic drawn at w × h → `{ key: picture }` for `setImage` |
588
+ | `normalizeGraphic`, `drawGraphic(ctx, spec, w, h)`, `loadGraphicFonts`, `cssFont`, `GRAPHIC_TYPES`, `GRAPHIC_DEFAULTS` | text and shapes, one at a time |
589
+ | `googleFontUrl(family)`, `googleFontFamily(url)`, `fontFileFromCss`, `familyFor` | web fonts for text graphics |
590
+ | `shadowLayerNames`, `layeredExpression`, `MAX_SHADOW_LAYERS` | text shadows as pictures of their own |
591
+ | `normalizeStrokes`, `strokeTimeline`, `rasterizeStrokes(spec, w, h, t, { mask })` | brush strokes, frame by frame |
592
+ | `BRUSHES`, `TIMINGS`, `WIDTH_FROM`, `CLIPS`, `FPS`, `STROKES_DEFAULTS` | brush options |
593
+ | `traceContours(mask, w, h)`, `simplify`, `simplifyLoop` | the outlines of a mask, as polylines |
594
+ | `compileCpuPass(pass)` | one pass as checked JavaScript (what the CPU runner runs; `.uses` says if it reads `t`, other pictures, `random`) |
595
+
596
+ ## Good to know
597
+
598
+ - **Sizes in pixels stay pixels.** `gaussian(4)` blurs 4 pixels whatever the picture's size, so effects look
599
+ finer on a bigger picture; scale such numbers with `w` or `h` (`gaussian(w / 200)`) to keep a look at any size.
600
+ - **Between passes the picture is 8-bit**, as an image is: values clamp to 0–1. `precision: 'half'` keeps
601
+ more where the effect needs it (bloom, edge strengths).
602
+ - **Big pictures.** WebGL limits a texture to `gl.getParameter(gl.MAX_TEXTURE_SIZE)` (often 4096 or more);
603
+ the CPU has no limit but takes longer — `drawAsync` uses every core.
604
+ - **Licence.** MIT. The object models used by the editor's "find objects" are not in the package.