@ericblade/quagga2 1.11.0 → 1.12.1
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/DEPENDENCIES.md +53 -1
- package/README.md +4 -2
- package/dist/quagga.js +7299 -5335
- package/dist/quagga.min.js +4 -4
- package/docs/contributing.md +18 -1
- package/docs/getting-started.md +1 -1
- package/docs/reference/api.md +42 -0
- package/docs/reference/configuration.md +1 -0
- package/docs/reference/readers.md +66 -1
- package/lib/quagga.js +18303 -12643
- package/package.json +15 -5
- package/type-definitions/quagga.d.ts +5 -1
package/docs/contributing.md
CHANGED
|
@@ -39,15 +39,24 @@ merging.
|
|
|
39
39
|
**Running Specific Tests**:
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
# All tests (unit +
|
|
42
|
+
# All tests (Node unit/integration + full Cypress suite)
|
|
43
43
|
npm test
|
|
44
44
|
|
|
45
|
+
# Run Node and Cypress in parallel (faster local iteration)
|
|
46
|
+
npm run test:parallel
|
|
47
|
+
|
|
45
48
|
# Node tests only
|
|
46
49
|
npm run test:node
|
|
47
50
|
|
|
48
51
|
# Browser tests only (requires Cypress)
|
|
49
52
|
npm run test:browser-all
|
|
50
53
|
|
|
54
|
+
# E2E examples spec with server (headless)
|
|
55
|
+
npm run test:e2e
|
|
56
|
+
|
|
57
|
+
# E2E examples spec (interactive, Electron)
|
|
58
|
+
npm run test:e2e:open
|
|
59
|
+
|
|
51
60
|
# Cypress: run only specific spec(s)
|
|
52
61
|
# Pass --spec through npm using --
|
|
53
62
|
npm run cypress:run -- --spec cypress/e2e/browser.cy.ts
|
|
@@ -61,6 +70,9 @@ npm run cypress:run -- --spec "cypress/e2e/**/browser*.cy.ts"
|
|
|
61
70
|
# Open interactive runner
|
|
62
71
|
npm run cypress:open
|
|
63
72
|
|
|
73
|
+
# Open only the examples E2E spec (Electron)
|
|
74
|
+
npm run cypress:open:e2e
|
|
75
|
+
|
|
64
76
|
# Choose a browser (if installed)
|
|
65
77
|
npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress run --browser chrome --env BUILD_ENV=development --spec cypress/e2e/browser.cy.ts
|
|
66
78
|
|
|
@@ -82,6 +94,11 @@ environments by default. If a test is known to fail in a specific environment, m
|
|
|
82
94
|
|
|
83
95
|
See `test/integration/README.md` for complete details on the test failure marking system.
|
|
84
96
|
|
|
97
|
+
**Notes**:
|
|
98
|
+
|
|
99
|
+
- The Cypress E2E examples (`cypress/e2e/examples.cy.ts`) require the local examples server on port 8080; the `test`, `test:e2e`, and `test:e2e:open` scripts start it automatically via `start-server-and-test`.
|
|
100
|
+
- The parallel runner uses prefixed logs (`e2e`, `node`) and exits non-zero if either side fails (`--kill-others-on-fail --success=all`).
|
|
101
|
+
|
|
85
102
|
#### Working on a changed copy of Quagga2 from another repository (ie, developing an external plugin) {#working-on-external-plugin}
|
|
86
103
|
|
|
87
104
|
If you need to make changes to Quagga2 to support some external code (such as an external reader plugin),
|
package/docs/getting-started.md
CHANGED
|
@@ -8,7 +8,7 @@ Quagga2 is a JavaScript barcode scanner library that works in both browsers and
|
|
|
8
8
|
|
|
9
9
|
- **Scan barcodes in real-time** using your device's camera
|
|
10
10
|
- **Decode barcodes from images** (photos, screenshots, etc.)
|
|
11
|
-
- **Support multiple formats**: EAN, CODE 128, CODE 39, EAN 8, UPC-A, UPC-C, I2of5, 2of5, CODE 93, CODE 32, and
|
|
11
|
+
- **Support multiple formats**: EAN, CODE 128, CODE 39, EAN 8, UPC-A, UPC-C, I2of5, 2of5, CODE 93, CODE 32, CODABAR, and PHARMACODE
|
|
12
12
|
- **Work offline** - all processing happens in the browser/Node.js, no server required
|
|
13
13
|
|
|
14
14
|
Unlike some libraries, Quagga2 includes a barcode **locator** that can find and decode barcodes regardless of their rotation or scale in the image.
|
package/docs/reference/api.md
CHANGED
|
@@ -126,6 +126,48 @@ Quagga.stop().then(() => {
|
|
|
126
126
|
- Does not remove event listeners (use `offDetected()` / `offProcessed()` for that)
|
|
127
127
|
- Returns a Promise that resolves when camera release is complete
|
|
128
128
|
|
|
129
|
+
### `Quagga.pause()` {#quagga-pause}
|
|
130
|
+
|
|
131
|
+
Pauses frame processing without stopping the camera or releasing resources.
|
|
132
|
+
|
|
133
|
+
**Parameters**: None
|
|
134
|
+
|
|
135
|
+
**Returns**: `void`
|
|
136
|
+
|
|
137
|
+
**Example**:
|
|
138
|
+
|
|
139
|
+
```javascript
|
|
140
|
+
// Pause scanning temporarily
|
|
141
|
+
Quagga.pause();
|
|
142
|
+
|
|
143
|
+
// Later, resume scanning
|
|
144
|
+
Quagga.start();
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**Behavior**:
|
|
148
|
+
|
|
149
|
+
- Stops processing new frames (no more `onProcessed` or `onDetected` callbacks)
|
|
150
|
+
- **Does not stop the camera** - the video stream continues running
|
|
151
|
+
- **Does not release resources** - the camera remains connected
|
|
152
|
+
- Can be resumed by calling `Quagga.start()`
|
|
153
|
+
|
|
154
|
+
**Use Cases**:
|
|
155
|
+
|
|
156
|
+
- Temporarily pause scanning while showing a modal or dialog
|
|
157
|
+
- Reduce CPU usage when the scanner is not visible
|
|
158
|
+
- Pause after detecting a barcode to allow user confirmation before resuming
|
|
159
|
+
|
|
160
|
+
**Difference from `stop()`**:
|
|
161
|
+
|
|
162
|
+
| Aspect | `pause()` | `stop()` |
|
|
163
|
+
|--------|-----------|----------|
|
|
164
|
+
| Frame processing | Stops | Stops |
|
|
165
|
+
| Camera stream | **Continues** | Disconnects |
|
|
166
|
+
| Resources | **Retained** | Released |
|
|
167
|
+
| Resume with | `start()` | `init()` + `start()` |
|
|
168
|
+
|
|
169
|
+
> **Note**: Since `pause()` keeps the camera running, the user's camera indicator light will remain on. If you want to fully release the camera, use `stop()` instead.
|
|
170
|
+
|
|
129
171
|
### `Quagga.onDetected(callback)` {#quagga-ondetected}
|
|
130
172
|
|
|
131
173
|
Registers a callback that is triggered when a barcode is successfully located and decoded.
|
|
@@ -560,6 +560,7 @@ decoder: {
|
|
|
560
560
|
- `2of5_reader` - Standard 2 of 5
|
|
561
561
|
- `code_93_reader` - Code 93
|
|
562
562
|
- `code_32_reader` - Code 32 (Italian Pharmacode)
|
|
563
|
+
- `pharmacode_reader` - Pharmacode (Pharmaceutical Binary Code)
|
|
563
564
|
|
|
564
565
|
See [Supported Barcode Types](readers.md) for complete details.
|
|
565
566
|
|
|
@@ -8,7 +8,7 @@ Quagga2 includes built-in readers for the following barcode formats:
|
|
|
8
8
|
|
|
9
9
|
| Reader Name | Barcode Format | Common Uses |
|
|
10
10
|
|-------------|----------------|-------------|
|
|
11
|
-
| `code_128_reader` | [Code 128](https://en.wikipedia.org/wiki/Code_128) | General purpose, shipping, packaging |
|
|
11
|
+
| `code_128_reader` | [Code 128](https://en.wikipedia.org/wiki/Code_128), [GS1-128](https://en.wikipedia.org/wiki/GS1-128) | General purpose, shipping, packaging, supply chain |
|
|
12
12
|
| `ean_reader` | [EAN-13](https://en.wikipedia.org/wiki/International_Article_Number) | Retail products worldwide |
|
|
13
13
|
| `ean_8_reader` | [EAN-8](https://en.wikipedia.org/wiki/EAN-8) | Small retail products |
|
|
14
14
|
| `code_39_reader` | [Code 39](https://en.wikipedia.org/wiki/Code_39) | Automotive, defense, healthcare |
|
|
@@ -20,6 +20,7 @@ Quagga2 includes built-in readers for the following barcode formats:
|
|
|
20
20
|
| `2of5_reader` | [Standard 2 of 5](https://en.wikipedia.org/wiki/Two-out-of-five_code) | Industrial, airline tickets |
|
|
21
21
|
| `code_93_reader` | [Code 93](https://en.wikipedia.org/wiki/Code_93) | Logistics, retail |
|
|
22
22
|
| `code_32_reader` | [Code 32](https://en.wikipedia.org/wiki/Pharmacode#Code_32) | Italian pharmaceuticals |
|
|
23
|
+
| `pharmacode_reader` | [Pharmacode](https://en.wikipedia.org/wiki/Pharmacode) | Pharmaceutical packaging |
|
|
23
24
|
|
|
24
25
|
## Basic Configuration {#basic-configuration}
|
|
25
26
|
|
|
@@ -99,6 +100,70 @@ Some barcode formats are subsets or extensions of others:
|
|
|
99
100
|
|
|
100
101
|
Be careful when enabling multiple related formats together.
|
|
101
102
|
|
|
103
|
+
## GS1-128 Barcodes {#gs1-128-barcodes}
|
|
104
|
+
|
|
105
|
+
[GS1-128](https://en.wikipedia.org/wiki/GS1-128) (formerly known as EAN-128 or UCC-128) is a subset of Code 128 used extensively in supply chain and logistics. It uses special FNC1 (Function Code 1) characters to separate variable-length data fields called Application Identifiers (AIs).
|
|
106
|
+
|
|
107
|
+
### How GS1-128 Works {#gs1-128-how-it-works}
|
|
108
|
+
|
|
109
|
+
GS1-128 barcodes encode structured data using standardized Application Identifiers. For example:
|
|
110
|
+
- **AI 01** = GTIN (Global Trade Item Number)
|
|
111
|
+
- **AI 10** = Batch/Lot Number
|
|
112
|
+
- **AI 17** = Expiration Date
|
|
113
|
+
- **AI 21** = Serial Number
|
|
114
|
+
|
|
115
|
+
The FNC1 character acts as a field separator between variable-length AIs, allowing decoders to know where one field ends and another begins.
|
|
116
|
+
|
|
117
|
+
### FNC1 Character Handling {#fnc1-character-handling}
|
|
118
|
+
|
|
119
|
+
When the `code_128_reader` decodes a GS1-128 barcode, FNC1 characters are represented as ASCII 29 (Group Separator, `\x1D` or `\u001d`). This follows the GS1 standard for representing FNC1 in decoded data.
|
|
120
|
+
|
|
121
|
+
```javascript
|
|
122
|
+
Quagga.decodeSingle({
|
|
123
|
+
src: 'gs1-128-barcode.jpg',
|
|
124
|
+
decoder: {
|
|
125
|
+
readers: ['code_128_reader']
|
|
126
|
+
}
|
|
127
|
+
}, function(result) {
|
|
128
|
+
if (result && result.codeResult) {
|
|
129
|
+
const code = result.codeResult.code;
|
|
130
|
+
// FNC1 characters appear as ASCII 29 (Group Separator)
|
|
131
|
+
const GS = String.fromCharCode(29); // '\x1D'
|
|
132
|
+
|
|
133
|
+
// Split on Group Separator to get individual AI fields
|
|
134
|
+
const fields = code.split(GS);
|
|
135
|
+
console.log('Fields:', fields);
|
|
136
|
+
// Example output: ["", "01034531200000111719050810ABCD1234", ...]
|
|
137
|
+
|
|
138
|
+
// Or check for GS1-128 format (starts with FNC1)
|
|
139
|
+
if (code.startsWith(GS)) {
|
|
140
|
+
console.log('This is a GS1-128 barcode');
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
});
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Parsing GS1-128 Data {#parsing-gs1-128-data}
|
|
147
|
+
|
|
148
|
+
Once decoded, you can parse the GS1-128 data using the Application Identifier structure:
|
|
149
|
+
|
|
150
|
+
```javascript
|
|
151
|
+
function parseGS1(code) {
|
|
152
|
+
const GS = String.fromCharCode(29);
|
|
153
|
+
// Remove leading FNC1 if present
|
|
154
|
+
const data = code.startsWith(GS) ? code.substring(1) : code;
|
|
155
|
+
|
|
156
|
+
// Split by FNC1 separator
|
|
157
|
+
const segments = data.split(GS);
|
|
158
|
+
|
|
159
|
+
// Parse each segment for its AI
|
|
160
|
+
// (A full implementation would use a complete AI table)
|
|
161
|
+
return segments;
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
For full GS1 parsing, consider using a dedicated library like [gs1-barcode-parser](https://www.npmjs.com/package/gs1-barcode-parser) after decoding with Quagga2.
|
|
166
|
+
|
|
102
167
|
## EAN Extensions {#ean-extensions}
|
|
103
168
|
|
|
104
169
|
### EAN-2 and EAN-5 Supplements {#ean-supplements}
|