millirec 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +156 -2
- package/dist/char-cnn/base-p25.bin +0 -0
- package/dist/char-cnn/base-p25.head.bin +0 -0
- package/dist/char-cnn/base.head.bin +0 -0
- package/dist/char-cnn/base.q4.bin +0 -0
- package/dist/char-cnn/cnn-web.js +8 -0
- package/dist/char-cnn/cnn-web.wasm +0 -0
- package/dist/char-cnn/core.d.ts +35 -0
- package/dist/char-cnn/core.js +536 -0
- package/dist/char-cnn/index.d.ts +9 -0
- package/dist/char-cnn/index.js +1009 -0
- package/dist/char-cnn/millirec-char-cnn-core.min.js +1 -0
- package/dist/char-cnn/millirec-char-cnn.min.js +1 -0
- package/dist/char-cnn/options/accurate.js +17 -0
- package/dist/char-cnn/options/accurate.json +15 -0
- package/dist/char-cnn/options/fast.js +17 -0
- package/dist/char-cnn/options/fast.json +15 -0
- package/dist/char-cnn/options/small.js +11 -0
- package/dist/char-cnn/options/small.json +9 -0
- package/dist/char-cnn/tiny.bin +0 -0
- package/dist/char-cnn/tiny.head.bin +0 -0
- package/dist/char-lite/index.d.ts +77 -0
- package/dist/char-lite/index.js +894 -0
- package/dist/char-lite/millirec-char-lite.min.js +1 -0
- package/dist/char-lite/millirec.wasm +0 -0
- package/dist/char-lite/sets/all.js +2 -0
- package/dist/char-lite/sets/all.json +1 -0
- package/dist/char-lite/sets/capitals.js +2 -0
- package/dist/char-lite/sets/capitals.json +1 -0
- package/dist/char-lite/sets/digits.js +2 -0
- package/dist/char-lite/sets/digits.json +1 -0
- package/dist/char-lite/sets/lowercase.js +2 -0
- package/dist/char-lite/sets/lowercase.json +1 -0
- package/dist/char-lite/sets/punctuation.js +2 -0
- package/dist/char-lite/sets/punctuation.json +1 -0
- package/dist/char-lite/sets.json +163 -0
- package/dist/char-lite/worker-stroke.js +11 -0
- package/dist/overlap/millirec-overlap.min.js +45 -0
- package/dist/overlap/millirec.wasm +0 -0
- package/dist/overlap/training.all.json +1 -0
- package/dist/overlap/training.capitals.json +1 -0
- package/dist/overlap/training.digits.json +1 -0
- package/dist/overlap/training.lowercase.json +1 -0
- package/dist/overlap/training.punctuation.json +1 -0
- package/dist/overlap/words.json +1 -0
- package/package.json +53 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Robert Wilcox
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,157 @@
|
|
|
1
|
-
#
|
|
1
|
+
# millirec
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Small, fast handwriting recognition in the browser. Draw a character, get the
|
|
4
|
+
three likeliest readings back. Runs entirely on the device — no server, no
|
|
5
|
+
upload of anyone's ink.
|
|
6
|
+
|
|
7
|
+
Three pieces, pick by what you need to read:
|
|
8
|
+
|
|
9
|
+
| | reads | size (gzip) | trainable on your own strokes |
|
|
10
|
+
|---|---|---|---|
|
|
11
|
+
| `millirec/char-lite` | anything you have samples for: digits, letters, punctuation, emoji, made-up symbols | 26 KB + the training set (digits 4 KB, all 27 KB) | **yes** — add samples, add whole new classes |
|
|
12
|
+
| `millirec/char-cnn` | capital letters A–Z | 15 KB (`small`) to 47 KB (`fast`); `accurate` 42 KB | refit on a writer's own letters (`personalize`) |
|
|
13
|
+
| overlap (script tag) | whole words written letter over letter in one box | 52 KB + training | — |
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install millirec
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
|
|
22
|
+
(use `import`, not `require`), or the script-tag builds below.
|
|
23
|
+
|
|
24
|
+
## char-lite
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
import { MillirecCharLite, loadSet } from 'millirec/char-lite'
|
|
28
|
+
|
|
29
|
+
const training = await loadSet('digits') // 'all' | 'capitals' | 'digits' | 'lowercase' | 'punctuation'
|
|
30
|
+
const rec = await MillirecCharLite.create({ training })
|
|
31
|
+
|
|
32
|
+
// a drawing pad that reports after every stroke
|
|
33
|
+
const pad = rec.attach(document.querySelector('#pad'))
|
|
34
|
+
document.querySelector('#pad').addEventListener('millirec:result', (e) => {
|
|
35
|
+
console.log(e.detail.results) // [{ char: '7', prob: 0.91 }, ...]
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
// or your own strokes: arrays of {x, y} points
|
|
39
|
+
await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Training on your users' strokes
|
|
43
|
+
|
|
44
|
+
A class name is any string, so a recognizer can learn one person's hand, or
|
|
45
|
+
symbols nobody else uses:
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
const mine = MillirecCharLite.withSamples(training, {
|
|
49
|
+
'7': [strokesOfASeven, anotherSeven], // appended to the shipped 7s
|
|
50
|
+
'★': [star1, star2, star3], // a brand-new class
|
|
51
|
+
})
|
|
52
|
+
const rec = await MillirecCharLite.create({ training: mine })
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Drawings are resampled to the set's points-per-shape, so pass raw strokes.
|
|
56
|
+
`{ replace: true }` drops a class's shipped samples instead of appending —
|
|
57
|
+
worth it once you have three or four of the writer's own. Keep the raw strokes
|
|
58
|
+
(in localStorage, IndexedDB, your server — the library never stores anything)
|
|
59
|
+
and rebuild the training object when the recognizer starts. The format is
|
|
60
|
+
plain JSON (`version: 2`, see `Training` in the type declarations), so a
|
|
61
|
+
training set can also be built offline and loaded with `fetch`.
|
|
62
|
+
|
|
63
|
+
## char-cnn
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
import { MillirecCharCnn } from 'millirec/char-cnn'
|
|
67
|
+
|
|
68
|
+
const rec = await MillirecCharCnn.create() // 'accurate' (default), 'fast' or 'small'
|
|
69
|
+
rec.attach(document.querySelector('#pad'))
|
|
70
|
+
await rec.recognize(strokes, { only: 'AEIOU' }) // restrict the answer to some letters
|
|
71
|
+
await rec.personalize({ A: [a1, a2, a3], R: [r1, r2] }) // lean toward this writer's hand
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`millirec/char-cnn/core` is the same recognizer without the drawing pad.
|
|
75
|
+
|
|
76
|
+
## overlap: words written in one box
|
|
77
|
+
|
|
78
|
+
Letters written one on top of another in a single box, read against a word list. Script tag only
|
|
79
|
+
for now:
|
|
80
|
+
|
|
81
|
+
```html
|
|
82
|
+
<script src="/millirec/overlap/millirec-overlap.min.js"></script>
|
|
83
|
+
<div id="box"></div>
|
|
84
|
+
<script>
|
|
85
|
+
MillirecOverlap.create(document.getElementById('box'), { set: 'capitals', words: ['HELLO', 'WORLD'] })
|
|
86
|
+
</script>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Copy `dist/overlap/` to your site (or load it from a CDN); the script finds its wasm, training and
|
|
90
|
+
default word list beside itself. `set` is `capitals`, `lowercase`, `digits`, `punctuation` or `all`.
|
|
91
|
+
|
|
92
|
+
## Serving the files
|
|
93
|
+
|
|
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:
|
|
99
|
+
|
|
100
|
+
```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/' })
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`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'] }`).
|
|
108
|
+
|
|
109
|
+
**`assetBase` (and char-cnn's `kernel`) decide which code is loaded** — the worker and kernel are
|
|
110
|
+
fetched from there and run. Set them in your own code; never fill them from a URL parameter, a
|
|
111
|
+
query string or anything a visitor can type.
|
|
112
|
+
|
|
113
|
+
### Content-Security-Policy
|
|
114
|
+
|
|
115
|
+
If your site sends a CSP, the recognizers need:
|
|
116
|
+
|
|
117
|
+
- `worker-src blob:` — char-lite boots its worker from a blob that loads `worker-stroke.js`;
|
|
118
|
+
- `script-src 'wasm-unsafe-eval' 'unsafe-eval'` — the matcher is WebAssembly, and its generated
|
|
119
|
+
bindings (char-lite's worker, overlap) use `new Function`;
|
|
120
|
+
- `connect-src` for wherever the files are served from, if that is another origin.
|
|
121
|
+
|
|
122
|
+
## Script tag / CDN
|
|
123
|
+
|
|
124
|
+
No build step needed:
|
|
125
|
+
|
|
126
|
+
```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>
|
|
129
|
+
<script>
|
|
130
|
+
MillirecCharLite.create().then((rec) => rec.attach(document.querySelector('#pad')))
|
|
131
|
+
</script>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`sets/<name>.js` sets `window.MILLIREC_TRAINING`; for char-cnn load
|
|
135
|
+
`dist/char-cnn/options/accurate.js` and then `millirec-char-cnn.min.js`. The
|
|
136
|
+
script finds its worker and wasm next to itself, on any origin that sends CORS
|
|
137
|
+
headers (jsDelivr and unpkg do).
|
|
138
|
+
|
|
139
|
+
## Where the data comes from
|
|
140
|
+
|
|
141
|
+
- **char-lite training sets and the overlap templates**: one writer's own handwriting, drawn for
|
|
142
|
+
this project.
|
|
143
|
+
- **char-cnn models**: small CNNs trained on handwritten capitals from EMNIST (derived from NIST
|
|
144
|
+
Special Database 19).
|
|
145
|
+
- **overlap's default word list** (`words.json`): the 10,000 commonest English words by millirec's
|
|
146
|
+
own count over about 1.9 billion words of English, mostly news — names and offensive words
|
|
147
|
+
removed. It leans toward news vocabulary; pass your own `words` for anything specific.
|
|
148
|
+
|
|
149
|
+
Recognition runs entirely in the browser: nothing a user draws is sent anywhere by this package.
|
|
150
|
+
|
|
151
|
+
## Versions
|
|
152
|
+
|
|
153
|
+
0.x: the API may still change between minor versions. 1.0 will mark it stable.
|
|
154
|
+
|
|
155
|
+
## License
|
|
156
|
+
|
|
157
|
+
MIT
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
async function CnnEmbed(moduleArg={}){var moduleRtn;var b=moduleArg,f=!!globalThis.WorkerGlobalScope,g=import.meta.url,h="",l,m;if(globalThis.window||f){try{h=(new URL(".",g)).href}catch{}f&&(m=a=>{var d=new XMLHttpRequest;d.open("GET",a,!1);d.responseType="arraybuffer";d.send(null);return new Uint8Array(d.response)});l=async a=>{a=await fetch(a,{credentials:"same-origin"});if(a.ok)return a.arrayBuffer();throw Error(a.status+" : "+a.url);}}var n=console.error.bind(console),p,q=!1,r,t,u,v=!1;
|
|
2
|
+
function w(){var a=x.buffer;new Int8Array(a);new Int16Array(a);b.HEAPU8=u=new Uint8Array(a);new Uint16Array(a);new Int32Array(a);new Uint32Array(a);b.HEAPF32=new Float32Array(a);new Float64Array(a);new BigInt64Array(a);new BigUint64Array(a)}var y;async function z(a){if(!p)try{var d=await l(a);return new Uint8Array(d)}catch{}if(a==y&&p)a=new Uint8Array(p);else if(m)a=m(a);else throw"both async and sync fetching of the wasm failed";return a}
|
|
3
|
+
async function A(a,d){try{var c=await z(a);return await WebAssembly.instantiate(c,d)}catch(e){throw n(`failed to asynchronously prepare wasm: ${e}`),a=e,b.onAbort?.(a),a="Aborted("+a+")",n(a),q=!0,a=new WebAssembly.RuntimeError(a+". Build with -sASSERTIONS for more info."),t?.(a),a;}}
|
|
4
|
+
async function B(a){var d=y;if(!p)try{var c=fetch(d,{credentials:"same-origin"});return await WebAssembly.instantiateStreaming(c,a)}catch(e){n(`wasm streaming compile failed: ${e}`),n("falling back to ArrayBuffer instantiation")}return A(d,a)}var C=a=>{for(;0<a.length;)a.shift()(b)},D=[],E=[],F=()=>{var a=b.preRun.shift();E.push(a)};b.printErr&&(n=b.printErr);b.wasmBinary&&(p=b.wasmBinary);if(b.preInit)for("function"==typeof b.preInit&&(b.preInit=[b.preInit]);0<b.preInit.length;)b.preInit.shift()();
|
|
5
|
+
var x,G={a:a=>{var d=u.length;a>>>=0;if(2147483648<a)return!1;for(var c=1;4>=c;c*=2){var e=d*(1+.2/c);e=Math.min(e,a+100663296);a:{e=(Math.min(2147483648,65536*Math.ceil(Math.max(a,e)/65536))-x.buffer.byteLength+65535)/65536|0;try{x.grow(e);w();var k=1;break a}catch(I){}k=void 0}if(k)return!0}return!1}},H;
|
|
6
|
+
H=await (async function(){function a(c){c=H=c.exports;b._cnnLoad=c.d;b._free=c.e;b._malloc=c.f;b._cnnSize=c.g;b._cnnDim=c.h;b._cnnInputPtr=c.i;b._cnnEmbedPtr=c.j;b._cnnRun=c.k;x=c.b;w();return H}var d={a:G};if(b.instantiateWasm)return new Promise(c=>{b.instantiateWasm(d,(e,k)=>{c(a(e,k))})});y??=b.locateFile?b.locateFile?b.locateFile("cnn-web.wasm",h):h+"cnn-web.wasm":(new URL("cnn-web.wasm",import.meta.url)).href;return a((await B(d)).instance)}());
|
|
7
|
+
(function(){function a(){b.calledRun=!0;if(!q){v=!0;H.c();r?.(b);b.onRuntimeInitialized?.();if(b.postRun)for("function"==typeof b.postRun&&(b.postRun=[b.postRun]);b.postRun.length;){var d=b.postRun.shift();D.push(d)}C(D)}}if(b.preRun)for("function"==typeof b.preRun&&(b.preRun=[b.preRun]);b.preRun.length;)F();C(E);b.setStatus?(b.setStatus("Running..."),setTimeout(()=>{setTimeout(()=>b.setStatus(""),1);a()},1)):a()})();v?moduleRtn=b:moduleRtn=new Promise((a,d)=>{r=a;t=d});
|
|
8
|
+
;return moduleRtn}export default CnnEmbed;
|
|
Binary file
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { Strokes, Stroke, Reading } from '../char-lite/index.js'
|
|
2
|
+
|
|
3
|
+
export interface Stage { model: string; head: string; theta?: number; headNorm?: boolean }
|
|
4
|
+
export interface CnnConfig { classes: string | string[]; stages: Stage[]; kernel?: string }
|
|
5
|
+
|
|
6
|
+
export interface CreateOptions extends Partial<CnnConfig> {
|
|
7
|
+
/** A shipped option, used when `stages` is not given. Default 'accurate'. */
|
|
8
|
+
option?: OptionName
|
|
9
|
+
/** Folder holding the model files and kernel. Default: next to this module. Absolute, root-relative
|
|
10
|
+
* or page-relative; the trailing slash is optional. It (and `kernel`) decide what code is loaded:
|
|
11
|
+
* never fill them from a URL parameter or user input. */
|
|
12
|
+
assetBase?: string
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export declare const OPTIONS: readonly ['accurate', 'fast', 'small']
|
|
16
|
+
export type OptionName = (typeof OPTIONS)[number]
|
|
17
|
+
export declare function loadOption(name: OptionName, opts?: { assetBase?: string }): Promise<CnnConfig>
|
|
18
|
+
|
|
19
|
+
export declare class MillirecCharCnnCore {
|
|
20
|
+
static create(opts?: CreateOptions): Promise<MillirecCharCnnCore>
|
|
21
|
+
readonly classes: string[]
|
|
22
|
+
readonly ready: Promise<void>
|
|
23
|
+
/** `only` restricts the reading to these classes. */
|
|
24
|
+
recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] }): Promise<(Reading[] & { stage?: number }) | null>
|
|
25
|
+
/** Refit the last stage's head on your own drawings: { 'A': [strokes, ...], ... }.
|
|
26
|
+
* Anchored to the shipped head, so a few samples nudge a letter and many take it over.
|
|
27
|
+
* Classes outside `classes` are ignored (the CNN cannot learn new characters this way). */
|
|
28
|
+
personalize(samples: Record<string, Array<Strokes | Stroke>>, opts?: { steps?: number; lr?: number; prior?: number }): Promise<{ n: number; classes: string[] } | null>
|
|
29
|
+
/** Back to the shipped head. */
|
|
30
|
+
depersonalize(): void
|
|
31
|
+
/** The last stage's unit embedding of a drawing — what the head reads. */
|
|
32
|
+
embedding(strokes: Strokes | Stroke): Promise<Float32Array>
|
|
33
|
+
/** Let go of the models; recognize() returns null afterwards. */
|
|
34
|
+
destroy(): void
|
|
35
|
+
}
|