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.
- package/CHANGELOG.md +71 -0
- package/README.md +229 -19
- package/dist/char-cnn/core.d.ts +18 -5
- package/dist/char-cnn/core.js +152 -25
- package/dist/char-cnn/index.d.ts +3 -2
- package/dist/char-cnn/index.js +152 -25
- package/dist/char-cnn/millirec-char-cnn-core.min.js +1 -1
- package/dist/char-cnn/millirec-char-cnn.min.js +1 -1
- package/dist/char-cnn/options/accurate.js +4 -4
- package/dist/char-cnn/options/accurate.json +4 -4
- package/dist/char-cnn/options/digits/digits-base.head.bin +0 -0
- package/dist/char-cnn/options/digits/digits-base.q4.bin +0 -0
- package/dist/char-cnn/options/digits/digits-tiny.bin +0 -0
- package/dist/char-cnn/options/digits/digits-tiny.head.bin +0 -0
- package/dist/char-cnn/options/digits.js +17 -0
- package/dist/char-cnn/options/digits.json +15 -0
- package/dist/char-cnn/options/fast/tiny.bin +0 -0
- package/dist/char-cnn/options/fast/tiny.head.bin +0 -0
- package/dist/char-cnn/options/fast.js +4 -4
- package/dist/char-cnn/options/fast.json +4 -4
- package/dist/char-cnn/options/lowercase/lowercase-base.head.bin +0 -0
- package/dist/char-cnn/options/lowercase/lowercase-base.q4.bin +0 -0
- package/dist/char-cnn/options/lowercase/lowercase-tiny.bin +0 -0
- package/dist/char-cnn/options/lowercase/lowercase-tiny.head.bin +0 -0
- package/dist/char-cnn/options/lowercase.js +17 -0
- package/dist/char-cnn/options/lowercase.json +15 -0
- package/dist/char-cnn/options/small/tiny.bin +0 -0
- package/dist/char-cnn/options/small/tiny.head.bin +0 -0
- package/dist/char-cnn/options/small.js +2 -2
- package/dist/char-cnn/options/small.json +2 -2
- package/dist/char-lite/index.d.ts +26 -4
- package/dist/char-lite/index.js +113 -11
- package/dist/char-lite/millirec-char-lite.min.js +1 -1
- package/dist/char-lite/millirec.wasm +0 -0
- package/dist/char-lite/sets.json +25 -29
- package/dist/overlap/index.d.ts +139 -0
- package/dist/overlap/millirec.wasm +0 -0
- package/package.json +45 -3
- /package/dist/char-cnn/{base.head.bin → options/accurate/base.head.bin} +0 -0
- /package/dist/char-cnn/{base.q4.bin → options/accurate/base.q4.bin} +0 -0
- /package/dist/char-cnn/{tiny.bin → options/accurate/tiny.bin} +0 -0
- /package/dist/char-cnn/{tiny.head.bin → options/accurate/tiny.head.bin} +0 -0
- /package/dist/char-cnn/{base-p25.bin → options/fast/base-p25.bin} +0 -0
- /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
|
|
13
|
-
| overlap (script tag) | whole words written letter over letter in one box |
|
|
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'
|
|
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
|
-
|
|
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,
|
|
95
|
-
the folder the module itself is in. That works as-is when the browser loads the
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
//
|
|
102
|
-
|
|
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.
|
|
107
|
-
|
|
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
|
|
301
|
+
No build step and no modules — a complete page:
|
|
125
302
|
|
|
126
303
|
```html
|
|
127
|
-
|
|
128
|
-
<
|
|
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) =>
|
|
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
|
|
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
|
|
package/dist/char-cnn/core.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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()
|
|
46
|
+
/** Let go of the models; recognize() and personalize() return null afterwards. */
|
|
34
47
|
destroy(): void
|
|
35
48
|
}
|