@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.
Files changed (51) hide show
  1. package/DEPENDENCIES.md +286 -0
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +119 -10
  4. package/dist/quagga.js +11087 -10681
  5. package/dist/quagga.min.js +4 -3
  6. package/docs/_config.yml +3 -0
  7. package/docs/assets/bb-binary.png +0 -0
  8. package/docs/assets/bb-rotated.png +0 -0
  9. package/docs/assets/binary.png +0 -0
  10. package/docs/assets/component-labeling-line.png +0 -0
  11. package/docs/assets/component-labeling-text.png +0 -0
  12. package/docs/assets/component-labeling.png +0 -0
  13. package/docs/assets/connected-patch-labels.png +0 -0
  14. package/docs/assets/mobile-detected.png +0 -0
  15. package/docs/assets/mobile-located.png +0 -0
  16. package/docs/assets/patches_found.png +0 -0
  17. package/docs/assets/quaggaJS-code128.png +0 -0
  18. package/docs/assets/remaining-patch-labels.png +0 -0
  19. package/docs/assets/skeleton.png +0 -0
  20. package/docs/assets/teaser.png +0 -0
  21. package/docs/contributing.md +102 -0
  22. package/docs/explanation/algorithm-overview.md +69 -0
  23. package/docs/explanation/architecture.md +117 -0
  24. package/docs/explanation/how-barcode-localization-works.md +197 -0
  25. package/docs/explanation/index.md +80 -0
  26. package/docs/explanation/input-streams.md +270 -0
  27. package/docs/getting-started.md +213 -0
  28. package/docs/how-to-guides/configure-readers.md +79 -0
  29. package/docs/how-to-guides/external-readers.md +234 -0
  30. package/docs/how-to-guides/handle-difficult-barcodes.md +127 -0
  31. package/docs/how-to-guides/index.md +77 -0
  32. package/docs/how-to-guides/optimize-performance.md +114 -0
  33. package/docs/how-to-guides/tips-and-tricks.md +115 -0
  34. package/docs/how-to-guides/use-debug-flags.md +776 -0
  35. package/docs/how-to-guides/working-with-coordinates.md +254 -0
  36. package/docs/index.md +118 -0
  37. package/docs/reference/api.md +716 -0
  38. package/docs/reference/browser-support.md +109 -0
  39. package/docs/reference/camera-access.md +376 -0
  40. package/docs/reference/configuration.md +1008 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +261 -0
  44. package/docs/tutorials/first-scan.md +141 -0
  45. package/docs/tutorials/index.md +77 -0
  46. package/docs/tutorials/node-usage.md +182 -0
  47. package/docs/tutorials/react-integration.md +176 -0
  48. package/docs/tutorials/static-image.md +130 -0
  49. package/lib/quagga.js +3140 -2757
  50. package/package.json +22 -18
  51. 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://serratus.github.io/quaggaJS/examples) and check out
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 // restrict input-size to be 800px in width (long-side)
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://serratus.github.io/quaggaJS/examples/live_w_locator.html)
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://serratus.github.io/quaggaJS/examples/live_w_locator.html)
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://serratus.github.io/quaggaJS/examples
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.