millirec 0.1.1 → 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.
Files changed (89) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +286 -51
  3. package/dist/char-cnn/cnn-web.wasm +0 -0
  4. package/dist/char-cnn/core.d.ts +15 -1
  5. package/dist/char-cnn/core.js +214 -100
  6. package/dist/char-cnn/index.d.ts +1 -1
  7. package/dist/char-cnn/index.js +267 -137
  8. package/dist/char-cnn/millirec-char-cnn-core.min.js +1 -1
  9. package/dist/char-cnn/millirec-char-cnn.min.js +1 -1
  10. package/dist/char-cnn/options/accurate/tiny.head.bin +0 -0
  11. package/dist/char-cnn/options/accurate.js +6 -6
  12. package/dist/char-cnn/options/accurate.json +5 -5
  13. package/dist/char-cnn/options/all/all-base.head.bin +0 -0
  14. package/dist/char-cnn/options/all/all-base.q4.bin +0 -0
  15. package/dist/char-cnn/options/all/all-tiny.bin +0 -0
  16. package/dist/char-cnn/options/all/all-tiny.head.bin +0 -0
  17. package/dist/char-cnn/options/all-fast/all-base-p25.bin +0 -0
  18. package/dist/char-cnn/options/all-fast/all-base-p25.head.bin +0 -0
  19. package/dist/char-cnn/options/all-fast/all-tiny.bin +0 -0
  20. package/dist/char-cnn/options/all-fast/all-tiny.head.bin +0 -0
  21. package/dist/char-cnn/options/all-fast.js +17 -0
  22. package/dist/char-cnn/options/all-fast.json +15 -0
  23. package/dist/char-cnn/options/all-small/all-tiny-qat4.head.bin +0 -0
  24. package/dist/char-cnn/options/all-small/all-tiny-qat4.q4.bin +0 -0
  25. package/dist/char-cnn/options/all-small.js +11 -0
  26. package/dist/char-cnn/options/all-small.json +9 -0
  27. package/dist/char-cnn/options/all.js +17 -0
  28. package/dist/char-cnn/options/all.json +15 -0
  29. package/dist/char-cnn/options/digits/digits-base.head.bin +0 -0
  30. package/dist/char-cnn/options/digits/digits-base.q4.bin +0 -0
  31. package/dist/char-cnn/options/digits/digits-tiny.bin +0 -0
  32. package/dist/char-cnn/options/digits/digits-tiny.head.bin +0 -0
  33. package/dist/char-cnn/options/digits-fast/digits-base-p25.bin +0 -0
  34. package/dist/char-cnn/options/digits-fast/digits-base-p25.head.bin +0 -0
  35. package/dist/char-cnn/options/digits-fast/digits-tiny.bin +0 -0
  36. package/dist/char-cnn/options/digits-fast/digits-tiny.head.bin +0 -0
  37. package/dist/char-cnn/options/digits-fast.js +17 -0
  38. package/dist/char-cnn/options/digits-fast.json +15 -0
  39. package/dist/char-cnn/options/digits-small/digits-tiny-qat4.head.bin +0 -0
  40. package/dist/char-cnn/options/digits-small/digits-tiny-qat4.q4.bin +0 -0
  41. package/dist/char-cnn/options/digits-small.js +11 -0
  42. package/dist/char-cnn/options/digits-small.json +9 -0
  43. package/dist/char-cnn/options/digits.js +17 -0
  44. package/dist/char-cnn/options/digits.json +15 -0
  45. package/dist/char-cnn/options/fast/base-p25.head.bin +0 -0
  46. package/dist/char-cnn/options/fast/tiny.bin +0 -0
  47. package/dist/char-cnn/options/fast/tiny.head.bin +0 -0
  48. package/dist/char-cnn/options/fast.js +6 -6
  49. package/dist/char-cnn/options/fast.json +5 -5
  50. package/dist/char-cnn/options/lowercase/lowercase-base.head.bin +0 -0
  51. package/dist/char-cnn/options/lowercase/lowercase-base.q4.bin +0 -0
  52. package/dist/char-cnn/options/lowercase/lowercase-tiny.bin +0 -0
  53. package/dist/char-cnn/options/lowercase/lowercase-tiny.head.bin +0 -0
  54. package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.bin +0 -0
  55. package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.head.bin +0 -0
  56. package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.bin +0 -0
  57. package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.head.bin +0 -0
  58. package/dist/char-cnn/options/lowercase-fast.js +17 -0
  59. package/dist/char-cnn/options/lowercase-fast.json +15 -0
  60. package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.head.bin +0 -0
  61. package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.q4.bin +0 -0
  62. package/dist/char-cnn/options/lowercase-small.js +11 -0
  63. package/dist/char-cnn/options/lowercase-small.json +9 -0
  64. package/dist/char-cnn/options/lowercase.js +17 -0
  65. package/dist/char-cnn/options/lowercase.json +15 -0
  66. package/dist/char-cnn/options/small/tiny.head.bin +0 -0
  67. package/dist/char-cnn/options/small/tiny.q4.bin +0 -0
  68. package/dist/char-cnn/options/small.js +3 -3
  69. package/dist/char-cnn/options/small.json +2 -2
  70. package/dist/char-lite/core.d.ts +1 -0
  71. package/dist/char-lite/core.js +628 -0
  72. package/dist/char-lite/index.d.ts +28 -8
  73. package/dist/char-lite/index.js +459 -297
  74. package/dist/char-lite/millirec-char-lite.min.js +1 -1
  75. package/dist/char-lite/millirec.wasm +0 -0
  76. package/dist/char-lite/sets.json +25 -29
  77. package/dist/index.d.ts +35 -0
  78. package/dist/index.js +88 -0
  79. package/dist/overlap/millirec-overlap.min.js +7 -7
  80. package/dist/overlap/millirec.wasm +0 -0
  81. package/dist/pad/index.d.ts +8 -0
  82. package/dist/pad/index.js +482 -0
  83. package/package.json +30 -8
  84. package/dist/char-cnn/base-p25.head.bin +0 -0
  85. package/dist/char-cnn/tiny.head.bin +0 -0
  86. /package/dist/char-cnn/{base.head.bin → options/accurate/base.head.bin} +0 -0
  87. /package/dist/char-cnn/{base.q4.bin → options/accurate/base.q4.bin} +0 -0
  88. /package/dist/char-cnn/{tiny.bin → options/accurate/tiny.bin} +0 -0
  89. /package/dist/char-cnn/{base-p25.bin → options/fast/base-p25.bin} +0 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,106 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0
4
+
5
+ - **`createRecognizer()`: say what to read, not which engine.** `import { createRecognizer } from
6
+ 'millirec'`, then `createRecognizer('digits')`, `createRecognizer({ alphabet: 'lowercase', priority:
7
+ 'small' })` or `createRecognizer({ examples: { yes: [...], no: [...] } })`. It picks char-cnn for
8
+ digits, capitals, lowercase and all (read from strangers), and char-lite for punctuation and for
9
+ your own symbols, and imports only the engine it picks. `chooseEngine()` says what it would load
10
+ without loading it. The README opens with a guide to which engine suits what.
11
+ - **The two engines share their surface.** char-lite gains `recognize(strokes, { only })` (answer
12
+ among some classes, as char-cnn has), `teach()` / `forget()` (read symbols of your own alone, the
13
+ same call as char-cnn's), and `classes` and `engine`; char-cnn gains `engine`. A set with fewer
14
+ than three classes now returns each reading once instead of padding with repeats.
15
+ - **The pad on its own: `millirec/pad`.** `attachPad(el, recognizer, options)` drives any
16
+ recognizer with `recognize(strokes)`, the pad-less cores included; the new `recognizeOptions`
17
+ option (also on `attach()`) passes e.g. `{ only: '0123456789' }` to every reading.
18
+ - **The pad and overlap keep a stroke begun before the last one's pen-up arrived.** A pointer coming
19
+ down with the same id as the open stroke (the mouse always has one id; a quick next stroke) used to
20
+ throw the open stroke away; it is committed now. A lost pointer capture ends the stroke instead of
21
+ leaving it open until the next pen-down, and while drawing only the new segment is painted (a full
22
+ repaint per move is what made iPadOS drop the next stroke on the project's writing page). overlap
23
+ also reads its box's position once per stroke instead of once per sample, and its colours once.
24
+ - **`millirec/char-lite/core`**: char-lite without the pad (5 KB gzipped instead of 8), as
25
+ `millirec/char-cnn/core` is for char-cnn.
26
+ - **char-cnn is 2–5× faster and needs no canvas.** Strokes are drawn in software instead of on a
27
+ `<canvas>` and read back (about 0.05 ms per character in Chrome), the plain-JS
28
+ network reuses its buffers (the `-small` options: 0.14 ms instead of 0.75 ms), and the WebAssembly
29
+ kernel is 2.3× faster. A single tap is now ink (the dot of an `i`, a full stop).
30
+ - **char-cnn reads a little better**: every model's last layer was refitted on its shipped, quantised
31
+ weights (chosen on held-out training data, never the test set). On strangers' EMNIST drawings:
32
+ capitals 98.5 / 97.9 / 96.8%, digits 99.6 / 99.5 / 99.1%, lowercase 93.8 / 91.9 / 90.4%, all
33
+ 77.2 / 74.0 / 71.5% (accurate / fast / small).
34
+ - **The `-small` options ship their 4-bit model file** (3.8 KB instead of 7.0 KB), so each stays
35
+ under 11 KB gzipped with its runtime.
36
+ - `'millirec'` still exports `MillirecCharLite`, `loadSet` and `SETS`, so 0.1 imports work
37
+ unchanged.
38
+
39
+ ## 0.1.3
40
+
41
+ - **char-cnn: nine new options.** Digits and lowercase letters now come as `accurate` (the existing
42
+ `digits`, `lowercase`), `-fast` and `-small`, like the capitals; and `all`, `all-fast`, `all-small`
43
+ read digits, capitals and lowercase letters in one recognizer (62 classes). On strangers' EMNIST
44
+ drawings: digits 99.6 / 99.4 / 99.1%, lowercase 93.7 / 91.3 / 89.7%, all 76.3 / 72.6 / 70.0%
45
+ (96.2 / 94.2 / 93.4% the likeliest of its own kind — digit, capital or lowercase; characters drawn
46
+ alike across kinds, c/C, o/O/0, l/I/1, make the exact one a toss-up).
47
+ - **overlap: input the OS cancels or loses no longer misbehaves.** A touch the OS takes back before
48
+ it moves (a palm, a scroll gesture) used to become a dot and add a letter; it is dropped. A pointer
49
+ whose `pointerup` never arrived used to lock the box against touch and mouse until a pen came; the
50
+ next pointer now finishes that stroke and draws (a palm beside a drawing pen is still ignored), and
51
+ a lost pointer capture ends the stroke.
52
+ - **overlap: `assetBase` without its trailing slash works**, as the README says (`/x/overlap`
53
+ used to fetch `/x/overlaptraining.capitals.json`).
54
+ - **overlap: a missing or unservable wasm names the file** (`…/millirec.wasm`) instead of
55
+ emscripten's bare "Aborted(both async and sync fetching of the wasm failed)".
56
+ - **overlap: `scan()` no longer leaves an unhandled rejection** for a widget that cannot boot; the
57
+ widget still shows the error and emits `error`.
58
+ - **char-lite: the result cache keys on stroke boundaries and full-precision coordinates.** The same
59
+ points split into two strokes (which resample differently) and 0–1 drawings that differ slightly
60
+ could share a key and return each other's reading.
61
+ - **char-lite: `rawScores(undefined)` returns `null`** like `recognize(undefined)` (it threw).
62
+ - **char-cnn: points that are not finite numbers read as `null`** (they returned a letter), and
63
+ `embedding()` of no strokes throws a `TypeError` (it returned a blank image's embedding).
64
+ - Types: `millirec/char-cnn` re-exports `Point`, `Stroke`, `Strokes` and `Reading`.
65
+ - README: which data each CNN option was trained on; overlap's wasm is 13 KB gzipped.
66
+ - `npm pack --json` output is valid JSON (the build's summary goes to stderr).
67
+
68
+ ## 0.1.2
69
+
70
+ - **char-cnn reads digits and lowercase letters**: two new options, `create('digits')` (99.6% of
71
+ strangers' digits) and `create('lowercase')` (93.7%), the same pair of networks as `accurate`,
72
+ trained on EMNIST plus this project's own writer.
73
+ - **`teach()`: symbols of your own with no training.** `rec.teach({ star: [d1, d2, d3], … })` keeps
74
+ each drawing as what the network makes of it and reads new drawings by the nearest example;
75
+ `forget()` undoes it, `create({ examples })` does it at creation. Three examples per class read
76
+ 96% of one writer's digits with the capitals-only network.
77
+ - **`fast` and `small` now run their own first network.** 0.1.0 and 0.1.1 shipped one `tiny.bin`
78
+ for all three capital-letter options, so `fast` and `small` ran `accurate`'s first network instead
79
+ of the ones they were measured with. Each option's model files now live in
80
+ `dist/char-cnn/options/<name>/` (the option's JSON names them there; the shared wasm kernel stays
81
+ beside the runtime). If you copied `dist/char-cnn/` into your site, copy it again.
82
+ - **char-lite and overlap: a new assignment solver, about a quarter faster.** The matcher's
83
+ assignment step is now millirec's own (`cpp/assign.cpp` in the repository), written for this
84
+ problem: it stops as soon as a template provably cannot matter, and it starts from prices that
85
+ account for the points either side may drop. One recognition against 215 templates went from
86
+ 0.66 ms to 0.49 ms; the wasm is 27.8 KB (was 29.9). Readings can differ from 0.1.1 in close
87
+ calls — on one writer's held-out drawings top-1 is unchanged for capitals and digits and two
88
+ better of 381 for lowercase. Input the matcher cannot use (thousands of points, NaN
89
+ coordinates) no longer traps.
90
+ - **A `recognize()` that timed out no longer poisons its strokes.** When char-lite's worker did
91
+ not answer within 4 s the call resolved `null`, but the request stayed marked as in flight, so
92
+ every later `recognize()` of the same strokes waited 4 s and resolved `null` again without the
93
+ worker being asked. The request is forgotten once nobody is waiting on it (`rawScores()` too).
94
+ - A worker that fails after it has booted releases every waiting call with `null` at once; a
95
+ worker that fails to boot is terminated and its blob URL revoked when `create()` rejects.
96
+ - README: a complete one-file page to start from (ES module from a CDN) and a complete script-tag
97
+ page; which CDNs work (jsDelivr, unpkg — not esm.sh); pin the full version; how to load the
98
+ overlap widget through a bundler; TypeScript notes; where to report bugs.
99
+ - package.json: `repository` (github.com/triplelog/millirec), `bugs` points at its issues.
100
+ - The source is public at github.com/triplelog/millirec, with the CNN trainer, one writer's
101
+ handwriting and a walk-through for training a recognizer for your own symbols (not part of the
102
+ npm download).
103
+
3
104
  ## 0.1.1
4
105
 
5
106
  - **Bundlers**: the package found its own folder with `new URL('./', import.meta.url)`, which Vite
package/README.md CHANGED
@@ -4,13 +4,80 @@ Small, fast handwriting recognition in the browser. Draw a character, get the
4
4
  three likeliest readings back. Runs entirely on the device — no server, no
5
5
  upload of anyone's ink.
6
6
 
7
- Three pieces, pick by what you need to read:
7
+ **[millirec.com](https://millirec.com)** has a pad to try it on and the measurements ·
8
+ source and issues: **[github.com/triplelog/millirec](https://github.com/triplelog/millirec)**
8
9
 
9
- | | reads | size (gzip) | trainable on your own strokes |
10
- |---|---|---|---|
11
- | `millirec/char-lite` | anything you have samples for: digits, letters, punctuation, emoji, made-up symbols | 26 KB + the training set (digits 4 KB, all 27 KB) | **yes** — add samples, add whole new classes |
12
- | `millirec/char-cnn` | capital letters A–Z | 15 KB (`small`) to 47 KB (`fast`); `accurate` 42 KB | refit on a writer's own letters (`personalize`) |
13
- | overlap (script tag) | whole words written letter over letter in one box | 34 KB (script 20 + wasm 14) + training (capitals 19 KB, all 42 KB) + the default word list (38 KB, skipped when you pass `words`) | — |
10
+ ## Try it: one file, no build
11
+
12
+ Save this as `index.html`, serve the folder (`npx serve`, `python3 -m http.server` — a page opened
13
+ straight from disk cannot load the model files) and draw a digit:
14
+
15
+ ```html
16
+ <!doctype html>
17
+ <meta charset="utf-8">
18
+ <div id="pad" style="width: 240px; height: 240px; border: 1px solid #999"></div>
19
+ <p id="out">draw a digit</p>
20
+ <script type="module">
21
+ import { createRecognizer } from 'https://cdn.jsdelivr.net/npm/millirec@0.2.0/dist/index.js'
22
+
23
+ const rec = await createRecognizer('digits')
24
+ rec.attach(document.querySelector('#pad'))
25
+ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
26
+ const r = e.detail.results || [] // best first; empty when the pad was cleared
27
+ document.querySelector('#out').textContent = r.length
28
+ ? r.map((x) => `${x.char} ${Math.round(x.prob * 100)}%`).join(' ')
29
+ : 'draw a digit'
30
+ })
31
+ </script>
32
+ ```
33
+
34
+ Write another digit after a two-second pause and the pad starts over; scribble over the ink to
35
+ clear it.
36
+
37
+ ## Which recognizer?
38
+
39
+ millirec has two engines, and `createRecognizer()` picks between them for you:
40
+
41
+ - **char-cnn** — small neural networks trained on EMNIST, handwriting from hundreds of writers. It
42
+ reads **strangers' handwriting** of digits, capital letters and lowercase letters, does not care
43
+ in which order or direction the strokes were drawn, and costs the same however many classes it
44
+ reads. Its alphabets are fixed when it is trained; `teach()` reads symbols of your own instead.
45
+ - **char-lite** — a point-cloud matcher that compares a drawing with stored example drawings. It
46
+ reads **anything you have examples of** — punctuation, emoji, made-up symbols, a digit set with a
47
+ ★ added — and a new symbol is a data edit, not a training run. Its shipped sets are one writer's
48
+ drawings, and it uses stroke order and direction, so it reads best the hand its examples came
49
+ from: the person who drew them, or a writer who draws the way they do.
50
+
51
+ | you want to read | createRecognizer picks | why |
52
+ |---|---|---|
53
+ | digits, capitals or lowercase letters, from anyone | char-cnn | trained on hundreds of writers: 99.6% of strangers' digits, 98.5% of capitals, 93.8% of lowercase letters |
54
+ | digits, capitals and lowercase in one box | char-cnn (`all`) | 77% exact, 97% the right character of its kind (`c`/`C`, `o`/`O`/`0` and `l`/`I`/`1` are drawn alike); restrict the box with `only` when you know what it takes |
55
+ | punctuation | char-lite | there is no CNN for it |
56
+ | your own symbols, or an alphabet plus a few of your own | char-lite | it can add any class to a set, from a few drawings each |
57
+ | the smallest download | char-cnn, `priority: 'small'` | 10 KB gzipped, against 27 KB plus the set for char-lite |
58
+ | the fastest reading | char-cnn, `priority: 'fast'` | 0.04–0.06 ms per character; char-lite 0.2–1.1 ms, growing with its set |
59
+
60
+ How the numbers were measured: char-cnn on EMNIST test images none of the models was trained on;
61
+ char-lite by cross-validation on the one writer who drew its sets (99–100% on digits, capitals and
62
+ lowercase, 92% on punctuation and on all 68 classes together). **char-lite has not been measured on
63
+ other people's handwriting**, so treat its numbers as what one person's own hand reads. Words written
64
+ letter over letter in one box are a third piece, overlap, built on char-lite (below).
65
+
66
+ ## What is in it
67
+
68
+ | import | what | gzip |
69
+ |---|---|---|
70
+ | `millirec` | `createRecognizer()` and `chooseEngine()`; loads the engine it picks on demand. Also exports char-lite's `MillirecCharLite` and `loadSet`, as 0.1 did, and `attachPad` | 1 KB + the engine (without a bundler, + char-lite's 8 KB module for those re-exports) |
71
+ | `millirec/char-cnn` | the CNN recognizer with a drawing pad, 12 shipped options | 10–51 KB with its models |
72
+ | `millirec/char-cnn/core` | the same without the pad | |
73
+ | `millirec/char-lite` | the matcher with a drawing pad, 5 shipped training sets | 27 KB + the set (digits 4 KB, all 27 KB) |
74
+ | `millirec/char-lite/core` | the same without the pad | |
75
+ | `millirec/pad` | `attachPad(el, recognizer)`: the drawing pad for any recognizer, your own included | 3 KB |
76
+ | `millirec/overlap` | whole words written letter over letter in one box (script tag) | 33 KB + training + word list |
77
+
78
+ Start with `createRecognizer()`. Import an engine directly when you want to fix the choice in your
79
+ code, configure it fully, or ship less: a page that captures strokes itself and imports
80
+ `millirec/char-cnn/core` loads neither the pad nor the other engine.
14
81
 
15
82
  ## Install
16
83
 
@@ -18,44 +85,68 @@ Three pieces, pick by what you need to read:
18
85
  npm install millirec
19
86
  ```
20
87
 
21
- `import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
22
- (use `import`, not `require`), or the script-tag builds below.
88
+ The package is ES modules only (use `import`, not `require`), or the script-tag builds below.
23
89
 
24
- **Browser only.** Recognition needs a browser: char-lite runs its matcher in a Web Worker, char-cnn
25
- draws strokes on a canvas (an `OffscreenCanvas` inside a worker works too). Importing the package
26
- is safe during server-side rendering; call `create()` on the client. In Node, `create()` throws a
27
- message saying so, and the training sets can be imported as JSON
90
+ **Where it runs.** char-lite needs a browser: it runs its matcher in a Web Worker. char-cnn needs
91
+ `fetch` and nothing else — it draws strokes in software, so it also runs inside a Web Worker, and
92
+ anywhere its model files can be fetched over http(s). Importing the package is safe during
93
+ server-side rendering; call `create()` on the client. In Node, a `file:` asset folder cannot be
94
+ fetched and `create()` says so; the training sets and options can be imported as JSON
28
95
  (`import digits from 'millirec/char-lite/sets/digits.json' with { type: 'json' }`) for tooling.
29
96
 
30
- ## char-lite
97
+ **TypeScript**: declarations are included. Importing a set or option as JSON needs
98
+ `resolveJsonModule` (and `esModuleInterop` under `moduleResolution: node10`).
99
+
100
+ ## createRecognizer
31
101
 
32
102
  ```js
33
- import { MillirecCharLite, loadSet } from 'millirec/char-lite'
103
+ import { createRecognizer, chooseEngine } from 'millirec'
34
104
 
35
- const training = await loadSet('digits') // 'all' | 'capitals' | 'digits' | 'lowercase' | 'punctuation'
36
- const rec = await MillirecCharLite.create({ training })
105
+ const rec = await createRecognizer('lowercase') // a string is the alphabet
106
+ const rec = await createRecognizer({ alphabet: 'capitals', priority: 'small' })
107
+ const rec = await createRecognizer({ alphabet: 'digits', examples: { '★': [s1, s2, s3] } }) // digits and a star
108
+ const rec = await createRecognizer({ examples: { yes: [y1, y2, y3], no: [n1, n2, n3] } }) // only your symbols
37
109
 
38
- // a drawing pad that reports after every stroke
39
- const pad = rec.attach(document.querySelector('#pad'))
40
- document.querySelector('#pad').addEventListener('millirec:result', (e) => {
41
- console.log(e.detail.results) // [{ char: '7', prob: 0.91 }, ...]
42
- })
110
+ chooseEngine({ alphabet: 'capitals', priority: 'small' }) // { engine: 'char-cnn', option: 'small', teach: false }, loads nothing
111
+ ```
43
112
 
44
- // or your own strokes: arrays of {x, y} points
45
- await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
113
+ | option | | |
114
+ |---|---|---|
115
+ | `alphabet` | `'digits'`, `'capitals'`, `'lowercase'`, `'all'`, `'punctuation'` | required unless `examples` are given |
116
+ | `priority` | `'accurate'` (default), `'fast'`, `'small'` | picks among the CNN options; char-lite has one build |
117
+ | `examples` | `{ name: [drawing, …] }` | your own symbols: added to `alphabet`, or read alone without one |
118
+ | `engine` | `'auto'` (default), `'cnn'`, `'lite'` | `'cnn'` with `examples` and no alphabet uses char-cnn's `teach()` |
119
+ | `assetBase` | default: beside the module | where you serve the package's `dist/` folder (see "Serving the files") |
46
120
 
47
- rec.destroy() // when you are done with it
121
+ `auto` takes char-cnn for `digits`, `capitals`, `lowercase` and `all`, and char-lite for
122
+ `punctuation` and whenever `examples` are given (the CNN cannot add classes to its alphabets). The
123
+ promise resolves to the engine's own recognizer, `MillirecCharCnn` or `MillirecCharLite`; `rec.engine`
124
+ says which.
125
+
126
+ ## What both engines do
127
+
128
+ The two recognizers share their everyday surface, so switching engines is a one-line change:
129
+
130
+ ```js
131
+ await rec.recognize(strokes) // [{ char, prob }, …] best first, up to three; null for no ink
132
+ await rec.recognize(strokes, { only: 'AEIOU' }) // answer among these classes only
133
+ rec.attach(el, { recognizeOptions: { only: '0123456789' } }) // a drawing pad (below)
134
+ await rec.teach({ star: [d1, d2, d3] }) // read your own symbols instead; { add: true } keeps earlier ones
135
+ rec.forget() // back to the shipped classes
136
+ rec.classes // the shipped classes (teach() returns the taught names)
137
+ rec.engine // 'char-cnn' or 'char-lite'
138
+ rec.destroy() // let go of workers and models
48
139
  ```
49
140
 
50
- Each char-lite instance holds a Web Worker and its own copy of the wasm matcher, so call
51
- `destroy()` when a recognizer is no longer needed (and share one recognizer between several pads
52
- rather than creating one per pad). After `destroy()`, `recognize()` and `rawScores()` resolve
53
- `null`, including calls that were still waiting.
141
+ A drawing is an array of strokes, each an array of `{ x, y }` points in any units (one stroke on its
142
+ own works too). `only` takes a string of one-character classes or an array or `Set` of names.
54
143
 
55
- ### The drawing pad
144
+ ## The drawing pad
56
145
 
57
- `attach(el, options)` mounts a canvas in `el` and returns a `Pad` (`clear()`, `undoClear()`,
58
- `getStrokes()`, `isStale()`, `configure()`, `setInk()`, `repaint()`, `canvas`). Options:
146
+ `rec.attach(el, options)` — or `attachPad(el, rec, options)` from `millirec/pad`, which works with
147
+ any object that has `recognize(strokes)`, a pad-less core included — mounts a canvas in `el` and
148
+ returns a `Pad` (`clear()`, `undoClear()`, `getStrokes()`, `isStale()`, `configure()`, `setInk()`,
149
+ `repaint()`, `canvas`). Options:
59
150
 
60
151
  | option | default | |
61
152
  |---|---|---|
@@ -66,6 +157,7 @@ rather than creating one per pad). After `destroy()`, `recognize()` and `rawScor
66
157
  | `scribble` | null | overrides for the scribble detector's bars (`turns`, `retrace`, `winding`, `cover`) |
67
158
  | `staleAlpha` | 0.3 | opacity of ink once the character has settled (1 keeps it solid) |
68
159
  | `onStale` | — | `(stale) => void`, called on every change of the settled state |
160
+ | `recognizeOptions` | — | passed to every `recognize()` the pad makes, e.g. `{ only: '0123456789' }` |
69
161
 
70
162
  `el` fires two events:
71
163
 
@@ -76,12 +168,43 @@ rather than creating one per pad). After `destroy()`, `recognize()` and `rawScor
76
168
  `undo()` puts it back.
77
169
 
78
170
  Both are typed on `HTMLElementEventMap`, so `el.addEventListener('millirec:result', (e) => e.detail.results)`
79
- type-checks. char-cnn's `attach()` takes the same options and fires the same events.
171
+ type-checks.
80
172
 
81
- ### Training on your users' strokes
173
+ ## char-lite
174
+
175
+ ```js
176
+ import { MillirecCharLite, loadSet } from 'millirec/char-lite'
82
177
 
83
- A class name is any string, so a recognizer can learn one person's hand, or
84
- symbols nobody else uses:
178
+ const training = await loadSet('digits') // 'all' | 'capitals' | 'digits' | 'lowercase' | 'punctuation'
179
+ const rec = await MillirecCharLite.create({ training })
180
+
181
+ // a drawing pad that reports after every stroke
182
+ const pad = rec.attach(document.querySelector('#pad'))
183
+ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
184
+ console.log(e.detail.results) // [{ char: '7', prob: 0.91 }, ...]
185
+ })
186
+
187
+ // or your own strokes: arrays of {x, y} points
188
+ await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
189
+
190
+ rec.destroy() // when you are done with it
191
+ ```
192
+
193
+ Each char-lite instance holds a Web Worker and its own copy of the wasm matcher (a second one while
194
+ something is taught), so call `destroy()` when a recognizer is no longer needed (and share one
195
+ recognizer between several pads rather than creating one per pad). After `destroy()`,
196
+ `recognize()` and `rawScores()` resolve `null`, including calls that were still waiting.
197
+
198
+ `recognize(strokes, { only })` scores every example exactly, so it is slower than a plain
199
+ `recognize()` — which gives up early on examples that cannot win: both give the same first answer,
200
+ but the runner-ups and their probabilities can differ. `millirec/char-lite/core` is the same
201
+ recognizer without the pad.
202
+
203
+ ### Your own symbols, and your users' strokes
204
+
205
+ A class name is any string. `teach()` reads symbols of your own alone, from a few drawings each
206
+ (the same call as char-cnn's). To ADD drawings or classes to a shipped set — one person's sevens, a
207
+ ★ beside the digits — build the training with `withSamples()`:
85
208
 
86
209
  ```js
87
210
  const mine = MillirecCharLite.withSamples(training, {
@@ -104,18 +227,88 @@ training set can also be built offline and loaded with `fetch`.
104
227
  ```js
105
228
  import { MillirecCharCnn } from 'millirec/char-cnn'
106
229
 
107
- const rec = await MillirecCharCnn.create() // the 'accurate' option
108
- // or: await MillirecCharCnn.create({ option: 'fast' }) // 'accurate' | 'fast' | 'small'
109
- // (a bare name works too: create('fast'))
230
+ const rec = await MillirecCharCnn.create() // the 'accurate' option: capital letters
231
+ // or: await MillirecCharCnn.create({ option: 'digits' }) // see the table below
232
+ // (a bare name works too: create('digits'))
110
233
  rec.attach(document.querySelector('#pad'))
111
234
  await rec.recognize(strokes, { only: 'AEIOU' }) // restrict the answer to some letters
112
235
  await rec.personalize({ A: [a1, a2, a3], R: [r1, r2] }) // lean toward this writer's hand
113
236
  rec.destroy() // let go of the models
114
237
  ```
115
238
 
239
+ | option | reads | strangers' handwriting read right | gzip, with the pad |
240
+ |---|---|---|---|
241
+ | `accurate` (default) | capitals A–Z | 98.5% | 43 KB |
242
+ | `fast` | capitals A–Z | 97.9% | 51 KB |
243
+ | `small` | capitals A–Z | 96.8% | 10 KB (no pad, no wasm) |
244
+ | `digits` | 0–9 | 99.6% | 41 KB |
245
+ | `digits-fast` | 0–9 | 99.5% | 46 KB |
246
+ | `digits-small` | 0–9 | 99.1% | 10 KB (no pad, no wasm) |
247
+ | `lowercase` | a–z | 93.8% | 43 KB |
248
+ | `lowercase-fast` | a–z | 91.9% | 48 KB |
249
+ | `lowercase-small` | a–z | 90.4% | 10 KB (no pad, no wasm) |
250
+ | `all` | 0–9, A–Z, a–z | 77.2% (96.6% of its own kind) | 46 KB |
251
+ | `all-fast` | 0–9, A–Z, a–z | 74.0% (95.0% of its own kind) | 51 KB |
252
+ | `all-small` | 0–9, A–Z, a–z | 71.5% (94.3% of its own kind) | 11 KB (no pad, no wasm) |
253
+
254
+ Measured on EMNIST test images, which none of the models were trained on (7,800 capitals, 3,000
255
+ digits, 7,800 lowercase letters, 18,600 of all 62 together, from hundreds of writers). Every
256
+ alphabet has the same three shapes: the plain name (`digits`, …) is the `accurate` pair — a small
257
+ network answers, a larger one takes the close calls; `-fast` sends fewer calls to a pruned larger
258
+ one; `-small` is the small network alone, in plain JavaScript. Most of what `lowercase` gets wrong
259
+ is `g`/`q` and `i`/`l`/`j`, which people draw alike. `all` reads digits, capitals and lowercase
260
+ letters at once, but many letters are drawn the same in both cases (`c C`, `o O 0`, `s S`, `l I 1`),
261
+ so the exact character is often a toss-up — the figure in brackets is how often the right one is the
262
+ likeliest of its own kind (an `I` among the capitals: `recognize(strokes, { only })` with that kind's
263
+ characters gets you that). When you know which alphabet a
264
+ box takes, use that alphabet's option.
265
+
116
266
  `millirec/char-cnn/core` is the same recognizer without the drawing pad; it also runs inside a
117
- Web Worker (it draws on an `OffscreenCanvas` there). After `destroy()`, `recognize()` and
118
- `personalize()` return `null` and `embedding()` throws.
267
+ Web Worker (strokes are drawn in software, so it needs no canvas). After `destroy()`, `recognize()`
268
+ and `personalize()` return `null` and `embedding()` throws.
269
+
270
+ ### Your own symbols
271
+
272
+ **No training: `teach()`.** Give the recognizer a few drawings of each symbol and it reads them —
273
+ letters of another alphabet, a rating scale, proof-reading marks, emoji:
274
+
275
+ ```js
276
+ const rec = await MillirecCharCnn.create() // 'accurate' (or 'fast')
277
+ await rec.teach({
278
+ star: [star1, star2, star3], // each a drawing: [[{x, y}, …], …]
279
+ heart: [heart1, heart2, heart3],
280
+ '✓': [tick1, tick2, tick3],
281
+ })
282
+ await rec.recognize(strokes) // [{ char: 'star', prob: 0.93 }, …]
283
+ await rec.teach({ arrow: [a1, a2, a3] }, { add: true }) // one more, keeping the others
284
+ rec.forget() // back to the letters
285
+ ```
286
+
287
+ Each example is kept as what the network makes of it, and a new drawing is given to the name of
288
+ its nearest example; after `teach()` the recognizer answers among the taught names only. Nothing is
289
+ trained and nothing is stored: keep the example strokes yourself (`pad.getStrokes()`) and call
290
+ `teach()` again when the page loads, or pass them as `create({ examples })`.
291
+
292
+ How well it works, measured with the shipped `accurate` network — which was trained on capital
293
+ letters only — on one writer's drawings of things it has never seen, tested on that writer's other
294
+ drawings:
295
+
296
+ | examples of each | digits (10) | lowercase (26) | six punctuation marks |
297
+ |---|---|---|---|
298
+ | 1 | 92% | 86% | 84% |
299
+ | 3 | 96% | 93% | 88% |
300
+ | 5 | 99% | 96% | 89% |
301
+
302
+ Three is a good start and five is better; draw the variants people really use. Symbols that
303
+ differ only in size or position (`.` and `,`, `o` and `O`) cannot be told apart: every drawing is
304
+ scaled to fill the picture before it is read.
305
+
306
+ **With training.** `create()` also takes any model in the same format:
307
+ `MillirecCharCnn.create({ classes, stages, assetBase })`, where `classes` is a string of single
308
+ characters or a list of names. Training one from your own drawings — a dozen per symbol, a few
309
+ seconds — is a four-command walk-through in the repository:
310
+ [train your own recognizer](https://github.com/triplelog/millirec/blob/main/packages/millirec/train/README.md).
311
+ That is the route to the last few percent, the smallest download, and a recognizer for many writers.
119
312
 
120
313
  ## overlap: words written in one box
121
314
 
@@ -133,7 +326,11 @@ for now:
133
326
  Copy `dist/overlap/` to your site (or load it from a CDN); the script finds its wasm, training and
134
327
  default word list beside itself. `set` is `capitals`, `lowercase`, `digits`, `punctuation` or `all`.
135
328
  TypeScript declarations for the `MillirecOverlap` global and its `millirec-overlap:*` events come
136
- with `import type {} from 'millirec/overlap'` (types only — the widget itself is the script tag).
329
+ with `import type {} from 'millirec/overlap'`. That path is **types only**: the widget itself is
330
+ the script tag, and a plain `import 'millirec/overlap'` fails with "path not exported". To pull the
331
+ script through a bundler instead, import the file —
332
+ `import 'millirec/overlap/millirec-overlap.min.js'` — and pass `assetBase` to `create()`, since a
333
+ bundled script can no longer find the files beside it.
137
334
 
138
335
  ## Serving the files
139
336
 
@@ -145,8 +342,17 @@ files where they are — no bundler, an import map, or a dev server that serves
145
342
  bundle and the other files are not emitted with it. Copy the recognizer's folder into the folder
146
343
  your site serves as-is, and pass its URL as `assetBase` to every call that loads something:
147
344
 
345
+ With `createRecognizer()`, copy the whole `dist/` folder and pass its URL:
346
+
148
347
  ```js
149
- import { MillirecCharLite, loadSet } from 'millirec'
348
+ import { createRecognizer } from 'millirec'
349
+ const rec = await createRecognizer({ alphabet: 'digits', assetBase: '/millirec/' }) // copied from node_modules/millirec/dist/
350
+ ```
351
+
352
+ With an engine imported directly, copy that engine's folder and pass it:
353
+
354
+ ```js
355
+ import { MillirecCharLite, loadSet } from 'millirec/char-lite'
150
356
  import { MillirecCharCnn } from 'millirec/char-cnn'
151
357
 
152
358
  const lite = '/millirec/char-lite/' // copied from node_modules/millirec/dist/char-lite/
@@ -164,6 +370,9 @@ mkdir -p public/millirec
164
370
  cp -R node_modules/millirec/dist/char-lite node_modules/millirec/dist/char-cnn public/millirec/
165
371
  ```
166
372
 
373
+ (that is the layout `createRecognizer({ assetBase: '/millirec/' })` expects: `char-cnn/` and
374
+ `char-lite/` side by side.)
375
+
167
376
  (a `postinstall` script with those two lines keeps it in step with the installed version).
168
377
  In `vite` dev alone, `optimizeDeps: { exclude: ['millirec'] }` also works without copying (the dev
169
378
  server then serves the package from `node_modules`), but `vite build` does not emit the files, so a
@@ -201,25 +410,43 @@ If your site sends a CSP, the recognizers need:
201
410
 
202
411
  ## Script tag / CDN
203
412
 
204
- No build step needed:
413
+ No build step and no modules — a complete page:
205
414
 
206
415
  ```html
207
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/millirec-char-lite.min.js"></script>
208
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/sets/digits.js"></script>
416
+ <!doctype html>
417
+ <meta charset="utf-8">
418
+ <div id="pad" style="width: 240px; height: 240px; border: 1px solid #999"></div>
419
+ <p id="out">draw a digit</p>
420
+ <script src="https://cdn.jsdelivr.net/npm/millirec@0.2.0/dist/char-lite/millirec-char-lite.min.js"></script>
421
+ <script src="https://cdn.jsdelivr.net/npm/millirec@0.2.0/dist/char-lite/sets/digits.js"></script>
209
422
  <script>
210
- MillirecCharLite.create().then((rec) => rec.attach(document.querySelector('#pad')))
423
+ MillirecCharLite.create().then((rec) => {
424
+ rec.attach(document.querySelector('#pad'))
425
+ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
426
+ var r = e.detail.results || []
427
+ document.querySelector('#out').textContent = r.length ? r.map((x) => x.char).join(' ') : 'draw a digit'
428
+ })
429
+ })
211
430
  </script>
212
431
  ```
213
432
 
214
433
  `sets/<name>.js` sets `window.MILLIREC_TRAINING`; for char-cnn load
215
434
  `dist/char-cnn/options/accurate.js` and then `millirec-char-cnn.min.js`. The
216
435
  script finds its worker and wasm next to itself, on any origin that sends CORS
217
- headers (jsDelivr and unpkg do).
436
+ headers.
437
+
438
+ **Which CDNs work** (tried in a browser from another origin): **jsDelivr** and **unpkg**, for the
439
+ script tags and for the ES modules (`…/dist/char-lite/index.js`, and jsDelivr's `/+esm`). **esm.sh
440
+ does not**: it serves a rewritten copy of the JavaScript without the worker and wasm files beside
441
+ it, so `create()` reports that they are not served.
442
+
443
+ **Pin the full version** (`@0.2.0`, not `@0.1`). The script, its worker and its wasm are separate
444
+ files that must come from the same release, and a CDN resolves a version range file by file.
218
445
 
219
446
  ## Stable paths
220
447
 
221
448
  The documented entry points are the stable API: `millirec`, `millirec/char-lite`,
222
- `millirec/char-cnn`, `millirec/char-cnn/core`, `millirec/char-lite/sets/<name>.json`,
449
+ `millirec/char-lite/core`, `millirec/char-cnn`, `millirec/char-cnn/core`, `millirec/pad`, `millirec/char-lite/sets/<name>.json`,
223
450
  `millirec/char-cnn/options/<name>.json`, `millirec/overlap/<file>` and the script-tag files in "Script tag / CDN"
224
451
  above. `millirec/dist/*` exposes every built file as an escape hatch; the layout under it may change
225
452
  in any release.
@@ -228,8 +455,9 @@ in any release.
228
455
 
229
456
  - **char-lite training sets and the overlap templates**: one writer's own handwriting, drawn for
230
457
  this project.
231
- - **char-cnn models**: small CNNs trained on handwritten capitals from EMNIST (derived from NIST
232
- Special Database 19).
458
+ - **char-cnn models**: small CNNs trained on handwritten characters from EMNIST (derived from NIST
459
+ Special Database 19) — capitals for `accurate`, `fast` and `small`; digits and lowercase letters,
460
+ plus one writer's own drawings, for `digits` and `lowercase`.
233
461
  - **overlap's default word list** (`words.json`): the 10,000 commonest English words by millirec's
234
462
  own count over about 1.9 billion words of English, mostly news — names and offensive words
235
463
  removed. It leans toward news vocabulary; pass your own `words` for anything specific.
@@ -238,7 +466,14 @@ Recognition runs entirely in the browser: nothing a user draws is sent anywhere
238
466
 
239
467
  ## Versions
240
468
 
241
- 0.x: the API may still change between minor versions. 1.0 will mark it stable.
469
+ 0.x: the API may still change between minor versions. 1.0 will mark it stable. Changes are in
470
+ [CHANGELOG.md](https://github.com/triplelog/millirec/blob/main/packages/millirec/CHANGELOG.md).
471
+
472
+ ## Questions and bugs
473
+
474
+ [Open an issue](https://github.com/triplelog/millirec/issues). A drawing that reads wrong is most
475
+ useful with its strokes (`pad.getStrokes()`, or `e.detail.strokes` from the result event) and the
476
+ set or option in use.
242
477
 
243
478
  ## License
244
479
 
Binary file
@@ -10,15 +10,20 @@ export interface CreateOptions extends Partial<CnnConfig> {
10
10
  * or page-relative; the trailing slash is optional. It (and `kernel`) decide what code is loaded:
11
11
  * never fill them from a URL parameter or user input. */
12
12
  assetBase?: string
13
+ /** Symbols of your own, a few drawings each: the same as calling `teach(examples)` after `create()`. */
14
+ examples?: Record<string, Array<Strokes | Stroke>>
13
15
  }
14
16
 
15
- export declare const OPTIONS: readonly ['accurate', 'fast', 'small']
17
+ /** `accurate`, `fast` and `small` read capital letters A–Z; `digits` reads 0–9 and `lowercase` a–z. */
18
+ export declare const OPTIONS: readonly ['accurate', 'fast', 'small', 'digits', 'digits-fast', 'digits-small', 'lowercase', 'lowercase-fast', 'lowercase-small', 'all', 'all-fast', 'all-small']
16
19
  export type OptionName = (typeof OPTIONS)[number]
17
20
  export declare function loadOption(name: OptionName, opts?: { assetBase?: string }): Promise<CnnConfig>
18
21
 
19
22
  export declare class MillirecCharCnnCore {
20
23
  /** A string is a shipped option's name: create('fast') = create({ option: 'fast' }). */
21
24
  static create(opts?: CreateOptions | OptionName): Promise<MillirecCharCnnCore>
25
+ readonly engine: 'char-cnn'
26
+ /** The option's classes (teach() does not change them; it returns the taught names). */
22
27
  readonly classes: string[]
23
28
  readonly ready: Promise<void>
24
29
  /** `only` restricts the reading to these classes. */
@@ -29,6 +34,15 @@ export declare class MillirecCharCnnCore {
29
34
  personalize(samples: Record<string, Array<Strokes | Stroke>>, opts?: { steps?: number; lr?: number; prior?: number }): Promise<{ n: number; classes: string[] } | null>
30
35
  /** Back to the shipped head. */
31
36
  depersonalize(): void
37
+ /**
38
+ * Read symbols of your own from a few drawings of each, with no training: every drawing is kept as what the
39
+ * last stage's network makes of it, and from then on `recognize()` answers among the taught names only, by the
40
+ * nearest example. Names are any strings. `{ add: true }` keeps what was taught before. Resolves `null` when
41
+ * nothing usable was given. Best on an option whose last stage is the larger network (`accurate`, `fast`).
42
+ */
43
+ teach(examples: Record<string, Array<Strokes | Stroke>>, opts?: { add?: boolean }): Promise<{ classes: string[]; n: number } | null>
44
+ /** Drop what `teach()` learned: `recognize()` reads the option's own classes again. */
45
+ forget(): void
32
46
  /** The last stage's unit embedding of a drawing — what the head reads. Throws after destroy(). */
33
47
  embedding(strokes: Strokes | Stroke): Promise<Float32Array>
34
48
  /** Let go of the models; recognize() and personalize() return null afterwards. */