# IChing-JS

An IChing encoding and decoding library written in typescript for use in javascript-based web apps.

## Installation

Clone the repository and run `npm install --no-save` followed by `npm run build`.

### Node.js

The Node.js files can be found in `./lib/esm5` after building.

### Javascript

This library can be used in javascript by including `./lib/umd/index.min.js` as script source.

## Usage

### Encoding

IChing-JS library exports a method `iching.encode(payload, options?)`.

#### Arguments
- `payload` - A string of alphanumeric characters that is the desired payload of the IChing.
- `options` (optional) - Additional options:
    - `ecLevel` - Error correction level, a number between 0 and 1 representing the maximum percentage of errors that can be corrected, relative to the payload length. Defaults to [`Encoder.EC_MEDIUM`](./src/core/encoder/Encoder.ts#L34) (0.15).
    - `resolution` - A number representing the width and height of the square image produced by the method. Defaults to 1250.
    - `roundEdges` - A boolean determining whether the symbols' edges in the output image are straight or round. Defaults to false, which means straight edges.
    - `inverted` - A boolean determining whether the output image is inverted, i.e. white on black instead of black on white. Defaults to false.

#### Return Value
If the encoding process succeeds, the method will return an object that implements the [`EncodedIChing`](./src/core/encoder/EncodedIChing.ts) interface.

#### Example
Example usage with options specified:
```javascript
const payload = "thisisanexample123";
const options = { ecLevel: 0.5, resolution: 2000, roundEdges: true, inverted: false };
const encoded = iching.encode(payload, options);
```
Or without options:
```javascript
const payload = "thisisanexample123";
const encoded = iching.encode(payload);
```
Which is equivalent to:
```javascript
const payload = "thisisanexample123";
const defaultOptions = { ecLevel: 0.15, resolution: 1250, roundEdges: false, inevrted: false };
const encoded = iching.encode(payload, defaultOptions);
```
Image can be displayed using HTML canvas:
```javascript
// 'cvs' and 'ctx' are an HTML canvas element, and its 2D rendering context, respectively.
const imgData = encoded.imageData;
cvs.width = imgData.width;
cvs.height = imgData.height;
const ctxImgData = new ImageData(imgData.data, imgData.width, imgData.height);
ctx.putImageData(ctxImgData, 0, 0);

// If 'img' is an HTML image element, its 'src' attribute can be set like follows:
img.src = cvs.toDataURL();
```

### Decoding

IChing-JS library exports a method `iching.decode(imageData, width, height)`.

#### Arguments
- `imageData` - A `Uint8ClampedArray` of RGBA pixel values in the form `[r0, g0, b0, a0, r1, g1, b1, a1, ...]`. The length of this array should be `4 * width * height`.
- `width` - The width of the image to be decoded.
- `height` - The height of the image to be decoded.

#### Return value
If the decoding process succeeds, the method will return an object that implements the [`DecodedIChing`](./src/core/decoder/DecodedIChing.ts) interface.

#### Example
Example usage:
```javascript
// Let 'width' and 'height' be the width and height of the input image, respectively,
// and 'imageData' be a Uint8ClampedArray of RGBA pixel values, and of length 4 * width * height.
const decoded = iching.decode(imageData, width, height);
console.log(decoded.version, decoded.size);
console.log(decoded.data);
```

## Documentation
Detailed HTML docs can be found [here](./docs/index.html).

## License
IChing-JS is released under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.txt) license.<br/>
Copyright © [Nodle](https://nodle.io/)