@ericblade/quagga2 1.10.1 → 1.11.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/DEPENDENCIES.md +286 -0
- package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
- package/README.md +119 -10
- package/dist/quagga.js +11087 -10681
- package/dist/quagga.min.js +4 -3
- package/docs/_config.yml +3 -0
- package/docs/assets/bb-binary.png +0 -0
- package/docs/assets/bb-rotated.png +0 -0
- package/docs/assets/binary.png +0 -0
- package/docs/assets/component-labeling-line.png +0 -0
- package/docs/assets/component-labeling-text.png +0 -0
- package/docs/assets/component-labeling.png +0 -0
- package/docs/assets/connected-patch-labels.png +0 -0
- package/docs/assets/mobile-detected.png +0 -0
- package/docs/assets/mobile-located.png +0 -0
- package/docs/assets/patches_found.png +0 -0
- package/docs/assets/quaggaJS-code128.png +0 -0
- package/docs/assets/remaining-patch-labels.png +0 -0
- package/docs/assets/skeleton.png +0 -0
- package/docs/assets/teaser.png +0 -0
- package/docs/contributing.md +102 -0
- package/docs/explanation/algorithm-overview.md +69 -0
- package/docs/explanation/architecture.md +117 -0
- package/docs/explanation/how-barcode-localization-works.md +197 -0
- package/docs/explanation/index.md +80 -0
- package/docs/explanation/input-streams.md +270 -0
- package/docs/getting-started.md +213 -0
- package/docs/how-to-guides/configure-readers.md +79 -0
- package/docs/how-to-guides/external-readers.md +234 -0
- package/docs/how-to-guides/handle-difficult-barcodes.md +127 -0
- package/docs/how-to-guides/index.md +77 -0
- package/docs/how-to-guides/optimize-performance.md +114 -0
- package/docs/how-to-guides/tips-and-tricks.md +115 -0
- package/docs/how-to-guides/use-debug-flags.md +776 -0
- package/docs/how-to-guides/working-with-coordinates.md +254 -0
- package/docs/index.md +118 -0
- package/docs/reference/api.md +716 -0
- package/docs/reference/browser-support.md +109 -0
- package/docs/reference/camera-access.md +376 -0
- package/docs/reference/configuration.md +1008 -0
- package/docs/reference/dependencies.md +295 -0
- package/docs/reference/index.md +74 -0
- package/docs/reference/readers.md +261 -0
- package/docs/tutorials/first-scan.md +141 -0
- package/docs/tutorials/index.md +77 -0
- package/docs/tutorials/node-usage.md +182 -0
- package/docs/tutorials/react-integration.md +176 -0
- package/docs/tutorials/static-image.md +130 -0
- package/lib/quagga.js +3140 -2757
- package/package.json +22 -18
- package/type-definitions/quagga.d.ts +111 -9
package/README.md
CHANGED
|
@@ -10,6 +10,13 @@ This is a fork of the original QuaggaJS library, that will be maintained until s
|
|
|
10
10
|
original author and maintainer returns, or it has been completely replaced by built-in browser and
|
|
11
11
|
node functionality.
|
|
12
12
|
|
|
13
|
+
## 📚 Documentation
|
|
14
|
+
|
|
15
|
+
**[Complete Documentation](https://ericblade.github.io/quagga2/)** - Tutorials, guides, API reference, and more
|
|
16
|
+
(UNDER CONSTRUCTION!!!)
|
|
17
|
+
|
|
18
|
+
Quick links from this README:
|
|
19
|
+
|
|
13
20
|
- [Changelog](https://github.com/ericblade/quagga2/releases)
|
|
14
21
|
- [Browser Support](#browser-support)
|
|
15
22
|
- [Installing](#installing)
|
|
@@ -23,7 +30,7 @@ node functionality.
|
|
|
23
30
|
|
|
24
31
|
## Using React / Redux?
|
|
25
32
|
|
|
26
|
-
Please see also <https://github.com/ericblade/quagga2-react-example/> and <https://github.com/ericblade/quagga2-redux-middleware
|
|
33
|
+
Please see also <https://github.com/ericblade/quagga2-react-example/> and <https://github.com/ericblade/quagga2-redux-middleware/>. For live browser examples, see [docs/examples/](docs/examples/).
|
|
27
34
|
|
|
28
35
|
## Using Angular?
|
|
29
36
|
|
|
@@ -46,7 +53,7 @@ __2of5__, __CODE 93__, __CODE 32__ and __CODABAR__. The library is also capable
|
|
|
46
53
|
code relies on heavy image-processing even recent smartphones are capable of
|
|
47
54
|
locating and decoding barcodes in real-time.
|
|
48
55
|
|
|
49
|
-
Try some [examples](https://
|
|
56
|
+
Try some [examples](https://ericblade.github.io/quagga2/examples) and check out
|
|
50
57
|
the blog post ([How barcode-localization works in QuaggaJS][oberhofer_co_how])
|
|
51
58
|
if you want to dive deeper into this topic.
|
|
52
59
|
|
|
@@ -199,6 +206,25 @@ Quagga2 exports the BarcodeReader prototype, which should also allow you to crea
|
|
|
199
206
|
reader implementations using the base BarcodeReader implementation inside Quagga2. The QR reader
|
|
200
207
|
does not make use of this functionality, as QR is not picked up as a barcode in BarcodeReader.
|
|
201
208
|
|
|
209
|
+
### External Reader Priority
|
|
210
|
+
|
|
211
|
+
External readers follow the same priority rules as built-in readers. Once registered with
|
|
212
|
+
`Quagga.registerReader()`, an external reader can be placed anywhere in the `readers` array,
|
|
213
|
+
and its position determines when it attempts to decode relative to other readers.
|
|
214
|
+
|
|
215
|
+
```javascript
|
|
216
|
+
// Register external reader first
|
|
217
|
+
Quagga.registerReader('my_custom_reader', MyCustomReader);
|
|
218
|
+
|
|
219
|
+
// Use in config - position determines priority
|
|
220
|
+
Quagga.init({
|
|
221
|
+
decoder: {
|
|
222
|
+
// External reader tried first, then built-in readers
|
|
223
|
+
readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
|
|
224
|
+
}
|
|
225
|
+
});
|
|
226
|
+
```
|
|
227
|
+
|
|
202
228
|
## <a name="Building">Building</a>
|
|
203
229
|
|
|
204
230
|
You can build the library yourself by simply cloning the repo and typing:
|
|
@@ -329,6 +355,13 @@ In contrast to the calls described above, this method does not rely on
|
|
|
329
355
|
`getUserMedia` and operates on a single image instead. The provided callback
|
|
330
356
|
is the same as in `onDetected` and contains the result `data` object.
|
|
331
357
|
|
|
358
|
+
**Important**: `decodeSingle` has a built-in default of `inputStream.size: 800`.
|
|
359
|
+
This means images are automatically scaled to 800px on their longest side (both
|
|
360
|
+
larger images scaled down AND smaller images scaled up). The `box`, `boxes`, and
|
|
361
|
+
`line` coordinates in the result are returned in this scaled coordinate space,
|
|
362
|
+
not the original image dimensions. To disable scaling and use original dimensions,
|
|
363
|
+
set `inputStream.size` to `0`.
|
|
364
|
+
|
|
332
365
|
### Quagga.offProcessed(handler)
|
|
333
366
|
|
|
334
367
|
In case the `onProcessed` event is no longer relevant, `offProcessed` removes
|
|
@@ -417,6 +450,8 @@ empty.
|
|
|
417
450
|
Quagga2 exposes a CameraAccess API that is available for performing some shortcut access to commonly
|
|
418
451
|
used camera functions. This API is available as `Quagga.CameraAccess` and is documented below.
|
|
419
452
|
|
|
453
|
+
**[Full CameraAccess API Documentation](https://ericblade.github.io/quagga2/reference/camera-access.html)** - Detailed reference with examples, error handling, and advanced usage.
|
|
454
|
+
|
|
420
455
|
## CameraAccess.request(HTMLVideoElement | null, MediaTrackConstraints?)
|
|
421
456
|
|
|
422
457
|
Will attempt to initialize the camera and start playback given the specified video element. Camera
|
|
@@ -430,11 +465,31 @@ This function will return a Promise that resolves when completed, or rejects on
|
|
|
430
465
|
If a video element is known to be running, this will pause the video element, then return a Promise
|
|
431
466
|
that when resolved will have stopped all tracks in the video element, and released all resources.
|
|
432
467
|
|
|
433
|
-
## CameraAccess.enumerateVideoDevices()
|
|
468
|
+
## CameraAccess.enumerateVideoDevices(constraints?)
|
|
434
469
|
|
|
435
470
|
This will send out a call to navigator.mediaDevices.enumerateDevices(), filter out any mediadevices
|
|
436
471
|
that do not have a kind of 'videoinput', and resolve the promise with an array of MediaDeviceInfo.
|
|
437
472
|
|
|
473
|
+
Optionally, you can pass MediaTrackConstraints to filter devices. When constraints are provided,
|
|
474
|
+
only devices that can satisfy the given constraints will be returned. This is useful for filtering
|
|
475
|
+
out cameras that don't meet your requirements (e.g., eliminating wide-angle cameras).
|
|
476
|
+
|
|
477
|
+
```javascript
|
|
478
|
+
// Get all video devices
|
|
479
|
+
const devices = await Quagga.CameraAccess.enumerateVideoDevices();
|
|
480
|
+
|
|
481
|
+
// Get only devices that support minimum resolution
|
|
482
|
+
const hdDevices = await Quagga.CameraAccess.enumerateVideoDevices({
|
|
483
|
+
width: { min: 1280 },
|
|
484
|
+
height: { min: 720 }
|
|
485
|
+
});
|
|
486
|
+
|
|
487
|
+
// Get only back-facing cameras
|
|
488
|
+
const backCameras = await Quagga.CameraAccess.enumerateVideoDevices({
|
|
489
|
+
facingMode: 'environment'
|
|
490
|
+
});
|
|
491
|
+
```
|
|
492
|
+
|
|
438
493
|
## CameraAccess.getActiveStreamLabel()
|
|
439
494
|
|
|
440
495
|
Returns the label for the active video track
|
|
@@ -447,7 +502,7 @@ Returns the MediaStreamTrack for the active video track
|
|
|
447
502
|
|
|
448
503
|
Turns off Torch. (Camera Flash) Resolves when complete, throws on error. Does not work on iOS devices of at least version 16.4 and earlier. May or may not work on later versions.
|
|
449
504
|
|
|
450
|
-
## CameraAccess
|
|
505
|
+
## CameraAccess.enableTorch()
|
|
451
506
|
|
|
452
507
|
Turns on Torch. (Camera Flash) Resolves when complete, throws on error. Does not work on iOS devices of at least version 16.4 and earlier. May or may not work on later versions.
|
|
453
508
|
|
|
@@ -507,7 +562,10 @@ The `inputStream` property defines the sources of images/videos within QuaggaJS.
|
|
|
507
562
|
left: "0%", // left offset
|
|
508
563
|
bottom: "0%" // bottom offset
|
|
509
564
|
},
|
|
510
|
-
singleChannel: false // true: only the red color-channel is read
|
|
565
|
+
singleChannel: false, // true: only the red color-channel is read
|
|
566
|
+
debug: {
|
|
567
|
+
showImageDetails: false // logs frame grabber info and canvas size adjustments to console
|
|
568
|
+
}
|
|
511
569
|
}
|
|
512
570
|
```
|
|
513
571
|
|
|
@@ -540,6 +598,12 @@ optional and defines the maximum number of scans per second. This renders
|
|
|
540
598
|
useful for cases where the scan-session is long-running and resources such as
|
|
541
599
|
CPU power are of concern.
|
|
542
600
|
|
|
601
|
+
Note: `frequency` specifies a maximum, not an absolute rate. If the system
|
|
602
|
+
cannot achieve the requested frequency due to CPU limitations, decoding
|
|
603
|
+
complexity, or other factors, scans will occur as fast as the system allows.
|
|
604
|
+
For example, if you set `frequency: 10` but your system can only process 8
|
|
605
|
+
scans per second, you will get approximately 8 scans per second.
|
|
606
|
+
|
|
543
607
|
### decoder
|
|
544
608
|
|
|
545
609
|
QuaggaJS usually runs in a two-stage manner (`locate` is set to `true`) where,
|
|
@@ -556,7 +620,8 @@ options within the `decoder` are for debugging/visualization purposes only.
|
|
|
556
620
|
drawBoundingBox: false,
|
|
557
621
|
showFrequency: false,
|
|
558
622
|
drawScanline: false,
|
|
559
|
-
showPattern: false
|
|
623
|
+
showPattern: false,
|
|
624
|
+
printReaderInfo: false // logs reader registration and initialization to console
|
|
560
625
|
}
|
|
561
626
|
multiple: false
|
|
562
627
|
}
|
|
@@ -584,6 +649,26 @@ more possible clashes, or false-positives. One should take care of the order
|
|
|
584
649
|
the readers are given, since some might return a value even though it is not
|
|
585
650
|
the correct type (EAN-13 vs. UPC-A).
|
|
586
651
|
|
|
652
|
+
#### Reader Priority and Order
|
|
653
|
+
|
|
654
|
+
**Readers are processed in the exact order they appear in the `readers` array.**
|
|
655
|
+
The first reader to successfully decode the barcode wins. This allows you to
|
|
656
|
+
prioritize certain formats over others when multiple formats might match the
|
|
657
|
+
same barcode pattern.
|
|
658
|
+
|
|
659
|
+
For example, if you know most of your barcodes are EAN-13, place `ean_reader`
|
|
660
|
+
first to ensure it attempts to decode before other readers:
|
|
661
|
+
|
|
662
|
+
```javascript
|
|
663
|
+
decoder: {
|
|
664
|
+
readers: ['ean_reader', 'upc_reader', 'upc_e_reader'] // EAN-13 checked first
|
|
665
|
+
}
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
This is particularly important when dealing with barcode formats that share
|
|
669
|
+
similar patterns (like EAN-13 and UPC-A/UPC-E), where incorrect matches might
|
|
670
|
+
occur if the wrong reader attempts to decode first.
|
|
671
|
+
|
|
587
672
|
The `multiple` property tells the decoder if it should continue decoding after
|
|
588
673
|
finding a valid barcode. If multiple is set to `true`, the results will be
|
|
589
674
|
returned as an array of result objects. Each object in the array will have a
|
|
@@ -644,6 +729,8 @@ Only two properties are relevant for the use in Quagga (`halfSample` and
|
|
|
644
729
|
showLabels: false,
|
|
645
730
|
showPatchLabels: false,
|
|
646
731
|
showRemainingPatchLabels: false,
|
|
732
|
+
showPatchSize: false, // logs calculated patch size to console
|
|
733
|
+
showImageDetails: false, // logs image wrapper size and canvas details to console
|
|
647
734
|
boxFromPatches: {
|
|
648
735
|
showTransformed: false,
|
|
649
736
|
showTransformedBox: false,
|
|
@@ -683,6 +770,7 @@ Quagga.decodeSingle({
|
|
|
683
770
|
},
|
|
684
771
|
locate: true, // try to locate the barcode in the image
|
|
685
772
|
src: '/test/fixtures/code_128/image-001.jpg' // or 'data:image/jpg;base64,' + data
|
|
773
|
+
// Note: inputStream.size defaults to 800; images are scaled to 800px (up or down).
|
|
686
774
|
}, function(result){
|
|
687
775
|
if(result.codeResult) {
|
|
688
776
|
console.log("result", result.codeResult.code);
|
|
@@ -706,7 +794,7 @@ Quagga.decodeSingle({
|
|
|
706
794
|
src: "image-abc-123.jpg",
|
|
707
795
|
numOfWorkers: 0, // Needs to be 0 when used within node
|
|
708
796
|
inputStream: {
|
|
709
|
-
size: 800 //
|
|
797
|
+
size: 800 // This is the default; shown explicitly for clarity
|
|
710
798
|
},
|
|
711
799
|
decoder: {
|
|
712
800
|
readers: ["code_128_reader"] // List of active readers
|
|
@@ -744,7 +832,7 @@ false-positives.
|
|
|
744
832
|
|
|
745
833
|
Starting in Chrome 59 you can now make use of `capabilities` and directly
|
|
746
834
|
control the zoom of the camera. Head over to the
|
|
747
|
-
[web-cam demo](https://
|
|
835
|
+
[web-cam demo](https://ericblade.github.io/quagga2/examples/live_w_locator.html)
|
|
748
836
|
and check out the __Zoom__ feature.
|
|
749
837
|
|
|
750
838
|
You can read more about those `capabilities` in
|
|
@@ -757,7 +845,7 @@ recognition logic.
|
|
|
757
845
|
|
|
758
846
|
Since Chrome 59 you can turn on/off the __Torch__ of your device and vastly
|
|
759
847
|
improve the quality of the images. Head over to the
|
|
760
|
-
[web-cam demo](https://
|
|
848
|
+
[web-cam demo](https://ericblade.github.io/quagga2/examples/live_w_locator.html)
|
|
761
849
|
and check out the __Torch__ feature.
|
|
762
850
|
|
|
763
851
|
To find out more about this feature [read on](https://www.oberhofer.co/mediastreamtrack-and-its-capabilities).
|
|
@@ -879,8 +967,29 @@ on the ``singleChannel`` flag in the configuration when using ``decodeSingle``.
|
|
|
879
967
|
[upc_wiki]: http://en.wikipedia.org/wiki/Universal_Product_Code
|
|
880
968
|
[ean_8_wiki]: http://en.wikipedia.org/wiki/EAN-8
|
|
881
969
|
[oberhofer_co_how]: http://www.oberhofer.co/how-barcode-localization-works-in-quaggajs/
|
|
882
|
-
[github_examples]: https://
|
|
970
|
+
[github_examples]: https://ericblade.github.io/quagga2/examples
|
|
883
971
|
[i2of5_wiki]: https://en.wikipedia.org/wiki/Interleaved_2_of_5
|
|
884
972
|
[enumerateDevices]: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
|
|
885
973
|
[reactExample]: https://github.com/ericblade/quagga2-react-example
|
|
886
974
|
[issue-94-comment]: https://github.com/serratus/quaggajs/issues/94#issuecomment-571478711
|
|
975
|
+
#### Sequence Mode
|
|
976
|
+
|
|
977
|
+
Quagga2 supports loading a sequence of images for batch processing using the `inputStream.sequence` option. When enabled, Quagga will attempt to load images named in the pattern `image-001.jpg`, `image-002.jpg`, etc., from the specified directory.
|
|
978
|
+
|
|
979
|
+
**Example:**
|
|
980
|
+
```javascript
|
|
981
|
+
Quagga.init({
|
|
982
|
+
inputStream: {
|
|
983
|
+
type: 'ImageStream',
|
|
984
|
+
sequence: true,
|
|
985
|
+
size: 3, // Number of images to load
|
|
986
|
+
offset: 1, // Starting index (optional)
|
|
987
|
+
src: '/path/to/images/', // Base path for images
|
|
988
|
+
},
|
|
989
|
+
decoder: { readers: ['code_128_reader'] }
|
|
990
|
+
});
|
|
991
|
+
```
|
|
992
|
+
|
|
993
|
+
This will load `/path/to/images/image-001.jpg`, `/path/to/images/image-002.jpg`, `/path/to/images/image-003.jpg` for processing.
|
|
994
|
+
|
|
995
|
+
Sequence mode is useful for batch testing or processing multiple images with predictable filenames.
|