Crate zenbitmaps 

zenbitmaps

PNM/PAM/PFM, BMP, and farbfeld image format decoder and encoder.

Reference bitmap formats for codec testing and apples-to-apples comparisons. no_std compatible (with alloc), forbid(unsafe_code), panic-free.

Quick Start

use zenbitmaps::*;
use enough::Unstoppable;

// Encode pixels to PPM
let pixels = vec![255u8, 0, 0, 0, 255, 0]; // 2 RGB pixels
let encoded = encode_ppm(&pixels, 2, 1, PixelLayout::Rgb8, Unstoppable)?;

// Decode (auto-detects PNM/BMP/farbfeld from magic bytes)
let decoded = decode(&encoded, Unstoppable)?;
assert!(decoded.is_borrowed()); // zero-copy for PPM with maxval=255
assert_eq!(decoded.pixels(), &pixels[..]);

Format Detection

detect_format() identifies the format from magic bytes without decoding:

match detect_format(&data) {
    Some(ImageFormat::Pnm) => { /* PGM, PPM, PAM, or PFM */ }
    Some(ImageFormat::Bmp) => { /* Windows bitmap */ }
    Some(ImageFormat::Farbfeld) => { /* farbfeld RGBA16 */ }
    None => { /* unknown format */ }
    _ => { /* future formats */ }
}

decode() uses this internally — you only need detect_format() if you want to inspect the format before committing to a full decode.

Zero-Copy Decoding

For PNM files with maxval=255 (the common case), decoding returns a borrowed slice into the input buffer — no allocation or copy needed. Formats that require transformation (BMP row flip, farbfeld endian swap, etc.) allocate.

Use DecodeOutput::as_pixels() for a zero-copy typed pixel view, or DecodeOutput::as_imgref() for a zero-copy 2D view (with imgref feature):

let decoded = decode(&data, Unstoppable)?;
// Zero-copy reinterpret as typed pixels
let pixels: &[RGB8] = decoded.as_pixels()?;
// Zero-copy 2D view (no allocation)
let img: imgref::ImgRef<'_, RGB8> = decoded.as_imgref()?;

BGRA Pipeline

BMP files store pixels in BGR/BGRA order. Use decode_bmp_native() to skip the BGR→RGB swizzle and work in native byte order:

// Requires `bmp` feature
use zenbitmaps::*;
use enough::Unstoppable;
let decoded = decode_bmp_native(bmp_data, Unstoppable)?;
// decoded.layout is Bgr8, Bgra8, or Gray8
// Encode to PAM or farbfeld — swizzle happens automatically
let pam = encode_pam(decoded.pixels(), decoded.width, decoded.height,
                     decoded.layout, Unstoppable)?;

All encoders accept BGR/BGRA input and swizzle to the target format’s channel order automatically.

Supported Formats

PNM family (always available)

• P5 (PGM binary) — grayscale, 8-bit and 16-bit
• P6 (PPM binary) — RGB, 8-bit and 16-bit
• P7 (PAM) — arbitrary channels (grayscale, RGB, RGBA), 8-bit and 16-bit
• PFM — floating-point grayscale and RGB (32-bit float per channel)

Farbfeld (always available)

• RGBA 16-bit per channel
• Auto-detected by decode() via "farbfeld" magic

BMP (bmp feature, opt-in)

• All standard bit depths: 1, 2, 4, 8, 16, 24, 32
• Compression: uncompressed, RLE4, RLE8, BITFIELDS
• Palette expansion, bottom-up/top-down, grayscale detection
• BmpPermissiveness levels: Strict, Standard, Permissive
• Auto-detected by decode() via "BM" magic

Cooperative Cancellation

Every function takes a stop parameter implementing enough::Stop. Pass Unstoppable when you don’t need cancellation. For server use, pass a token that checks a shutdown flag — decode/encode will bail out promptly via BitmapError::Cancelled.

Resource Limits

let limits = Limits {
    max_width: Some(4096),
    max_height: Some(4096),
    max_pixels: Some(16_000_000),
    max_memory_bytes: Some(64 * 1024 * 1024),
    ..Default::default()
};
let decoded = decode_with_limits(&data, &limits, Unstoppable)?;

Credits

• PNM: draws from zune-ppm by Caleb Etemesi (MIT/Apache-2.0/Zlib)
• BMP: forked from zune-bmp 0.5.2 by Caleb Etemesi (MIT/Apache-2.0/Zlib)
• Farbfeld: forked from zune-farbfeld 0.5.2 by Caleb Etemesi (MIT/Apache-2.0/Zlib)

Structs

DecodeOutput

Decoded image output. Pixels may be borrowed (zero-copy) or owned.

Limits

Resource limits for decode/encode operations.

Unstoppable

A Stop implementation that never stops (no cooperative cancellation).

Enums

BitmapError

Errors from PNM/BMP decoding and encoding.

ImageFormat

Image format detected from magic bytes.

PixelLayout

Pixel memory layout.

Traits

Stop

Cooperative cancellation check.

Functions

decode

Decode any supported format (auto-detected from magic bytes).

decode_farbfeld

Decode farbfeld data to pixels.

decode_farbfeld_with_limits

Decode farbfeld with resource limits.

decode_with_limits

Decode any supported format with resource limits.

detect_format

Detect image format from magic bytes.

encode_farbfeld

Encode pixels as farbfeld.

encode_pam

Encode pixels as PAM (P7, arbitrary channels).

encode_pfm

Encode pixels as PFM (floating-point).

encode_pgm

Encode pixels as PGM (P5, binary grayscale).

encode_ppm

Encode pixels as PPM (P6, binary RGB).