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
@ -46,24 +48,23 @@ by simply typing:
You can check out the [examples](http://serratus.github.io/quaggaJS/examples) to get an idea of how to use QuaggaJS.
Basically the library exposes the following API:
### Quagga.init(config)
### Quagga.init(config, callback)
This method initializes the library for a given configuration (see below) which also includes a callback function (`readyFunc`) which is called when Quagga is ready to start. 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"]
},
readyFunc : function() {
console.log("Initialization finished. Ready to start");
Quagga.start();
}
});
inputStream : {
name : "Live",
type : "LiveStream"
},
decoder : {
readers : ["code_128_reader"]
}
}, function() {
console.log("Initialization finished. Ready to start");
Quagga.start();
});
```
### Quagga.start()
@ -73,18 +74,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)
Registers 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.
@ -99,11 +173,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,
@ -112,6 +188,7 @@ The default `config` object is set as followed:
]
},
locator: {
halfSample: true,
showCanvas: false,
showPatches: false,
showFoundPatches: false,
@ -151,7 +228,24 @@ Unit Tests can be run with [Karma][karmaUrl] and written using [Mocha][mochaUrl]
> 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))
- Added `Quagga.onProcessed(callback)` which provides a way to get information for each image processed.
The callback receives the same `data` object as `Quagga.onDetected` does. Depending on the success of the process the `data` object
might not contain any `resultCode` and/or `box` properties.
Christoph Oberhofer
11 years ago