diff --git a/README.md b/README.md
index 29ad8f0..3c82edb 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
quaggaJS
========
+- [Changelog](#changelog) (2015-01-21)
+
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.
+
+## The result object
+
+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.
+
+```javascript
+{
+ "codeResult": {
+ "code": "FANAVF1461710",
+ "start": 355,
+ "end": 26,
+ "codeset": 100,
+ "startInfo": {
+ "error": 1.0000000000000002,
+ "code": 104,
+ "start": 21,
+ "end": 41
+ },
+ "decodedCodes": [{
+ "code": 104,
+ "start": 21,
+ "end": 41
+ },
+ // stripped for brevity
+ {
+ "error": 0.8888888888888893,
+ "code": 106,
+ "start": 328,
+ "end": 350
+ }],
+ "endInfo": {
+ "error": 0.8888888888888893,
+ "code": 106,
+ "start": 328,
+ "end": 350
+ },
+ "direction": -1
+ },
+ "line": [{
+ "x": 25.97278706156836,
+ "y": 360.5616435369468
+ }, {
+ "x": 401.9220519377024,
+ "y": 70.87524989906444
+ }],
+ "angle": -0.6565217179979483,
+ "pattern": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, /* ... */ 1],
+ "box": [
+ [77.4074243622672, 410.9288668804402],
+ [0.050203235235130705, 310.53619724086366],
+ [360.15706727788256, 33.05711026051813],
+ [437.5142884049146, 133.44977990009465]
+ ],
+ "boxes": [
+ [
+ [77.4074243622672, 410.9288668804402],
+ [0.050203235235130705, 310.53619724086366],
+ [360.15706727788256, 33.05711026051813],
+ [437.5142884049146, 133.44977990009465]
+ ],
+ [
+ [248.90769330706507, 415.2041489551161],
+ [198.9532321622869, 352.62160512937635],
+ [339.546160777576, 240.3979259789976],
+ [389.5006219223542, 302.98046980473737]
+ ]
+ ]
+}
+```
## Config
@@ -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,21 @@ 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.
+
+## Changelog
+### 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))
[zxing_github]: https://github.com/zxing/zxing
[teaser_left]: https://github.com/serratus/quaggaJS/blob/master/doc/img/mobile-located.png