<commit_before>ZXing TypeScript
================

[![Build Status](https://travis-ci.org/aleris/zxing-typescript.svg?branch=master)](https://travis-ci.org/aleris/zxing-typescript)

ZXing ("zebra crossing") TypeScript is an open-source, multi-format 1D/2D barcode image processing library ported to TypeScript from Java.

See https://github.com/zxing/zxing for original Java project.

Demo
====

See [some demo examples](https://aleris.github.io/zxing-typescript/) in browser.

Usage
=====

The library has separate builds for node and browser so can be used:
- from browser with TypeScript (just reference anything from src/browser)
- from browser with plain javascript (see below)
- from node with TypeScript (just reference anything from src/core)
- from node with plain javascript (see below)


Browser Usage
-------------

Examples below are for QR barcode, all other supported barcodes work similary.

`npm install zxing-typescript --save`

To use from javascript you need to build it:

`npm run build.browser.dist`

And then reference, for example `zxing.qrcodereader.min.js` from `build-browser` folder.

See [some demo examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples) for browser usage javascript code examples.

All the examples are using es6, be sure is supported in your browser or modify as needed (eg. var instead of const etc.).

### Scanning from Video Camera

To display the input from the video camera you will need to add a video element in the html page:

```html
    <video id="video" width="300" height="200" style="border: 1px solid gray"></video>
```

To start decoding, first obtain a list of video input devices with:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
codeReader.getVideoInputDevices()
    .then((videoInputDevices) => {
        videoInputDevices.forEach((element) => {
            console.log(`${element.label}, ${element.deviceId}`)            
        })
    .catch((err) => {
        console.error(err)
    })
```

If there is just one input device you can use the first deviceId and the video element id (in the example below is also 'video') to decode:

```javascript
const firstDeviceId = videoInputDevices[0].deviceId
codeReader.decodeFromInputVideoDevice(firstDeviceId, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

If there are more input devices then you will need to chose one for `codeReader.decodeFromInputVideoDevice` device id parameter.

You can also provide `undefined` for the device id parameter in which case the library will automatically choose the camera, prefering the main (environment facing) camera if more are available:

```javascript
codeReader.decodeFromInputVideoDevice(undefined, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Video Camera](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-camera/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).

### Scanning from Video File
Similar as above you can use a video element in the html page:

```html
    <video id="video" width="300" height="200" style="border: 1px solid gray"></video>
```

And to decode the video from an url:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
const videoSrc = 'your url to a video'
codeReader.decodeFromVideoSource(videoSrc, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

You can also decode the video url without showing it in the page, in this case no `video` element is needed in html.

```javascript
codeReader.decodeFromVideoSource(videoSrc)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Video File](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-video/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).


### Scanning from Image
Similar as above you can use a img element in the html page (with src attribute set):

```html
    <img id="img" src="qrcode-image.png" width="200" height="300" style="border: 1px solid gray"></img>
```

And to decode the image:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
const img = document.getElementById('img')
codeReader.decodeFromImage(img)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

You can also decode the image url without showing it in the page, in this case no `img` element is needed in html:

```javascript
const imgSrc = 'url to image'
codeReader.decodeFromImage(undefined, imgSrc)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

Or decode the image url directly from an url, with an `img` element in page (notice in this case no `src` attribute is set for `img` element):

```html
    <img id="img" width="200" height="300" style="border: 1px solid gray"></img>
```

```javascript
const imgSrc = 'url to image'
codeReader.decodeFromImage('img', imgSrc)//here img is the image id from html, in our case 'img'
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Image](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-image/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).

Node Usage
----------

`npm install zxing-typescript --save`

If you want to use plain js (es5):

`npm run build.node`

And the files will be available in `build-node` folder.

To use in node you will need to provide an implementation of [`LuminanceSource`](https://github.com/aleris/zxing-typescript/blob/master/src/core/LuminanceSource.ts) for an image. A starting point is [`SharpImageLuminanceSource`](https://github.com/aleris/zxing-typescript/blob/master/src/test/core/SharpImageLuminanceSource.ts) from tests that is using [sharp image processing](https://github.com/lovell/sharp) node library.

No examples are availabe for now, however you can have a look at the extensive [tests cases](https://github.com/aleris/zxing-typescript/tree/master/src/test/core/qrcode).

Porting Information
===================

See [TypeScript Port Info](typescriptport.md) for information regarging poring approach and reasoning behind some of the approaches taken.


Status and Roadmap
==================

Done:
- [x] Port root, common and qrcode format and make it compile
- [x] Add unit test infrastructure, a first unit test and make it pass (common/BitArrayTestCase)
- [x] Add all unit tests for everything in root, common and qrcode
- [x] Add one "back box" test for qrcode
- [x] Add all "back box" tests for qrcode
- [x] Create browser integration module and demo UI for qrcode
- [x] Document browser usage

Todo:
- [ ] Create tests for node.js usage for qrcode
- [ ] Adapt documentation for JSDoc, generate documentation, cleanup source files
- [ ] Document node usage
- [ ] Port aztec format with unit and browser tests
- [ ] Port client/result parsing with unit and browser tests and documentation
- [ ] Port datamatrix format with unit and browser tests and documentation
- [ ] Port maxicode format with unit and browser tests and documentation
- [ ] Port multi parsing with unit and browser tests and documentation
- [ ] Port oned format with unit and browser tests and documentation
- [ ] Port pdf417 format with unit and browser tests and documentation<commit_msg>added text encoding/decoding info in readme<commit_after>ZXing TypeScript
================

[![Build Status](https://travis-ci.org/aleris/zxing-typescript.svg?branch=master)](https://travis-ci.org/aleris/zxing-typescript)

ZXing ("zebra crossing") TypeScript is an open-source, multi-format 1D/2D barcode image processing library ported to TypeScript from Java.

See https://github.com/zxing/zxing for original Java project.

Demo
====

See [some demo examples](https://aleris.github.io/zxing-typescript/) in browser.

Usage
=====

The library has separate builds for node and browser so can be used:
- from browser with TypeScript (just reference anything from src/browser)
- from browser with plain javascript (see below)
- from node with TypeScript (just reference anything from src/core)
- from node with plain javascript (see below)


Browser Usage
-------------

Examples below are for QR barcode, all other supported barcodes work similary.

`npm install zxing-typescript --save`

To use from javascript you need to build it:

`npm run build.browser.dist`

And then reference, for example `zxing.qrcodereader.min.js` from `build-browser` folder.

See [some demo examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples) for browser usage javascript code examples.

All the examples are using es6, be sure is supported in your browser or modify as needed (eg. var instead of const etc.).

### Scanning from Video Camera

To display the input from the video camera you will need to add a video element in the html page:

```html
    <video id="video" width="300" height="200" style="border: 1px solid gray"></video>
```

To start decoding, first obtain a list of video input devices with:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
codeReader.getVideoInputDevices()
    .then((videoInputDevices) => {
        videoInputDevices.forEach((element) => {
            console.log(`${element.label}, ${element.deviceId}`)            
        })
    .catch((err) => {
        console.error(err)
    })
```

If there is just one input device you can use the first deviceId and the video element id (in the example below is also 'video') to decode:

```javascript
const firstDeviceId = videoInputDevices[0].deviceId
codeReader.decodeFromInputVideoDevice(firstDeviceId, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

If there are more input devices then you will need to chose one for `codeReader.decodeFromInputVideoDevice` device id parameter.

You can also provide `undefined` for the device id parameter in which case the library will automatically choose the camera, prefering the main (environment facing) camera if more are available:

```javascript
codeReader.decodeFromInputVideoDevice(undefined, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Video Camera](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-camera/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).

### Scanning from Video File
Similar as above you can use a video element in the html page:

```html
    <video id="video" width="300" height="200" style="border: 1px solid gray"></video>
```

And to decode the video from an url:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
const videoSrc = 'your url to a video'
codeReader.decodeFromVideoSource(videoSrc, 'video')
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

You can also decode the video url without showing it in the page, in this case no `video` element is needed in html.

```javascript
codeReader.decodeFromVideoSource(videoSrc)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Video File](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-video/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).


### Scanning from Image
Similar as above you can use a img element in the html page (with src attribute set):

```html
    <img id="img" src="qrcode-image.png" width="200" height="300" style="border: 1px solid gray"></img>
```

And to decode the image:

```javascript
const codeReader = new ZXing.BrowserQRCodeReader()
const img = document.getElementById('img')
codeReader.decodeFromImage(img)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

You can also decode the image url without showing it in the page, in this case no `img` element is needed in html:

```javascript
const imgSrc = 'url to image'
codeReader.decodeFromImage(undefined, imgSrc)
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

Or decode the image url directly from an url, with an `img` element in page (notice in this case no `src` attribute is set for `img` element):

```html
    <img id="img" width="200" height="300" style="border: 1px solid gray"></img>
```

```javascript
const imgSrc = 'url to image'
codeReader.decodeFromImage('img', imgSrc)//here img is the image id from html, in our case 'img'
    .then((result) => {
        console.log(result.text)
    }).catch((err) => {
        console.error(err)
    })
```

A full working example for [QR Code from Image](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/qr-image/) is provided in the [examples](https://github.com/aleris/zxing-typescript/tree/master/docs/examples/).

### Barcode generation

Not available yet.

Node Usage
----------

`npm install zxing-typescript --save`

If you want to use plain js (es5):

`npm run build.node`

And the files will be available in `build-node` folder.

To use in node you will need to provide an implementation of [`LuminanceSource`](https://github.com/aleris/zxing-typescript/blob/master/src/core/LuminanceSource.ts) for an image. A starting point is [`SharpImageLuminanceSource`](https://github.com/aleris/zxing-typescript/blob/master/src/test/core/SharpImageLuminanceSource.ts) from tests that is using [sharp image processing](https://github.com/lovell/sharp) node library.

No examples are availabe for now, however you can have a look at the extensive [tests cases](https://github.com/aleris/zxing-typescript/tree/master/src/test/core/qrcode).

Text Encoding and Decoding
==========================

The state of encoding and encoding text in javascript/browser is somehow messy at the moment. 

To have full support for all encodings in [CharacterSetECI](https://github.com/aleris/zxing-typescript/blob/master/src/core/common/CharacterSetECI.ts) *except Cp437* use [text-encoding](https://github.com/inexorabletash/text-encoding) library. The library is used implicitly for node, but is an optional dependency for browser because is rather large (> 600k). You will need to include it yourself if you want/need to use it.

By default, in browser, [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)/[TextEncoder](https://developer.mozilla.org/ro/docs/Web/API/TextEncoder) web api are used if available (take care as these are labeled as experimental as of this writing). Alos be aware that TextEncoder encodes only to UTF-8 as per spec. If these are not available the library falls back to a minimal implementation that only encodes and decodes to/from UTF-8.

Porting Information
===================

See [TypeScript Port Info](typescriptport.md) for information regarging poring approach and reasoning behind some of the approaches taken.


Status and Roadmap
==================

Done:
- [x] Port root, common and qrcode format and make it compile
- [x] Add unit test infrastructure, a first unit test and make it pass (common/BitArrayTestCase)
- [x] Add all unit tests for everything in root, common and qrcode
- [x] Add one "back box" test for qrcode
- [x] Add all "back box" tests for qrcode
- [x] Create browser integration module and demo UI for qrcode
- [x] Document browser usage

Todo:
- [ ] Create tests for node.js usage for qrcode
- [ ] Adapt documentation for JSDoc, generate documentation, cleanup source files
- [ ] Document node usage
- [ ] Port aztec format with unit and browser tests
- [ ] Port client/result parsing with unit and browser tests and documentation
- [ ] Port datamatrix format with unit and browser tests and documentation
- [ ] Port maxicode format with unit and browser tests and documentation
- [ ] Port multi parsing with unit and browser tests and documentation
- [ ] Port oned format with unit and browser tests and documentation
- [ ] Port pdf417 format with unit and browser tests and documentation
{'fraction_non_alphanumeric': 0.12085618888623897, 'fraction_numerical': 0.004769854519437157, 'mean_word_length': 4.044511278195489, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 54, 'https://': 34, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5159126', 'n_tokens_mistral': 5002, 'n_tokens_neox': 4764, 'n_words': 1771}