@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.
- package/DEPENDENCIES.md +44 -13
- package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
- package/README.md +115 -10
- package/dist/quagga.js +7611 -5195
- package/dist/quagga.min.js +4 -4
- 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 +119 -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 +758 -0
- package/docs/reference/browser-support.md +109 -0
- package/docs/reference/camera-access.md +376 -0
- package/docs/reference/configuration.md +1009 -0
- package/docs/reference/dependencies.md +295 -0
- package/docs/reference/index.md +74 -0
- package/docs/reference/readers.md +326 -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 +9362 -5793
- package/package.json +21 -12
- package/type-definitions/quagga.d.ts +91 -10
package/docs/_config.yml
ADDED
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
## Contributing {#contributing}
|
|
2
|
+
|
|
3
|
+
### Questions, Bugs, Enhancements / Suggestions {#questions-bugs-enhancements}
|
|
4
|
+
|
|
5
|
+
For questions, bug reports, and enhancement requests / suggestions, please use the GitHub issue
|
|
6
|
+
tracker at https://github.com/ericblade/quagga2/issues
|
|
7
|
+
|
|
8
|
+
### Chat / Real Time Communication? {#chat}
|
|
9
|
+
|
|
10
|
+
We have a Gitter chat channel available at https://gitter.im/quaggaJS/Lobby . Please join us there,
|
|
11
|
+
and be patient. Thanks!
|
|
12
|
+
|
|
13
|
+
### Code {#code}
|
|
14
|
+
|
|
15
|
+
#### Developing enhancements to Quagga2 {#developing-enhancements}
|
|
16
|
+
|
|
17
|
+
If you'd like to work directly on the Quagga2 code, it is quite easy to build a local development
|
|
18
|
+
copy and get started hacking on the base code. Simply clone this repository, then run:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
npm install
|
|
22
|
+
npm run build
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
#### Running tests {#running-tests}
|
|
26
|
+
|
|
27
|
+
There are several tests included in Quagga2, in the test/ folder. Please make sure before you
|
|
28
|
+
send in any pull requests, that you have run ```npm test``` against the existing tests, as well as
|
|
29
|
+
implemented any tests that may be needed to test your new code. If you're not sure how to properly
|
|
30
|
+
unit test your new code, then go ahead and make that pull request, and we'll try to help you before
|
|
31
|
+
merging.
|
|
32
|
+
|
|
33
|
+
**Test Structure**:
|
|
34
|
+
|
|
35
|
+
- Unit tests are in `src/` alongside source files (`.spec.ts` files)
|
|
36
|
+
- Integration tests are in `test/integration/` organized by decoder type
|
|
37
|
+
- See `test/integration/README.md` for detailed information about integration test structure and configuration
|
|
38
|
+
|
|
39
|
+
**Running Specific Tests**:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# All tests (Node unit/integration + full Cypress suite)
|
|
43
|
+
npm test
|
|
44
|
+
|
|
45
|
+
# Run Node and Cypress in parallel (faster local iteration)
|
|
46
|
+
npm run test:parallel
|
|
47
|
+
|
|
48
|
+
# Node tests only
|
|
49
|
+
npm run test:node
|
|
50
|
+
|
|
51
|
+
# Browser tests only (requires Cypress)
|
|
52
|
+
npm run test:browser-all
|
|
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
|
+
|
|
60
|
+
# Cypress: run only specific spec(s)
|
|
61
|
+
# Pass --spec through npm using --
|
|
62
|
+
npm run cypress:run -- --spec cypress/e2e/browser.cy.ts
|
|
63
|
+
|
|
64
|
+
# Multiple specs (comma-separated)
|
|
65
|
+
npm run cypress:run -- --spec cypress/e2e/browser.cy.ts,cypress/e2e/integration.cy.ts
|
|
66
|
+
|
|
67
|
+
# Glob pattern
|
|
68
|
+
npm run cypress:run -- --spec "cypress/e2e/**/browser*.cy.ts"
|
|
69
|
+
|
|
70
|
+
# Open interactive runner
|
|
71
|
+
npm run cypress:open
|
|
72
|
+
|
|
73
|
+
# Open only the examples E2E spec (Electron)
|
|
74
|
+
npm run cypress:open:e2e
|
|
75
|
+
|
|
76
|
+
# Choose a browser (if installed)
|
|
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
|
|
78
|
+
|
|
79
|
+
# Integration tests only (Node)
|
|
80
|
+
npx ts-mocha -p test/tsconfig.json test/integration/**/*.spec.ts
|
|
81
|
+
|
|
82
|
+
# Specific decoder integration tests
|
|
83
|
+
npx ts-mocha -p test/tsconfig.json test/integration/decoders/ean_8.spec.ts
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Adding Integration Tests**:
|
|
87
|
+
|
|
88
|
+
When adding new test cases to decoder integration tests, tests should pass in both Node and browser
|
|
89
|
+
environments by default. If a test is known to fail in a specific environment, mark it explicitly with:
|
|
90
|
+
|
|
91
|
+
- `allowFailInNode: true` - Test can fail in Node without failing CI
|
|
92
|
+
- `allowFailInBrowser: true` - Test can fail in browser without failing CI
|
|
93
|
+
- Both flags - Test can fail in both environments
|
|
94
|
+
|
|
95
|
+
See `test/integration/README.md` for complete details on the test failure marking system.
|
|
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
|
+
|
|
102
|
+
#### Working on a changed copy of Quagga2 from another repository (ie, developing an external plugin) {#working-on-external-plugin}
|
|
103
|
+
|
|
104
|
+
If you need to make changes to Quagga2 to support some external code (such as an external reader plugin),
|
|
105
|
+
you will probably need to be able to test the code in your other repo. One such way to do that is
|
|
106
|
+
to ```npm install @ericblade/quagga2``` inside the external repo, which will initialize the module
|
|
107
|
+
structure, and fill it with the current release of quagga2. Once that is completed, then copy the
|
|
108
|
+
lib/quagga.js (node) and/or dist/quagga.js and/or dist/quagga.min.js files into
|
|
109
|
+
ExternalRepo/node_modules/@ericblade/quagga2, preserving the "lib" or "dist" folder. Then your code
|
|
110
|
+
will have the new changes that you have implemented in your copy of the quagga2 repo.
|
|
111
|
+
|
|
112
|
+
#### Pull requests {#pull-requests}
|
|
113
|
+
|
|
114
|
+
Please, submit pull requests! Open source works best when we all work together. If you find a change
|
|
115
|
+
to be useful, the odds are that other users will, as well!
|
|
116
|
+
|
|
117
|
+
## BE AWESOME {#be-awesome}
|
|
118
|
+
|
|
119
|
+
Don't forget to BE AWESOME.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Algorithm Overview {#algorithm-overview}
|
|
2
|
+
|
|
3
|
+
This page provides a high-level overview of how Quagga2 processes images to detect and decode barcodes.
|
|
4
|
+
|
|
5
|
+
## Processing Pipeline {#processing-pipeline}
|
|
6
|
+
|
|
7
|
+
Quagga2 processes each frame through a multi-stage pipeline:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Input Image → Preprocessing → Localization → Decoding → Result
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
### 1. Preprocessing {#preprocessing}
|
|
14
|
+
|
|
15
|
+
- **Scaling**: Image is resized based on `inputStream.size`
|
|
16
|
+
- **Grayscale conversion**: Color image converted to grayscale
|
|
17
|
+
- **Area cropping**: If `inputStream.area` is set, crop to that region
|
|
18
|
+
|
|
19
|
+
### 2. Localization {#localization}
|
|
20
|
+
|
|
21
|
+
When `locate: true` (default):
|
|
22
|
+
|
|
23
|
+
1. **Binarization**: Convert to black/white using Otsu's method
|
|
24
|
+
2. **Grid division**: Split image into patches
|
|
25
|
+
3. **Skeletonization**: Extract line structures
|
|
26
|
+
4. **Pattern analysis**: Find barcode-like patterns
|
|
27
|
+
5. **Bounding box**: Calculate barcode region
|
|
28
|
+
|
|
29
|
+
See [How Barcode Localization Works](how-barcode-localization-works.md) for detailed explanation.
|
|
30
|
+
|
|
31
|
+
### 3. Decoding {#decoding}
|
|
32
|
+
|
|
33
|
+
1. **Scanline extraction**: Sample pixels along detected barcode
|
|
34
|
+
2. **Pattern matching**: Match bar/space patterns to barcode format
|
|
35
|
+
3. **Character decoding**: Convert patterns to characters
|
|
36
|
+
4. **Checksum validation**: Verify barcode integrity
|
|
37
|
+
|
|
38
|
+
## Key Algorithms {#key-algorithms}
|
|
39
|
+
|
|
40
|
+
### Otsu's Method {#otsus-method}
|
|
41
|
+
|
|
42
|
+
Automatic threshold selection for binarization. Adapts to varying lighting conditions by analyzing the image histogram.
|
|
43
|
+
|
|
44
|
+
### Connected Component Labeling {#connected-component-labeling}
|
|
45
|
+
|
|
46
|
+
Groups adjacent pixels into distinct regions. Used during localization to identify potential barcode patterns.
|
|
47
|
+
|
|
48
|
+
### Image Moments {#image-moments}
|
|
49
|
+
|
|
50
|
+
Mathematical technique to calculate orientation and position of detected patterns.
|
|
51
|
+
|
|
52
|
+
## Performance Characteristics {#performance-characteristics}
|
|
53
|
+
|
|
54
|
+
| Factor | Impact | Mitigation |
|
|
55
|
+
|--------|--------|------------|
|
|
56
|
+
| Image size | Linear increase | Use `inputStream.size` |
|
|
57
|
+
| Number of readers | Linear increase | Only enable needed readers |
|
|
58
|
+
| Localization | ~60% of processing time | Use `locate: false` if position known |
|
|
59
|
+
| Half sampling | 4x faster | Keep `halfSample: true` |
|
|
60
|
+
|
|
61
|
+
## Related {#related}
|
|
62
|
+
|
|
63
|
+
- [How Barcode Localization Works](how-barcode-localization-works.md) - Detailed localization explanation
|
|
64
|
+
- [Architecture](architecture.md) - Code structure overview
|
|
65
|
+
- [Optimize Performance](../how-to-guides/optimize-performance.md) - Performance tuning
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
[← Back to Explanation](index.md)
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Architecture {#architecture}
|
|
2
|
+
|
|
3
|
+
This page describes Quagga2's code structure and design decisions.
|
|
4
|
+
|
|
5
|
+
## Project Structure {#project-structure}
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
quagga2/
|
|
9
|
+
├── src/
|
|
10
|
+
│ ├── quagga.ts # Main entry point
|
|
11
|
+
│ ├── config/ # Configuration handling
|
|
12
|
+
│ ├── decoder/ # Barcode decoding
|
|
13
|
+
│ │ ├── barcode_decoder.ts
|
|
14
|
+
│ │ └── readers/ # Individual barcode readers
|
|
15
|
+
│ ├── locator/ # Barcode localization
|
|
16
|
+
│ │ ├── barcode_locator.ts
|
|
17
|
+
│ │ └── skeletonizer.ts
|
|
18
|
+
│ ├── input/ # Input handling
|
|
19
|
+
│ │ ├── camera_access.ts
|
|
20
|
+
│ │ └── frame_grabber.ts
|
|
21
|
+
│ └── common/ # Shared utilities
|
|
22
|
+
│ ├── cv_utils.ts # Computer vision utilities
|
|
23
|
+
│ └── image_wrapper.ts
|
|
24
|
+
├── dist/ # Browser builds
|
|
25
|
+
├── lib/ # Node.js build
|
|
26
|
+
└── type-definitions/ # TypeScript types
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Core Components {#core-components}
|
|
30
|
+
|
|
31
|
+
### Quagga (Main API) {#main-api}
|
|
32
|
+
|
|
33
|
+
The main entry point (`src/quagga.ts`) exposes the public API:
|
|
34
|
+
|
|
35
|
+
- `init()` / `start()` / `stop()`
|
|
36
|
+
- `decodeSingle()`
|
|
37
|
+
- `onDetected()` / `onProcessed()`
|
|
38
|
+
- `CameraAccess` namespace
|
|
39
|
+
|
|
40
|
+
### Barcode Locator {#barcode-locator}
|
|
41
|
+
|
|
42
|
+
Located in `src/locator/`, responsible for finding barcode regions in images:
|
|
43
|
+
|
|
44
|
+
- **barcode_locator.ts**: Main localization logic
|
|
45
|
+
- **skeletonizer.ts**: Line structure extraction (asm.js optimized)
|
|
46
|
+
|
|
47
|
+
### Barcode Decoder {#barcode-decoder}
|
|
48
|
+
|
|
49
|
+
Located in `src/decoder/`, handles barcode decoding:
|
|
50
|
+
|
|
51
|
+
- **barcode_decoder.ts**: Coordinates decoding process
|
|
52
|
+
- **readers/**: Individual reader implementations
|
|
53
|
+
- Each reader extends `BarcodeReader` base class
|
|
54
|
+
- Implements format-specific pattern matching
|
|
55
|
+
|
|
56
|
+
### Input Handling {#input-handling}
|
|
57
|
+
|
|
58
|
+
Located in `src/input/`:
|
|
59
|
+
|
|
60
|
+
- **camera_access.ts**: Camera enumeration and control
|
|
61
|
+
- **frame_grabber_browser.ts**: Browser frame capture
|
|
62
|
+
- **frame_grabber_node.ts**: Node.js image loading
|
|
63
|
+
|
|
64
|
+
## Data Flow {#data-flow}
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
Camera/Image
|
|
68
|
+
↓
|
|
69
|
+
FrameGrabber (captures frame)
|
|
70
|
+
↓
|
|
71
|
+
ImageWrapper (grayscale conversion)
|
|
72
|
+
↓
|
|
73
|
+
BarcodeLocator (finds barcode region)
|
|
74
|
+
↓
|
|
75
|
+
BarcodeDecoder (decodes barcode)
|
|
76
|
+
↓
|
|
77
|
+
Result callbacks
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Design Decisions {#design-decisions}
|
|
81
|
+
|
|
82
|
+
### Bundle Everything {#bundle-everything}
|
|
83
|
+
|
|
84
|
+
All dependencies are bundled into the final build. This means:
|
|
85
|
+
|
|
86
|
+
- Consumers never install dependencies directly
|
|
87
|
+
- All packages go in `devDependencies`
|
|
88
|
+
- Builds are self-contained
|
|
89
|
+
|
|
90
|
+
### Dual Build Targets {#dual-build-targets}
|
|
91
|
+
|
|
92
|
+
- **Browser**: `dist/quagga.min.js` - UMD bundle
|
|
93
|
+
- **Node.js**: `lib/quagga.js` - CommonJS module
|
|
94
|
+
|
|
95
|
+
### Reader Architecture {#reader-architecture}
|
|
96
|
+
|
|
97
|
+
Readers are pluggable:
|
|
98
|
+
|
|
99
|
+
- Built-in readers in `src/decoder/readers/`
|
|
100
|
+
- External readers via `Quagga.registerReader()`
|
|
101
|
+
- All readers extend common `BarcodeReader` class
|
|
102
|
+
|
|
103
|
+
## Build System {#build-system}
|
|
104
|
+
|
|
105
|
+
- **Webpack 4**: Module bundling
|
|
106
|
+
- **Babel**: ES6+ transpilation
|
|
107
|
+
- **TypeScript**: Type checking (but source is mixed JS/TS)
|
|
108
|
+
|
|
109
|
+
## Related {#related}
|
|
110
|
+
|
|
111
|
+
- [Algorithm Overview](algorithm-overview.md) - How the algorithms work
|
|
112
|
+
- [Create External Readers](../how-to-guides/external-readers.md) - Extend Quagga2
|
|
113
|
+
- [Contributing](../contributing.md) - Development setup
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
[← Back to Explanation](index.md)
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# How Barcode Localization Works {#how-barcode-localization-works}
|
|
2
|
+
|
|
3
|
+
> **Note on Terminology**: "Localization" in this context refers to finding the **physical location** (position, bounding box) of a barcode within an image - not language localization (i18n). This is standard computer vision terminology.
|
|
4
|
+
|
|
5
|
+
This article explains the technical details of how Quagga2 locates and decodes barcodes in images. Understanding this can help you optimize performance and troubleshoot issues.
|
|
6
|
+
|
|
7
|
+
## Overview {#overview}
|
|
8
|
+
|
|
9
|
+
Quagga2 uses a two-stage process:
|
|
10
|
+
|
|
11
|
+
1. **Barcode Locator** (blue box in the images below) - Finds regions that look like barcodes
|
|
12
|
+
2. **Barcode Decoder** (red line in the images below) - Reads the actual barcode data
|
|
13
|
+
|
|
14
|
+
This approach is based on the paper [Locating and decoding EAN-13 barcodes from images captured by digital cameras](http://www.icics.org/2005/download/P0840.pdf) by Douglas et al., with adaptations and modifications for web browsers.
|
|
15
|
+
|
|
16
|
+
## Stage 1: Barcode Locator {#stage-1-barcode-locator}
|
|
17
|
+
|
|
18
|
+
The locator finds patterns that look like barcodes. A barcode is typically characterized by:
|
|
19
|
+
|
|
20
|
+
- **Lines** (black bars and white gaps)
|
|
21
|
+
- That are **close to each other**
|
|
22
|
+
- With a **similar angle** (parallel lines)
|
|
23
|
+
|
|
24
|
+
### Step 1: Creating a Binary Image {#step-1-binary-image}
|
|
25
|
+
|
|
26
|
+
The first step is converting the color image to binary (black and white). Instead of using a simple threshold (e.g., everything below 127 is black), Quagga2 uses **Otsu's method**, which adapts to lighting changes across the image.
|
|
27
|
+
|
|
28
|
+

|
|
29
|
+
|
|
30
|
+
Otsu's method analyzes the image histogram and automatically separates foreground (barcode) from background, even with uneven lighting.
|
|
31
|
+
|
|
32
|
+
### Step 2: Slicing into a Grid {#step-2-slicing-grid}
|
|
33
|
+
|
|
34
|
+
The binary image is divided into a **20×15 grid** (assuming 4:3 aspect ratio). Each cell is analyzed independently to determine if it contains barcode-like patterns.
|
|
35
|
+
|
|
36
|
+
### Step 3: Extract Skeleton {#step-3-extract-skeleton}
|
|
37
|
+
|
|
38
|
+
Each cell undergoes **skeletonization** - reducing bars to their centerline (1px width). This is done through iterative erosion and dilation.
|
|
39
|
+
|
|
40
|
+

|
|
41
|
+
|
|
42
|
+
The skeleton clearly shows where parallel lines exist, making it easier to identify barcode regions.
|
|
43
|
+
|
|
44
|
+
### Step 4: Component Labeling {#step-4-component-labeling}
|
|
45
|
+
|
|
46
|
+
Using **connected-component labeling**, each line in the skeletonized image is separated into individual components. This is done with a fast algorithm based on the paper ["A Linear-Time Component-Labeling Algorithm Using Contour Tracing Technique"](http://www.iis.sinica.edu.tw/papers/fchang/1362-F.pdf) by Fu Chang et al.
|
|
47
|
+
|
|
48
|
+

|
|
49
|
+
|
|
50
|
+
Each color represents a distinct labeled component (line). Notice how each cell is processed independently.
|
|
51
|
+
|
|
52
|
+
Here are zoomed examples of two cells:
|
|
53
|
+
|
|
54
|
+

|
|
55
|
+
*Good: Parallel lines indicate a possible barcode*
|
|
56
|
+
|
|
57
|
+

|
|
58
|
+
*Bad: Random components indicate noise/text*
|
|
59
|
+
|
|
60
|
+
### Step 5: Determining Orientation {#step-5-determining-orientation}
|
|
61
|
+
|
|
62
|
+
For each component, Quagga2 calculates its orientation using **central image moments**. This is a mathematical technique to extract the angle of a shape.
|
|
63
|
+
|
|
64
|
+
The orientation (θ) is calculated as:
|
|
65
|
+
|
|
66
|
+

|
|
67
|
+
|
|
68
|
+
Where μ (mu) are central moments calculated from raw moments (M):
|
|
69
|
+
|
|
70
|
+

|
|
71
|
+
|
|
72
|
+
The centroid (x̄, ȳ) is calculated from raw moments:
|
|
73
|
+
|
|
74
|
+

|
|
75
|
+
|
|
76
|
+
And the raw moments (M) are computed as:
|
|
77
|
+
|
|
78
|
+

|
|
79
|
+
|
|
80
|
+
Where I(x,y) is the pixel value at position (x,y) - either 0 or 1 in a binary image.
|
|
81
|
+
|
|
82
|
+
Don't worry if the math looks intimidating - the key insight is that these formulas calculate **which direction each line is pointing**.
|
|
83
|
+
|
|
84
|
+
### Step 6: Determining Cell Quality {#step-6-determining-cell-quality}
|
|
85
|
+
|
|
86
|
+
Cells are evaluated based on how parallel their lines are:
|
|
87
|
+
|
|
88
|
+
1. **Filter out noise**: Discard cells with fewer than 2 components, or components smaller than 6 pixels
|
|
89
|
+
2. **Cluster angles**: Group similar angles together
|
|
90
|
+
3. **Select dominant cluster**: Pick the cluster with the most members
|
|
91
|
+
4. **Quality threshold**: Only accept cells where ≥75% of components share the same angle
|
|
92
|
+
|
|
93
|
+
Cells that pass this test are called **patches** and contain:
|
|
94
|
+
|
|
95
|
+
- Unique index
|
|
96
|
+
- Bounding box
|
|
97
|
+
- All components with their angles
|
|
98
|
+
- Average angle
|
|
99
|
+
- Direction vector
|
|
100
|
+
|
|
101
|
+

|
|
102
|
+
|
|
103
|
+
Yellow boxes show patches that were classified as possible barcode areas. Note some false positives (text regions).
|
|
104
|
+
|
|
105
|
+
### Step 7: Finding Connected Cells {#step-7-finding-connected-cells}
|
|
106
|
+
|
|
107
|
+
Patches are grouped together if they're neighbors with similar orientation (within 5% angle difference). This is done using recursive component labeling.
|
|
108
|
+
|
|
109
|
+

|
|
110
|
+
|
|
111
|
+
Each color represents a distinct group. Sometimes adjacent patches have different colors due to angle differences exceeding the 5% threshold.
|
|
112
|
+
|
|
113
|
+
### Step 8: Selecting Groups {#step-8-selecting-groups}
|
|
114
|
+
|
|
115
|
+
Groups are sorted by size (number of patches) and only the largest groups are kept - these are most likely to be actual barcodes.
|
|
116
|
+
|
|
117
|
+

|
|
118
|
+
|
|
119
|
+
Small groups and false positives have been filtered out.
|
|
120
|
+
|
|
121
|
+
### Step 9: Create Bounding Box {#step-9-create-bounding-box}
|
|
122
|
+
|
|
123
|
+
For each group, a **minimum bounding box** is calculated:
|
|
124
|
+
|
|
125
|
+
1. Calculate average angle of all patches in the group
|
|
126
|
+
2. Rotate all patches by this angle
|
|
127
|
+
3. Find outermost corners (min/max x and y)
|
|
128
|
+
4. Create bounding box
|
|
129
|
+
5. Rotate box back to original orientation
|
|
130
|
+
|
|
131
|
+

|
|
132
|
+
*Patches rotated to horizontal, bounding box calculated*
|
|
133
|
+
|
|
134
|
+

|
|
135
|
+
*Final bounding box rotated back to match barcode orientation*
|
|
136
|
+
|
|
137
|
+
The bounding box now precisely outlines the barcode, including its rotation and scale. This information is passed to the decoder.
|
|
138
|
+
|
|
139
|
+
## Stage 2: Barcode Decoder {#stage-2-barcode-decoder}
|
|
140
|
+
|
|
141
|
+
With the bounding box and orientation known, the decoder:
|
|
142
|
+
|
|
143
|
+
1. Samples pixel intensities along scan lines within the box
|
|
144
|
+
2. Detects transitions from black to white (edges of bars)
|
|
145
|
+
3. Calculates bar widths
|
|
146
|
+
4. Matches patterns against the selected barcode format(s)
|
|
147
|
+
5. Validates checksums
|
|
148
|
+
6. Returns the decoded data
|
|
149
|
+
|
|
150
|
+
## Why This Approach? {#why-this-approach}
|
|
151
|
+
|
|
152
|
+
Unlike simpler barcode scanners that require the barcode to be:
|
|
153
|
+
|
|
154
|
+
- Horizontal (aligned with the viewport)
|
|
155
|
+
- At a specific distance (scale)
|
|
156
|
+
- Centered in the frame
|
|
157
|
+
|
|
158
|
+
Quagga2's localization algorithm is **invariant to rotation and scale**. It can find and decode barcodes:
|
|
159
|
+
|
|
160
|
+
- At any angle
|
|
161
|
+
- At any size (within reason)
|
|
162
|
+
- Anywhere in the image
|
|
163
|
+
- Even with multiple barcodes present
|
|
164
|
+
|
|
165
|
+
This makes it much more practical for real-world camera scanning where users can't always position the camera perfectly.
|
|
166
|
+
|
|
167
|
+
## Performance Considerations {#performance-considerations}
|
|
168
|
+
|
|
169
|
+
The localization algorithm is computationally intensive. Key factors affecting performance:
|
|
170
|
+
|
|
171
|
+
- **Image size**: Smaller images process faster. Consider downscaling if speed is critical.
|
|
172
|
+
- **Grid size**: The default 20×15 grid balances accuracy and speed
|
|
173
|
+
- **Patch filtering**: Aggressive filtering reduces false positives but may miss difficult barcodes
|
|
174
|
+
- **Number of readers**: Enabling multiple barcode formats increases decode time
|
|
175
|
+
|
|
176
|
+
See [Optimize Performance](../how-to-guides/optimize-performance.md) for practical tips.
|
|
177
|
+
|
|
178
|
+
## Related Reading {#related-reading}
|
|
179
|
+
|
|
180
|
+
- **Original Paper**: [Locating and decoding EAN-13 barcodes from images captured by digital cameras](http://www.icics.org/2005/download/P0840.pdf)
|
|
181
|
+
- **Otsu's Method**: [Wikipedia - Otsu's method](http://en.wikipedia.org/wiki/Otsu%27s_method)
|
|
182
|
+
- **Skeletonization**: [Wikipedia - Morphological skeleton](http://en.wikipedia.org/wiki/Morphological_skeleton)
|
|
183
|
+
- **Component Labeling**: [Wikipedia - Connected-component labeling](http://en.wikipedia.org/wiki/Connected-component_labeling)
|
|
184
|
+
- **Image Moments**: [Wikipedia - Image moment](http://en.wikipedia.org/wiki/Image_moment#Central_moments)
|
|
185
|
+
- **Fast Labeling Algorithm**: [A Linear-Time Component-Labeling Algorithm (PDF)](http://www.iis.sinica.edu.tw/papers/fchang/1362-F.pdf)
|
|
186
|
+
- **CodeProject Implementation**: [Connected Component Labeling and Vectorization](http://www.codeproject.com/Tips/407172/Connected-Component-Labeling-and-Vectorization)
|
|
187
|
+
|
|
188
|
+
## Source Code {#source-code}
|
|
189
|
+
|
|
190
|
+
The localization algorithm is implemented in:
|
|
191
|
+
|
|
192
|
+
- `src/locator/barcode_locator.js` - Main locator logic
|
|
193
|
+
- `src/locator/skeletonizer.js` - Skeletonization algorithm (asm.js)
|
|
194
|
+
- `src/common/cluster.js` - Clustering algorithms
|
|
195
|
+
- `src/common/cv_utils.js` - Computer vision utilities
|
|
196
|
+
|
|
197
|
+
Contributions and improvements are welcome!
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Explanation
|
|
2
|
+
|
|
3
|
+
Background knowledge and context about Quagga2. These articles explain *why* things work the way they do, providing deeper understanding beyond just how to use the library.
|
|
4
|
+
|
|
5
|
+
## Algorithm & Theory
|
|
6
|
+
|
|
7
|
+
### [How Barcode Localization Works](how-barcode-localization-works.md) ⭐ Featured
|
|
8
|
+
|
|
9
|
+
Deep dive into the computer vision algorithms that find barcodes in images. Covers:
|
|
10
|
+
|
|
11
|
+
- Binary image creation with Otsu's method
|
|
12
|
+
- Skeletonization
|
|
13
|
+
- Component labeling
|
|
14
|
+
- Orientation detection using image moments
|
|
15
|
+
- Why this approach is rotation/scale invariant
|
|
16
|
+
|
|
17
|
+
**Read this if**: You want to understand the "magic" behind barcode detection, optimize performance, or contribute to the localization code.
|
|
18
|
+
|
|
19
|
+
## Architecture
|
|
20
|
+
|
|
21
|
+
### [How Input Streams Work](input-streams.md)
|
|
22
|
+
|
|
23
|
+
Technical deep dive into the three input stream types and their initialization flow. Covers:
|
|
24
|
+
|
|
25
|
+
- LiveStream, VideoStream, and ImageStream differences
|
|
26
|
+
- The async initialization sequence
|
|
27
|
+
- Why `framegrabber` indicates init completion
|
|
28
|
+
- Race conditions and how to avoid them
|
|
29
|
+
|
|
30
|
+
**Read this if**: You're debugging initialization issues, dealing with React StrictMode, or want to understand the media pipeline.
|
|
31
|
+
|
|
32
|
+
### [Algorithm Overview](algorithm-overview.md) *(Coming Soon)*
|
|
33
|
+
|
|
34
|
+
High-level overview of Quagga2's processing pipeline from input to output.
|
|
35
|
+
|
|
36
|
+
### [Code Architecture](architecture.md)
|
|
37
|
+
|
|
38
|
+
Structure of the codebase, module organization, and design decisions.
|
|
39
|
+
|
|
40
|
+
## Concepts
|
|
41
|
+
|
|
42
|
+
### [Why asm.js for Skeletonization](why-asmjs.md) *(Coming Soon)*
|
|
43
|
+
|
|
44
|
+
Explanation of why performance-critical code uses asm.js and what that means.
|
|
45
|
+
|
|
46
|
+
### [Reader Design Patterns](reader-patterns.md) *(Coming Soon)*
|
|
47
|
+
|
|
48
|
+
How barcode readers are implemented and how to create custom ones.
|
|
49
|
+
|
|
50
|
+
## Differences from Other Doc Types
|
|
51
|
+
|
|
52
|
+
**Explanation** articles:
|
|
53
|
+
|
|
54
|
+
- Provide context and background
|
|
55
|
+
- Discuss alternatives and trade-offs
|
|
56
|
+
- Explain historical decisions
|
|
57
|
+
- Connect concepts together
|
|
58
|
+
- Are OK to read casually
|
|
59
|
+
|
|
60
|
+
**Tutorials**: Step-by-step learning by doing
|
|
61
|
+
**How-To Guides**: Task-focused, get things done
|
|
62
|
+
**Reference**: Precise technical specifications
|
|
63
|
+
|
|
64
|
+
## When to Read Explanations
|
|
65
|
+
|
|
66
|
+
Read these articles when you:
|
|
67
|
+
|
|
68
|
+
- Want to **understand** how things work under the hood
|
|
69
|
+
- Need to **debug** complex issues
|
|
70
|
+
- Want to **contribute** to the codebase
|
|
71
|
+
- Are **curious** about design decisions
|
|
72
|
+
- Want to **optimize** beyond basic tuning
|
|
73
|
+
|
|
74
|
+
## Contributing
|
|
75
|
+
|
|
76
|
+
Have insights to share about how Quagga2 works? We welcome explanation articles! See the [Contributing Guide](../contributing.md).
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
[← Back to Documentation Home](../index.md)
|