@replytechnologies/zpl-image-convert
Version:
Encode and decode ZPL images
186 lines (130 loc) • 5.94 kB
Markdown
## ZPL-IMAGE-CONVERT
   
Encode and decode ZPL images.
---
---
---
### Installation
```shell
npm install @replytechnologies/zpl-image-convert
```
**CommonJS**
```js
const zplImageConvert = require('@replytechnologies/zpl-image-convert');
```
**EJS**
```js
import zplImageConvert from '@replytechnologies/zpl-image-convert';
```
### Encoding
Encoding takes image data and turns it into a ZPL statement. This library supports Z64 and ASCII output formats.
```js
const zpl = await zplImageConvert.encode(image: string | Buffer, options: object);
```
**Options**
| Property | Default | Description |
| ------------- | -------- | ------------------------------------------------------------ |
| `method` | `Z64` | The encoding method to use (`Z64`, `ASCII`) |
| `mimeType` | `null` | The mime type of the provided image (only required if image is a buffer) |
| `threshold` | `0x80` | The threshold above which the pixel luminance value is interpreted as white |
| `luminance.r` | `0.2126` | Pixel luminance calculation red channel multiplier |
| `luminance.g` | `0.7152` | Pixel luminance calculation green channel multiplier |
| `luminance.b` | `0.0722` | Pixel luminance calculation blue channel multiplier |
**Using method `Z64`**
```js
const zpl = await zplImageConvert.encode('... path to image file ...', {
method: 'Z64',
});
// ^GFA,2850,2850,19,:Z64:eJzV1j1u2zAUAOBH ... ^FS
```
**Using method `ASCII`**
```js
const zpl = await zplImageConvert.encode('... path to image file ...', {
method: 'ASCII',
});
// ^GFA,2850,2850,19,,:::::::::S0IFC,R01JF8 ... ^FS
```
**Using pre-existing image data**
If you already have image data, you can pass the data directly to the encode method. Doing this requires you to set the data mime type in the options.
```js
const image = fs.readFileSync('... path to image file ...');
const zpl = await zplImageConvert.encode(image, {
method: 'Z64',
mimeType: 'image/png',
});
```
### Decoding
Decoding takes a ZPL statement and turns it into a binary image. The `decode` function handles input with either `Z64` or `ASCII` formatting. Additional processing must be performed on the decoded result to turn it into an image.
**Result**
| Property | Description |
| -------- | ------------------------------------------------------------ |
| `width` | Width of the image |
| `height` | Height of the image |
| `buffer` | Binary bytes of the image (each bit represents a pixel: 1 = black, 0 = white) |
**Decoding a ZPL statement**
```js
const zpl = `^GFA,2850,2850,19,:Z64:eJzV1j1u2AOB ... ^FS`;
const image = await zplImageConvert.decode(zpl);
// image.width = 152
// image.height = 150
// image.buffer.length = 2850
```
**Turning the decoded result into an image**
Below is an example of turning the decoded result into a PNG image. This example makes use of [jimp](https://www.npmjs.com/package/jimp) to create the image.
```js
const Jimp = require('jimp');
// zpl = ^GFA,2850,2850,19,:Z64:eJzV1j1u2zAUAOB ... ^FS;
const decodeResult = await zplImageConvert.decode(zpl);
// image.width = 152
// image.height = 150
// image.buffer.length = 2850
const outputImage = new Jimp(decodeResult.width, decodeResult.height);
// set pixel color values on image
for (let i = 0; i < decodeResult.buffer.length; i++) {
const currentByte = decodeResult.buffer[i];
for (let bitIndex = 0; bitIndex < 8; bitIndex++) {
const pixelBit = (currentByte >> (7 - bitIndex)) & 0x01;
const currentBitIndex = i * 8 + bitIndex;
const y = ~~(currentBitIndex / decodeResult.width);
const x = currentBitIndex % decodeResult.width;
const color = pixelBit ? 0x000000FF : 0xFFFFFFFF;
outputImage.setPixelColor(color, x, y);
}
}
outputImage.write('... output file path ...');
```
If processing power is at your disposal, you may choose to use the code from the example below to get pixel values from the decoded result buffer.
```js
...
// set pixel color values on image
for (let x = 0; x < decodeResult.width; x++) {
for (let y = 0; y < decodeResult.height; y++) {
const pixelBit = decodeResult.getPixelBit(x, y);
const color = pixelBit ? 0x000000FF : 0xFFFFFFFF;
outputImage.setPixelColor(color, x, y);
}
}
...
```
### Preprocessing
If you need to alter the image before encoding to ZPL, you can either use any image manipulation program to create a new image or you can use [jimp](https://www.npmjs.com/package/jimp).
**Example of resizing the image before encoding**
```js
const Jimp = require('jimp');
const image = await Jimp.read('... path to image ...');
// Resize the image to 300px by 300px
image.resize(300, 300);
const zpl = await zplImageConvert.encode(image);
/// ^GFA,11400,11400,38,:Z64:eJztmj1u5DYUgMlwEaYY ... ^FS
```
### Tests
Unit tests can be executed by running the test command. This command is configured to run `jest` on the project.
```shell
npm test
```
### Issues
If any issues are found in the library, please create a new issue describing the problem with potential reproduction steps and potential solutions.
### Contributing
If you would like to add additional functionality to this library, please create a new issue describing the functionality.