From a0f6afaddcc78bab5420e477d555209f4ef48e26 Mon Sep 17 00:00:00 2001 From: Christoph Oberhofer Date: Tue, 20 Jan 2015 21:42:53 +0100 Subject: [PATCH] Update README.md --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 111 insertions(+), 20 deletions(-) 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