millirec 0.1.2 → 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 (76) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +171 -58
  3. package/dist/char-cnn/cnn-web.wasm +0 -0
  4. package/dist/char-cnn/core.d.ts +3 -1
  5. package/dist/char-cnn/core.js +145 -99
  6. package/dist/char-cnn/index.d.ts +1 -1
  7. package/dist/char-cnn/index.js +198 -136
  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 +2 -2
  12. package/dist/char-cnn/options/accurate.json +1 -1
  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-tiny.head.bin +0 -0
  31. package/dist/char-cnn/options/digits-fast/digits-base-p25.bin +0 -0
  32. package/dist/char-cnn/options/digits-fast/digits-base-p25.head.bin +0 -0
  33. package/dist/char-cnn/options/digits-fast/digits-tiny.bin +0 -0
  34. package/dist/char-cnn/options/digits-fast/digits-tiny.head.bin +0 -0
  35. package/dist/char-cnn/options/digits-fast.js +17 -0
  36. package/dist/char-cnn/options/digits-fast.json +15 -0
  37. package/dist/char-cnn/options/digits-small/digits-tiny-qat4.head.bin +0 -0
  38. package/dist/char-cnn/options/digits-small/digits-tiny-qat4.q4.bin +0 -0
  39. package/dist/char-cnn/options/digits-small.js +11 -0
  40. package/dist/char-cnn/options/digits-small.json +9 -0
  41. package/dist/char-cnn/options/digits.js +2 -2
  42. package/dist/char-cnn/options/digits.json +1 -1
  43. package/dist/char-cnn/options/fast/base-p25.head.bin +0 -0
  44. package/dist/char-cnn/options/fast/tiny.head.bin +0 -0
  45. package/dist/char-cnn/options/fast.js +2 -2
  46. package/dist/char-cnn/options/fast.json +1 -1
  47. package/dist/char-cnn/options/lowercase/lowercase-tiny.head.bin +0 -0
  48. package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.bin +0 -0
  49. package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.head.bin +0 -0
  50. package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.bin +0 -0
  51. package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.head.bin +0 -0
  52. package/dist/char-cnn/options/lowercase-fast.js +17 -0
  53. package/dist/char-cnn/options/lowercase-fast.json +15 -0
  54. package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.head.bin +0 -0
  55. package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.q4.bin +0 -0
  56. package/dist/char-cnn/options/lowercase-small.js +11 -0
  57. package/dist/char-cnn/options/lowercase-small.json +9 -0
  58. package/dist/char-cnn/options/lowercase.js +2 -2
  59. package/dist/char-cnn/options/lowercase.json +1 -1
  60. package/dist/char-cnn/options/small/tiny.head.bin +0 -0
  61. package/dist/char-cnn/options/small/tiny.q4.bin +0 -0
  62. package/dist/char-cnn/options/small.js +2 -2
  63. package/dist/char-cnn/options/small.json +1 -1
  64. package/dist/char-lite/core.d.ts +1 -0
  65. package/dist/char-lite/core.js +628 -0
  66. package/dist/char-lite/index.d.ts +28 -8
  67. package/dist/char-lite/index.js +845 -717
  68. package/dist/char-lite/millirec-char-lite.min.js +1 -1
  69. package/dist/char-lite/sets.json +17 -17
  70. package/dist/index.d.ts +35 -0
  71. package/dist/index.js +88 -0
  72. package/dist/overlap/millirec-overlap.min.js +7 -7
  73. package/dist/pad/index.d.ts +8 -0
  74. package/dist/pad/index.js +482 -0
  75. package/package.json +21 -7
  76. package/dist/char-cnn/options/small/tiny.bin +0 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,70 @@
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
+
3
68
  ## 0.1.2
4
69
 
5
70
  - **char-cnn reads digits and lowercase letters**: two new options, `create('digits')` (99.6% of
package/README.md CHANGED
@@ -10,7 +10,7 @@ source and issues: **[github.com/triplelog/millirec](https://github.com/triplelo
10
10
  ## Try it: one file, no build
11
11
 
12
12
  Save this as `index.html`, serve the folder (`npx serve`, `python3 -m http.server` — a page opened
13
- straight from disk cannot start the worker) and draw a digit:
13
+ straight from disk cannot load the model files) and draw a digit:
14
14
 
15
15
  ```html
16
16
  <!doctype html>
@@ -18,9 +18,9 @@ straight from disk cannot start the worker) and draw a digit:
18
18
  <div id="pad" style="width: 240px; height: 240px; border: 1px solid #999"></div>
19
19
  <p id="out">draw a digit</p>
20
20
  <script type="module">
21
- import { MillirecCharLite, loadSet } from 'https://cdn.jsdelivr.net/npm/millirec@0.1.2/dist/char-lite/index.js'
21
+ import { createRecognizer } from 'https://cdn.jsdelivr.net/npm/millirec@0.2.0/dist/index.js'
22
22
 
23
- const rec = await MillirecCharLite.create({ training: await loadSet('digits') })
23
+ const rec = await createRecognizer('digits')
24
24
  rec.attach(document.querySelector('#pad'))
25
25
  document.querySelector('#pad').addEventListener('millirec:result', (e) => {
26
26
  const r = e.detail.results || [] // best first; empty when the pad was cleared
@@ -34,15 +34,50 @@ straight from disk cannot start the worker) and draw a digit:
34
34
  Write another digit after a two-second pause and the pad starts over; scribble over the ink to
35
35
  clear it.
36
36
 
37
- ## What is in it
37
+ ## Which recognizer?
38
38
 
39
- Three pieces, pick by what you need to read:
39
+ millirec has two engines, and `createRecognizer()` picks between them for you:
40
40
 
41
- | | reads | size (gzip) | trainable on your own strokes |
42
- |---|---|---|---|
43
- | `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 |
44
- | `millirec/char-cnn` | capital letters, lowercase letters or digits — and symbols of your own from a few drawings each (`teach`) | 15 KB (`small`) to 47 KB (`fast`); `accurate`, `digits`, `lowercase` about 41 KB each | `teach` new symbols with no training; `personalize` toward one writer; or train a model |
45
- | 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`) | — |
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.
46
81
 
47
82
  ## Install
48
83
 
@@ -50,47 +85,68 @@ Three pieces, pick by what you need to read:
50
85
  npm install millirec
51
86
  ```
52
87
 
53
- `import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
54
- (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.
55
89
 
56
- **Browser only.** Recognition needs a browser: char-lite runs its matcher in a Web Worker, char-cnn
57
- draws strokes on a canvas (an `OffscreenCanvas` inside a worker works too). Importing the package
58
- is safe during server-side rendering; call `create()` on the client. In Node, `create()` throws a
59
- 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
60
95
  (`import digits from 'millirec/char-lite/sets/digits.json' with { type: 'json' }`) for tooling.
61
96
 
62
97
  **TypeScript**: declarations are included. Importing a set or option as JSON needs
63
98
  `resolveJsonModule` (and `esModuleInterop` under `moduleResolution: node10`).
64
99
 
65
- ## char-lite
100
+ ## createRecognizer
66
101
 
67
102
  ```js
68
- import { MillirecCharLite, loadSet } from 'millirec/char-lite'
103
+ import { createRecognizer, chooseEngine } from 'millirec'
69
104
 
70
- const training = await loadSet('digits') // 'all' | 'capitals' | 'digits' | 'lowercase' | 'punctuation'
71
- 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
72
109
 
73
- // a drawing pad that reports after every stroke
74
- const pad = rec.attach(document.querySelector('#pad'))
75
- document.querySelector('#pad').addEventListener('millirec:result', (e) => {
76
- console.log(e.detail.results) // [{ char: '7', prob: 0.91 }, ...]
77
- })
110
+ chooseEngine({ alphabet: 'capitals', priority: 'small' }) // { engine: 'char-cnn', option: 'small', teach: false }, loads nothing
111
+ ```
78
112
 
79
- // or your own strokes: arrays of {x, y} points
80
- 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") |
81
120
 
82
- 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
83
139
  ```
84
140
 
85
- Each char-lite instance holds a Web Worker and its own copy of the wasm matcher, so call
86
- `destroy()` when a recognizer is no longer needed (and share one recognizer between several pads
87
- rather than creating one per pad). After `destroy()`, `recognize()` and `rawScores()` resolve
88
- `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.
89
143
 
90
- ### The drawing pad
144
+ ## The drawing pad
91
145
 
92
- `attach(el, options)` mounts a canvas in `el` and returns a `Pad` (`clear()`, `undoClear()`,
93
- `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:
94
150
 
95
151
  | option | default | |
96
152
  |---|---|---|
@@ -101,6 +157,7 @@ rather than creating one per pad). After `destroy()`, `recognize()` and `rawScor
101
157
  | `scribble` | null | overrides for the scribble detector's bars (`turns`, `retrace`, `winding`, `cover`) |
102
158
  | `staleAlpha` | 0.3 | opacity of ink once the character has settled (1 keeps it solid) |
103
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' }` |
104
161
 
105
162
  `el` fires two events:
106
163
 
@@ -111,12 +168,43 @@ rather than creating one per pad). After `destroy()`, `recognize()` and `rawScor
111
168
  `undo()` puts it back.
112
169
 
113
170
  Both are typed on `HTMLElementEventMap`, so `el.addEventListener('millirec:result', (e) => e.detail.results)`
114
- type-checks. char-cnn's `attach()` takes the same options and fires the same events.
171
+ type-checks.
115
172
 
116
- ### Training on your users' strokes
173
+ ## char-lite
117
174
 
118
- A class name is any string, so a recognizer can learn one person's hand, or
119
- symbols nobody else uses:
175
+ ```js
176
+ import { MillirecCharLite, loadSet } from 'millirec/char-lite'
177
+
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()`:
120
208
 
121
209
  ```js
122
210
  const mine = MillirecCharLite.withSamples(training, {
@@ -150,22 +238,34 @@ rec.destroy() // let go of the mo
150
238
 
151
239
  | option | reads | strangers' handwriting read right | gzip, with the pad |
152
240
  |---|---|---|---|
153
- | `accurate` (default) | capitals A–Z | 98.5% | 41 KB |
154
- | `fast` | capitals A–Z | 97.8% | 49 KB |
155
- | `small` | capitals A–Z | 96.4% | 10 KB (no pad, no wasm) |
156
- | `digits` | 0–9 | 99.6% | 40 KB |
157
- | `lowercase` | a–z | 93.7% | 42 KB |
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) |
158
253
 
159
254
  Measured on EMNIST test images, which none of the models were trained on (7,800 capitals, 3,000
160
- digits, 7,800 lowercase letters, from hundreds of writers). `digits` and `lowercase` are the same
161
- pair of networks as `accurate` — a small one answers, a larger one takes the close calls. Most of
162
- what `lowercase` gets wrong is `g`/`q` and `i`/`l`/`j`, which people draw alike. One recognizer
163
- reads one alphabet; to read two, create two and take the more confident answer, or `teach` your
164
- own set.
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.
165
265
 
166
266
  `millirec/char-cnn/core` is the same recognizer without the drawing pad; it also runs inside a
167
- Web Worker (it draws on an `OffscreenCanvas` there). After `destroy()`, `recognize()` and
168
- `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.
169
269
 
170
270
  ### Your own symbols
171
271
 
@@ -242,8 +342,17 @@ files where they are — no bundler, an import map, or a dev server that serves
242
342
  bundle and the other files are not emitted with it. Copy the recognizer's folder into the folder
243
343
  your site serves as-is, and pass its URL as `assetBase` to every call that loads something:
244
344
 
345
+ With `createRecognizer()`, copy the whole `dist/` folder and pass its URL:
346
+
245
347
  ```js
246
- 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'
247
356
  import { MillirecCharCnn } from 'millirec/char-cnn'
248
357
 
249
358
  const lite = '/millirec/char-lite/' // copied from node_modules/millirec/dist/char-lite/
@@ -261,6 +370,9 @@ mkdir -p public/millirec
261
370
  cp -R node_modules/millirec/dist/char-lite node_modules/millirec/dist/char-cnn public/millirec/
262
371
  ```
263
372
 
373
+ (that is the layout `createRecognizer({ assetBase: '/millirec/' })` expects: `char-cnn/` and
374
+ `char-lite/` side by side.)
375
+
264
376
  (a `postinstall` script with those two lines keeps it in step with the installed version).
265
377
  In `vite` dev alone, `optimizeDeps: { exclude: ['millirec'] }` also works without copying (the dev
266
378
  server then serves the package from `node_modules`), but `vite build` does not emit the files, so a
@@ -305,8 +417,8 @@ No build step and no modules — a complete page:
305
417
  <meta charset="utf-8">
306
418
  <div id="pad" style="width: 240px; height: 240px; border: 1px solid #999"></div>
307
419
  <p id="out">draw a digit</p>
308
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1.2/dist/char-lite/millirec-char-lite.min.js"></script>
309
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1.2/dist/char-lite/sets/digits.js"></script>
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>
310
422
  <script>
311
423
  MillirecCharLite.create().then((rec) => {
312
424
  rec.attach(document.querySelector('#pad'))
@@ -328,13 +440,13 @@ script tags and for the ES modules (`…/dist/char-lite/index.js`, and jsDelivr'
328
440
  does not**: it serves a rewritten copy of the JavaScript without the worker and wasm files beside
329
441
  it, so `create()` reports that they are not served.
330
442
 
331
- **Pin the full version** (`@0.1.2`, not `@0.1`). The script, its worker and its wasm are separate
443
+ **Pin the full version** (`@0.2.0`, not `@0.1`). The script, its worker and its wasm are separate
332
444
  files that must come from the same release, and a CDN resolves a version range file by file.
333
445
 
334
446
  ## Stable paths
335
447
 
336
448
  The documented entry points are the stable API: `millirec`, `millirec/char-lite`,
337
- `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`,
338
450
  `millirec/char-cnn/options/<name>.json`, `millirec/overlap/<file>` and the script-tag files in "Script tag / CDN"
339
451
  above. `millirec/dist/*` exposes every built file as an escape hatch; the layout under it may change
340
452
  in any release.
@@ -343,8 +455,9 @@ in any release.
343
455
 
344
456
  - **char-lite training sets and the overlap templates**: one writer's own handwriting, drawn for
345
457
  this project.
346
- - **char-cnn models**: small CNNs trained on handwritten capitals from EMNIST (derived from NIST
347
- 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`.
348
461
  - **overlap's default word list** (`words.json`): the 10,000 commonest English words by millirec's
349
462
  own count over about 1.9 billion words of English, mostly news — names and offensive words
350
463
  removed. It leans toward news vocabulary; pass your own `words` for anything specific.
Binary file
@@ -15,13 +15,15 @@ export interface CreateOptions extends Partial<CnnConfig> {
15
15
  }
16
16
 
17
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', 'lowercase']
18
+ export declare const OPTIONS: readonly ['accurate', 'fast', 'small', 'digits', 'digits-fast', 'digits-small', 'lowercase', 'lowercase-fast', 'lowercase-small', 'all', 'all-fast', 'all-small']
19
19
  export type OptionName = (typeof OPTIONS)[number]
20
20
  export declare function loadOption(name: OptionName, opts?: { assetBase?: string }): Promise<CnnConfig>
21
21
 
22
22
  export declare class MillirecCharCnnCore {
23
23
  /** A string is a shipped option's name: create('fast') = create({ option: 'fast' }). */
24
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). */
25
27
  readonly classes: string[]
26
28
  readonly ready: Promise<void>
27
29
  /** `only` restricts the reading to these classes. */