@ericblade/quagga2 1.10.2 → 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 +4 -13
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +111 -8
  4. package/dist/quagga.js +702 -250
  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 +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 +645 -265
  50. package/package.json +14 -11
  51. package/type-definitions/quagga.d.ts +86 -9
@@ -0,0 +1,3 @@
1
+ title: Quagga2 Documentation
2
+ description: Barcode scanning for browser and node!
3
+ theme: jekyll-theme-cayman
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -0,0 +1,102 @@
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 (unit + integration, Node + browser)
43
+ npm test
44
+
45
+ # Node tests only
46
+ npm run test:node
47
+
48
+ # Browser tests only (requires Cypress)
49
+ npm run test:browser-all
50
+
51
+ # Cypress: run only specific spec(s)
52
+ # Pass --spec through npm using --
53
+ npm run cypress:run -- --spec cypress/e2e/browser.cy.ts
54
+
55
+ # Multiple specs (comma-separated)
56
+ npm run cypress:run -- --spec cypress/e2e/browser.cy.ts,cypress/e2e/integration.cy.ts
57
+
58
+ # Glob pattern
59
+ npm run cypress:run -- --spec "cypress/e2e/**/browser*.cy.ts"
60
+
61
+ # Open interactive runner
62
+ npm run cypress:open
63
+
64
+ # Choose a browser (if installed)
65
+ 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
+
67
+ # Integration tests only (Node)
68
+ npx ts-mocha -p test/tsconfig.json test/integration/**/*.spec.ts
69
+
70
+ # Specific decoder integration tests
71
+ npx ts-mocha -p test/tsconfig.json test/integration/decoders/ean_8.spec.ts
72
+ ```
73
+
74
+ **Adding Integration Tests**:
75
+
76
+ When adding new test cases to decoder integration tests, tests should pass in both Node and browser
77
+ environments by default. If a test is known to fail in a specific environment, mark it explicitly with:
78
+
79
+ - `allowFailInNode: true` - Test can fail in Node without failing CI
80
+ - `allowFailInBrowser: true` - Test can fail in browser without failing CI
81
+ - Both flags - Test can fail in both environments
82
+
83
+ See `test/integration/README.md` for complete details on the test failure marking system.
84
+
85
+ #### Working on a changed copy of Quagga2 from another repository (ie, developing an external plugin) {#working-on-external-plugin}
86
+
87
+ If you need to make changes to Quagga2 to support some external code (such as an external reader plugin),
88
+ you will probably need to be able to test the code in your other repo. One such way to do that is
89
+ to ```npm install @ericblade/quagga2``` inside the external repo, which will initialize the module
90
+ structure, and fill it with the current release of quagga2. Once that is completed, then copy the
91
+ lib/quagga.js (node) and/or dist/quagga.js and/or dist/quagga.min.js files into
92
+ ExternalRepo/node_modules/@ericblade/quagga2, preserving the "lib" or "dist" folder. Then your code
93
+ will have the new changes that you have implemented in your copy of the quagga2 repo.
94
+
95
+ #### Pull requests {#pull-requests}
96
+
97
+ Please, submit pull requests! Open source works best when we all work together. If you find a change
98
+ to be useful, the odds are that other users will, as well!
99
+
100
+ ## BE AWESOME {#be-awesome}
101
+
102
+ 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
+ ![Binary Image](../assets/binary.png)
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
+ ![Skeleton Image](../assets/skeleton.png)
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
+ ![Component Labeling](../assets/component-labeling.png)
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
+ ![Component labeling - barcode lines](../assets/component-labeling-line.png)
55
+ *Good: Parallel lines indicate a possible barcode*
56
+
57
+ ![Component labeling - text](../assets/component-labeling-text.png)
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
+ ![Theta calculation](http://www.sciweavers.org/tex2img.php?eq=%5CTheta%20%3D%20%5Cfrac%7B1%7D%7B2%7D%20%5Carctan%20%5Cleft%28%20%5Cfrac%7B2%5Cmu%27_%7B11%7D%7D%7B%5Cmu%27_%7B20%7D%20-%20%5Cmu%27_%7B02%7D%7D%20%5Cright%29&bc=Transparent&fc=Black&im=png&fs=12&ff=arev&edit=0)
67
+
68
+ Where μ (mu) are central moments calculated from raw moments (M):
69
+
70
+ ![Mu calculation](http://www.sciweavers.org/tex2img.php?eq=%5Cmu%27_%7B11%7D%20%3D%20M_%7B11%7D%2FM_%7B00%7D%20-%20%5Cbar%7Bx%7D%5Cbar%7By%7D%20%5C%5C%0A%5Cmu%27_%7B02%7D%20%3D%20M_%7B02%7D%2FM_%7B00%7D%20-%20%5Cbar%7By%7D%5E2%20%5C%5C%0A%5Cmu%27_%7B20%7D%20%3D%20M_%7B20%7D%2FM_%7B00%7D%20-%20%5Cbar%7Bx%7D%5E2&bc=Transparent&fc=Black&im=png&fs=12&ff=arev&edit=0)
71
+
72
+ The centroid (x̄, ȳ) is calculated from raw moments:
73
+
74
+ ![X Y bar calculation](http://www.sciweavers.org/tex2img.php?eq=%5Cbar%7Bx%7D%20%3D%20M_%7B10%7D%2FM_%7B00%7D%20%5C%5C%0A%5Cbar%7By%7D%20%3D%20M_%7B01%7D%2FM_%7B00%7D&bc=Transparent&fc=Black&im=png&fs=12&ff=arev&edit=0)
75
+
76
+ And the raw moments (M) are computed as:
77
+
78
+ ![M calculation](http://www.sciweavers.org/tex2img.php?eq=M_%7B00%7D%20%3D%20%5Csum_x%20%5Csum_y%20I%28x%2Cy%29%20%5C%5C%0AM_%7B10%7D%20%3D%20%5Csum_x%20%5Csum_y%20x%20I%28x%2Cy%29%20%5C%5C%0AM_%7B01%7D%20%3D%20%5Csum_x%20%5Csum_y%20y%20I%28x%2Cy%29%20%5C%5C%0AM_%7B11%7D%20%3D%20%5Csum_x%20%5Csum_y%20xy%20I%28x%2Cy%29%20%5C%5C%0AM_%7B20%7D%20%3D%20%5Csum_x%20%5Csum_y%20x%5E2%20I%28x%2Cy%29%20%5C%5C%0AM_%7B02%7D%20%3D%20%5Csum_x%20%5Csum_y%20y%5E2%20I%28x%2Cy%29&bc=Transparent&fc=Black&im=png&fs=12&ff=arev&edit=0)
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
+ ![Found patches](../assets/patches_found.png)
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
+ ![Connected patch labels](../assets/connected-patch-labels.png)
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
+ ![Remaining patch labels](../assets/remaining-patch-labels.png)
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
+ ![Rotated cells with box](../assets/bb-rotated.png)
132
+ *Patches rotated to horizontal, bounding box calculated*
133
+
134
+ ![Bounding box](../assets/bb-binary.png)
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)