@sythos/js_barcode_universal 0.1.0 → 1.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/README.md +483 -425
- package/bundle/sythos-barcode.esm.js +3089 -1181
- package/bundle/sythos-barcode.js +3081 -1181
- package/examples/create.html +732 -730
- package/licenses/README.md +2 -0
- package/licenses/aztec-code.license +74 -0
- package/licenses/data-matrix.license +82 -0
- package/package.json +94 -88
- package/src/aztec/decoder.js +317 -0
- package/src/aztec/detector.js +224 -0
- package/src/aztec/encoder.js +257 -0
- package/src/aztec/high-level.js +211 -0
- package/src/aztec/index.js +45 -0
- package/src/aztec/tables.js +210 -0
- package/src/core/galois-field.js +3 -0
- package/src/core/reed-solomon.js +313 -313
- package/src/datamatrix/decoder.js +262 -0
- package/src/datamatrix/detector.js +225 -0
- package/src/datamatrix/encoder.js +191 -0
- package/src/datamatrix/index.js +42 -0
- package/src/datamatrix/tables.js +123 -0
- package/src/index.js +70 -2
package/README.md
CHANGED
|
@@ -1,433 +1,491 @@
|
|
|
1
|
-
# Sythos Barcode Suite
|
|
2
|
-
|
|
3
|
-
Read and write barcodes in JavaScript.
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@sythos/js_barcode_universal)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](package.json)
|
|
8
|
+
|
|
9
|
+
100% original code, zero runtime dependencies, MIT. It runs unmodified in Node, in browsers
|
|
10
|
+
(including Safari on iOS) and in web workers. The core requires no canvas, no filesystem and no
|
|
11
|
+
DOM — images go in and come out as plain `{ data, width, height }` RGBA objects, which is exactly
|
|
12
|
+
what an `ImageData` is.
|
|
13
|
+
|
|
14
|
+
**The code is complete and entirely human-readable.** The full source ships. There is no
|
|
15
|
+
WebAssembly, no native addon, no compiled artefact, no binary blob and no minified file anywhere
|
|
16
|
+
in this repository — every tracked file is text you can open and read.
|
|
17
|
+
|
|
18
|
+
That includes the prebuilt bundles. They are *generated*, concatenated and wrapped from `src/` by
|
|
19
|
+
the project's own bundler, but nothing is stripped in the process:
|
|
20
|
+
[`bundle/sythos-barcode.js`](bundle/sythos-barcode.js) runs to roughly 7,900 lines, about a third
|
|
21
|
+
of them comments, averaging a little over 30 characters a line. Open it anywhere and you are
|
|
22
|
+
reading the same annotated code as the source, in the same order — a convenience, not a black box.
|
|
23
|
+
|
|
24
|
+
Don't take that on trust either; it takes one command:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
awk '{ n += length($0) } END { print "lines:", NR, " avg length:", int(n/NR) }' bundle/sythos-barcode.js
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
A minified bundle gives you a handful of lines averaging thousands of characters. This one does
|
|
31
|
+
not, and that is the whole point.
|
|
32
|
+
|
|
33
|
+
This is deliberate. A barcode library decides what a scanner believes a label says, so it belongs
|
|
34
|
+
in the category of code you can audit rather than have to trust. Every constant table, every
|
|
35
|
+
check digit and every error-correction step is here in full, with the reasoning next to it.
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
import { encode, decode, toSVG, toImageData } from './src/index.js';
|
|
39
|
+
|
|
40
|
+
const matrix = encode('https://example.com', { format: 'qr', ecc: 'M' });
|
|
41
|
+
const svg = toSVG(matrix, { scale: 8 });
|
|
42
|
+
|
|
43
|
+
const found = decode(toImageData(matrix, { scale: 4 }), { formats: ['qr'] });
|
|
44
|
+
console.log(found[0].text); // 'https://example.com'
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Quick start
|
|
50
|
+
|
|
51
|
+
There are four ways in, and none of them needs a build step.
|
|
52
|
+
|
|
53
|
+
### 1. npm
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
npm install @sythos/js_barcode_universal
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`yarn add @sythos/js_barcode_universal` and `pnpm add @sythos/js_barcode_universal` do the same thing. Nothing is installed
|
|
60
|
+
alongside it — there are no runtime dependencies, no postinstall script and no native build. The
|
|
61
|
+
package is plain ESM (`"type": "module"`) and asks for Node 18 or newer.
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
import { encode, decode, toSVG, toImageData } from '@sythos/js_barcode_universal';
|
|
65
|
+
|
|
66
|
+
const code = encode('SYT-2026-0042', { format: 'code128' });
|
|
67
|
+
|
|
68
|
+
const svg = toSVG(code, { scale: 2, margin: 10, barHeight: 60 });
|
|
69
|
+
// '<svg xmlns="http://www.w3.org/2000/svg" width="374" height="100" …'
|
|
70
|
+
|
|
71
|
+
const found = decode(toImageData(code, { scale: 4, margin: 10 }), { formats: ['code128'] });
|
|
72
|
+
console.log(found[0].text); // 'SYT-2026-0042'
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**Subpath exports** hand you one layer instead of the whole surface, which is what lets a
|
|
76
|
+
tree-shaking bundler drop everything you did not ask for. Importing only the QR writer and only
|
|
77
|
+
the SVG renderer never pulls in the 1D formats, the PNG encoder or the read pipeline:
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
import { encodeQR } from '@sythos/js_barcode_universal/qr';
|
|
81
|
+
import { toSVG } from '@sythos/js_barcode_universal/render/svg';
|
|
82
|
+
|
|
83
|
+
const svg = toSVG(encodeQR('https://example.com', { ecc: 'M' }), { scale: 8 });
|
|
84
|
+
// a 25×25 module symbol — 264×264 px at scale 8 with the default 4-module quiet zone
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
| Subpath | What it exports |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `@sythos/js_barcode_universal` | The whole surface: `encode`, `decode`, every renderer, every error type |
|
|
90
|
+
| `@sythos/js_barcode_universal/core` | `BitMatrix`, `GaloisField`, Reed–Solomon, the error classes |
|
|
91
|
+
| `@sythos/js_barcode_universal/image` | `LuminanceSource`, the binarizers, grid sampling, `PerspectiveTransform` |
|
|
92
|
+
| `@sythos/js_barcode_universal/oned` | The per-format 1D writers (`encodeEAN13`, `encodeCode128`, …) and `decodeOneD` |
|
|
93
|
+
| `@sythos/js_barcode_universal/qr` | `encodeQR`, `decodeQR`, `detectQR`, `detectAndDecodeQR` |
|
|
94
|
+
| `@sythos/js_barcode_universal/datamatrix` | `encodeDataMatrix`, `decodeDataMatrix`, `detectDataMatrix`, `detectAndDecodeDataMatrix` |
|
|
95
|
+
| `@sythos/js_barcode_universal/render` | Every renderer plus `isWebGL2Available` / `isWebGPUAvailable` |
|
|
96
|
+
| `@sythos/js_barcode_universal/render/svg` | `toSVG`, `toSVGDataURI` |
|
|
97
|
+
| `@sythos/js_barcode_universal/render/png` | `toPNG`, `toPNGDataURI` |
|
|
98
|
+
| `@sythos/js_barcode_universal/render/image-data` | `toImageData`, `toCanvas` |
|
|
99
|
+
| `@sythos/js_barcode_universal/bundle` | The prebuilt ESM bundle, as one file |
|
|
100
|
+
| `@sythos/js_barcode_universal/bundle/iife` | The prebuilt IIFE bundle, for a `<script>` tag |
|
|
101
|
+
|
|
102
|
+
The `unpkg` and `jsdelivr` fields point at the IIFE bundle, so a CDN needs no install at all:
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<script src="https://unpkg.com/@sythos/js_barcode_universal"></script>
|
|
106
|
+
<script src="https://unpkg.com/@sythos/js_barcode_universal@1.1.0"></script>
|
|
107
|
+
<script src="https://cdn.jsdelivr.net/npm/@sythos/js_barcode_universal@1.1.0"></script>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Pin the version for anything you ship; the unpinned form resolves to `latest` and will move under
|
|
111
|
+
you.
|
|
112
|
+
|
|
113
|
+
Both CDNs serve the same file the repository ships in
|
|
114
|
+
[`bundle/sythos-barcode.js`](bundle/sythos-barcode.js) — byte for byte, since that is exactly what
|
|
115
|
+
npm publishes.
|
|
116
|
+
|
|
117
|
+
### 2. A `<script>` tag
|
|
118
|
+
|
|
119
|
+
[`bundle/sythos-barcode.js`](bundle/sythos-barcode.js) is a self-contained IIFE that exposes a
|
|
120
|
+
single global, `SythosBarcode`. It works straight from `file://` — open an HTML file off your
|
|
121
|
+
disk and it runs.
|
|
122
|
+
|
|
123
|
+
```html
|
|
124
|
+
<script src="bundle/sythos-barcode.js"></script>
|
|
125
|
+
<script>
|
|
126
|
+
var encode = SythosBarcode.encode;
|
|
127
|
+
var toSVGDataURI = SythosBarcode.toSVGDataURI;
|
|
128
|
+
|
|
129
|
+
var img = new Image();
|
|
130
|
+
img.src = toSVGDataURI(encode('https://example.com', { format: 'qr' }), { scale: 8 });
|
|
131
|
+
document.body.appendChild(img);
|
|
132
|
+
</script>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 3. ESM bundle
|
|
136
|
+
|
|
137
|
+
[`bundle/sythos-barcode.esm.js`](bundle/sythos-barcode.esm.js) is the same code as a single ES
|
|
138
|
+
module, for `<script type="module">`, a bundler, or Node.
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import { encode, toSVG, toPNG } from './bundle/sythos-barcode.esm.js';
|
|
142
|
+
|
|
143
|
+
const ean = encode('5901234123457', { format: 'ean13' });
|
|
144
|
+
|
|
145
|
+
const svg = toSVG(ean, { scale: 3, margin: 10, barHeight: 80 });
|
|
146
|
+
// '<svg xmlns="http://www.w3.org/2000/svg" width="345" height="141" …'
|
|
147
|
+
|
|
148
|
+
toPNG(ean, { scale: 3, barHeight: 80 }).then((bytes) => {
|
|
149
|
+
// Uint8Array — a 1-bit palette PNG
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### 4. The source directly
|
|
154
|
+
|
|
155
|
+
[`src/index.js`](src/index.js) is plain ESM with JSDoc types and no build step of its own. Import
|
|
156
|
+
it and let your bundler tree-shake; the package is marked side-effect free.
|
|
157
|
+
|
|
158
|
+
```js
|
|
159
|
+
import { encode, decode, toImageData, listFormats } from './src/index.js';
|
|
160
|
+
|
|
161
|
+
const matrix = encode('https://example.com', { format: 'qr', ecc: 'M' });
|
|
162
|
+
const image = toImageData(matrix, { scale: 4, margin: 4 });
|
|
163
|
+
|
|
164
|
+
const found = decode(image, { formats: ['qr'] });
|
|
165
|
+
// [ { text: 'https://example.com', format: 'qr', version: 2, ecc: 'M', … } ]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Decoding takes anything `ImageData`-shaped, so a canvas, an `OffscreenCanvas`,
|
|
169
|
+
`createImageBitmap`, or an image library's raw buffer all satisfy it without an adapter:
|
|
170
|
+
|
|
171
|
+
```js
|
|
172
|
+
const ctx = canvas.getContext('2d');
|
|
173
|
+
ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
|
|
174
|
+
|
|
175
|
+
for (const hit of decode(ctx.getImageData(0, 0, canvas.width, canvas.height))) {
|
|
176
|
+
console.log(hit.format, hit.text);
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`decode` returns an array, empty when nothing is found. A frame with no barcode is an ordinary
|
|
181
|
+
outcome for a camera loop, not an error, so the common case needs no `try`/`catch`. Use
|
|
182
|
+
`decodeStrict` when absence really is a failure.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Supported formats
|
|
187
|
+
|
|
188
|
+
Generated from `listFormats()`, which reports writing and reading as separate capabilities.
|
|
189
|
+
Writing a symbology is a table lookup; reading one needs a detector that finds it in a
|
|
190
|
+
photograph. The two lists legitimately differ, and saying so here is better than failing at call
|
|
191
|
+
time.
|
|
192
|
+
|
|
193
|
+
| Format | `id` | Kind | Write | Read |
|
|
194
|
+
|---|---|:---:|:---:|:---:|
|
|
195
|
+
| EAN-13 | `ean13` | 1D | ✅ | ✅ |
|
|
196
|
+
| EAN-8 | `ean8` | 1D | ✅ | ✅ |
|
|
197
|
+
| UPC-A | `upca` | 1D | ✅ | ✅ |
|
|
198
|
+
| UPC-E | `upce` | 1D | ✅ | ✅ |
|
|
199
|
+
| ISBN (Bookland) | `isbn` | 1D | ✅ | ✅ [^1] |
|
|
200
|
+
| Code 128 | `code128` | 1D | ✅ | ✅ |
|
|
201
|
+
| GS1-128 | `gs1128` | 1D | ✅ | ✅ [^1] |
|
|
202
|
+
| Code 39 | `code39` | 1D | ✅ | ✅ |
|
|
203
|
+
| Code 93 | `code93` | 1D | ✅ | ✅ |
|
|
204
|
+
| ITF (Interleaved 2 of 5) | `itf` | 1D | ✅ | ✅ |
|
|
205
|
+
| ITF-14 | `itf14` | 1D | ✅ | ✅ [^1] |
|
|
206
|
+
| Codabar | `codabar` | 1D | ✅ | ✅ |
|
|
207
|
+
| Code 11 | `code11` | 1D | ✅ | — |
|
|
208
|
+
| MSI Plessey | `msi` | 1D | ✅ | — |
|
|
209
|
+
| Pharmacode | `pharmacode` | 1D | ✅ | — |
|
|
209
210
|
| QR Code | `qr` | 2D | ✅ | ✅ |
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
###
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
> folder over localhost for that half; the page detects the situation and says so rather than
|
|
253
|
-
> failing silently.
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
## API summary
|
|
258
|
-
|
|
259
|
-
Two functions carry the whole surface. Everything else is a renderer or a format-specific escape
|
|
260
|
-
hatch.
|
|
261
|
-
|
|
262
|
-
### Encoding and decoding
|
|
211
|
+
| Data Matrix ECC 200 | `datamatrix` | 2D | ✅ | ✅ |
|
|
212
|
+
| Aztec Code | `aztec` | 2D | ✅ | ✅ |
|
|
213
|
+
|
|
214
|
+
Eighteen formats, all writable, fifteen readable. **Code 11, MSI Plessey and Pharmacode are
|
|
215
|
+
write-only** — they encode correctly, but there is no reader for them, and `decode` will never
|
|
216
|
+
return one.
|
|
217
|
+
|
|
218
|
+
[^1]: `gs1128`, `itf14` and `isbn` are sub-variants that share a decoder with their base format, so
|
|
219
|
+
they decode under that base id: a GS1-128 comes back as `code128`, an ITF-14 as `itf`, and an ISBN
|
|
220
|
+
as `ean13`. The payload is intact either way — a GS1-128 *is* a Code 128 with a leading FNC1, an
|
|
221
|
+
ITF-14 *is* an ITF fixed at fourteen digits, and an ISBN barcode *is* an EAN-13 with a 978/979
|
|
222
|
+
prefix. Match on `result.format === 'code128'` rather than `'gs1128'`, or a
|
|
223
|
+
condition on the sub-variant id will silently never fire.
|
|
224
|
+
|
|
225
|
+
### Data Matrix ECC 200
|
|
226
|
+
|
|
227
|
+
`datamatrix` writes and reads the 30 classic ECC 200 square and rectangular symbol sizes. The
|
|
228
|
+
encoder supports ASCII compaction (including numeric pairs), Base256 binary payloads, automatic
|
|
229
|
+
or forced square/rectangular shape, Reed–Solomon error correction and GS1 FNC1 in the first
|
|
230
|
+
position. DMRE is not included.
|
|
231
|
+
|
|
232
|
+
```js
|
|
233
|
+
import { encodeDataMatrix, decodeDataMatrix } from '@sythos/js_barcode_universal/datamatrix';
|
|
234
|
+
|
|
235
|
+
const symbol = encodeDataMatrix('0101234567890128', { gs1: true, shape: 'square' });
|
|
236
|
+
const result = decodeDataMatrix(symbol);
|
|
237
|
+
console.log(result.text, result.gs1); // 0101234567890128 true
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Binary content is accepted as a `Uint8Array` with `encoding: 'base256'`. The current high-level
|
|
241
|
+
decoder handles ASCII and Base256 codewords; C40, Text, X12 and EDIFACT input symbols are not yet
|
|
242
|
+
decoded. The current detector accepts axis-aligned square or rectangular symbols; the normal
|
|
243
|
+
`decode(image, { formats: ['datamatrix'] })` pipeline also retries quarter-turn rotations.
|
|
244
|
+
Arbitrary-angle and perspective-skewed Data Matrix photographs are not yet guaranteed.
|
|
245
|
+
|
|
246
|
+
### Aztec Code
|
|
247
|
+
|
|
248
|
+
`aztec` writes Compact layers 1–4 and Full layers 1–32, selecting a fitting symbol automatically
|
|
249
|
+
unless `layers` and `compact` are forced. It supports the five Aztec text tables and UTF-8 byte
|
|
250
|
+
payloads through Binary Shift, with `eccPercent` (default 23) controlling the requested
|
|
251
|
+
error-correction level.
|
|
252
|
+
ECI is not yet a configurable public option.
|
|
263
253
|
|
|
264
254
|
```js
|
|
265
|
-
|
|
266
|
-
```
|
|
255
|
+
import { encodeAztec, decodeAztec } from '@sythos/js_barcode_universal/aztec';
|
|
267
256
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
```js
|
|
272
|
-
encode('5901234123457', { format: 'ean13' })
|
|
273
|
-
encode('ABC-123', { format: 'code39', fullAscii: true, checkDigit: true })
|
|
274
|
-
encode('https://example.com', { format: 'qr', ecc: 'H', version: 7 })
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
```js
|
|
278
|
-
decode(image, options?) → Result[]
|
|
279
|
-
decodeStrict(image, options?) → Result // throws NotFoundError instead of returning []
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
`image` is `{ data, width, height }` with RGBA bytes. `options`: `formats` (restrict the search,
|
|
283
|
-
and go faster), `tryHarder` (retry inverted, default `true`), `binarizer`
|
|
284
|
-
(`'global' | 'hybrid' | 'auto'`). A `Result` carries at least `text` and `format`; QR results also
|
|
285
|
-
carry `bytes`, `version` and `ecc`.
|
|
286
|
-
|
|
287
|
-
```js
|
|
288
|
-
listFormats() → { id, label, canWrite, canRead, kind }[]
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
The table above is this function's output. Read it at runtime rather than hard-coding a format
|
|
292
|
-
list — that is how the demo pages build their dropdowns.
|
|
293
|
-
|
|
294
|
-
### Renderers
|
|
295
|
-
|
|
296
|
-
```js
|
|
297
|
-
toSVG(matrix, options?) → string // one merged <path>, not a rect per module
|
|
298
|
-
toSVGDataURI(matrix, options?) → string // data: URI for an <img src>
|
|
299
|
-
toImageData(matrix, options?) → { data, width, height }
|
|
300
|
-
toPNG(matrix, options?) → Promise<Uint8Array> // 1-bit palette PNG
|
|
301
|
-
toPNGDataURI(matrix, options?) → Promise<string>
|
|
302
|
-
toCanvas(matrix, canvas, options?) → boolean // 2D context
|
|
303
|
-
renderToCanvasAuto(matrix, canvas, options?) → { backend: 'webgl2' | '2d' | 'none' }
|
|
304
|
-
renderToCanvasAutoAsync(matrix, canvas, options?) → Promise<{ backend: 'webgpu' | 'webgl2' | '2d' | 'none' }>
|
|
257
|
+
const symbol = encodeAztec('Ciao, mondo 👋', { eccPercent: 23 });
|
|
258
|
+
const result = decodeAztec(symbol);
|
|
259
|
+
console.log(result.text); // Ciao, mondo 👋
|
|
305
260
|
```
|
|
306
261
|
|
|
307
|
-
The
|
|
308
|
-
|
|
262
|
+
The image detector handles rotation, inverted polarity and quadrilateral sampling around the
|
|
263
|
+
central bull’s-eye. Severe photographic perspective remains an interoperability and robustness
|
|
264
|
+
gate rather than a guaranteed capability.
|
|
309
265
|
|
|
310
|
-
|
|
311
|
-
asynchronous, and a synchronous function can never wait for one. Use `renderToCanvasAutoAsync`
|
|
312
|
-
when you want WebGPU in the chain. Both fall through to the 2D context, which always exists.
|
|
313
|
-
|
|
314
|
-
All renderers share the same options:
|
|
315
|
-
|
|
316
|
-
| Option | Default | Meaning |
|
|
317
|
-
|---|---|---|
|
|
318
|
-
| `scale` | `8` | Pixels per module |
|
|
319
|
-
| `margin` | `4` | Quiet-zone modules on every side |
|
|
320
|
-
| `dark` | `'#000000'` | Colour of set modules |
|
|
321
|
-
| `light` | `'#ffffff'` | Colour of clear modules; `'none'` for transparent |
|
|
322
|
-
| `barHeight` | auto | 1D only: total bar height in pixels |
|
|
323
|
-
|
|
324
|
-
Also exported: `BitMatrix`, the error types (`BarcodeError`, `EncodeError`, `NotFoundError`,
|
|
325
|
-
`FormatError`, `ChecksumError`), the per-format writers (`encodeEAN13`, `encodeCode128`, …), the
|
|
326
|
-
QR entry points (`encodeQR`, `decodeQR`, `detectQR`, `detectAndDecodeQR`), the image primitives
|
|
327
|
-
(`LuminanceSource`, `binarize`, `binarizeGlobal`, `binarizeHybrid`), and the capability probes
|
|
328
|
-
`isWebGL2Available` / `isWebGPUAvailable`.
|
|
329
|
-
|
|
330
|
-
---
|
|
331
|
-
|
|
332
|
-
## How it works
|
|
333
|
-
|
|
334
|
-
**`BitMatrix` is the interchange type.** Every writer produces one, every reader consumes one,
|
|
335
|
-
every renderer draws one. That single currency is what keeps symbologies and output targets
|
|
336
|
-
independent of each other — adding a format touches no renderer, and adding a renderer touches no
|
|
337
|
-
format. Storage is row-packed into a `Uint32Array`: one allocation, cache-friendly row scans, and
|
|
338
|
-
cheap whole-row operations for the 1D readers.
|
|
339
|
-
|
|
340
|
-
**A set bit is a dark module.** This matches how every specification describes its symbols;
|
|
341
|
-
renderers invert where their medium needs it.
|
|
342
|
-
|
|
343
|
-
**`encode` returns no quiet zone.** The margin is a rendering decision, not an encoding one — how
|
|
344
|
-
much white space a symbol needs depends on where it is going — so the renderers add it and the
|
|
345
|
-
matrix stays the pure symbol. For the same reason, **linear symbols come back exactly one module
|
|
346
|
-
tall**: height carries no information in a 1D barcode, so encoding one would be inventing data.
|
|
347
|
-
The renderer stretches the single row to `barHeight` *before* applying the quiet zone, so the
|
|
348
|
-
margin ends up uniform on all four sides.
|
|
349
|
-
|
|
350
|
-
**The read pipeline** is a straight line, each stage a separate module:
|
|
351
|
-
|
|
352
|
-
```
|
|
353
|
-
RGBA bytes → luminance → binarize → detect → sample → error-correct → decode
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
Luminance conversion flattens the image to greyscale. Binarization turns that into a `BitMatrix`,
|
|
357
|
-
either globally or with a hybrid local threshold that survives uneven lighting. Detection locates
|
|
358
|
-
a symbol and its corners in that bit plane. Sampling reads the symbol back onto its module grid
|
|
359
|
-
through a perspective transform, so a photograph taken at an angle still yields a square grid.
|
|
360
|
-
Error correction repairs what the camera lost. Only then is the payload decoded.
|
|
361
|
-
|
|
362
|
-
**Reed–Solomon is generic over the finite field.** The `GaloisField` class is constructed with a
|
|
363
|
-
field order and a primitive polynomial rather than hard-coding GF(256), which is what lets one
|
|
364
|
-
implementation serve QR, and the prime field GF(929) that PDF417 needs. Prime fields are the
|
|
365
|
-
subtle case: in a binary field addition and subtraction are both XOR, so a decoder that inlines
|
|
366
|
-
`^` for field addition passes every binary field and fails only the prime one.
|
|
367
|
-
|
|
368
|
-
---
|
|
369
|
-
|
|
370
|
-
## About the GPU path
|
|
371
|
-
|
|
372
|
-
The WebGL2 and WebGPU backends accelerate **drawing** a barcode, not **computing** one. That is
|
|
373
|
-
worth stating plainly, because "GPU barcode generation" naturally suggests the latter.
|
|
374
|
-
|
|
375
|
-
Encoding is sequential integer work: Reed–Solomon polynomial division, mask penalty scoring, bit
|
|
376
|
-
placement along a zig-zag path. Each step depends on the one before it, which is precisely the
|
|
377
|
-
shape a GPU cannot exploit. A complete QR encode takes well under a millisecond on the CPU — less
|
|
378
|
-
time than dispatching a compute shader and reading the result back would cost. Moving it to the
|
|
379
|
-
GPU would make it slower.
|
|
380
|
-
|
|
381
|
-
So encoding stays on the CPU because that is the correct engineering answer, not because
|
|
382
|
-
something is missing. Where the GPU genuinely earns its place is drawing large symbols, or many
|
|
383
|
-
symbols per frame, straight into a canvas without a CPU-side pixel buffer — and it would earn it
|
|
384
|
-
again on the read side, where per-frame greyscale conversion and block statistics over a 4K camera
|
|
385
|
-
image are both the real bottleneck and embarrassingly parallel.
|
|
386
|
-
|
|
387
|
-
---
|
|
388
|
-
|
|
389
|
-
## Browser support
|
|
390
|
-
|
|
391
|
-
The syntax floor is **iOS Safari 15**. No `Array.prototype.at`, no top-level `await`, no
|
|
392
|
-
`Object.groupBy`.
|
|
393
|
-
|
|
394
|
-
`OffscreenCanvas`, WebGL2 and WebGPU are feature-detected, never assumed. The 2D canvas path
|
|
395
|
-
always exists, so nothing is unreachable on an older device — `renderToCanvasAuto` degrades to it
|
|
396
|
-
and reports which backend actually drew.
|
|
397
|
-
|
|
398
|
-
---
|
|
399
|
-
|
|
400
|
-
## Licence
|
|
401
|
-
|
|
402
|
-
MIT © 2026 Sythos. Every source file carries the header.
|
|
403
|
-
|
|
404
|
-
**The code is 100% original.** No source code and no constant table from any other barcode
|
|
405
|
-
implementation is present, under any licence, permissive or otherwise. The symbologies are
|
|
406
|
-
implemented from published descriptions of the formats — which are systems and facts, not works of
|
|
407
|
-
authorship — and from constant tables generated by this project's own scripts wherever a table is
|
|
408
|
-
derivable rather than arbitrary. There is consequently no upstream licence to carry and no
|
|
409
|
-
co-author to credit.
|
|
410
|
-
|
|
411
|
-
**Trademark is not licence.** QR Code® is a registered trademark of DENSO WAVE; Aztec Code,
|
|
412
|
-
MaxiCode and GS1 DataBar are likewise marks of their owners. A trademark does not restrict
|
|
413
|
-
implementing a symbology, but it does constrain branding — which is why this package is named
|
|
414
|
-
descriptively rather than after any mark.
|
|
415
|
-
|
|
416
|
-
[`LICENSE`](LICENSE) carries the full MIT text plus an informational appendix inventorying the
|
|
417
|
-
specification copyrights, patent history and trademarks that surround these symbologies. None of
|
|
418
|
-
them encumbers this code; the appendix is an engineering inventory, not legal advice.
|
|
419
|
-
[`NOTICE.md`](NOTICE.md) records the origin of the code and how its correctness is verified.
|
|
420
|
-
|
|
421
|
-
---
|
|
422
|
-
|
|
423
|
-
## Contributing and roadmap
|
|
424
|
-
|
|
425
|
-
[`PLAN.md`](PLAN.md) is the live status document: what is shipped, what is next, and the ground
|
|
426
|
-
rules — chief among them that no code or constant table from any other barcode implementation
|
|
427
|
-
enters this project, which is what keeps the licence clean.
|
|
266
|
+
### Not implemented
|
|
428
267
|
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
268
|
+
**PDF417, GS1 DataBar and MaxiCode are not implemented** — neither writing
|
|
269
|
+
nor reading. Data Matrix ECC 200 is implemented for its classic square and rectangular symbols;
|
|
270
|
+
DMRE remains outside the current scope. Some scaffolding for the remaining formats exists in the core (the Galois field code already handles
|
|
271
|
+
the prime field PDF417 needs), but none of those remaining symbologies is usable today. See [`PLAN.md`](PLAN.md)
|
|
272
|
+
for where they sit.
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Live examples
|
|
277
|
+
|
|
278
|
+
Two self-contained pages, each loading the IIFE bundle with a plain `<script>` tag. **Both open
|
|
279
|
+
directly from disk** — double-click the file, no server and no build. This `examples/` directory is
|
|
280
|
+
the single canonical source; the development workspace references these files instead of keeping
|
|
281
|
+
a second copy.
|
|
282
|
+
|
|
283
|
+
### [`examples/create.html`](examples/create.html)
|
|
284
|
+
|
|
285
|
+
Pick any writable format, type a payload, and watch the symbol redraw as you type; download it as
|
|
286
|
+
PNG or SVG. For QR it adds a **content-type builder** that assembles the payload for you across
|
|
287
|
+
URL, email, phone, SMS, Wi-Fi network, contact card (both vCard and MeCard), geo location and
|
|
288
|
+
calendar event — with correct escaping for each — and shows you the exact string it produced, so
|
|
289
|
+
you can see what a Wi-Fi or vCard QR actually contains. ECC level, version, scale, margin and both
|
|
290
|
+
colours are exposed.
|
|
291
|
+
|
|
292
|
+
### [`examples/read.html`](examples/read.html)
|
|
293
|
+
|
|
294
|
+
Decode from an image: drop one onto the page, or click to choose a file. It then offers a live
|
|
295
|
+
camera loop that decodes continuously from the video stream.
|
|
296
|
+
|
|
297
|
+
> The file and drag-drop path works anywhere, `file://` included. **The camera needs http(s)**,
|
|
298
|
+
> because `getUserMedia` requires a secure context and refuses to run from `file://`. Serve the
|
|
299
|
+
> folder over localhost for that half; the page detects the situation and says so rather than
|
|
300
|
+
> failing silently.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## API summary
|
|
305
|
+
|
|
306
|
+
Two functions carry the whole surface. Everything else is a renderer or a format-specific escape
|
|
307
|
+
hatch.
|
|
308
|
+
|
|
309
|
+
### Encoding and decoding
|
|
310
|
+
|
|
311
|
+
```js
|
|
312
|
+
encode(text, options?) → BitMatrix
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`options`: `format` (default `'qr'`), `ecc` (`'L'|'M'|'Q'|'H'`), `version` (QR 1–40, auto if
|
|
316
|
+
omitted), `checkDigit`, `fullAscii` (Code 39 extended), `gs1` (emit a leading FNC1). Data Matrix
|
|
317
|
+
ECC 200 accepts `shape: 'any' | 'square' | 'rectangular'` and `encoding: 'ascii' | 'base256'`.
|
|
318
|
+
Aztec accepts `layers`, `compact` and `eccPercent`; it transports UTF-8 byte payloads through
|
|
319
|
+
Binary Shift, and it does not expose configurable ECI yet.
|
|
320
|
+
|
|
321
|
+
```js
|
|
322
|
+
encode('5901234123457', { format: 'ean13' })
|
|
323
|
+
encode('ABC-123', { format: 'code39', fullAscii: true, checkDigit: true })
|
|
324
|
+
encode('https://example.com', { format: 'qr', ecc: 'H', version: 7 })
|
|
325
|
+
encode('0101234567890128', { format: 'datamatrix', gs1: true })
|
|
326
|
+
encode('Ciao, mondo 👋', { format: 'aztec', eccPercent: 23 })
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
```js
|
|
330
|
+
decode(image, options?) → Result[]
|
|
331
|
+
decodeStrict(image, options?) → Result // throws NotFoundError instead of returning []
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
`image` is `{ data, width, height }` with RGBA bytes. `options`: `formats` (restrict the search,
|
|
335
|
+
and go faster), `tryHarder` (retry inverted, default `true`), `binarizer`
|
|
336
|
+
(`'global' | 'hybrid' | 'auto'`). A `Result` carries at least `text` and `format`; QR results also
|
|
337
|
+
carry `bytes`, `version` and `ecc`.
|
|
338
|
+
|
|
339
|
+
```js
|
|
340
|
+
listFormats() → { id, label, canWrite, canRead, kind }[]
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
The table above is this function's output. Read it at runtime rather than hard-coding a format
|
|
344
|
+
list — that is how the demo pages build their dropdowns.
|
|
345
|
+
|
|
346
|
+
### Renderers
|
|
347
|
+
|
|
348
|
+
```js
|
|
349
|
+
toSVG(matrix, options?) → string // one merged <path>, not a rect per module
|
|
350
|
+
toSVGDataURI(matrix, options?) → string // data: URI for an <img src>
|
|
351
|
+
toImageData(matrix, options?) → { data, width, height }
|
|
352
|
+
toPNG(matrix, options?) → Promise<Uint8Array> // 1-bit palette PNG
|
|
353
|
+
toPNGDataURI(matrix, options?) → Promise<string>
|
|
354
|
+
toCanvas(matrix, canvas, options?) → boolean // 2D context
|
|
355
|
+
renderToCanvasAuto(matrix, canvas, options?) → { backend: 'webgl2' | '2d' | 'none' }
|
|
356
|
+
renderToCanvasAutoAsync(matrix, canvas, options?) → Promise<{ backend: 'webgpu' | 'webgl2' | '2d' | 'none' }>
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
The two PNG functions are async because they use the platform's deflate — `node:zlib` or
|
|
360
|
+
`CompressionStream` — and fall back to stored blocks where neither exists.
|
|
361
|
+
|
|
362
|
+
`renderToCanvasAuto` is synchronous and therefore cannot reach WebGPU: acquiring an adapter is
|
|
363
|
+
asynchronous, and a synchronous function can never wait for one. Use `renderToCanvasAutoAsync`
|
|
364
|
+
when you want WebGPU in the chain. Both fall through to the 2D context, which always exists.
|
|
365
|
+
|
|
366
|
+
All renderers share the same options:
|
|
367
|
+
|
|
368
|
+
| Option | Default | Meaning |
|
|
369
|
+
|---|---|---|
|
|
370
|
+
| `scale` | `8` | Pixels per module |
|
|
371
|
+
| `margin` | `4` | Quiet-zone modules on every side |
|
|
372
|
+
| `dark` | `'#000000'` | Colour of set modules |
|
|
373
|
+
| `light` | `'#ffffff'` | Colour of clear modules; `'none'` for transparent |
|
|
374
|
+
| `barHeight` | auto | 1D only: total bar height in pixels |
|
|
375
|
+
|
|
376
|
+
Also exported: `BitMatrix`, the error types (`BarcodeError`, `EncodeError`, `NotFoundError`,
|
|
377
|
+
`FormatError`, `ChecksumError`), the per-format writers (`encodeEAN13`, `encodeCode128`, …), the
|
|
378
|
+
QR entry points (`encodeQR`, `decodeQR`, `detectQR`, `detectAndDecodeQR`), the image primitives
|
|
379
|
+
(`LuminanceSource`, `binarize`, `binarizeGlobal`, `binarizeHybrid`), and the capability probes
|
|
380
|
+
`isWebGL2Available` / `isWebGPUAvailable`.
|
|
381
|
+
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
## How it works
|
|
385
|
+
|
|
386
|
+
**`BitMatrix` is the interchange type.** Every writer produces one, every reader consumes one,
|
|
387
|
+
every renderer draws one. That single currency is what keeps symbologies and output targets
|
|
388
|
+
independent of each other — adding a format touches no renderer, and adding a renderer touches no
|
|
389
|
+
format. Storage is row-packed into a `Uint32Array`: one allocation, cache-friendly row scans, and
|
|
390
|
+
cheap whole-row operations for the 1D readers.
|
|
391
|
+
|
|
392
|
+
**A set bit is a dark module.** This matches how every specification describes its symbols;
|
|
393
|
+
renderers invert where their medium needs it.
|
|
394
|
+
|
|
395
|
+
**`encode` returns no quiet zone.** The margin is a rendering decision, not an encoding one — how
|
|
396
|
+
much white space a symbol needs depends on where it is going — so the renderers add it and the
|
|
397
|
+
matrix stays the pure symbol. For the same reason, **linear symbols come back exactly one module
|
|
398
|
+
tall**: height carries no information in a 1D barcode, so encoding one would be inventing data.
|
|
399
|
+
The renderer stretches the single row to `barHeight` *before* applying the quiet zone, so the
|
|
400
|
+
margin ends up uniform on all four sides.
|
|
401
|
+
|
|
402
|
+
**The read pipeline** is a straight line, each stage a separate module:
|
|
403
|
+
|
|
404
|
+
```
|
|
405
|
+
RGBA bytes → luminance → binarize → detect → sample → error-correct → decode
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
Luminance conversion flattens the image to greyscale. Binarization turns that into a `BitMatrix`,
|
|
409
|
+
either globally or with a hybrid local threshold that survives uneven lighting. Detection locates
|
|
410
|
+
a symbol and its corners in that bit plane. Detectors that recover four perspective-aware corners
|
|
411
|
+
(currently QR) sample the symbol back through a perspective transform. Data Matrix currently uses
|
|
412
|
+
an axis-aligned bounding box plus quarter-turn retries. Error correction repairs what the camera
|
|
413
|
+
lost. Only then is the payload decoded.
|
|
414
|
+
|
|
415
|
+
**Reed–Solomon is generic over the finite field.** The `GaloisField` class is constructed with a
|
|
416
|
+
field order and a primitive polynomial rather than hard-coding GF(256), which is what lets one
|
|
417
|
+
implementation serve QR, and the prime field GF(929) that PDF417 needs. Prime fields are the
|
|
418
|
+
subtle case: in a binary field addition and subtraction are both XOR, so a decoder that inlines
|
|
419
|
+
`^` for field addition passes every binary field and fails only the prime one.
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## About the GPU path
|
|
424
|
+
|
|
425
|
+
The WebGL2 and WebGPU backends accelerate **drawing** a barcode, not **computing** one. That is
|
|
426
|
+
worth stating plainly, because "GPU barcode generation" naturally suggests the latter.
|
|
427
|
+
|
|
428
|
+
Encoding is sequential integer work: Reed–Solomon polynomial division, mask penalty scoring, bit
|
|
429
|
+
placement along a zig-zag path. Each step depends on the one before it, which is precisely the
|
|
430
|
+
shape a GPU cannot exploit. A complete QR encode takes well under a millisecond on the CPU — less
|
|
431
|
+
time than dispatching a compute shader and reading the result back would cost. Moving it to the
|
|
432
|
+
GPU would make it slower.
|
|
433
|
+
|
|
434
|
+
So encoding stays on the CPU because that is the correct engineering answer, not because
|
|
435
|
+
something is missing. Where the GPU genuinely earns its place is drawing large symbols, or many
|
|
436
|
+
symbols per frame, straight into a canvas without a CPU-side pixel buffer — and it would earn it
|
|
437
|
+
again on the read side, where per-frame greyscale conversion and block statistics over a 4K camera
|
|
438
|
+
image are both the real bottleneck and embarrassingly parallel.
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## Browser support
|
|
443
|
+
|
|
444
|
+
The syntax floor is **iOS Safari 15**. No `Array.prototype.at`, no top-level `await`, no
|
|
445
|
+
`Object.groupBy`.
|
|
446
|
+
|
|
447
|
+
`OffscreenCanvas`, WebGL2 and WebGPU are feature-detected, never assumed. The 2D canvas path
|
|
448
|
+
always exists, so nothing is unreachable on an older device — `renderToCanvasAuto` degrades to it
|
|
449
|
+
and reports which backend actually drew.
|
|
450
|
+
|
|
451
|
+
---
|
|
452
|
+
|
|
453
|
+
## Licence
|
|
454
|
+
|
|
455
|
+
MIT © 2026 Sythos. Every source file carries the header.
|
|
456
|
+
|
|
457
|
+
**The code is 100% original.** No source code and no constant table from any other barcode
|
|
458
|
+
implementation is present, under any licence, permissive or otherwise. The symbologies are
|
|
459
|
+
implemented from published descriptions of the formats — which are systems and facts, not works of
|
|
460
|
+
authorship — and from constant tables generated by this project's own scripts wherever a table is
|
|
461
|
+
derivable rather than arbitrary. There is consequently no upstream licence to carry and no
|
|
462
|
+
co-author to credit.
|
|
463
|
+
|
|
464
|
+
**Trademark is not licence.** QR Code® is a registered trademark of DENSO WAVE; Aztec Code,
|
|
465
|
+
MaxiCode and GS1 DataBar are likewise marks of their owners. A trademark does not restrict
|
|
466
|
+
implementing a symbology, but it does constrain branding — which is why this package is named
|
|
467
|
+
descriptively rather than after any mark.
|
|
468
|
+
|
|
469
|
+
Data Matrix ECC 200 is governed by ISO/IEC 16022:2024; GS1 DataMatrix additionally uses the GS1
|
|
470
|
+
General Specifications and a leading FNC1. Its engineering provenance, patent and trademark
|
|
471
|
+
research notes are recorded in [`licenses/data-matrix.license`](licenses/data-matrix.license),
|
|
472
|
+
with unresolved claims kept explicitly marked `[TO VERIFY]`.
|
|
473
|
+
|
|
474
|
+
[`LICENSE`](LICENSE) carries the full MIT text plus an informational appendix inventorying the
|
|
475
|
+
specification copyrights, patent history and trademarks that surround these symbologies. None of
|
|
476
|
+
them encumbers this code; the appendix is an engineering inventory, not legal advice.
|
|
477
|
+
[`NOTICE.md`](NOTICE.md) records the origin of the code and how its correctness is verified.
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## Contributing and roadmap
|
|
482
|
+
|
|
483
|
+
[`PLAN.md`](PLAN.md) is the live status document: what is shipped, what is next, and the ground
|
|
484
|
+
rules — chief among them that no code or constant table from any other barcode implementation
|
|
485
|
+
enters this project, which is what keeps the licence clean.
|
|
486
|
+
|
|
487
|
+
Issues and pull requests are welcome at
|
|
488
|
+
[Sythos/JS_Barcode_Universal](https://github.com/Sythos/JS_Barcode_Universal). A patch that adds a
|
|
489
|
+
symbology should implement it from the published description of the format, generate its tables
|
|
490
|
+
where they are derivable, and come with a symbol that a scanner this project did not write has
|
|
491
|
+
actually read — that last one is the check that matters.
|