ZPL-IMAGE-CONVERT

Encode and decode ZPL images.

Installation

npm install @replytechnologies/zpl-image-convert

CommonJS

const zplImageConvert = require('@replytechnologies/zpl-image-convert');

EJS

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.

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

const zpl = await zplImageConvert.encode('... path to image file ...', {
	method: 'Z64',
});
// ^GFA,2850,2850,19,:Z64:eJzV1j1u2zAUAOBH ... ^FS

Using method ASCII

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.

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

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 to create the image.

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.

...
// 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.

Example of resizing the image before encoding

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.

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.