@ericblade/quagga2 1.10.2 → 1.12.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 +44 -13
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +115 -10
  4. package/dist/quagga.js +7611 -5195
  5. package/dist/quagga.min.js +4 -4
  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 +119 -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 +758 -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 +1009 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +326 -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 +9362 -5793
  50. package/package.json +21 -12
  51. package/type-definitions/quagga.d.ts +91 -10
package/package.json CHANGED
@@ -1,13 +1,10 @@
1
1
  {
2
2
  "name": "@ericblade/quagga2",
3
- "version": "1.10.2",
3
+ "version": "1.12.0",
4
4
  "description": "An advanced barcode-scanner written in JavaScript",
5
5
  "main": "lib/quagga.js",
6
6
  "types": "type-definitions/quagga.d.ts",
7
7
  "browser": "dist/quagga.min.js",
8
- "overrides": {
9
- "@cypress/request": "^3.0.9"
10
- },
11
8
  "optionalDependencies": {
12
9
  "fsevents": "2.3.3"
13
10
  },
@@ -39,7 +36,7 @@
39
36
  "chai": "^4.3.10",
40
37
  "core-js": "^3.46.0",
41
38
  "cross-env": "^10.1.0",
42
- "cypress": "^13.1.0",
39
+ "cypress": "^13.17.0",
43
40
  "eslint": "^8.57.1",
44
41
  "eslint-config-airbnb-base": "^15.0.0",
45
42
  "eslint-config-airbnb-typescript": "^18.0.0",
@@ -47,7 +44,6 @@
47
44
  "eslint-plugin-import": "^2.32.0",
48
45
  "eslint-plugin-jsx-a11y": "^6.10.2",
49
46
  "eslint-plugin-typescript-sort-keys": "^3.3.0",
50
- "gl-matrix": "^3.4.4",
51
47
  "lodash": "^4.17.21",
52
48
  "mocha": "^5.2.0",
53
49
  "ndarray": "^1.0.19",
@@ -63,29 +59,40 @@
63
59
  "webpack": "^4.44.2",
64
60
  "webpack-cli": "^3.3.12"
65
61
  },
62
+ "overrides": {
63
+ "minimist": "1.2.8"
64
+ },
66
65
  "directories": {
67
- "doc": "doc"
66
+ "doc": "docs",
67
+ "example": "docs/examples"
68
68
  },
69
69
  "scripts": {
70
70
  "check-types": "tsc",
71
71
  "precoverage": "npx rimraf .nyc_output coverage",
72
72
  "coverage:node": "// DOES NOT WORK YET // npx cross-env NODE_ENV=test BUILD_ENV=development nyc --no-clean ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.*",
73
73
  "coverage": "npm run cypress:run",
74
- "cypress:open": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress open --env BUILD_ENV=development",
74
+ "server:examples": "npx http-server docs/examples -p 8080",
75
+ "cypress:open": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress open --env BUILD_ENV=development --browser electron",
76
+ "cypress:open:e2e": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress open --e2e --env BUILD_ENV=development --config specPattern=\"cypress/e2e/examples.cy.ts\" --browser electron",
75
77
  "cypress:run": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress run --env BUILD_ENV=development",
78
+ "cypress:run:e2e": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider cypress run --env BUILD_ENV=development --spec \"cypress/e2e/examples.cy.ts\"",
79
+ "test:e2e": "npx start-server-and-test server:examples http://localhost:8080 cypress:run:e2e",
80
+ "test:e2e:open": "npx start-server-and-test server:examples http://localhost:8080 cypress:open:e2e",
76
81
  "test:browser-specific": "NOT WORKING -- something like npx cypress run --config testFiles=[browser]",
77
82
  "test:browser-universal": "NOT WORKING -- something like npx cypress run --config testFiles=[universal]",
78
83
  "test:browser-all": "npm run cypress:run",
79
84
  "test:import": "mocha test/test-import.mjs",
80
- "test:node": "npx cross-env NODE_ENV=test ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/integration.spec.ts",
85
+ "test:node": "npx cross-env NODE_ENV=test ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/**/*.spec.ts",
81
86
  "test:require": "mocha test/test-require",
82
87
  "test:module": "npm run test:require && npm run test:import",
83
- "test": "npm run cypress:run && npx cross-env NODE_ENV=test BUILD_ENV=development ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/integration.spec.ts",
88
+ "test": "npx start-server-and-test server:examples http://localhost:8080 cypress:run && npx cross-env NODE_ENV=test BUILD_ENV=development ts-mocha -p test/tsconfig.json src/**/test/node/*.spec.* src/**/test/*.spec.* test/integration/**/*.spec.ts",
89
+ "test:parallel": "npx concurrently --kill-others-on-fail --success=all -n e2e,node -c green,blue \"npx start-server-and-test server:examples http://localhost:8080 cypress:run\" \"npm run test:node\"",
84
90
  "build-and-test": "npm run build && npm run test",
85
91
  "build:dev": "npx cross-env NODE_ENV=development BUILD_ENV=development NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.config.js",
86
92
  "build:prod": "npx cross-env NODE_ENV=production BUILD_ENV=production NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.config.min.js",
87
93
  "build:node": "npx cross-env NODE_ENV=production BABEL_ENV=commonjs BUILD_ENV=node NODE_OPTIONS=--openssl-legacy-provider webpack --config configs/webpack.node.config.js",
88
- "build": "npx cross-env NODE_OPTIONS=--openssl-legacy-provider npm run build-old",
94
+ "build": "npx cross-env NODE_OPTIONS=--openssl-legacy-provider npm run build-old && npm run copy-dist-examples",
95
+ "copy-dist-examples": "npx cpx \"dist/*\" \"docs/examples/dist\"",
89
96
  "build-old": "npm run check-types && npm run build:dev && npm run build:prod && npm run build:node",
90
97
  "watch": "npx cross-env BUILD_ENV=development webpack --watch",
91
98
  "lint": "eslint src",
@@ -189,5 +196,7 @@
189
196
  "publishConfig": {
190
197
  "access": "public"
191
198
  },
192
- "dependencies": {}
199
+ "dependencies": {
200
+ "gl-matrix": "^3.4.4"
201
+ }
193
202
  }
@@ -112,6 +112,12 @@ export type QuaggaImageData = Array<number>;
112
112
 
113
113
  export type BarcodeReaderType = string;
114
114
 
115
+ /**
116
+ * Constructor type for a BarcodeReader class.
117
+ * Used when registering custom readers via registerReader().
118
+ */
119
+ export type BarcodeReaderConstructor = new (config?: BarcodeReaderConfig, supplements?: Array<Readers.BarcodeReader>) => Readers.BarcodeReader;
120
+
115
121
  export interface BarcodeReaderConfig {
116
122
  normalizeBarSpaceWidth?: boolean,
117
123
  supplements?: Array<BarcodeReaderType>,
@@ -189,6 +195,8 @@ export declare module Readers {
189
195
  StartNotFoundException: string;
190
196
  };
191
197
 
198
+ static adjacentLineValidationMatches: number;
199
+
192
200
  constructor(config: BarcodeReaderConfig, supplements?: Array<BarcodeReader>);
193
201
 
194
202
  abstract decode(row?: Array<number>, start?: BarcodePosition | number): Barcode | null;
@@ -489,9 +497,21 @@ export interface QuaggaJSStatic {
489
497
  * When the library is initialized, the start()
490
498
  * method starts the video-stream and begins locating and decoding the
491
499
  * images.
500
+ *
501
+ * Optionally, you can pass a config object to start(), which will
502
+ * call init() and then start() for convenience.
503
+ *
504
+ * If start() is called without init() having been completed first,
505
+ * and no config is provided, an error will be thrown.
492
506
  */
493
507
  start(): void;
494
508
 
509
+ /**
510
+ * Combines init() and start() into a single call. Pass a config object
511
+ * and optionally a callback. If no callback is provided, returns a Promise.
512
+ */
513
+ start(config: QuaggaJSConfigObject, callback?: (err: any) => void): Promise<void>;
514
+
495
515
  /**
496
516
  * If the decoder is currently running, after calling
497
517
  * stop() the decoder does not process any more images.
@@ -535,7 +555,7 @@ export interface QuaggaJSStatic {
535
555
  ResultCollector: QuaggaJSResultCollector;
536
556
  registerResultCollector(resultCollector: QuaggaJSResultCollector): void;
537
557
  setReaders(readers: (QuaggaJSReaderConfig | string)[]): void;
538
- registerReader(name: string, reader: object): void;
558
+ registerReader(name: string, reader: BarcodeReaderConstructor): void;
539
559
 
540
560
  /**
541
561
  * In contrast to the calls described
@@ -564,15 +584,23 @@ export interface QuaggaJSStatic {
564
584
  canvas: {
565
585
  ctx: {
566
586
  image: CanvasRenderingContext2D;
567
- overlay: CanvasRenderingContext2D;
587
+ overlay: CanvasRenderingContext2D | null;
568
588
  };
569
589
  dom: {
570
590
  image: HTMLCanvasElement;
571
- overlay: HTMLCanvasElement;
591
+ overlay: HTMLCanvasElement | null;
572
592
  };
573
593
  };
574
594
 
575
595
  CameraAccess: QuaggaJSCameraAccess;
596
+
597
+ /**
598
+ * Draws a scanner area overlay onto the overlay canvas using the current instance's configured area.
599
+ * Uses the actual adjusted scanning area (after patch alignment) to accurately show where barcodes will be detected.
600
+ * Useful when user code clears the overlay each frame and wants to re-render the area.
601
+ * Only draws when locate is false and inputStream.area is configured with styling.
602
+ */
603
+ drawScannerArea(): void;
576
604
  }
577
605
 
578
606
  /**
@@ -581,7 +609,23 @@ export interface QuaggaJSStatic {
581
609
  export interface QuaggaJSCameraAccess {
582
610
  disableTorch(): Promise<void>;
583
611
  enableTorch(): Promise<void>;
584
- enumerateVideoDevices(): Promise<MediaDeviceInfo[]> | never;
612
+ /**
613
+ * Enumerates video input devices, optionally filtering by constraints.
614
+ * @param videoConstraints Optional constraints to filter devices.
615
+ * When provided, only devices that satisfy the given constraints will be returned.
616
+ * This works by attempting to get a media stream for each device with the constraints
617
+ * and returning only the devices that succeed.
618
+ * @returns Promise resolving to an array of MediaDeviceInfo for video input devices.
619
+ */
620
+ enumerateVideoDevices(
621
+ videoConstraints?: MediaTrackConstraintsWithDeprecated
622
+ ): Promise<MediaDeviceInfo[]> | never;
623
+ /**
624
+ * Returns the active MediaStream, or null if no stream is active.
625
+ * Use this when you need access to the full stream, for example to pass to WebRTC
626
+ * or to clone the stream. For just the video track, use getActiveTrack() instead.
627
+ */
628
+ getActiveStream(): MediaStream | null;
585
629
  getActiveStreamLabel(): string;
586
630
  getActiveTrack(): MediaStreamTrack | null;
587
631
  release(): Promise<void>;
@@ -784,11 +828,6 @@ export interface QuaggaJSConfigObject {
784
828
  src?: string | Uint8Array;
785
829
 
786
830
  inputStream?: {
787
- /**
788
- * @default "Live"
789
- */
790
- name?: string;
791
-
792
831
  /**
793
832
  * @default "LiveStream"
794
833
  */
@@ -834,6 +873,28 @@ export interface QuaggaJSConfigObject {
834
873
  * 'line' that is in the middle half
835
874
  */
836
875
  bottom?: string;
876
+
877
+ /**
878
+ * Color of the area border. When defined, draws a rectangle on the overlay canvas
879
+ * showing the scan area boundaries. Requires createOverlay to be true.
880
+ * Can be any valid CSS color value.
881
+ * @default undefined (no border drawn)
882
+ */
883
+ borderColor?: string;
884
+
885
+ /**
886
+ * Line width of the area border in pixels.
887
+ * When defined with a value > 0, draws a rectangle on the overlay canvas.
888
+ * @default undefined (no border drawn)
889
+ */
890
+ borderWidth?: number;
891
+
892
+ /**
893
+ * Background color to fill the scan area.
894
+ * Can be any valid CSS color value (e.g., 'rgba(0, 255, 0, 0.1)' for a light green tint).
895
+ * @default undefined (no background fill)
896
+ */
897
+ backgroundColor?: string;
837
898
  };
838
899
 
839
900
  mime?: string;
@@ -841,6 +902,7 @@ export interface QuaggaJSConfigObject {
841
902
  singleChannel?: boolean;
842
903
  size?: number;
843
904
  sequence?: boolean;
905
+
844
906
  debug?: {
845
907
  /**
846
908
  * @default false
@@ -870,9 +932,26 @@ export interface QuaggaJSConfigObject {
870
932
  * It’s optional and defines the maximum number of scans per second.
871
933
  * This renders useful for cases where the scan-session is long-running and
872
934
  * resources such as CPU power are of concern.
935
+ *
936
+ * Note: This specifies a maximum, not an absolute rate. If the system cannot
937
+ * achieve the requested frequency due to CPU limitations or other factors,
938
+ * scans will occur as fast as the system allows.
873
939
  */
874
940
  frequency?: number;
875
941
 
942
+ /**
943
+ * Canvas configuration options for controlling overlay and debug canvases.
944
+ */
945
+ canvas?: {
946
+ /**
947
+ * Whether to create the overlay canvas (drawingBuffer) for drawing bounding boxes
948
+ * and scan lines. Set to false if you don't need visual feedback and want to
949
+ * improve performance.
950
+ * @default true
951
+ */
952
+ createOverlay?: boolean;
953
+ };
954
+
876
955
  decoder?: {
877
956
  /**
878
957
  * @default [ "code_128_reader" ]
@@ -927,6 +1006,7 @@ export interface QuaggaJSConfigObject {
927
1006
  * Available values: x-small, small, medium, large, x-large
928
1007
  */
929
1008
  patchSize?: string;
1009
+
930
1010
  willReadFrequently?: boolean;
931
1011
  debug?: {
932
1012
  /**
@@ -1045,4 +1125,5 @@ export type QuaggaJSCodeReader =
1045
1125
  | 'i2of5_reader'
1046
1126
  | '2of5_reader'
1047
1127
  | 'code_93_reader'
1048
- | 'code_32_reader';
1128
+ | 'code_32_reader'
1129
+ | 'pharmacode_reader';