@mathzetta/qblur 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/library.md CHANGED
@@ -1,41 +1,37 @@
1
1
  # qblur on your own pages
2
2
 
3
- qblur is the library behind [the editor](https://qblur.com/): image filters written as maths, compiled to
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.
7
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
8
  ## What you can do with it
13
9
 
14
10
  - **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`,
11
+ comic, tilt-shift, a color splash, or one of your own in a line of math: `1 - rgb`,
16
12
  `if gray > 0.5 then (1, 0, 0) else rgb`, `mix(rgb, gaussian(4), y)`.
17
13
  - **Knobs.** A filter declares its parameters (`strength`, `tint`, …) with ranges; your sliders set them
18
14
  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.
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.
21
17
  - **Chains.** Filters run one after another, each with its own settings and opacity; a chain is a filter
22
18
  too, so published chains nest and keep their authors' names.
23
19
  - **Animation.** `t` counts frames: `pixel(px + 8 sin(py / 10 + t / 5), py)` is a wave. On a video, the
24
20
  filter runs on every frame.
25
21
  - **Several pictures.** Masks, overlays, a second photo to blend in, a background for a green screen —
26
22
  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.
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.
30
26
  - **Save the result** as PNG (in Node too), JPEG, WebP or an animated GIF.
31
27
  - **GPU or CPU, the same pixels.** WebGL when it is there (fast: the shaders are compiled once), plain
32
28
  JavaScript when it isn't — old browsers, locked-down machines, **Node** (thumbnails on a server, tests).
33
29
 
34
30
  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
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
37
33
  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
34
+ profile picture, color splash, make it move, fancy text — are each a page of this library and a few
39
35
  controls.
40
36
 
41
37
  ## Start here
@@ -45,14 +41,14 @@ controls.
45
41
  ```html runnable
46
42
  <img id="photo" src="photo.jpg" alt="" hidden>
47
43
  <canvas id="out"></canvas>
48
- <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.global.min.js"></script>
44
+ <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.global.min.js"></script>
49
45
  <script>
50
46
  const img = document.getElementById('photo');
51
47
  img.decode().then(() => QBlur.applyFilter(img, 'Sepia', { canvas: document.getElementById('out') }));
52
48
  </script>
53
49
  ```
54
50
 
55
- `applyFilter(picture, filter, options)` takes the filter in any form — maths (`'1 - rgb'`), a built-in
51
+ `applyFilter(picture, filter, options)` takes the filter in any form — math (`'1 - rgb'`), a built-in
56
52
  filter's name (`'Sepia'`, `'Gaussian blur'`), a filter document, JSON, a share link or a compiled filter —
57
53
  and resolves with the result at the picture's size: a 2D canvas (yours, given as `canvas`, or a new one) in a
58
54
  page, `{ data, width, height }` in Node. A picture longer than 4096 px on its long side (2048 on the CPU) is
@@ -73,8 +69,8 @@ picture that redraws many times a second as a knob moves, a runner of your own (
73
69
  ### As an HTML element
74
70
 
75
71
  ```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>
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.2/dist/qblur-element.js"></script>
78
74
  ```
79
75
 
80
76
  `<qblur-image>` draws its picture with the filter on it, and again whenever an attribute changes:
@@ -89,13 +85,13 @@ picture from another site must allow CORS). It fires `load` after each drawing a
89
85
  ```html runnable
90
86
  <img id="photo" src="photo.jpg" alt="">
91
87
  <canvas id="out"></canvas>
92
- <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.global.min.js"></script>
88
+ <script src="https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.global.min.js"></script>
93
89
  <script>
94
90
  const img = document.getElementById('photo'), canvas = document.getElementById('out');
95
91
  img.decode().then(() => {
96
92
  canvas.width = img.naturalWidth; // the result is the canvas's size: make it the picture's
97
93
  canvas.height = img.naturalHeight;
98
- const compiled = QBlur.compileFilter('1 - rgb'); // a filter: here, one line of maths
94
+ const compiled = QBlur.compileFilter('1 - rgb'); // a filter: here, one line of math
99
95
  const { runner } = QBlur.createRunner(compiled, { gl: canvas.getContext('webgl') });
100
96
  runner.setImage(img).draw({ canvas }); // the GPU draws on gl's canvas; without WebGL, the CPU draws on `canvas`
101
97
  });
@@ -111,7 +107,7 @@ a WebGL context and the CPU when it doesn't; pass the same canvas to `draw` eith
111
107
  <canvas id="out"></canvas>
112
108
  <label>Vignette <input id="strength" type="range" min="0" max="4" step="0.01" value="1.6"></label>
113
109
  <script type="module">
114
- import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
110
+ import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
115
111
 
116
112
  const img = new Image();
117
113
  img.src = 'photo.jpg';
@@ -136,7 +132,7 @@ a WebGL context and the CPU when it doesn't; pass the same canvas to `draw` eith
136
132
  ### From npm
137
133
 
138
134
  ```bash
139
- npm install @mathzetta/qblur mathzetta # mathzetta is a peer dependency: qblur uses its maths parser and GLSL output
135
+ npm install @mathzetta/qblur mathzetta # mathzetta is a peer dependency: qblur uses its math parser and GLSL output
140
136
  ```
141
137
 
142
138
  ```js
@@ -177,7 +173,7 @@ at one file:
177
173
  } }
178
174
  </script>
179
175
  <script type="module">
180
- import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.external.js';
176
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.external.js';
181
177
  const img = new Image();
182
178
  img.src = 'photo.jpg';
183
179
  await img.decode();
@@ -189,21 +185,21 @@ at one file:
189
185
  </script>
190
186
  ```
191
187
 
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`.
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.2/dist/qblur.external.global.min.js`.
194
190
 
195
- Pin a version (`@0.1` follows fixes, `@0.1.0` never changes) and, for a fixed version, add an `integrity`
191
+ Pin a version (`@0.2` follows fixes, `@0.2.0` never changes) and, for a fixed version, add an `integrity`
196
192
  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`
193
+ yourself: `curl -s https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2.0/dist/qblur.js | openssl dgst -sha384 -binary | openssl base64 -A`
198
194
  gives the part after `sha384-`.
199
195
 
200
196
  ## Filters
201
197
 
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
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
204
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
205
201
  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).
202
+ `pixel(px, py)` reads another pixel. The result is a color `(r, g, b)` or a number (gray).
207
203
 
208
204
  What you pass to `compileFilter`:
209
205
 
@@ -231,9 +227,9 @@ The fields of a filter document:
231
227
  | --- | --- |
232
228
  | `format` | `"mathzetta-filter/1"` — optional when writing one; `filterToJSON` adds it. The format is frozen: later versions add, never change |
233
229
  | `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 }` |
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 }` |
237
233
  | `images` | other pictures it reads, by name: `{ mask: { description: 'light where the effect shows' } }` |
238
234
  | `graphics` | text, rectangles, ovals or brush strokes drawn into pictures it reads ([Text and shapes](#text-and-shapes)) |
239
235
  | `steps` | a chain instead of `color`: each step a filter (or an expression), with `with`, `opacity` and `skip` |
@@ -250,8 +246,8 @@ compiled.graphics; // every graphic, by name
250
246
  compiled.credits; // [{ name: 'Sepia', author: '' }, …] — the filters it is made of
251
247
  ```
252
248
 
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
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
255
251
  found when a runner is made: `unknown name "nope"`. `validateFilter(def)` lists every problem with the
256
252
  document itself, as messages naming the filter (`"Vignette": "with" sets "nope", but there is no parameter
257
253
  called that`), without throwing.
@@ -338,14 +334,14 @@ await sharp(Buffer.from(out.data), { raw: { width: out.width, height: out.height
338
334
  ## Knobs
339
335
 
340
336
  `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] }` —
337
+ `{ strength: { type: 'number', default: 1.6, min: 0, max: 4 } }`, colors as `{ type: 'color', default: [r, g, b] }` —
342
338
  so a page can build its controls from the filter:
343
339
 
344
340
  ```html runnable
345
341
  <canvas id="out"></canvas>
346
342
  <form id="knobs"></form>
347
343
  <script type="module">
348
- import { compileFilter, createRunner, normalizeFilter, filterParams } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
344
+ import { compileFilter, createRunner, normalizeFilter, filterParams } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
349
345
 
350
346
  const def = {
351
347
  name: 'Duotone',
@@ -388,7 +384,7 @@ In a chain, `filterParams` gives each knob's own default; the values a chain set
388
384
  ```html runnable
389
385
  <canvas id="out"></canvas>
390
386
  <script type="module">
391
- import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
387
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
392
388
  const img = new Image();
393
389
  img.src = 'photo.jpg';
394
390
  await img.decode();
@@ -408,7 +404,7 @@ A video is a picture that changes: give the runner each frame.
408
404
  <video id="clip" src="clip.mp4" muted loop playsinline autoplay hidden></video>
409
405
  <canvas id="out"></canvas>
410
406
  <script type="module">
411
- import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
407
+ import { compileFilter, createRunner } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
412
408
  const video = document.getElementById('clip'), canvas = document.getElementById('out');
413
409
  await new Promise((r) => { video.onloadeddata = r; if (video.readyState >= 2) r(); });
414
410
  canvas.width = video.videoWidth;
@@ -428,14 +424,14 @@ To save what is shown as a video: `new MediaRecorder(canvas.captureStream(30))`.
428
424
 
429
425
  ## Other pictures: masks, overlays, backgrounds
430
426
 
431
- A filter names the pictures it reads in `images`; the maths uses them by name — `mask` is its colour at
427
+ A filter names the pictures it reads in `images`; the math uses them by name — `mask` is its color at
432
428
  this pixel, `luma(mask)` its brightness, `alpha(mask)` its transparency — and you give them with
433
429
  `setImage(name, picture)`. A picture not given is white.
434
430
 
435
431
  ```html runnable
436
432
  <canvas id="out"></canvas>
437
433
  <script type="module">
438
- import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
434
+ import { compileFilter, createRunner, LIBRARY } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
439
435
  const img = new Image();
440
436
  img.src = 'photo.jpg';
441
437
  await img.decode();
@@ -449,7 +445,7 @@ this pixel, `luma(mask)` its brightness, `alpha(mask)` its transparency — and
449
445
  grad.addColorStop(0, '#fff'); grad.addColorStop(1, '#000');
450
446
  g.fillStyle = grad; g.fillRect(0, 0, 256, 256);
451
447
 
452
- // grey everywhere, colour where the mask is light ("Through a mask" is mix(source, rgb, luma(mask)))
448
+ // gray everywhere, color where the mask is light ("Through a mask" is mix(source, rgb, luma(mask)))
453
449
  const byName = (name) => LIBRARY.find((f) => f.name === name);
454
450
  const { runner } = createRunner(compileFilter({ steps: [byName('Grayscale'), byName('Through a mask')] }), { gl: canvas.getContext('webgl') });
455
451
  runner.setImage(img).setImage('mask', mask).draw({ canvas });
@@ -464,14 +460,14 @@ part of the picture.
464
460
 
465
461
  ## Text and shapes
466
462
 
467
- A filter's `graphics` are drawn into pictures of the frame's size, which the maths reads like any other
463
+ A filter's `graphics` are drawn into pictures of the frame's size, which the math reads like any other
468
464
  picture. `renderGraphics` draws them (loading web fonts first); positions and sizes are fractions of the
469
465
  frame, so they are crisp at any size.
470
466
 
471
467
  ```html runnable
472
468
  <canvas id="out"></canvas>
473
469
  <script type="module">
474
- import { compileFilter, createRunner, renderGraphics } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.1/dist/qblur.js';
470
+ import { compileFilter, createRunner, renderGraphics } from 'https://cdn.jsdelivr.net/npm/@mathzetta/qblur@0.2/dist/qblur.js';
475
471
  const img = new Image();
476
472
  img.src = 'photo.jpg';
477
473
  await img.decode();
@@ -491,7 +487,7 @@ frame, so they are crisp at any size.
491
487
  ```
492
488
 
493
489
  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`,
490
+ `align`, `angle`, `color`, `outline` and shadows; `rect` and `ellipse` have `x`, `y` (the center), `w`, `h`,
495
491
  `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
492
  for each frame with `renderGraphics(compiled, w, h, { t })` or `rasterizeStrokes`. The guide's
497
493
  "Text and shapes" and "Brushes" have every field.
@@ -499,7 +495,7 @@ for each frame with `renderGraphics(compiled, w, h, { t })` or `rasterizeStrokes
499
495
  ## Saving the result
500
496
 
501
497
  ```js
502
- const png = await toBlob(canvas); // a PNG: indexed when there are ≤ 256 colours, RGB when opaque
498
+ const png = await toBlob(canvas); // a PNG: indexed when there are ≤ 256 colors, RGB when opaque
503
499
  const jpeg = await toBlob(canvas, { type: 'image/jpeg', quality: 0.9 }); // JPEG and WebP: the browser's encoder
504
500
  const { data, width, height } = cpuRunner.draw(); // CPU: the bytes themselves
505
501
  ```
@@ -509,7 +505,7 @@ PNG itself, so it works in Node as well; JPEG and WebP need a browser. A WebGL c
509
505
  with a 2D context: pass the canvas `applyFilter` gave you, or call the canvas's own `toBlob` right after
510
506
  `draw()` (or create the context with `preserveDrawingBuffer: true`).
511
507
 
512
- An animated GIF needs a colour quantizer and an LZW encoder. The package has no dependencies, so bring
508
+ An animated GIF needs a color quantizer and an LZW encoder. The package has no dependencies, so bring
513
509
  [gifenc](https://www.npmjs.com/package/gifenc) (`npm i gifenc`, 9 KB) and pass it in:
514
510
 
515
511
  ```js node
@@ -531,14 +527,14 @@ of that size, or with the CPU runner on a picture of that size.
531
527
  ## Sharing filters
532
528
 
533
529
  ```js
534
- const link = filterToLink(def, 'https://qblur.com/'); // https://qblur.com/#eyJmb3Jt… — opens in the editor
530
+ const link = filterToLink(def, 'https://qblur.com/editor.html'); // https://qblur.com/editor.html#eyJmb3Jt… — opens in the editor
535
531
  const json = filterToJSON(def); // the document, defaults left out
536
532
  readFilter(text); // whatever was pasted: a link, JSON, or an expression
537
533
  filterFromLink(location.hash); // a filter from your own page's address
538
534
  validateFilter(readFilter(text)); // [] when it is fine
539
535
  ```
540
536
 
541
- A filter from someone else is safe to run: it is maths over the picture, compiled by qblur into shaders (or
537
+ A filter from someone else is safe to run: it is math over the picture, compiled by qblur into shaders (or
542
538
  checked JavaScript on the CPU), with no access to the page, the network or anything else. One thing does reach
543
539
  the network: a filter with text may name a font (a Google Fonts family or an https address), which the page
544
540
  then fetches to draw it — so whoever serves that font sees the request.
@@ -548,12 +544,12 @@ then fetches to draw it — so whoever serves that font sees the request.
548
544
  `LIBRARY` is an array of filter documents (79), each with a `group` from `GROUPS`:
549
545
 
550
546
  ```js
551
- GROUPS; // ['Colour & tone', 'Blur & edges', 'Shape & motion', 'Text & shapes', 'Brushes', 'Other pictures', 'Chains']
547
+ GROUPS; // ['Color & tone', 'Blur & edges', 'Shape & motion', 'Text & shapes', 'Brushes', 'Other pictures', 'Chains']
552
548
  LIBRARY.filter((f) => f.group === 'Blur & edges').map((f) => f.name);
553
549
  const comic = LIBRARY.find((f) => f.name === 'Comic'); // a chain of four
554
550
  ```
555
551
 
556
- The editor's [library](https://qblur.com/) shows them all on your own photo, with their maths.
552
+ 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.
557
553
 
558
554
  ## Reference
559
555
 
@@ -566,11 +562,11 @@ Everything the package exports — from `@mathzetta/qblur/apply`, the first seve
566
562
  | `MAX_SIZE`, `MAX_SIZE_CPU` | the default `maxSize`: 4096 on the GPU, 2048 on the CPU |
567
563
  | `toCompiled(filter)` | any form `applyFilter` takes → the compiled filter |
568
564
  | `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) |
565
+ | `encodeGif(frames, { gifenc, delay, repeat, colors })` | an animated GIF, with gifenc passed in |
566
+ | `encodePng({ width, height, data, palette, colors, quantize })` | the PNG writer `toBlob` uses (indexed, RGB or RGBA) |
571
567
  | `pictureData(canvasOrPicture)` | its RGBA bytes |
572
568
  | `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 |
569
+ | `compileFilter(def, { version })` | a filter (expression, document or chain) → `{ passes, images, graphics, credits, … }`; throws on a malformed filter or math that doesn't parse |
574
570
  | `createRunner(compiled, { gl, prefer, precision, workers })` | `{ runner, engine, reason }`: the GPU when `gl` is a WebGL context, else the CPU |
575
571
  | `createFilterRunner(gl, compiled, { precision })` | the WebGL runner |
576
572
  | `createCpuRunner(compiled, { precision, workers, parallelFrom, workerUrl })` | the JavaScript runner (browsers and Node); `draw()` and `drawAsync()` |
@@ -601,4 +597,5 @@ Everything the package exports — from `@mathzetta/qblur/apply`, the first seve
601
597
  more where the effect needs it (bloom, edge strengths).
602
598
  - **Big pictures.** WebGL limits a texture to `gl.getParameter(gl.MAX_TEXTURE_SIZE)` (often 4096 or more);
603
599
  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.
600
+ - **License.** MIT ([LICENSE](https://github.com/triplelog/qblur/blob/main/LICENSE), Copyright (c) 2025-2026 Robert Wilcox), and so is
601
+ 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.1.0",
4
- "description": "Shareable image filters written as maths: a JSON format with params, pictures and chains, compiled to WebGL shaders by MathZetta.",
3
+ "version": "0.2.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.0.0"
70
+ "mathzetta": "^1.4.0"
71
71
  },
72
72
  "devDependencies": {
73
73
  "@mathzetta/inlinemath": "file:../mathzetta/packages/inlinemath",
@@ -105,10 +105,16 @@
105
105
  },
106
106
  "keywords": [
107
107
  "image",
108
+ "image-processing",
108
109
  "filter",
110
+ "photo-filter",
109
111
  "webgl",
110
112
  "shader",
111
113
  "glsl",
114
+ "canvas",
115
+ "gif",
116
+ "web-component",
117
+ "math",
112
118
  "mathzetta"
113
119
  ]
114
120
  }
@@ -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'); // maths
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 maths, a filter document, JSON or a share link (readFilter), a
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 maths or document — by what it says, so a changed document is a new
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 named = LIBRARY.find((f) => f.name.toLowerCase() === filter.trim().toLowerCase());
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 maths, a filter document, JSON, a link, a compiled filter, or a LIBRARY name
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 colour is [r, g, b], 0–1); the rest keep their defaults.
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 colour, [r, g, b] with each 0–1' : 'a number'}, not ${JSON.stringify(value)}`);
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, Colour, Engine } from './index.js';
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 colour is [r, g, b], 0–1. The rest keep their defaults. */
8
- params?: Record<string, number | Colour>;
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`: maths, a document, JSON, a share link, a compiled filter, or a LIBRARY filter's name.
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 colours. */
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
- colours?: number;
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 colours, RGB when opaque; null without CompressionStream. */
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
- colours?: number;
61
+ colors?: number;
61
62
  dither?: boolean;
62
- /** Needed for palette 'force' on a picture with more than `colours` colours. */
63
- quantize?: (data: Uint8ClampedArray | Uint8Array, colours: number, options: { dither: boolean; width: number }) => { palette: number[][]; indices: Uint8Array };
64
- }): Promise<{ blob: Blob; kind: 'palette' | 'rgb' | 'rgba'; colours: number; bits: number } | null>;
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>;
@@ -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 neighbourhood functions as whole planes.
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 centres in that frame: (px, py) is pixel px of
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 colour params (the generated code may not index twice). */
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); }
@@ -29,6 +29,8 @@ export function smoothstep(e0, e1, x) { const t = Math.min(Math.max((x - e0) / (
29
29
  export function factorial(n) { let r = 1; for (let i = 2; i <= 170; i++) { if (i > n) break; r *= i; } return r; }
30
30
  export function perm(n, k) { let r = 1; for (let i = 0; i < 170; i++) { if (i >= k) break; r *= n - i; } return r; }
31
31
  export function gcd(a, b) { a = Math.abs(a); b = Math.abs(b); for (let i = 0; i < 64; i++) { if (b === 0) break; const t = fmod(a, b); a = b; b = t; } return a; }
32
+ /** Halves go away from zero, as the shader's mz_round and every other MathZetta output round. */
33
+ export function round(x, digits) { const p = Math.pow(10, digits); return Math.sign(x) * Math.floor(Math.abs(x) * p + 0.5) / p; }
32
34
  export function root(n, x) { return n === 2 ? Math.sqrt(x) : n === 3 ? Math.sign(x) * Math.pow(Math.abs(x), 1 / 3) : Math.pow(x, 1 / n); }
33
35
  /** The shader's hash: a new value per pixel and per call, seeded with t. (A GPU's float sin differs, so the values do too.) */
34
36
  export function random(px, py, h, seed) {
@@ -40,7 +42,7 @@ export function random(px, py, h, seed) {
40
42
 
41
43
  const clampi = (v, max) => (v < 0 ? 0 : v > max ? max : v);
42
44
 
43
- /** Bilinear sample of picture data at pixel-centre position (X, Y), edges clamped, into out[0..3]. */
45
+ /** Bilinear sample of picture data at pixel-center position (X, Y), edges clamped, into out[0..3]. */
44
46
  export function sample(D, w, h, X, Y, out) {
45
47
  const x0f = Math.floor(X);
46
48
  const y0f = Math.floor(Y);
@@ -67,7 +69,7 @@ export function sampleOrZero(D, w, h, X, Y, out) {
67
69
 
68
70
  /**
69
71
  * A named picture laid over the frame (the shader's mz_sample_<name>): scaled by `place`
70
- * (0 cover, 1 fit, 2 stretch, 3 tile) times zoom, centred at (x, y) of the frame, turned by
72
+ * (0 cover, 1 fit, 2 stretch, 3 tile) times zoom, centered at (x, y) of the frame, turned by
71
73
  * angle; transparent outside unless tiled.
72
74
  */
73
75
  export function picture(Q, qw, qh, w, h, zoom, x, y, angle, mode, X, Y, out) {
@@ -89,7 +91,7 @@ export function picture(Q, qw, qh, w, h, zoom, x, y, angle, mode, X, Y, out) {
89
91
  return sample(Q, qw, qh, qx - 0.5, qy - 0.5, out);
90
92
  }
91
93
 
92
- // ---- neighbourhoods: whole planes, computed once per pass ------------------------------
94
+ // ---- neighborhoods: whole planes, computed once per pass ------------------------------
93
95
  //
94
96
  // Taps are whole-pixel offsets, edges clamped; dy runs downwards. Square windows are done as a
95
97
  // horizontal pass then a vertical one — the same sums, maxima and weights as the shader's
@@ -339,7 +341,7 @@ export function convolve(I, w, h, px, py, k00, k01, k02, k10, k11, k12, k20, k21
339
341
  return out;
340
342
  }
341
343
 
342
- // ---- colour spaces: the shader's to<space> / from<space> (mathzetta render/glsl.js colourGlsl), sRGB on the other side ----
344
+ // ---- color spaces: the shader's to<space> / from<space> (mathzetta render/glsl.js colorGlsl), sRGB on the other side ----
343
345
  const toLin = (c) => (c < 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
344
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; };
345
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); };