QuaggaJS is a barcode-scanner entirely written in JavaScript supporting real-time localization and decoding of
various types of barcodes such as __EAN__ and __CODE128__. The library is also capable of using `getUserMedia` to get direct
access to the user's camera stream. Although the code relies on heavy image-processing even recent smartphones are
@ -54,9 +56,22 @@ Basically the library exposes the following API:
### Quagga.init(config, callback)
This method initializes the library for a given configuration (see below) and a function which is called
when the loading-process has finished. The initialization process also requests for camera access if real-time
detection is configured.
This method initializes the library for a given configuration `config` (see below) and invokes the `callback` when Quagga is ready to start. The initialization process also requests for camera access if real-time detection is configured.
```javascript
Quagga.init({
inputStream : {
name : "Live",
type : "LiveStream"
},
decoder : {
readers : ["code_128_reader"]
}
}, function() {
console.log("Initialization finished. Ready to start");
Quagga.start();
});
```
### Quagga.start()
@ -65,18 +80,91 @@ the images.
### Quagga.stop()
If the decoder is currently running, after calling `stop()` the decoder does not process any more images.
If the decoder is currently running, after calling `stop()` the decoder does not process any more images. Additionally, if a camera-stream was requested upon initialization, this operation also disconnects the camera.
### Quagga.onProcessed(callback)
This method registers a `callback(data)` function that is called for each frame after the processing is done. The `data` object contains detailed information about the success/failure of the operation. The output varies, depending whether the detection and/or decoding were successful or not.
### Quagga.onDetected(callback)
Registeres a callback function which is triggered whenever a barcode-pattern has been located and decoded
successfully. The callback function is called with the decoded data as the first parameter.
Registers a `callback(data)` function which is triggered whenever a barcode-pattern has been located and decoded
successfully. The passed `data` object contains information about the decoding process including the detected code which can be obtained by calling `data.codeResult.code`.
### Quagga.decodeSingle(config, callback)
In contrast to the calls described above, this method does not rely on `getUserMedia` and operates on a
single image instead. The provided callback is the same as in `onDetected` and contains the decoded data
as first parameter.
single image instead. The provided callback is the same as in `onDetected` and contains the result `data`
object.
## <aname="resultobject">The result object</a>
The callbacks passed into `onProcessed`, `onDetected` and `decodeSingle` receive a `data` object upon execution. The `data` object contains the following information. Depending on the success, some fields may be `undefined` or just empty.
@ -91,11 +179,13 @@ The default `config` object is set as followed:
debug: false,
controls: false,
locate: true,
numOfWorkers: 4,
scriptName: 'quagga.js',
visual: {
show: true
},
decoder:{
drawBoundingBox: true,
drawBoundingBox: false,
showFrequency: false,
drawScanline: true,
showPattern: false,
@ -104,6 +194,7 @@ The default `config` object is set as followed:
]
},
locator: {
halfSample: true,
showCanvas: false,
showPatches: false,
showFoundPatches: false,
@ -135,7 +226,35 @@ Quagga.decodeSingle({
});
```
## Tests
Unit Tests can be run with [Karma][karmaUrl] and written using [Mocha][mochaUrl], [Chai][chaiUrl] and [SinonJS][sinonUrl]. Coverage reports are automatically generated in the coverage/ folder.
```console
> npm install
> grunt test
```
## Image Debugging
In case you want to take a deeper dive into the inner workings of Quagga, get to know the _debugging_ capabilities of the current implementation. The various flags exposed through the `config` object give you the abilily to visualize almost every step in the processing. Because of the introduction of the web-workers, and their restriction not to have access to the DOM, the configuration must be explicitly set to `config.numOfWorkers = 0` in order to work.
## <aname="changelog">Changelog</a>
### 2015-01-21
- Features
- Added support for web-worker (using 4 workers as default, can be changed through `config.numOfWorkers`)
- Due to the way how web-workers are created, the name of the script file (`config.scriptName`) should be kept in sync with your actual filename
- Removed canvas-overlay for decoding (boxes & scanline) which can now be easily implemented using the existing API (see example)
- API Changes
In the course of implementing web-workers some breaking changes were introduced to the API.
- The `Quagga.init` function no longer receives the callback as part of the config but rather as a second argument: `Quagga.init(config, cb)`
- The callback to `Quagga.onDetected` now receives an object containing much more information in addition to the decoded code. (see [data](#resultobject))
Christoph Oberhofer
11 years ago