From da8ec1d3d7634582494b52b5b4f58af85065a714 Mon Sep 17 00:00:00 2001 From: Christoph Oberhofer Date: Sun, 20 Dec 2015 21:19:10 -0500 Subject: [PATCH] Improved docs --- index.md | 198 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 147 insertions(+), 51 deletions(-) diff --git a/index.md b/index.md index 7dbe29b..849e87e 100644 --- a/index.md +++ b/index.md @@ -8,6 +8,10 @@ quaggaJS ======== - [Changelog](#changelog) (2015-11-22) +- [Installing](#installing) +- [Getting Started](#gettingstarted) +- [API](#api) +- [Configuration](#configobject) ## What is QuaggaJS? @@ -49,7 +53,7 @@ In cases where real-time decoding is not needed, or the platform does not support `getUserMedia` QuaggaJS is also capable of decoding image-files using the File API or other URL sources. -## Installing +## Installing QuaggaJS can be installed using __npm__, __bower__, or by including it with the __script__ tag. @@ -83,8 +87,7 @@ You can also install QuaggaJS through __bower__: You can simply include `dist/quagga.min.js` in your project and you are ready to go. - -## Getting Started +## Getting Started For starters, have a look at the [examples][github_examples] to get an idea where to go from here. @@ -106,7 +109,7 @@ file is only valid for the non-uglified version `quagga.js` because the minified version is altered after compression and does not align with the map file any more. -## API +## API You can check out the [examples][github_examples] to get an idea of how to use QuaggaJS. Basically the library exposes the following API: @@ -255,63 +258,156 @@ empty. } ``` -## Config +## Configuration + +The configuration that ships with QuaggaJS covers the default use-cases and can +be fine-tuned for specific requirements. -The default `config` object is set as followed: +The configuration is managed by the `config` object defining the following +high-level properties: ```javascript { - inputStream: { name: "Live", - type: "LiveStream", - constraints: { - width: 640, - height: 480, - facing: "environment" - }, - area: { // defines rectangle of the detection/localization area - top: "0%", // top offset - right: "0%", // right offset - left: "0%", // left offset - bottom: "0%" // bottom offset - }, - singleChannel: false // true: only the red color-channel is read - }, - tracking: false, - debug: false, - controls: false, - locate: true, numOfWorkers: 4, - visual: { - show: true + locate: true, + inputStream: {...}, + decoder:{...}, + locator: {...}, + debug: false, +} +``` + +### numOfWorkers + +QuaggaJS supports web-workers out of the box and runs with `4` workers in its +default configuration. The number should align with the number of cores +available in your targeted devices. + +In case you don't know the number upfront, or if the variety of devices is +too big, you can either use `navigator.hardwareConcurrency` (see +[here](https://wiki.whatwg.org/wiki/Navigator_HW_Concurrency)) where available +or make use of [core-estimator](https://github.com/oftn/core-estimator). + +### locate + +One of the main features of QuaggaJS is its ability to locate a barcode in a +given image. The `locate` property controls whether this feature is turned on +(default) or off. + +Why would someone turn this feature off? Localizing a barcode is a +computationally expensive operation and might not work properly on some +devices. Another reason would be the lack of auto-focus producing blurry +images which makes the localization feature very unstable. + +However, even if none of the above apply, there is one more case where it might +be useful to disable `locate`: If the orientation, and/or the approximate +position of the barcode is known, or if you want to guide the user through a +rectangular outline. This can increase performance and robustness at the same +time. + +### inputStream + +The `inputStream` property defines the sources of images/videos within QuaggaJS. + +```javascript +{ + name: "Live", + type: "LiveStream", + constraints: { + width: 640, + height: 480, + facing: "environment" }, - decoder:{ - drawBoundingBox: false, - showFrequency: false, - drawScanline: true, - showPattern: false, - readers: [ - 'code_128_reader' - ] + area: { // defines rectangle of the detection/localization area + top: "0%", // top offset + right: "0%", // right offset + left: "0%", // left offset + bottom: "0%" // bottom offset }, - locator: { - halfSample: true, - patchSize: "medium", // x-small, small, medium, large, x-large - showCanvas: false, - showPatches: false, - showFoundPatches: false, - showSkeleton: false, - showLabels: false, - showPatchLabels: false, - showRemainingPatchLabels: false, - boxFromPatches: { - showTransformed: false, - showTransformedBox: false, - showBB: false - } - } + singleChannel: false // true: only the red color-channel is read } ``` +First, the `type` property can be set to three different values: +`ImageStream`, `VideoStream`, or `LiveStream` (default) and should be selected +depending on the use-case. Most probably, the default value is sufficient. + +Second, the `constraint` key defines the physical dimensions of the input image +and additional properties, such as `facing` which sets the source of the user's +camera in case of multiple attached devices. + +Thirdly, the `area` prop restricts the decoding area of the image. The values +are given in percentage, similar to the CSS style property when using +`position: absolute`. This `area` is also useful in cases the `locate` property +is set to `false`, defining the rectangle for the user. + +The last key `singleChannel` is only relevant in cases someone wants to debug +erroneous behavior of the decoder. If set to `true` the input image's red +color-channel is read instead of calculating the gray-scale values of the +source's RGB. This is useful in combination with the `ResultCollector` where +the gray-scale representations of the wrongly identified images are saved. + +### decoder + +QuaggaJS usually runs in a two-stage manner (`locate` is set to `true`) where, +after the barcode is located, the decoding process starts. Decoding is the +process of converting the bars into its true meaning. Most of the configuration +options within the `decoder` are for debugging/visualization purposes only. + +```javascript +{ + drawBoundingBox: false, + showFrequency: false, + drawScanline: true, + showPattern: false, + readers: [ + 'code_128_reader' + ] +} +``` + +The most important property is `readers` which takes an array of types of +barcodes which should be decoded during the session. Possible values are: + +- code_128_reader (default) +- ean_reader +- ean_8_reader +- code_39_reader +- code_39_vin_reader +- codabar_reader +- upc_reader +- upc_e_reader +- i2of5_reader + +Why are not all types activated by default? Simply because one should +explicitly define the set of barcodes for their use-case. More decoders means +more possible clashes, or false-positives. One should take care of the order +the readers are given, since some might return a value even though it is not +the correct type (EAN-13 vs. UPC-A). + +The remaining properties `drawBoundingBox`, `showFrequency`, `drawScanline` and +`showPattern` are mostly of interest during debugging and visualization. + +### locator + +```javascript +{ + halfSample: true, + patchSize: "medium", // x-small, small, medium, large, x-large + showCanvas: false, + showPatches: false, + showFoundPatches: false, + showSkeleton: false, + showLabels: false, + showPatchLabels: false, + showRemainingPatchLabels: false, + boxFromPatches: { + showTransformed: false, + showTransformedBox: false, + showBB: false + } +} + ## Examples The following example takes an image `src` as input and prints the result on the