@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/docs/filters.md CHANGED
@@ -1,8 +1,9 @@
1
1
  # Writing image filters
2
2
 
3
- A filter is a bit of maths that runs on every pixel of a picture. It reads the pixel — its
4
- colour `r` `g` `b`, its brightness `gray`, where it is (`x` `y`, or `px` `py` in pixels) — and works
5
- out the new colour. Type one into the editor's *Add a new filter* box and press *Add*:
3
+ A filter is a bit of math that runs on every pixel of a picture. It reads the pixel — its
4
+ color `r` `g` `b`, its brightness `gray`, where it is (`x` `y`, or `px` `py` in pixels) — and works
5
+ out the new color. Type one into the *Add a new filter* box on the filters page (`filters.html`, where filters
6
+ are written; the editor puts them on your pictures) and press *Add*:
6
7
 
7
8
  | Write | You get |
8
9
  | --- | --- |
@@ -15,36 +16,38 @@ out the new colour. Type one into the editor's *Add a new filter* box and press
15
16
  | `gaussian(3)` | a soft blur |
16
17
 
17
18
  Then give it knobs: with the step's *Edit* on, *+ slider* adds a line like
18
- `strength := [[0..1 step 0.01 = 0.5]]` — a slider the maths can use as `strength` (*Edit* also shows
19
+ `strength := [[0..1 step 0.01 = 0.5]]` — a slider the math can use as `strength` (*Edit* also shows
19
20
  the step's name and author, and lets you write notes). Steps run top to bottom, each on the result of the one
20
21
  above, so filters chain; *Copy link* puts the whole thing in a link anyone can open, change and
21
- keep (see [Sharing filters](#sharing-filters)). Everything runs in your browser — nothing is
22
- uploaded. The rest of this guide is everything an expression can use; the editor's *Examples* each
23
- explain one idea, and the *Library* has dozens of filters to open and read.
24
-
25
- **Saving the result.** *Download* draws the filter at the picture's own size. *Download options*
26
- choose the format — PNG, JPEG or WebP, or *auto*, which picks the smallest sensible one (a result
27
- with few colours becomes a small indexed PNG; one with transparency stays lossless; a photo goes to
22
+ keep (see [Sharing filters](#sharing-filters)). *Use it in the editor* takes the filter to the editor, where a
23
+ step shows just its knobs and notes beside a large picture (its *Edit this filter* brings it back here). Everything
24
+ runs in your browser — nothing is uploaded. The rest of this guide is everything an expression can use; the
25
+ *Examples* (under the steps, on both pages) each explain one idea, and *From the library* has dozens of filters to
26
+ open and read.
27
+
28
+ **Saving the result.** In the editor, *Download* (at the top) draws the filter at the picture's own size. The
29
+ *Download* tab's options choose the format — PNG, JPEG or WebP, or *auto*, which picks the smallest sensible one (a result
30
+ with few colors becomes a small indexed PNG; one with transparency stays lossless; a photo goes to
28
31
  whichever of JPEG and WebP is smaller) — the size, a crop you drag on the result, and for moving
29
32
  pictures *Save as GIF* (at the preview size; a GIF plays through once with its own delays, anything
30
33
  else gets 3 seconds) or *Record* (video). Effects measured in pixels — blur radii, `px` — stay the
31
34
  same number of pixels, so they look finer on a big picture.
32
35
 
33
36
  <!-- dev -->
34
- **For developers.** MathZetta turns the maths into GLSL, and `filterShader()` wraps it in a complete
37
+ **For developers.** MathZetta turns the math into GLSL, and `filterShader()` wraps it in a complete
35
38
  fragment shader, so a filter runs on the GPU — fast enough for video:
36
39
 
37
40
  ```js
38
41
  import { filterShader, filterVertexShader } from 'mathzetta/glsl';
39
42
 
40
43
  filterShader('(1 - r, 1 - g, 1 - b)') // invert
41
- filterShader('gray') // greyscale
44
+ filterShader('gray') // grayscale
42
45
  filterShader({ r: 'g', g: 'r' }) // swap red and green; b and a unchanged
43
46
  filterShader('if gray > 0.5 then 1 else 0') // threshold
44
47
  filterShader('pixel(px + 8 sin(py / 10 + t / 5), py)') // a wave that moves with t
45
48
  ```
46
49
 
47
- `demo/index.html` is the editor; `LIBRARY` (exported by the package) is the built-in catalogue it
50
+ `demo/editor.html` is the editor; `LIBRARY` (exported by the package) is the built-in catalog it
48
51
  shows. [qblur on your own pages](library.md) is how to use the package.
49
52
  <!-- /dev -->
50
53
 
@@ -68,15 +71,15 @@ And everything GLSL has: `clamp(v, 0, 1)`, `mix(a, b, 0.5)`, `smoothstep(0, 1, x
68
71
  `step(0.5, x)`, `fract(x)`, `length((x, y))`, `distance(…)`, `floor`, `abs`,
69
72
  `min`, `max`, `sin`, `cos`, `exp`, `log`, `sqrt`, `pow`, `atan2(y, x)`, `mod`.
70
73
 
71
- ## Results: numbers, colours, true/false
74
+ ## Results: numbers, colors, true/false
72
75
 
73
76
  The shader accepts whatever the expression works out to:
74
77
 
75
- - a **number** is grey (or, for a channel, that channel's value);
76
- - a **tuple** `(r, g, b)` or `(r, g, b, a)` is the colour;
78
+ - a **number** is gray (or, for a channel, that channel's value);
79
+ - a **tuple** `(r, g, b)` or `(r, g, b, a)` is the color;
77
80
  - a **comparison** is 1 or 0 — `r > 0.5` is a mask you can multiply by.
78
81
 
79
- Give one expression for the whole colour, or an object with any of
82
+ Give one expression for the whole color, or an object with any of
80
83
  `r`, `g`, `b`, `a`, `rgb`, `rgba`. Channels you don't mention keep their
81
84
  value. In a per-channel expression, `r g b a` are always the *original*
82
85
  pixel, so `{ r: 'g', g: 'r' }` swaps rather than copies.
@@ -117,7 +120,7 @@ rgb * (1 - 1.6 ((x - 0.5)^2 + (y - 0.5)^2)) vignette (no t)
117
120
  For time in seconds instead, set `t` to `performance.now() / 1000` and
118
121
  write `sin(2π t)` for one cycle a second.
119
122
 
120
- ## Neighbouring pixels
123
+ ## Neighboring pixels
121
124
 
122
125
  `pixel(px, py)` reads any pixel, so blurs, edges and distortions are
123
126
  expressions too:
@@ -141,7 +144,7 @@ still picture moves:
141
144
 
142
145
  | Function | Result |
143
146
  | --- | --- |
144
- | `zoom(s)` `zoom(s, cx, cy)` | the picture `s` times larger, about its centre or the point (cx, cy) in 0–1 |
147
+ | `zoom(s)` `zoom(s, cx, cy)` | the picture `s` times larger, about its center or the point (cx, cy) in 0–1 |
145
148
  | `shift(dx, dy)` | moved right and down by that many pixels, wrapping around |
146
149
  | `rotate(a)` `rotate(a, cx, cy)` | turned clockwise by `a` radians (`rotate(10°)` works) |
147
150
  | `crop(x0, y0, x1, y1)` | that part of the picture, in 0–1 fractions, filling the frame |
@@ -159,9 +162,9 @@ tile(2) four copies
159
162
  Each is one transform about the frame; to combine them, chain steps
160
163
  (`Zoom` then `Spin`). Where a transform leaves the frame — zoomed out,
161
164
  rotated corners — the picture is **transparent** when the transform is
162
- the whole colour (`zoom(0.5)` alone: the page, or a PNG's transparency,
165
+ the whole color (`zoom(0.5)` alone: the page, or a PNG's transparency,
163
166
  shows through; a later step sees `a` = 0 there and can fill it:
164
- `mix(background, rgb, a)`). Inside a bigger expression it is a colour,
167
+ `mix(background, rgb, a)`). Inside a bigger expression it is a color,
165
168
  black there, and `alpha(zoom(0.5))` is 1 inside the picture and 0
166
169
  outside, so `mix(rgb, zoom(0.5), alpha(zoom(0.5)))` lays the small copy
167
170
  over the original. `shift` and `tile` wrap instead.
@@ -180,13 +183,13 @@ A named picture is laid over the frame according to its own size:
180
183
  - `place` — `cover` (fills the frame keeping the aspect ratio, the
181
184
  default), `fit` (shows all of it), `stretch` (ignores the ratio), or
182
185
  `tile` (repeats it at its own size).
183
- - `zoom`, `x`, `y`, `angle` — then scaled, centred at (x, y) in 0–1 of
186
+ - `zoom`, `x`, `y`, `angle` — then scaled, centered at (x, y) in 0–1 of
184
187
  the frame, and turned. Outside the picture it is transparent, so
185
188
  `mix(rgb, inset, alpha(inset))` composites it — a picture in picture.
186
189
 
187
190
  Whoever uses the filter can move it: `"with": { "inset": { "x": 0.2,
188
191
  "zoom": 0.5 } }` in a chain step (the demo shows these as knobs beside
189
- each picture), and `zoom(inset, 1 + t / 500)` in the maths animates on
192
+ each picture), and `zoom(inset, 1 + t / 500)` in the math animates on
190
193
  top of that. The `source` picture is the frame's size, so it has no
191
194
  placement.
192
195
 
@@ -194,7 +197,7 @@ placement.
194
197
 
195
198
  A filter can draw text, rectangles and ovals. Each is named in
196
199
  `graphics`, drawn by the browser into a transparent picture the size of
197
- the frame, and read by the maths like any picture:
200
+ the frame, and read by the math like any picture:
198
201
 
199
202
  ```json
200
203
  { "name": "Caption",
@@ -202,10 +205,10 @@ the frame, and read by the maths like any picture:
202
205
  "color": "mix(rgb, title, alpha(title))" }
203
206
  ```
204
207
 
205
- - `title` is the graphic's colour at this pixel, `alpha(title)` where it
206
- is — so the maths decides how it lands: `mix(rgb, title, alpha(title))`
208
+ - `title` is the graphic's color at this pixel, `alpha(title)` where it
209
+ is — so the math decides how it lands: `mix(rgb, title, alpha(title))`
207
210
  lays it on; `mix(rgb, mix((1, 0.35, 0.3), (1, 0.85, 0.25), x), alpha(title))`
208
- colours the letters with a gradient; `mix(rgb, gaussian(5) * 0.7, alpha(panel))`
211
+ colors the letters with a gradient; `mix(rgb, gaussian(5) * 0.7, alpha(panel))`
209
212
  frosts the picture behind a panel (a shape with its own filter);
210
213
  `mix(rgb * 0.3, rgb, alpha(spot))` darkens all but an oval.
211
214
  - **Animated** through the same geometry as any picture, with `t`:
@@ -216,9 +219,9 @@ the frame, and read by the maths like any picture:
216
219
  | Setting | For | Meaning |
217
220
  | --- | --- | --- |
218
221
  | `type` | all | `text` (the default), `rect` or `ellipse` |
219
- | `x`, `y` | all | the centre, 0–1 across and down the frame |
222
+ | `x`, `y` | all | the center, 0–1 across and down the frame |
220
223
  | `angle` | all | turned clockwise, radians |
221
- | `color` | all | any CSS colour: `#ffcc00`, `rgba(0,0,0,0.5)`, `white` |
224
+ | `color` | all | any CSS color: `#ffcc00`, `rgba(0,0,0,0.5)`, `white` |
222
225
  | `shadow` | all | `{ "color", "blur", "dx", "dy" }` drawn into the graphic (sizes as fractions of the text size, or the frame height for shapes), or `null` |
223
226
  | `shadows` | all | a list of up to 8 shadow layers, back to front, each drawn into a picture of its own (see below) |
224
227
  | `outline` | all | `{ "color", "width" }`, or `null` |
@@ -230,10 +233,10 @@ the frame, and read by the maths like any picture:
230
233
 
231
234
  ### Shadow layers, each with its own filter
232
235
 
233
- `shadow` is drawn into the graphic, so whatever the maths does to the
236
+ `shadow` is drawn into the graphic, so whatever the math does to the
234
237
  text it does to that shadow too. `shadows` keeps them apart: each layer
235
238
  is drawn into a picture of its own — `title_shadow1`, `title_shadow2`…,
236
- back to front — and the maths lays each on as it likes:
239
+ back to front — and the math lays each on as it likes:
237
240
 
238
241
  ```json
239
242
  { "graphics": { "title": { "text": "LAYERS", "shadow": null,
@@ -242,13 +245,13 @@ back to front — and the maths lays each on as it likes:
242
245
  ```
243
246
 
244
247
  Here the first layer darkens the picture under a soft glow that breathes
245
- with `t`, and the second is a hard offset shadow coloured by a gradient
246
- whatever colour it was cast in ("Layered shadow" in the library). The
248
+ with `t`, and the second is a hard offset shadow colored by a gradient
249
+ whatever color it was cast in ("Layered shadow" in the library). The
247
250
  plain way to lay them all on is `mix(mix(mix(rgb, title_shadow1,
248
251
  alpha(title_shadow1)), title_shadow2, alpha(title_shadow2)), title,
249
252
  alpha(title))`; the editor writes that for you when you add a layer to
250
- a step whose maths is still the plain one, and points out a layer your
251
- own maths doesn't use yet.
253
+ a step whose math is still the plain one, and points out a layer your
254
+ own math doesn't use yet.
252
255
 
253
256
  ### Fonts
254
257
 
@@ -267,9 +270,9 @@ a graphic with `with`, merging settings: `{ "filter": …Caption…, "with":
267
270
  graphics are not shared between steps: two steps whose text is called
268
271
  `title` draw two texts (the compiler binds them as `title`, `title~2`…).
269
272
 
270
- In the editor, *+ text*, *+ rectangle* and *+ oval* add a step with an
273
+ In the editor's *Select & draw* tab, *+ text*, *+ rectangle* and *+ oval* add a step with an
271
274
  editable expression; each graphic gets controls for its words, font,
272
- size, place, angle, colour, shadow and outline, and can be dragged on
275
+ size, place, angle, color, shadow and outline, and can be dragged on
273
276
  the picture. A font file loaded from the computer works there but can't
274
277
  travel in a link; a font URL can (the browser of whoever opens the link
275
278
  fetches it from that address).
@@ -290,7 +293,7 @@ A brush is a graphic of type `strokes`: what the user paints on the
290
293
  picture, recorded point by point (`[x, y, milliseconds, pressure]`, x and
291
294
  y as fractions of the frame) and drawn again for every frame — only the
292
295
  paint laid down by frame `t` is there, so the painting animates. Its
293
- picture carries data rather than colour:
296
+ picture carries data rather than color:
294
297
 
295
298
  | Channel | Meaning |
296
299
  | --- | --- |
@@ -299,15 +302,15 @@ picture carries data rather than colour:
299
302
  | `green(brush)` | passes ÷ 4: how many strokes have gone over it (`4 green(brush)` counts them) |
300
303
  | `blue(brush)` | progress: how far through the whole drawing it was painted, 0 → 1 |
301
304
 
302
- So the maths decides what the paint does, and how it changes:
305
+ So the math decides what the paint does, and how it changes:
303
306
 
304
307
  ```
305
- mix(rgb, ink, alpha(brush)) ink in a colour (a knob)
308
+ mix(rgb, ink, alpha(brush)) ink in a color (a knob)
306
309
  mix(rgb, gaussian(2 + 3 min(4 green(brush), 3)), alpha(brush)) a blur, stronger with every pass
307
310
  rgb (1 - 0.22 min(4 green(brush), 4) alpha(brush)) darker with every pass, like a wash
308
311
  mix(rgb, mix((1, 0.9, 0.5), (0.1, 0.07, 0.06), red(brush)), alpha(brush)) glowing as it goes down, then cooling
309
312
  mix(rgb, fromhsv(blue(brush), 0.85, 1), alpha(brush)) a rainbow along the drawing
310
- mix((gray, gray, gray), rgb, alpha(brush)) the picture's colour painted back in
313
+ mix((gray, gray, gray), rgb, alpha(brush)) the picture's color painted back in
311
314
  ```
312
315
 
313
316
  | Setting | Meaning |
@@ -323,7 +326,7 @@ mix((gray, gray, gray), rgb, alpha(brush)) the pictur
323
326
  | `clip` | `none`, `inside` or `outside`: paint only inside (or outside) the user's selection |
324
327
 
325
328
  A stroke counts once wherever it goes, however often it crosses itself,
326
- so `green` counts separate passes. In the editor, "+ brush" adds a step
329
+ so `green` counts separate passes. In the editor (*Select & draw*), "+ brush" adds a step
327
330
  and starts drawing (the picture shows the painting finished while you
328
331
  draw; "replay" plays it); each brush's panel chooses what the paint does,
329
332
  the brush, the timing and where it may paint, and "outline the
@@ -334,7 +337,7 @@ takes `{ t, mask }`.
334
337
 
335
338
  ## Several pictures: masks and blending
336
339
 
337
- A filter can ask for more pictures by name, and the maths treats each
340
+ A filter can ask for more pictures by name, and the math treats each
338
341
  like the main one:
339
342
 
340
343
  ```json
@@ -343,8 +346,8 @@ like the main one:
343
346
  "color": "mix(source, rgb, luma(mask))" }
344
347
  ```
345
348
 
346
- - `mask` is that picture's colour at this pixel (like `rgb`);
347
- `mask(px, py)` is any pixel of it, also a colour; `red(mask)` …
349
+ - `mask` is that picture's color at this pixel (like `rgb`);
350
+ `mask(px, py)` is any pixel of it, also a color; `red(mask)` …
348
351
  `alpha(mask)` and `luma(mask)` read one channel.
349
352
  - `source` is always available: the picture the chain started from,
350
353
  before any step. So "Through a mask" as the last step shows everything
@@ -371,11 +374,30 @@ outside — 1 everywhere when nothing is selected, so a filter that uses
371
374
  it works unchanged. `mix(source, rgb, selected)` as a last step keeps
372
375
  the chain's result only inside the selection ("Only inside the
373
376
  selection" in the library); `selection(px, py)` reads the mask elsewhere.
374
- It is a mask, so a colour space leaves it alone. The runner takes it as
377
+ It is a mask, so a color space leaves it alone. The runner takes it as
375
378
  a picture named `selection` (white = in): `runner.setImage('selection',
376
379
  maskCanvas)`.
377
380
 
378
- The editor makes one two ways. *Trace the edge* is intelligent scissors
381
+ `away` is how far the pixel is from the selection, in pixels: 0 inside
382
+ it, 10 ten pixels out, and so on (0 everywhere when nothing is selected).
383
+ It makes halos and fades that follow the object's shape:
384
+
385
+ ```
386
+ mix((1, 0.8, 0.3), rgb, smoothstep(0, 60, away)) a warm glow round the selection, 60 pixels wide
387
+ mix(rgb, gaussian(6), min(1, away / 150)) sharp near the object, blurrier farther away
388
+ if away > 0 and away < 4 then (1, 1, 1) a 4-pixel outline just outside it
389
+ ```
390
+
391
+ <!-- dev -->
392
+ The runners work it out from the `selection` they are given, only for a
393
+ filter that uses `away` (an exact distance transform of the selection
394
+ measured at most 512 pixels across, about 12 ms; `awayPicture()` in
395
+ src/distance.js), so a page has nothing more to do. A page with its own
396
+ distances can pass them as `runner.setImage('away', picture)`: white is
397
+ 0, red = 1 − min(d, 255)/255, green = 1 − min(d, 1020)/1020.
398
+ <!-- /dev -->
399
+
400
+ The editor's *Select & draw* tab makes one. *Trace the edge* is intelligent scissors
379
401
  (livewire): click a few points around the object and the line between
380
402
  them follows the edge — every pixel has a cost, low where the brightness
381
403
  changes sharply, and the line is the cheapest path (Dijkstra) between
@@ -409,24 +431,24 @@ object. The model and its runtime (ONNX Runtime Web) are
409
431
  served by the site itself — no CDN, no Hugging Face — load only when
410
432
  asked and are then cached by the browser; the rest of the editor never
411
433
  depends on them. Anything not among the 80 kinds is for the edge tracer,
412
- the colour fill or the refine brush.
434
+ the color fill or the refine brush.
413
435
 
414
436
  The *refine* brush fixes any selection, however it was made. Paint with
415
437
  *inside* over a part that was missed, or with *outside* over a part that
416
438
  leaked; the boundary then settles on the nearest real edge near the
417
439
  stroke. Under the hood, the stroke and the rim of a band round it are
418
440
  seeds, and each side grows through the band with a cost that is tiny in
419
- even colour and steep across an edge (measured over three pixels, so a
441
+ even color and steep across an edge (measured over three pixels, so a
420
442
  soft edge counts in full) — whichever side reaches a pixel first claims it
421
443
  (a seeded region competition, Dijkstra again); nothing outside the band
422
444
  moves. With nothing selected, an inside stroke makes a selection from
423
445
  scratch: the whole picture is in play and its border is "outside", so the
424
- stroke grows to the object's edges. The size slider sets the brush. *Fill a colour* is a magic wand that
425
- knows several colours: each click adds that pixel's colour to a set,
446
+ stroke grows to the object's edges. The size slider sets the brush. *Fill a color* is a magic wand that
447
+ knows several colors: each click adds that pixel's color to a set,
426
448
  and the fill grows from every click through any pixel within the
427
- tolerance of *any* colour in the set — a striped shirt is two clicks;
428
- "connected only" off takes those colours anywhere in the picture;
429
- click a swatch to drop a colour, and the tolerance slider refills live. Feather softens the edge,
449
+ tolerance of *any* color in the set — a striped shirt is two clicks;
450
+ "connected only" off takes those colors anywhere in the picture;
451
+ click a swatch to drop a color, and the tolerance slider refills live. Feather softens the edge,
430
452
  invert swaps inside and out; the selection is drawn at any export size.
431
453
  It belongs to the picture, not the filter, so share links don't carry it.
432
454
 
@@ -471,7 +493,7 @@ forward and backward a frame at a time:
471
493
  disagree with the rest are pulled back to the group's movement, and
472
494
  each may stray only a few pixels from the group's overall move, scale
473
495
  and turn, so the outline can't wander off;
474
- - the keyframe teaches it the object's colours against a band just
496
+ - the keyframe teaches it the object's colors against a band just
475
497
  outside, so each frame has a map of how object-like every pixel is;
476
498
  the outline between the points follows the edge of that map (and some
477
499
  plain brightness edges) — not every leaf behind the object;
@@ -480,7 +502,7 @@ forward and backward a frame at a time:
480
502
  jumped. Between two keyframes, each frame keeps the direction that
481
503
  scored higher.
482
504
 
483
- The timeline under the picture shows confidence (green sure, red not):
505
+ In the editor's *Select & draw* tab, under *Follow the selection through the clip*, the timeline shows confidence (green sure, red not):
484
506
  click a frame to go there, fix it ("edit this frame" puts the outline into
485
507
  the edge tracer to drag its points, or select again), and use it as another
486
508
  keyframe. "Fix red frames with AI" runs the chosen model on each unsure frame
@@ -500,7 +522,7 @@ The runner takes them with `runner.setImage('mask', image)`; a picture
500
522
  not given is white, so a missing mask lets everything through. Pictures
501
523
  are stretched to the canvas, so size them like the main picture.
502
524
 
503
- ## Colour spaces
525
+ ## Color spaces
504
526
 
505
527
  The frame holds sRGB — the numbers a screen shows. A filter can work in
506
528
  another space instead:
@@ -520,28 +542,28 @@ on the way in only, when the expression writes sRGB itself.
520
542
  | `srgb` | what the picture holds (the default) |
521
543
  | `linear` | light rather than gamma-encoded values: blurs and mixes in it behave like a lens, bright spots stay bright |
522
544
  | `hsv`, `hsl` | hue (0–1 around the wheel), saturation, value / lightness |
523
- | `lab` | L 0–1, then a and b centred on 0.5 (0.5 ± value/256) |
524
- | `oklab` | L 0–1, then a and b centred on 0.5 (0.5 + value) — perceptually even |
525
- | `ycbcr` | luma, then Cb and Cr centred on 0.5 |
545
+ | `lab` | L 0–1, then a and b centered on 0.5 (0.5 ± value/256) |
546
+ | `oklab` | L 0–1, then a and b centered on 0.5 (0.5 + value) — perceptually even |
547
+ | `ycbcr` | luma, then Cb and Cr centered on 0.5 |
526
548
 
527
549
  Every space keeps its values in 0–1 so they survive the 8-bit texture
528
550
  between passes — but 8 bits of Lab or OKLab is coarse for dark, saturated
529
- colours (up to ~20/255 off after the round trip), so the editor uses
530
- half-float textures for a chain with a colour space where the GPU
551
+ colors (up to ~20/255 off after the round trip), so the editor uses
552
+ half-float textures for a chain with a color space where the GPU
531
553
  allows (`createFilterRunner(gl, c, { precision: 'half' })`,
532
554
  `createCpuRunner(c, { precision: 'float' })`). A step's opacity blends
533
555
  the result over its input in sRGB. The conversions are also functions you can use anywhere —
534
556
  `tohsv(c)`, `fromhsv(c)`, `tolinear`, `fromlinear`, `tohsl`, `tolab`,
535
557
  `tooklab`, `toycbcr` and their inverses, sRGB on the other side —
536
558
  so a single expression can do it: `fromhsv(fract(red(tohsv(rgb)) + t /
537
- 300), green(tohsv(rgb)), blue(tohsv(rgb)))` cycles the hue. The editor
538
- has a space chooser beside the expression box.
559
+ 300), green(tohsv(rgb)), blue(tohsv(rgb)))` cycles the hue. On the filters
560
+ page, a step's space chooser sits beside its expression box (and beside *Add a new filter*'s).
539
561
 
540
- ## Blur, edges and other neighbourhood functions
562
+ ## Blur, edges and other neighborhood functions
541
563
 
542
564
  The classic image-processing operations are functions you can use in
543
565
  any expression, so they combine with everything else and with each
544
- other. Colour-valued ones return a colour like `rgb` (alpha is left
566
+ other. Color-valued ones return a color like `rgb` (alpha is left
545
567
  alone); the edge detectors work on brightness and return a number.
546
568
 
547
569
  | Function | Result |
@@ -550,10 +572,10 @@ alone); the edge detectors work on brightness and return a number.
550
572
  | `gaussian(sigma)` | Gaussian blur, weights falling off with `sigma` |
551
573
  | `blurx(r)` `blury(r)` `gaussianx(s)` `gaussiany(s)` | the same along one axis — chain an x then a y step for a wide, fast blur |
552
574
  | `sharpen(amount)` | the 3×3 sharpen kernel, scaled by `amount` |
553
- | `dilate(radius)` `erode(radius)` | the brightest / darkest colour within ±radius: light or dark areas grow |
575
+ | `dilate(radius)` `erode(radius)` | the brightest / darkest color within ±radius: light or dark areas grow |
554
576
  | `convolve(k1, …, k9)` | your own 3×3 kernel, row by row |
555
577
  | `sobel()` `sobelx()` `sobely()` | Sobel edge strength (and its horizontal / vertical parts) |
556
- | `laplacian()` | the 4-neighbour Laplacian of brightness |
578
+ | `laplacian()` | the 4-neighbor Laplacian of brightness |
557
579
  | `emboss()` | brightness relief lit from the top-left, around 0.5 |
558
580
 
559
581
  ```
@@ -561,14 +583,14 @@ gaussian(3) a blur
561
583
  rgb + 1.5 (rgb - gaussian(2)) unsharp mask
562
584
  rgb + 0.8 max(gaussian(3) - 0.6, 0) bloom: bright parts glow
563
585
  if sobel() > 0.3 then 1 else 0 an edge map
564
- rgb (1 - 3 sobel()) ink outline over the colour
586
+ rgb (1 - 3 sobel()) ink outline over the color
565
587
  convolve(0, -1, 0, -1, 5, -1, 0, -1, 0) sharpen, as a kernel
566
588
  dilate(2) - erode(2) morphological gradient: outlines of shapes
567
589
  ```
568
590
 
569
591
  Every one of them takes expressions, so a parameter can drive it
570
592
  (`gaussian(sigma)`), and `t` can too (`gaussian(2 + 2 sin(t / 20))`).
571
- In a per-channel expression a colour result gives that channel:
593
+ In a per-channel expression a color result gives that channel:
572
594
  `{ "r": "gaussian(4)" }` blurs only red. The library in the demo has
573
595
  each of these as a filter with knobs, and chains built from them
574
596
  (Cartoon = Gaussian blur → Posterize → Outline).
@@ -576,11 +598,11 @@ each of these as a filter with knobs, and chains built from them
576
598
  Two limits, because a shader loop needs fixed bounds: the square
577
599
  functions reach ±8 pixels, so `gaussian(sigma)` inside an expression is
578
600
  truncated above `sigma ≈ 2.7`; the one-axis functions reach ±24. A step
579
- whose whole colour is just `gaussian(sigma)` or `blur(radius)` is
601
+ whose whole color is just `gaussian(sigma)` or `blur(radius)` is
580
602
  computed separably for you — an x pass then a y pass, 2n taps instead
581
603
  of n², reaching ±24 — so the plain blur is the fast, wide one; write
582
604
  `gaussianx`/`gaussiany` yourself only when you want one axis.
583
- Each call samples the neighbourhood again, so `gaussian(3)` used twice
605
+ Each call samples the neighborhood again, so `gaussian(3)` used twice
584
606
  in one expression costs twice — put it in its own step if that matters.
585
607
  "Canny edges" in the library is a chain of these: a Gaussian, then
586
608
  gradient strength and direction (`atan2(sobely(), sobelx())` into four
@@ -592,7 +614,7 @@ expressions, so it runs on the CPU too.
592
614
  ## Running it
593
615
 
594
616
  The editor runs a filter on the GPU (WebGL) when the browser has it, and on the CPU otherwise —
595
- *Advanced* → *runs on* lets you choose. Both give the same pixels; the GPU is much faster, so big
617
+ in the editor, the *Download* tab's *Advanced* → *runs on* lets you choose. Both give the same pixels; the GPU is much faster, so big
596
618
  pictures and video want it.
597
619
 
598
620
  <!-- dev -->
@@ -618,7 +640,7 @@ language, types and sampling as the shader (bilinear `pixel()`, edges
618
640
  clamped, 8-bit rounding between passes), so both give the same pixels:
619
641
  `npm run check -- --cpu` compares them on every library filter (all within
620
642
  1/255 apart from a handful of pixels exactly on an edge; `random()` can't
621
- match — GPUs compute the hash's `sin` in lower precision). Neighbourhood
643
+ match — GPUs compute the hash's `sin` in lower precision). Neighborhood
622
644
  functions with an argument that is the same for every pixel (`blur(radius)`)
623
645
  are computed once per pass, separably; one that changes per pixel
624
646
  (`blur(x * 8)`) is computed pixel by pixel and is slow. Rough single-thread
@@ -628,7 +650,7 @@ workers is 3–5× faster on the heavy ones.
628
650
 
629
651
  The generated code is compiled only after MathZetta's `checkGeneratedJs`
630
652
  passes it (no names but its own, no strings, only its own arrays indexed),
631
- so a filter from a share link can read the picture and write colours,
653
+ so a filter from a share link can read the picture and write colors,
632
654
  nothing else. Pages whose Content-Security-Policy forbids `'unsafe-eval'`
633
655
  can't use the CPU runner.
634
656
 
@@ -673,9 +695,9 @@ to a canvas, upload it, draw, and read the canvas back (`toBlob` or
673
695
 
674
696
  ## Sharing filters
675
697
 
676
- A filter is a small JSON document: the maths, a name and author, and the
677
- knobs it exposes. Since it is only maths, it is safe to accept from
678
- anyone — it can read the picture and write colours, nothing else.
698
+ A filter is a small JSON document: the math, a name and author, and the
699
+ knobs it exposes. Since it is only math, it is safe to accept from
700
+ anyone — it can read the picture and write colors, nothing else.
679
701
 
680
702
  ```json
681
703
  {
@@ -688,19 +710,19 @@ anyone — it can read the picture and write colours, nothing else.
688
710
  }
689
711
  ```
690
712
 
691
- - `color` is one expression for the colour, or an object with any of
713
+ - `color` is one expression for the color, or an object with any of
692
714
  `r`, `g`, `b`, `a`, `rgb`, `rgba` — exactly as `filterShader()` takes.
693
715
  - `params` are the knobs. Each is a number (`"cutoff": 0.5` means
694
716
  0–1; larger defaults get 0–2×) or `{ "default", "min", "max", "step",
695
- "label" }`, or a colour: `"tint": [1, 0.85, 0.7]` (three numbers, 0–1).
717
+ "label" }`, or a color: `"tint": [1, 0.85, 0.7]` (three numbers, 0–1).
696
718
  A parameter is a value, never a function, so `strength (x + 1)` is a
697
719
  product.
698
720
  A number knob is a slider, unless it has `"options": [2, 4, 8]` (a menu
699
721
  of those values; the default is the first unless given) or
700
- `"input": "box"` (a box to type a value in — any maths that works out
722
+ `"input": "box"` (a box to type a value in — any math that works out
701
723
  to a number, such as `1/3`).
702
724
  - `notes` is the filter's page, shown in its step in the editor: a list of
703
- Markdown texts (maths in `$…$` is drawn by Inline Math, and `{{cutoff}}`
725
+ Markdown texts (math in `$…$` is drawn by Inline Math, and `{{cutoff}}`
704
726
  inside it is a knob's value) and `{ "param": "cutoff" }` entries that
705
727
  place a knob's input among them; knobs it doesn't place come first.
706
728
  Notes never change the picture.
@@ -711,11 +733,11 @@ anyone — it can read the picture and write colours, nothing else.
711
733
  - `name`, `author`, `description` are free text; `format` says which
712
734
  version of this format the document follows.
713
735
 
714
- In the editor each knob is written as an Inline Math variable, one line
715
- you can edit (shown while the step's *Edit* is on): `cutoff := [[0..1 step 0.01 = 0.5]]` (a slider: from, to,
736
+ On the filters page each knob is written as an Inline Math variable, one line
737
+ you can edit (shown while the step's *Edit* is on; the editor shows only the knob): `cutoff := [[0..1 step 0.01 = 0.5]]` (a slider: from, to,
716
738
  its step, where it starts), `radius := [[3]]` (a box), `levels := [[2 | 4 | 8]]`
717
- (a menu) or `tint := #ff8800` (a colour). Renaming a knob there renames it
718
- in the maths too.
739
+ (a menu) or `tint := #ff8800` (a color). Renaming a knob there renames it
740
+ in the math too.
719
741
 
720
742
  ### Combining filters
721
743
 
@@ -832,7 +854,7 @@ only run what has a numeric meaning per pixel:
832
854
  - **Names:** `x y r g b a t w h px py rgb gray unchanged` are taken, as
833
855
  are GLSL's own words (`in`, `out`, `float`, `main`, …). Greek letters are
834
856
  spelled out (`θ` → `theta`), primes become `_prime`. `f`, `g` and `h`
835
- followed by a bracket are read as function calls, as in maths: write
857
+ followed by a bracket are read as function calls, as in math: write
836
858
  `g * (1 - r)`, not `g(1 - r)`.
837
859
 
838
860
  MathZetta's [how it works](https://github.com/triplelog/mathzetta/blob/main/packages/mathzetta/docs/how-it-works.md)