millirec 0.1.0 → 0.1.2

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 (44) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +229 -19
  3. package/dist/char-cnn/core.d.ts +18 -5
  4. package/dist/char-cnn/core.js +152 -25
  5. package/dist/char-cnn/index.d.ts +3 -2
  6. package/dist/char-cnn/index.js +152 -25
  7. package/dist/char-cnn/millirec-char-cnn-core.min.js +1 -1
  8. package/dist/char-cnn/millirec-char-cnn.min.js +1 -1
  9. package/dist/char-cnn/options/accurate.js +4 -4
  10. package/dist/char-cnn/options/accurate.json +4 -4
  11. package/dist/char-cnn/options/digits/digits-base.head.bin +0 -0
  12. package/dist/char-cnn/options/digits/digits-base.q4.bin +0 -0
  13. package/dist/char-cnn/options/digits/digits-tiny.bin +0 -0
  14. package/dist/char-cnn/options/digits/digits-tiny.head.bin +0 -0
  15. package/dist/char-cnn/options/digits.js +17 -0
  16. package/dist/char-cnn/options/digits.json +15 -0
  17. package/dist/char-cnn/options/fast/tiny.bin +0 -0
  18. package/dist/char-cnn/options/fast/tiny.head.bin +0 -0
  19. package/dist/char-cnn/options/fast.js +4 -4
  20. package/dist/char-cnn/options/fast.json +4 -4
  21. package/dist/char-cnn/options/lowercase/lowercase-base.head.bin +0 -0
  22. package/dist/char-cnn/options/lowercase/lowercase-base.q4.bin +0 -0
  23. package/dist/char-cnn/options/lowercase/lowercase-tiny.bin +0 -0
  24. package/dist/char-cnn/options/lowercase/lowercase-tiny.head.bin +0 -0
  25. package/dist/char-cnn/options/lowercase.js +17 -0
  26. package/dist/char-cnn/options/lowercase.json +15 -0
  27. package/dist/char-cnn/options/small/tiny.bin +0 -0
  28. package/dist/char-cnn/options/small/tiny.head.bin +0 -0
  29. package/dist/char-cnn/options/small.js +2 -2
  30. package/dist/char-cnn/options/small.json +2 -2
  31. package/dist/char-lite/index.d.ts +26 -4
  32. package/dist/char-lite/index.js +113 -11
  33. package/dist/char-lite/millirec-char-lite.min.js +1 -1
  34. package/dist/char-lite/millirec.wasm +0 -0
  35. package/dist/char-lite/sets.json +25 -29
  36. package/dist/overlap/index.d.ts +139 -0
  37. package/dist/overlap/millirec.wasm +0 -0
  38. package/package.json +45 -3
  39. /package/dist/char-cnn/{base.head.bin → options/accurate/base.head.bin} +0 -0
  40. /package/dist/char-cnn/{base.q4.bin → options/accurate/base.q4.bin} +0 -0
  41. /package/dist/char-cnn/{tiny.bin → options/accurate/tiny.bin} +0 -0
  42. /package/dist/char-cnn/{tiny.head.bin → options/accurate/tiny.head.bin} +0 -0
  43. /package/dist/char-cnn/{base-p25.bin → options/fast/base-p25.bin} +0 -0
  44. /package/dist/char-cnn/{base-p25.head.bin → options/fast/base-p25.head.bin} +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,71 @@
1
+ # Changelog
2
+
3
+ ## 0.1.2
4
+
5
+ - **char-cnn reads digits and lowercase letters**: two new options, `create('digits')` (99.6% of
6
+ strangers' digits) and `create('lowercase')` (93.7%), the same pair of networks as `accurate`,
7
+ trained on EMNIST plus this project's own writer.
8
+ - **`teach()`: symbols of your own with no training.** `rec.teach({ star: [d1, d2, d3], … })` keeps
9
+ each drawing as what the network makes of it and reads new drawings by the nearest example;
10
+ `forget()` undoes it, `create({ examples })` does it at creation. Three examples per class read
11
+ 96% of one writer's digits with the capitals-only network.
12
+ - **`fast` and `small` now run their own first network.** 0.1.0 and 0.1.1 shipped one `tiny.bin`
13
+ for all three capital-letter options, so `fast` and `small` ran `accurate`'s first network instead
14
+ of the ones they were measured with. Each option's model files now live in
15
+ `dist/char-cnn/options/<name>/` (the option's JSON names them there; the shared wasm kernel stays
16
+ beside the runtime). If you copied `dist/char-cnn/` into your site, copy it again.
17
+ - **char-lite and overlap: a new assignment solver, about a quarter faster.** The matcher's
18
+ assignment step is now millirec's own (`cpp/assign.cpp` in the repository), written for this
19
+ problem: it stops as soon as a template provably cannot matter, and it starts from prices that
20
+ account for the points either side may drop. One recognition against 215 templates went from
21
+ 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
22
+ calls — on one writer's held-out drawings top-1 is unchanged for capitals and digits and two
23
+ better of 381 for lowercase. Input the matcher cannot use (thousands of points, NaN
24
+ coordinates) no longer traps.
25
+ - **A `recognize()` that timed out no longer poisons its strokes.** When char-lite's worker did
26
+ not answer within 4 s the call resolved `null`, but the request stayed marked as in flight, so
27
+ every later `recognize()` of the same strokes waited 4 s and resolved `null` again without the
28
+ worker being asked. The request is forgotten once nobody is waiting on it (`rawScores()` too).
29
+ - A worker that fails after it has booted releases every waiting call with `null` at once; a
30
+ worker that fails to boot is terminated and its blob URL revoked when `create()` rejects.
31
+ - README: a complete one-file page to start from (ES module from a CDN) and a complete script-tag
32
+ page; which CDNs work (jsDelivr, unpkg — not esm.sh); pin the full version; how to load the
33
+ overlap widget through a bundler; TypeScript notes; where to report bugs.
34
+ - package.json: `repository` (github.com/triplelog/millirec), `bugs` points at its issues.
35
+ - The source is public at github.com/triplelog/millirec, with the CNN trainer, one writer's
36
+ handwriting and a walk-through for training a recognizer for your own symbols (not part of the
37
+ npm download).
38
+
39
+ ## 0.1.1
40
+
41
+ - **Bundlers**: the package found its own folder with `new URL('./', import.meta.url)`, which Vite
42
+ and webpack 5 rewrite into a reference to the module FILE, so `loadSet()` fetched
43
+ `…/index.js/sets/digits.json`. The folder is now sliced from `import.meta.url`. With a bundler,
44
+ copy `dist/char-lite/` / `dist/char-cnn/` to your site and pass `assetBase` (README "Serving the
45
+ files", with Vite and webpack recipes; the old `optimizeDeps` advice did not work in 0.1.0; with this fix `optimizeDeps: { exclude: ['millirec'] }` works in Vite dev only, and builds still need the copy).
46
+ - **Clear errors when the files are not served**: `loadSet`, `loadOption`, the CNN model/kernel
47
+ loader and char-lite's worker/wasm boot now say which URL failed, what came back (a 404, an HTML
48
+ page from an SPA fallback, unparseable JSON) and what to do, instead of failing in `JSON.parse` or
49
+ the matcher.
50
+ - `"sideEffects"` lists the script-tag files (`dist/**/*.min.js`, `sets/*.js`, `options/*.js`) so a
51
+ bundler keeps `import 'millirec/overlap/millirec-overlap.min.js'`.
52
+ - `destroy()`: char-lite resolves pending and later `recognize()`/`rawScores()` with `null`;
53
+ char-cnn's `personalize()` returns `null`, `embedding()` throws `millirec: recognizer destroyed`,
54
+ `depersonalize()` is a no-op (they used to read past an empty stage list).
55
+ - char-cnn runs in a Web Worker (draws on `OffscreenCanvas`); webpack no longer tries to bundle the
56
+ kernel's dynamic import (`webpackIgnore`).
57
+ - Node / SSR: `create()` outside a browser throws a message saying so; `loadSet`/`loadOption` in
58
+ Node say to import the JSON instead.
59
+ - `MillirecCharCnn.create('fast')` = `create({ option: 'fast' })`.
60
+ - char-lite's result cache is an LRU of 256 (it grew without bound).
61
+ - Types: `Training.version` is `number` (and `mode` a string) so an imported set JSON type-checks;
62
+ `millirec:result` / `millirec:clear` are typed on `HTMLElementEventMap`; declarations for the
63
+ overlap widget's global (`import type {} from 'millirec/overlap'`); `typesVersions` for
64
+ `moduleResolution: node10`.
65
+ - package.json: `bugs`, `engines` (node ≥ 18, for tooling that imports the JSON).
66
+ - README: browser-only note, `destroy()`, the pad's options and events, overlap gzip sizes,
67
+ stable paths.
68
+
69
+ ## 0.1.0
70
+
71
+ First release.
package/README.md CHANGED
@@ -4,13 +4,45 @@ 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
+ **[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)**
9
+
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 start the worker) 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 { MillirecCharLite, loadSet } from 'https://cdn.jsdelivr.net/npm/millirec@0.1.2/dist/char-lite/index.js'
22
+
23
+ const rec = await MillirecCharLite.create({ training: await loadSet('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
+ ## What is in it
38
+
7
39
  Three pieces, pick by what you need to read:
8
40
 
9
41
  | | reads | size (gzip) | trainable on your own strokes |
10
42
  |---|---|---|---|
11
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 |
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 | 52 KB + training | — |
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`) | — |
14
46
 
15
47
  ## Install
16
48
 
@@ -21,6 +53,15 @@ npm install millirec
21
53
  `import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
22
54
  (use `import`, not `require`), or the script-tag builds below.
23
55
 
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
60
+ (`import digits from 'millirec/char-lite/sets/digits.json' with { type: 'json' }`) for tooling.
61
+
62
+ **TypeScript**: declarations are included. Importing a set or option as JSON needs
63
+ `resolveJsonModule` (and `esModuleInterop` under `moduleResolution: node10`).
64
+
24
65
  ## char-lite
25
66
 
26
67
  ```js
@@ -37,8 +78,41 @@ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
37
78
 
38
79
  // or your own strokes: arrays of {x, y} points
39
80
  await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
81
+
82
+ rec.destroy() // when you are done with it
40
83
  ```
41
84
 
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.
89
+
90
+ ### The drawing pad
91
+
92
+ `attach(el, options)` mounts a canvas in `el` and returns a `Pad` (`clear()`, `undoClear()`,
93
+ `getStrokes()`, `isStale()`, `configure()`, `setInk()`, `repaint()`, `canvas`). Options:
94
+
95
+ | option | default | |
96
+ |---|---|---|
97
+ | `width`, `height` | 240, 240 | pad size in CSS px |
98
+ | `ink` | `'#1e293b'` | ink colour |
99
+ | `idleOverwrite` | 2 | seconds of pen-up after which the next stroke starts a new character (0 = off) |
100
+ | `scribbleClear` | true | scribbling over the character throws it away |
101
+ | `scribble` | null | overrides for the scribble detector's bars (`turns`, `retrace`, `winding`, `cover`) |
102
+ | `staleAlpha` | 0.3 | opacity of ink once the character has settled (1 keeps it solid) |
103
+ | `onStale` | — | `(stale) => void`, called on every change of the settled state |
104
+
105
+ `el` fires two events:
106
+
107
+ - `millirec:result` — after every stroke, `detail = { results, strokes }` (`results` is the top
108
+ three `{ char, prob }`; an empty pad reports `results: []`, so a reading of ink that is gone can be
109
+ cleared);
110
+ - `millirec:clear` — the pad dropped its own ink, `detail = { reason: 'idle' | 'scribble', undo }`;
111
+ `undo()` puts it back.
112
+
113
+ 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.
115
+
42
116
  ### Training on your users' strokes
43
117
 
44
118
  A class name is any string, so a recognizer can learn one person's hand, or
@@ -65,13 +139,76 @@ training set can also be built offline and loaded with `fetch`.
65
139
  ```js
66
140
  import { MillirecCharCnn } from 'millirec/char-cnn'
67
141
 
68
- const rec = await MillirecCharCnn.create() // 'accurate' (default), 'fast' or 'small'
142
+ const rec = await MillirecCharCnn.create() // the 'accurate' option: capital letters
143
+ // or: await MillirecCharCnn.create({ option: 'digits' }) // see the table below
144
+ // (a bare name works too: create('digits'))
69
145
  rec.attach(document.querySelector('#pad'))
70
146
  await rec.recognize(strokes, { only: 'AEIOU' }) // restrict the answer to some letters
71
147
  await rec.personalize({ A: [a1, a2, a3], R: [r1, r2] }) // lean toward this writer's hand
148
+ rec.destroy() // let go of the models
72
149
  ```
73
150
 
74
- `millirec/char-cnn/core` is the same recognizer without the drawing pad.
151
+ | option | reads | strangers' handwriting read right | gzip, with the pad |
152
+ |---|---|---|---|
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 |
158
+
159
+ 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.
165
+
166
+ `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.
169
+
170
+ ### Your own symbols
171
+
172
+ **No training: `teach()`.** Give the recognizer a few drawings of each symbol and it reads them —
173
+ letters of another alphabet, a rating scale, proof-reading marks, emoji:
174
+
175
+ ```js
176
+ const rec = await MillirecCharCnn.create() // 'accurate' (or 'fast')
177
+ await rec.teach({
178
+ star: [star1, star2, star3], // each a drawing: [[{x, y}, …], …]
179
+ heart: [heart1, heart2, heart3],
180
+ '✓': [tick1, tick2, tick3],
181
+ })
182
+ await rec.recognize(strokes) // [{ char: 'star', prob: 0.93 }, …]
183
+ await rec.teach({ arrow: [a1, a2, a3] }, { add: true }) // one more, keeping the others
184
+ rec.forget() // back to the letters
185
+ ```
186
+
187
+ Each example is kept as what the network makes of it, and a new drawing is given to the name of
188
+ its nearest example; after `teach()` the recognizer answers among the taught names only. Nothing is
189
+ trained and nothing is stored: keep the example strokes yourself (`pad.getStrokes()`) and call
190
+ `teach()` again when the page loads, or pass them as `create({ examples })`.
191
+
192
+ How well it works, measured with the shipped `accurate` network — which was trained on capital
193
+ letters only — on one writer's drawings of things it has never seen, tested on that writer's other
194
+ drawings:
195
+
196
+ | examples of each | digits (10) | lowercase (26) | six punctuation marks |
197
+ |---|---|---|---|
198
+ | 1 | 92% | 86% | 84% |
199
+ | 3 | 96% | 93% | 88% |
200
+ | 5 | 99% | 96% | 89% |
201
+
202
+ Three is a good start and five is better; draw the variants people really use. Symbols that
203
+ differ only in size or position (`.` and `,`, `o` and `O`) cannot be told apart: every drawing is
204
+ scaled to fill the picture before it is read.
205
+
206
+ **With training.** `create()` also takes any model in the same format:
207
+ `MillirecCharCnn.create({ classes, stages, assetBase })`, where `classes` is a string of single
208
+ characters or a list of names. Training one from your own drawings — a dozen per symbol, a few
209
+ seconds — is a four-command walk-through in the repository:
210
+ [train your own recognizer](https://github.com/triplelog/millirec/blob/main/packages/millirec/train/README.md).
211
+ That is the route to the last few percent, the smallest download, and a recognizer for many writers.
75
212
 
76
213
  ## overlap: words written in one box
77
214
 
@@ -88,23 +225,63 @@ for now:
88
225
 
89
226
  Copy `dist/overlap/` to your site (or load it from a CDN); the script finds its wasm, training and
90
227
  default word list beside itself. `set` is `capitals`, `lowercase`, `digits`, `punctuation` or `all`.
228
+ TypeScript declarations for the `MillirecOverlap` global and its `millirec-overlap:*` events come
229
+ with `import type {} from 'millirec/overlap'`. That path is **types only**: the widget itself is
230
+ the script tag, and a plain `import 'millirec/overlap'` fails with "path not exported". To pull the
231
+ script through a bundler instead, import the file —
232
+ `import 'millirec/overlap/millirec-overlap.min.js'` — and pass `assetBase` to `create()`, since a
233
+ bundled script can no longer find the files beside it.
91
234
 
92
235
  ## Serving the files
93
236
 
94
- The recognizers load a worker, a wasm file and model files at run time, from
95
- the folder the module itself is in. That works as-is when the browser loads the
96
- package files directly (no bundler, or a bundler that copies them). If your
97
- bundler moves the JavaScript somewhere else, copy the folder and say where it
98
- is:
237
+ The recognizers load a worker, a wasm file, training sets and model files at run time, by default
238
+ from the folder the module itself is in. That works as-is when the browser loads the package's
239
+ files where they are — no bundler, an import map, or a dev server that serves `node_modules`.
240
+
241
+ **With a bundler** (Vite, webpack, Rollup, esbuild, Parcel …) the JavaScript is moved into your
242
+ bundle and the other files are not emitted with it. Copy the recognizer's folder into the folder
243
+ your site serves as-is, and pass its URL as `assetBase` to every call that loads something:
244
+
245
+ ```js
246
+ import { MillirecCharLite, loadSet } from 'millirec'
247
+ import { MillirecCharCnn } from 'millirec/char-cnn'
248
+
249
+ const lite = '/millirec/char-lite/' // copied from node_modules/millirec/dist/char-lite/
250
+ const training = await loadSet('digits', { assetBase: lite })
251
+ const rec = await MillirecCharLite.create({ training, assetBase: lite })
252
+
253
+ const cnn = await MillirecCharCnn.create({ option: 'fast', assetBase: '/millirec/char-cnn/' }) // dist/char-cnn/
254
+ // loadOption(name, { assetBase }) takes it too
255
+ ```
256
+
257
+ Vite — copy into `public/`, which is served (and copied into the build) unchanged:
258
+
259
+ ```sh
260
+ mkdir -p public/millirec
261
+ cp -R node_modules/millirec/dist/char-lite node_modules/millirec/dist/char-cnn public/millirec/
262
+ ```
263
+
264
+ (a `postinstall` script with those two lines keeps it in step with the installed version).
265
+ In `vite` dev alone, `optimizeDeps: { exclude: ['millirec'] }` also works without copying (the dev
266
+ server then serves the package from `node_modules`), but `vite build` does not emit the files, so a
267
+ production build still needs the copy and `assetBase`.
268
+
269
+ webpack 5 — with `copy-webpack-plugin`:
99
270
 
100
271
  ```js
101
- // copy node_modules/millirec/dist/char-lite/ to /millirec/char-lite/ on your site
102
- await MillirecCharLite.create({ training, assetBase: '/millirec/char-lite/' })
272
+ // webpack.config.js
273
+ import CopyPlugin from 'copy-webpack-plugin'
274
+ export default {
275
+ plugins: [new CopyPlugin({ patterns: [
276
+ { from: 'node_modules/millirec/dist/char-lite', to: 'millirec/char-lite' },
277
+ { from: 'node_modules/millirec/dist/char-cnn', to: 'millirec/char-cnn' },
278
+ ] })],
279
+ }
103
280
  ```
104
281
 
105
282
  `assetBase` may be absolute, root-relative or relative to the page, with or without the trailing
106
- slash. With Vite, either do that or exclude the package from dependency pre-bundling
107
- (`optimizeDeps: { exclude: ['millirec'] }`).
283
+ slash. If the files are not there, the error names the URL it tried and what came back (a dev
284
+ server's index.html fallback is recognised as such) instead of failing inside the matcher.
108
285
 
109
286
  **`assetBase` (and char-cnn's `kernel`) decide which code is loaded** — the worker and kernel are
110
287
  fetched from there and run. Set them in your own code; never fill them from a URL parameter, a
@@ -121,20 +298,46 @@ If your site sends a CSP, the recognizers need:
121
298
 
122
299
  ## Script tag / CDN
123
300
 
124
- No build step needed:
301
+ No build step and no modules — a complete page:
125
302
 
126
303
  ```html
127
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/millirec-char-lite.min.js"></script>
128
- <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/sets/digits.js"></script>
304
+ <!doctype html>
305
+ <meta charset="utf-8">
306
+ <div id="pad" style="width: 240px; height: 240px; border: 1px solid #999"></div>
307
+ <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>
129
310
  <script>
130
- MillirecCharLite.create().then((rec) => rec.attach(document.querySelector('#pad')))
311
+ MillirecCharLite.create().then((rec) => {
312
+ rec.attach(document.querySelector('#pad'))
313
+ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
314
+ var r = e.detail.results || []
315
+ document.querySelector('#out').textContent = r.length ? r.map((x) => x.char).join(' ') : 'draw a digit'
316
+ })
317
+ })
131
318
  </script>
132
319
  ```
133
320
 
134
321
  `sets/<name>.js` sets `window.MILLIREC_TRAINING`; for char-cnn load
135
322
  `dist/char-cnn/options/accurate.js` and then `millirec-char-cnn.min.js`. The
136
323
  script finds its worker and wasm next to itself, on any origin that sends CORS
137
- headers (jsDelivr and unpkg do).
324
+ headers.
325
+
326
+ **Which CDNs work** (tried in a browser from another origin): **jsDelivr** and **unpkg**, for the
327
+ script tags and for the ES modules (`…/dist/char-lite/index.js`, and jsDelivr's `/+esm`). **esm.sh
328
+ does not**: it serves a rewritten copy of the JavaScript without the worker and wasm files beside
329
+ it, so `create()` reports that they are not served.
330
+
331
+ **Pin the full version** (`@0.1.2`, not `@0.1`). The script, its worker and its wasm are separate
332
+ files that must come from the same release, and a CDN resolves a version range file by file.
333
+
334
+ ## Stable paths
335
+
336
+ 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`,
338
+ `millirec/char-cnn/options/<name>.json`, `millirec/overlap/<file>` and the script-tag files in "Script tag / CDN"
339
+ above. `millirec/dist/*` exposes every built file as an escape hatch; the layout under it may change
340
+ in any release.
138
341
 
139
342
  ## Where the data comes from
140
343
 
@@ -150,7 +353,14 @@ Recognition runs entirely in the browser: nothing a user draws is sent anywhere
150
353
 
151
354
  ## Versions
152
355
 
153
- 0.x: the API may still change between minor versions. 1.0 will mark it stable.
356
+ 0.x: the API may still change between minor versions. 1.0 will mark it stable. Changes are in
357
+ [CHANGELOG.md](https://github.com/triplelog/millirec/blob/main/packages/millirec/CHANGELOG.md).
358
+
359
+ ## Questions and bugs
360
+
361
+ [Open an issue](https://github.com/triplelog/millirec/issues). A drawing that reads wrong is most
362
+ useful with its strokes (`pad.getStrokes()`, or `e.detail.strokes` from the result event) and the
363
+ set or option in use.
154
364
 
155
365
  ## License
156
366
 
@@ -10,26 +10,39 @@ 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', 'lowercase']
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
- static create(opts?: CreateOptions): Promise<MillirecCharCnnCore>
23
+ /** A string is a shipped option's name: create('fast') = create({ option: 'fast' }). */
24
+ static create(opts?: CreateOptions | OptionName): Promise<MillirecCharCnnCore>
21
25
  readonly classes: string[]
22
26
  readonly ready: Promise<void>
23
27
  /** `only` restricts the reading to these classes. */
24
- recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] }): Promise<(Reading[] & { stage?: number }) | null>
28
+ recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] | Set<string> }): Promise<(Reading[] & { stage?: number }) | null>
25
29
  /** Refit the last stage's head on your own drawings: { 'A': [strokes, ...], ... }.
26
30
  * Anchored to the shipped head, so a few samples nudge a letter and many take it over.
27
31
  * Classes outside `classes` are ignored (the CNN cannot learn new characters this way). */
28
32
  personalize(samples: Record<string, Array<Strokes | Stroke>>, opts?: { steps?: number; lr?: number; prior?: number }): Promise<{ n: number; classes: string[] } | null>
29
33
  /** Back to the shipped head. */
30
34
  depersonalize(): void
31
- /** The last stage's unit embedding of a drawing — what the head reads. */
35
+ /**
36
+ * Read symbols of your own from a few drawings of each, with no training: every drawing is kept as what the
37
+ * last stage's network makes of it, and from then on `recognize()` answers among the taught names only, by the
38
+ * nearest example. Names are any strings. `{ add: true }` keeps what was taught before. Resolves `null` when
39
+ * nothing usable was given. Best on an option whose last stage is the larger network (`accurate`, `fast`).
40
+ */
41
+ teach(examples: Record<string, Array<Strokes | Stroke>>, opts?: { add?: boolean }): Promise<{ classes: string[]; n: number } | null>
42
+ /** Drop what `teach()` learned: `recognize()` reads the option's own classes again. */
43
+ forget(): void
44
+ /** The last stage's unit embedding of a drawing — what the head reads. Throws after destroy(). */
32
45
  embedding(strokes: Strokes | Stroke): Promise<Float32Array>
33
- /** Let go of the models; recognize() returns null afterwards. */
46
+ /** Let go of the models; recognize() and personalize() return null afterwards. */
34
47
  destroy(): void
35
48
  }