ZPL Image Modern

Base zpl-image

The original zpl-image library is no longer maintained. It was a simple JavaScript library for converting images to ZPL (Zebra Programming Language) format, but it lacked modern features and support for newer environments.

A modern TypeScript library for converting images to ZPL (Zebra Programming Language) format. Supports both Z64 and ACS compression formats and works in both browser and Node.js environments.

Features

- 🌐 Universal: Works in both browser and Node.js environments
- 📦 Modern: Written in TypeScript with full type definitions
- 🔄 Multiple Formats: Supports both Z64 and ACS compression
- 🖼️ Image Processing: Automatic cropping, rotation, and threshold adjustment
- ⚡ Performance: Optimized for speed and memory efficiency

Installation

``bash
pnpm add zpl-image-modern
`

Or with npm:
`bash
npm install zpl-image-modern
`

Or with yarn:
`bash
yarn add zpl-image-modern
`

Usage

$3

`javascript
import { imageToZ64, imageToACS } from 'zpl-image-modern';

// Convert an HTML image element to Z64 format
const img = document.getElementById('myImage');
const z64Result = imageToZ64(img, {
black: 50, // Black threshold (1-99)
rotate: 'N', // Rotation: 'N', 'R', 'L', 'I', 'B'
notrim: false // Don't crop whitespace
});

console.log(z64Result.z64); // ZPL string ready for printing

// Convert to ACS format
const acsResult = imageToACS(img, { black: 30 });
console.log(acsResult.acs); // ACS compressed ZPL string
`

$3

`javascript
import { rgbaToZ64, rgbaToACS } from 'zpl-image-modern';
import sharp from 'sharp'; // or any other image processing library

// Load and process image
const { data, info } = await sharp('image.png')
.raw()
.ensureAlpha()
.toBuffer({ resolveWithObject: true });

// Convert RGBA buffer to Z64
const result = rgbaToZ64(data, info.width, {
black: 50,
rotate: 'R'
});

console.log(result.z64);
`

API Reference

$3

#### ZplRotation
- 'N': No rotation (default)
- 'R': Rotate 90 degrees clockwise
- 'L': Rotate 90 degrees counter-clockwise
- 'I': Rotate 180 degrees (inverted)
- 'B': Same as 'L'

#### ZplImageOptions
`typescript
interface ZplImageOptions {
black?: number; // Black threshold percentage (1-99), default: 50
rotate?: ZplRotation; // Rotation option
notrim?: boolean; // If true, don't crop whitespace around image
}
`

#### ZplImageResult
`typescript
interface ZplImageResult {
length: number; // Byte length of uncompressed data
rowlen: number; // Bytes per row after compression
width: number; // Image width after rotation
height: number; // Image height after rotation
z64?: string; // Z64 compressed ZPL string
acs?: string; // ACS compressed ZPL string
}
`

$3

#### imageToZ64(img: HTMLImageElement, opts?: ZplImageOptions): ZplImageResult
Converts an HTML image element to Z64 compressed ZPL format (browser only).

#### imageToACS(img: HTMLImageElement, opts?: ZplImageOptions): ZplImageResult
Converts an HTML image element to ACS compressed ZPL format (browser only).

#### rgbaToZ64(rgba: Uint8ClampedArray | Buffer, width: number, opts?: ZplImageOptions): ZplImageResult
Converts RGBA pixel data to Z64 compressed ZPL format.

#### rgbaToACS(rgba: Uint8ClampedArray | Buffer, width: number, opts?: ZplImageOptions): ZplImageResult
Converts RGBA pixel data to ACS compressed ZPL format.

ZPL Usage

Once you have the ZPL string, you can use it in your ZPL commands:

`zpl
^XA
^FO50,50
^GFA,{length},{rowlen},{rowlen},{z64 or acs data}
^XZ
`

Example:
`zpl
^XA
^FO50,50
^GFA,1024,32,32,:Z64:eJzt....:A1B2
^XZ
`

Compression Formats

$3

- Uses deflate compression followed by base64 encoding
- Generally provides better compression ratios
- Requires CRC16 checksum
- Format: :Z64:{base64_data}:{crc16}`

$3

- Alternative Data Compression Scheme
- Uses run-length encoding
- Simpler format, no checksum required
- Better for images with large solid areas

License

MIT