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.
- package/CHANGELOG.md +65 -0
- package/README.md +171 -58
- package/dist/char-cnn/cnn-web.wasm +0 -0
- package/dist/char-cnn/core.d.ts +3 -1
- package/dist/char-cnn/core.js +145 -99
- package/dist/char-cnn/index.d.ts +1 -1
- package/dist/char-cnn/index.js +198 -136
- 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/tiny.head.bin +0 -0
- package/dist/char-cnn/options/accurate.js +2 -2
- package/dist/char-cnn/options/accurate.json +1 -1
- package/dist/char-cnn/options/all/all-base.head.bin +0 -0
- package/dist/char-cnn/options/all/all-base.q4.bin +0 -0
- package/dist/char-cnn/options/all/all-tiny.bin +0 -0
- package/dist/char-cnn/options/all/all-tiny.head.bin +0 -0
- package/dist/char-cnn/options/all-fast/all-base-p25.bin +0 -0
- package/dist/char-cnn/options/all-fast/all-base-p25.head.bin +0 -0
- package/dist/char-cnn/options/all-fast/all-tiny.bin +0 -0
- package/dist/char-cnn/options/all-fast/all-tiny.head.bin +0 -0
- package/dist/char-cnn/options/all-fast.js +17 -0
- package/dist/char-cnn/options/all-fast.json +15 -0
- package/dist/char-cnn/options/all-small/all-tiny-qat4.head.bin +0 -0
- package/dist/char-cnn/options/all-small/all-tiny-qat4.q4.bin +0 -0
- package/dist/char-cnn/options/all-small.js +11 -0
- package/dist/char-cnn/options/all-small.json +9 -0
- package/dist/char-cnn/options/all.js +17 -0
- package/dist/char-cnn/options/all.json +15 -0
- package/dist/char-cnn/options/digits/digits-base.head.bin +0 -0
- package/dist/char-cnn/options/digits/digits-tiny.head.bin +0 -0
- package/dist/char-cnn/options/digits-fast/digits-base-p25.bin +0 -0
- package/dist/char-cnn/options/digits-fast/digits-base-p25.head.bin +0 -0
- package/dist/char-cnn/options/digits-fast/digits-tiny.bin +0 -0
- package/dist/char-cnn/options/digits-fast/digits-tiny.head.bin +0 -0
- package/dist/char-cnn/options/digits-fast.js +17 -0
- package/dist/char-cnn/options/digits-fast.json +15 -0
- package/dist/char-cnn/options/digits-small/digits-tiny-qat4.head.bin +0 -0
- package/dist/char-cnn/options/digits-small/digits-tiny-qat4.q4.bin +0 -0
- package/dist/char-cnn/options/digits-small.js +11 -0
- package/dist/char-cnn/options/digits-small.json +9 -0
- package/dist/char-cnn/options/digits.js +2 -2
- package/dist/char-cnn/options/digits.json +1 -1
- package/dist/char-cnn/options/fast/base-p25.head.bin +0 -0
- package/dist/char-cnn/options/fast/tiny.head.bin +0 -0
- package/dist/char-cnn/options/fast.js +2 -2
- package/dist/char-cnn/options/fast.json +1 -1
- package/dist/char-cnn/options/lowercase/lowercase-tiny.head.bin +0 -0
- package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.bin +0 -0
- package/dist/char-cnn/options/lowercase-fast/lowercase-base-p25.head.bin +0 -0
- package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.bin +0 -0
- package/dist/char-cnn/options/lowercase-fast/lowercase-tiny.head.bin +0 -0
- package/dist/char-cnn/options/lowercase-fast.js +17 -0
- package/dist/char-cnn/options/lowercase-fast.json +15 -0
- package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.head.bin +0 -0
- package/dist/char-cnn/options/lowercase-small/lowercase-tiny-qat4.q4.bin +0 -0
- package/dist/char-cnn/options/lowercase-small.js +11 -0
- package/dist/char-cnn/options/lowercase-small.json +9 -0
- package/dist/char-cnn/options/lowercase.js +2 -2
- package/dist/char-cnn/options/lowercase.json +1 -1
- package/dist/char-cnn/options/small/tiny.head.bin +0 -0
- package/dist/char-cnn/options/small/tiny.q4.bin +0 -0
- package/dist/char-cnn/options/small.js +2 -2
- package/dist/char-cnn/options/small.json +1 -1
- package/dist/char-lite/core.d.ts +1 -0
- package/dist/char-lite/core.js +628 -0
- package/dist/char-lite/index.d.ts +28 -8
- package/dist/char-lite/index.js +845 -717
- package/dist/char-lite/millirec-char-lite.min.js +1 -1
- package/dist/char-lite/sets.json +17 -17
- package/dist/index.d.ts +35 -0
- package/dist/index.js +88 -0
- package/dist/overlap/millirec-overlap.min.js +7 -7
- package/dist/pad/index.d.ts +8 -0
- package/dist/pad/index.js +482 -0
- package/package.json +21 -7
- 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
|
|
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 {
|
|
21
|
+
import { createRecognizer } from 'https://cdn.jsdelivr.net/npm/millirec@0.2.0/dist/index.js'
|
|
22
22
|
|
|
23
|
-
const rec = await
|
|
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
|
-
##
|
|
37
|
+
## Which recognizer?
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
millirec has two engines, and `createRecognizer()` picks between them for you:
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
57
|
-
draws strokes
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
##
|
|
100
|
+
## createRecognizer
|
|
66
101
|
|
|
67
102
|
```js
|
|
68
|
-
import {
|
|
103
|
+
import { createRecognizer, chooseEngine } from 'millirec'
|
|
69
104
|
|
|
70
|
-
const
|
|
71
|
-
const rec = await
|
|
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
|
-
//
|
|
74
|
-
|
|
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
|
-
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
86
|
-
|
|
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
|
-
|
|
144
|
+
## The drawing pad
|
|
91
145
|
|
|
92
|
-
`attach(el, options)`
|
|
93
|
-
|
|
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.
|
|
171
|
+
type-checks.
|
|
115
172
|
|
|
116
|
-
|
|
173
|
+
## char-lite
|
|
117
174
|
|
|
118
|
-
|
|
119
|
-
|
|
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% |
|
|
154
|
-
| `fast` | capitals A–Z | 97.
|
|
155
|
-
| `small` | capitals A–Z | 96.
|
|
156
|
-
| `digits` | 0–9 | 99.6% |
|
|
157
|
-
| `
|
|
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).
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
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 (
|
|
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 {
|
|
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.
|
|
309
|
-
<script src="https://cdn.jsdelivr.net/npm/millirec@0.
|
|
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.
|
|
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
|
|
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
|
package/dist/char-cnn/core.d.ts
CHANGED
|
@@ -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. */
|