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

pnpm add zpl-image-modern

Or with npm:

npm install zpl-image-modern

Or with yarn:

yarn add zpl-image-modern

Usage

Browser Environment

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

Node.js Environment

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

Types

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

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

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
}

Functions

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:

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

Example:

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

Compression Formats

Z64 Format

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

ACS Format

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

License

MIT