zpl-image-modern/README.md

Modern ZPL image conversion library supporting both browser and Node.js environments

# 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

### Browser Environment

```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
```

### Node.js Environment

```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

### 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`
```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
}
```

### 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:

```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

### 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