@cross/image

A pure JavaScript, dependency-free, cross-runtime image processing library for Deno, Node.js, Bun
and browsers. Decode, encode, manipulate, and process images in multiple formats including PNG,
JPEG, WebP, GIF, and more—all without native dependencies.

📚 Full Documentation

Features

- 🚀 Pure JavaScript - No native dependencies
- 🔌 Pluggable formats - Easy to extend with custom formats
- 📦 Cross-runtime - Works on Deno, Node.js (18+), Bun and Browsers.
- 🎨 Multiple formats - PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PCX, ASCII,
HEIC, and AVIF support
- ✂️ Image manipulation - Resize, crop, composite, and more
- 🎛️ Image processing - Chainable filters including brightness, contrast, saturation,
hue, exposure, blur, sharpen, sepia, and more
- 🖌️ Drawing operations - Create, fill, and manipulate pixels
- 🧩 Multi-frame - Decode/encode animated GIFs, APNGs and multi-page TIFFs
- 🔧 Simple API - Easy to use, intuitive interface

Installation

$3

``ts
import { Image } from "jsr:@cross/image";
`

$3

`bash
npm install cross-image
`

`ts
import { Image } from "cross-image";
`

$3

`bash
npm install cross-image
`

`ts
import { Image } from "cross-image";
`

Quick Start

$3

`ts
import { Image } from "jsr:@cross/image";

// Decode an image (auto-detects format)
const data = await Deno.readFile("input.png");
const image = await Image.decode(data);

console.log(Image size: ${image.width}x${image.height});

// Create a new blank image
const canvas = Image.create(800, 600, 255, 255, 255); // white background

// Composite the loaded image on top
canvas.composite(image, 50, 50);

// Apply image processing filters
canvas
.brightness(0.1)
.contrast(0.2)
.saturation(-0.1)
.blur(1)
.sharpen(0.3);

// Encode in a different format
const jpeg = await canvas.encode("jpeg");
await Deno.writeFile("output.jpg", jpeg);
`

$3

`ts
import { Image } from "cross-image";
import { readFile, writeFile } from "node:fs/promises";

// Read an image (auto-detects format)
const data = await readFile("input.png");
const image = await Image.decode(data);

console.log(Image size: ${image.width}x${image.height});

// Resize the image
image.resize({ width: 800, height: 600 });

// Save in a different format
const jpeg = await image.encode("jpeg");
await writeFile("output.jpg", jpeg);
`

$3

`ts
import { Image } from "cross-image";

// Read an image (auto-detects format)
const data = await Bun.file("input.png").arrayBuffer();
const image = await Image.decode(new Uint8Array(data));

console.log(Image size: ${image.width}x${image.height});

// Resize the image and save
image.resize({ width: 800, height: 600 });
const jpeg = await image.encode("jpeg");
await Bun.write("output.jpg", jpeg);
`

Supported Formats

| Format | Pure-JS | Notes |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------- |
| PNG | ✅ Full | Complete pure-JS implementation |
| APNG | ✅ Full | Animated PNG with multi-frame |
| BMP | ✅ Full | Complete pure-JS implementation |
| ICO | ✅ Full | Windows Icon format |
| GIF | ✅ Full | Animated GIF with multi-frame |
| DNG | ✅ Full | Linear DNG (Uncompressed RGBA) |
| PAM | ✅ Full | Netpbm PAM format |
| PPM | ✅ Full | Netpbm PPM format (P3/P6) |
| PCX | ✅ Full | ZSoft PCX (RLE compressed) |
| ASCII | ✅ Full | Text-based ASCII art |
| JPEG | ⚠️ Baseline & Progressive | Pure-JS baseline & progressive DCT: decode with spectral selection; encode with 2-scan (DC+AC) |
| WebP | ⚠️ Lossless | Pure-JS lossless VP8L |
| TIFF | ⚠️ Basic | Pure-JS uncompressed, LZW, PackBits, & Deflate; grayscale & RGB/RGBA |
| HEIC | 🔌 Runtime | Requires ImageDecoder/OffscreenCanvas API support |
| AVIF | 🔌 Runtime | Requires ImageDecoder/OffscreenCanvas API support |

See the full format support documentation for detailed
compatibility information.

Advanced Usage

Most users should stick to the Image API (Image.decode, image.encode, etc.).

If you need to work with format handlers directly (e.g. new PNGFormat()) or register your own
ImageFormat implementation via Image.registerFormat(...), see the API reference section
“Exported Format Classes”:

- https://cross-image.56k.guru/api/

JPEG Tolerant Decoding

The JPEG decoder includes a tolerant decoding mode (enabled by default) that gracefully handles
partially corrupted images or complex encoding patterns from mobile phone cameras. When enabled, the
decoder will continue processing even if some blocks fail to decode, filling failed blocks with
neutral values.

Features:

- Enabled by default - Handles real-world JPEGs from various devices
- Progressive JPEG support - Decodes both baseline and progressive JPEGs
- Configurable - Can be disabled for strict validation
- Fault-tolerant - Recovers partial image data instead of failing completely
- Zero configuration - Works automatically with the standard Image.decode() API

When to use:

- Mobile phone JPEGs with complex encoding patterns
- Progressive JPEG images from web sources
- Images from various camera manufacturers
- Partially corrupted JPEG files
- Production applications requiring maximum compatibility

Example:

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("mobile-photo.jpg");
// Default behavior - tolerant decoding enabled
const image = await Image.decode(data);

// Strict mode - fail fast on decode errors
const strictImage = await Image.decode(data, { tolerantDecoding: false });

// Optional: receive warnings during partial decode (pure-JS decoder paths)
const imageWithWarnings = await Image.decode(data, {
tolerantDecoding: true,
runtimeDecoding: "never",
onWarning: (message, details) => {
console.log(JPEG Warning: ${message}, details);
},
});
`

Note: When using Image.decode(), the library automatically tries runtime-optimized decoders

CMYK Color Space Support

The library provides utilities for working with CMYK (Cyan, Magenta, Yellow, Key/Black) color space,
commonly used in professional printing and color manipulation.

$3

`ts
import { cmykToRgb, rgbToCmyk } from "jsr:@cross/image";

// Convert RGB to CMYK
const [c, m, y, k] = rgbToCmyk(255, 0, 0); // Red
console.log({ c, m, y, k }); // { c: 0, m: 1, y: 1, k: 0 }

// Convert CMYK back to RGB
const [r, g, b] = cmykToRgb(c, m, y, k);
console.log({ r, g, b }); // { r: 255, g: 0, b: 0 }
`

$3

`ts
import { Image } from "jsr:@cross/image";

// Load an image and convert to CMYK
const data = await Deno.readFile("photo.jpg");
const image = await Image.decode(data);

// Get CMYK representation (Float32Array with 4 values per pixel)
const cmykData = image.toCMYK();

// Create an image from CMYK data
const restored = Image.fromCMYK(cmykData, image.width, image.height);

// Save the restored image
await Deno.writeFile("output.png", await restored.encode("png"));
`

$3

`ts
import { cmykToRgba, rgbaToCmyk } from "jsr:@cross/image";

// Convert entire image data to CMYK
const rgbaData = new Uint8Array([255, 0, 0, 255]); // Red pixel
const cmykData = rgbaToCmyk(rgbaData);

// Convert CMYK data back to RGBA
const rgbaRestored = cmykToRgba(cmykData);
`

Use Cases:

- Pre-press and print preparation workflows
- Color space conversion for professional printing
- Color analysis and manipulation in CMYK space
- Educational tools for understanding color models

$3

TIFF format has native support for CMYK images:

`ts
import { Image } from "jsr:@cross/image";

// Decode CMYK TIFF (automatically converted to RGBA)
const cmykTiff = await Deno.readFile("cmyk-image.tif");
const image = await Image.decode(cmykTiff); // Automatic CMYK → RGBA conversion

// Encode image as CMYK TIFF
const output = await image.encode("tiff", { cmyk: true });
await Deno.writeFile("output-cmyk.tif", output);

// CMYK works with all TIFF compression methods
const compressed = await image.encode("tiff", {
cmyk: true,
compression: "lzw", // or "packbits", "deflate", "none"
});
`

Benefits:

- Seamless workflow: CMYK TIFFs decode automatically, no special handling needed
- Print-ready output: Generate CMYK TIFFs for professional printing workflows
- Full compression support: CMYK works with all TIFF compression methods
- Industry standard: TIFF is the preferred format for CMYK images in print production

JPEG Coefficient Extraction

The library provides advanced APIs for extracting and encoding JPEG quantized DCT coefficients,
enabling coefficient-domain steganography and other frequency-domain processing techniques.

$3

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("photo.jpg");

// Extract quantized DCT coefficients
const coefficients = await Image.extractCoefficients(data, "jpeg");

if (coefficients) {
console.log(Image: ${coefficients.width}x${coefficients.height});
console.log(Progressive: ${coefficients.isProgressive});
console.log(Components: ${coefficients.components.length});

// Access coefficient blocks (Y, Cb, Cr components)
for (const comp of coefficients.components) {
console.log(Component ${comp.id}: ${comp.blocks.length} block rows);
}
}
`

$3

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("input.jpg");
const coefficients = await Image.extractCoefficients(data, "jpeg");

if (coefficients) {
// Modify coefficients (e.g., for steganography)
for (const comp of coefficients.components) {
for (const row of comp.blocks) {
for (const block of row) {
// Modify AC coefficients (indices 1-63)
// DC coefficient is at index 0
// block is an Int32Array of 64 quantized DCT values in zigzag order
}
}
}

// Re-encode to JPEG
const encoded = await Image.encodeFromCoefficients(coefficients, "jpeg");
await Deno.writeFile("output.jpg", encoded);
}
`

$3

The JPEGQuantizedCoefficients type provides:

- width, height - Image dimensions
- isProgressive - Whether the source was progressive JPEG
- components - Array of Y, Cb, Cr (or grayscale) component data
- quantizationTables - The quantization tables used
- mcuWidth, mcuHeight - MCU block dimensions

Each component contains blocks[][] where each block is an Int32Array of 64 quantized DCT
coefficients in zigzag order.

Use Cases:

- DCT-domain steganography (survives JPEG re-compression)
- Coefficient analysis and visualization
- Custom frequency-domain filtering
- Forensic analysis of JPEG compression artifacts

Base64 / Data URLs

The library includes small utilities for working with base64 and data: URLs.

`ts
import { Image, parseDataUrl, toDataUrl } from "jsr:@cross/image";

const image = Image.create(2, 2, 255, 0, 0);
const pngBytes = await image.encode("png");

const dataUrl = toDataUrl("image/png", pngBytes);
const parsed = parseDataUrl(dataUrl);

// parsed.bytes is a Uint8Array containing the PNG
const roundtrip = await Image.decode(parsed.bytes, "png");
console.log(roundtrip.width, roundtrip.height);
`

(ImageDecoder API) first, falling back to the pure JS decoder with tolerant mode for maximum
compatibility.

Fault-Tolerant Decoding for Other Formats

In addition to JPEG, @cross/image provides fault-tolerant decoding for several other formats that
commonly encounter corruption or complex encoding patterns:

$3

The GIF decoder supports frame-level tolerance for animated GIFs. When enabled (default), corrupted
frames are skipped instead of causing complete decode failure.

Features:

- Enabled by default - Handles multi-frame GIFs with some corrupted frames
- Frame-level recovery - Skips bad frames, preserves good ones
- LZW decompression errors - Continues past compression errors

Example:

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("animated.gif");

// Tolerant mode (default) - skips corrupted frames
const tolerantFrames = await Image.decodeFrames(data);

// Strict mode - throws on first corrupted frame
const strictFrames = await Image.decodeFrames(data, {
tolerantDecoding: false,
});

// Optional: receive warnings when frames are skipped
const framesWithWarnings = await Image.decodeFrames(data, {
tolerantDecoding: true,
runtimeDecoding: "never",
onWarning: (message, details) => {
console.log(GIF Warning: ${message}, details);
},
});
`

$3

The WebP VP8L (lossless) decoder supports pixel-level tolerance. When enabled (default), decoding
errors result in gray pixels for remaining data instead of complete failure.

Features:

- Enabled by default - Handles VP8L images with Huffman/LZ77 errors
- Pixel-level recovery - Fills remaining pixels with neutral gray
- Huffman decode errors - Continues past invalid codes

Example:

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("image.webp");

// Tolerant mode (default) - fills bad pixels with gray
const tolerantImage = await Image.decode(data);

// Strict mode - throws on first decode error
const strictImage = await Image.decode(data, { tolerantDecoding: false });

// Optional: receive warnings during partial decode
const imageWithWarnings = await Image.decode(data, {
tolerantDecoding: true,
runtimeDecoding: "never",
onWarning: (message, details) => {
console.log(WebP Warning: ${message}, details);
},
});
void imageWithWarnings;
`

$3

Use tolerant decoding (default) when:

- Processing user-uploaded images from various sources
- Building production applications requiring maximum compatibility
- Handling images from mobile devices or cameras
- Recovering data from partially corrupted files
- Batch processing where some failures are acceptable

Use strict decoding when:

- Validating image file integrity
- Quality control in professional workflows
- Detecting file corruption explicitly
- Testing image encoder implementations

$3

Decoding APIs accept an optional onWarning callback that gets invoked when non-fatal issues occur
during decoding. This is useful for logging, monitoring, or debugging decoding issues without using
console methods.

Example:

`typescript
import { Image } from "jsr:@cross/image";

const data = await Deno.readFile("input.webp");

const image = await Image.decode(data, {
tolerantDecoding: true,
runtimeDecoding: "never",
onWarning: (message, details) => {
// Log to your preferred logging system
myLogger.warn(message, details);
},
});
void image;
`

The callback receives:

- message: A human-readable description of the warning
- details: Optional additional context (usually the error object)

Metadata Support

@cross/image provides comprehensive EXIF 3.0 compliant metadata support for image files, including
camera information, GPS coordinates, and InteropIFD compatibility markers.

$3

Basic Metadata:

- title, description, author, copyright
- creationDate - Date/time image was created

Camera Settings (JPEG, TIFF, WebP via XMP):

- cameraMake, cameraModel - Camera manufacturer and model
- lensMake, lensModel - Lens information
- iso - ISO speed rating
- exposureTime - Shutter speed in seconds
- fNumber - Aperture (f-number)
- focalLength - Focal length in mm
- flash, whiteBalance - Capture settings
- orientation - Image orientation (1=normal, 3=180°, 6=90°CW, 8=90°CCW)
- software - Software used
- userComment - User notes

GPS Coordinates (All EXIF formats: JPEG, PNG, WebP, TIFF):

- latitude, longitude - GPS coordinates in decimal degrees
- Full microsecond precision with DMS (degrees-minutes-seconds) conversion

DPI (JPEG, PNG, TIFF):

- dpiX, dpiY - Dots per inch for printing

$3

The library implements the EXIF 3.0 specification with:

- 50+ Exif Sub-IFD tags for comprehensive camera metadata
- 30+ IFD0 tags for image information
- InteropIFD support for format compatibility (R98/sRGB, R03/Adobe RGB, THM/thumbnail)
- GPS IFD with proper coordinate conversion
- All EXIF data types (BYTE, ASCII, SHORT, LONG, RATIONAL, etc.)

$3

`typescript
import { Image } from "jsr:@cross/image";

// Load an image
const data = await Deno.readFile("photo.jpg");
const image = await Image.decode(data);

// Set metadata
image.setMetadata({
author: "Jane Photographer",
copyright: "© 2024",
cameraMake: "Canon",
cameraModel: "EOS R5",
iso: 800,
exposureTime: 0.004, // 1/250s
fNumber: 2.8,
focalLength: 50,
});

// Set GPS coordinates
image.setPosition(40.7128, -74.0060); // NYC

// Check what metadata a format supports
const jpegSupports = Image.getSupportedMetadata("jpeg");
console.log(jpegSupports); // Includes ISO, camera info, GPS, etc.

// Save with metadata
const jpeg = await image.encode("jpeg");
await Deno.writeFile("output.jpg", jpeg);

// Metadata is preserved on reload!
const loaded = await Image.decode(jpeg);
console.log(loaded.metadata?.cameraMake); // "Canon"
console.log(loaded.getPosition()); // { latitude: 40.7128, longitude: -74.0060 }
`

$3

For quickly reading metadata from images without the overhead of decoding pixel data, use
Image.extractMetadata(). This is particularly useful for:

- Reading EXIF data from large images or photos
- Extracting metadata from images with unsupported compression
- Building image catalogs or galleries
- Processing metadata in batch operations

`typescript
import { Image } from "jsr:@cross/image";

// Extract metadata without decoding pixels
const data = await Deno.readFile("large-photo.jpg");
const metadata = await Image.extractMetadata(data);

console.log(metadata?.cameraMake); // "Canon"
console.log(metadata?.iso); // 800
console.log(metadata?.exposureTime); // 0.004

// Works with auto-detection
const metadata2 = await Image.extractMetadata(data); // Detects JPEG

// Or specify format explicitly
const metadata3 = await Image.extractMetadata(data, "jpeg");
`

This method is significantly faster than full decode when you only need metadata, as it:

- Skips pixel data decompression
- Only parses metadata chunks/markers
- Returns undefined for unsupported formats
- Works with JPEG, PNG, WebP, TIFF, HEIC, and AVIF formats

$3

Use Image.getSupportedMetadata(format) to check which fields are supported:

`typescript
Image.getSupportedMetadata("jpeg"); // Full camera metadata + GPS (21 fields)
Image.getSupportedMetadata("tiff"); // Comprehensive EXIF + GPS + InteropIFD (23+ fields)
Image.getSupportedMetadata("png"); // DateTime, GPS, DPI, basic text (9 fields)
Image.getSupportedMetadata("webp"); // Enhanced XMP + GPS (15 fields - includes camera metadata!)
Image.getSupportedMetadata("heic"); // Full camera metadata + GPS (19 fields)
Image.getSupportedMetadata("avif"); // Full camera metadata + GPS (19 fields)
`

Format Highlights:

- JPEG: Most comprehensive EXIF support, including all camera settings and GPS
- TIFF: Full EXIF 3.0 support with IFD structure, InteropIFD compatibility
- WebP: Enhanced XMP implementation with Dublin Core, EXIF, and TIFF namespaces
- PNG: Basic EXIF support via eXIf chunk plus GPS coordinates
- HEIC: Full EXIF metadata extraction including camera settings, GPS, and image info
(runtime-dependent encoding)
- AVIF: Full EXIF metadata extraction including camera settings, GPS, and image info
(runtime-dependent encoding)

Documentation

- API Reference - Complete API documentation
- Format Support - Supported formats and specifications
- Image Processing - Filters, manipulation, and
color adjustments
- Filters - Blur, sharpen, and noise reduction
- Manipulation - Resize, crop, composite,
and draw
- Color Adjustments - Brightness,
contrast, saturation, and more
- Examples - Practical examples for common tasks
- Decoding & Encoding -
Format-specific examples
- Using Filters - Filter workflows and
techniques
- Manipulation - Resizing, cropping, and
compositing
- Multi-Frame Images - Animated GIFs, APNGs,
and TIFFs
- JPEG Implementation -
Technical details for JPEG
- WebP Implementation -
Technical details for WebP
- TIFF Implementation -
Technical details for TIFF
- GIF Implementation -
Technical details for GIF

Development

`bash
deno task precommit
``

CI validates cross-runtime compatibility (Deno, Bun, Node). See CONTRIBUTING.md for contributor
workflow details.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.