Crate zenjpeg 

zenjpeg

Pure Rust JPEG encoder and decoder with perceptual optimizations.

Provides enhanced compression quality compared to standard JPEG through adaptive quantization, optional XYB color space, and other perceptual optimizations.

Feature Requirements

Important: The decoder requires a feature flag. Add to Cargo.toml:

[dependencies]
zenjpeg = { version = "0.6", features = ["decoder"] }

Available features:

• decoder - Enable JPEG decoding (required for zenjpeg::decoder module)
• parallel - Multi-threaded encoding via rayon
• archmage-simd - Safe SIMD acceleration (default, ~10-20% faster)
• cms-lcms2 - ICC color management via lcms2 (default)
• ultrahdr - UltraHDR gain map support

See Feature Flags section below for details.

Quick Start

use zenjpeg::encoder::{EncoderConfig, ChromaSubsampling, PixelLayout, Unstoppable};

// Create reusable config (quality + color mode in constructor)
let config = EncoderConfig::ycbcr(85, ChromaSubsampling::Quarter)
    .progressive(true);

// Encode from raw bytes
let mut enc = config.encode_from_bytes(1920, 1080, PixelLayout::Rgb8Srgb)?;
enc.push_packed(&rgb_bytes, Unstoppable)?;
let jpeg = enc.finish()?;

Encoder API

All encoder types are in encoder:

use zenjpeg::encoder::{
    // Core types
    EncoderConfig,          // Builder for encoder configuration
    BytesEncoder,           // Encoder for raw byte buffers
    RgbEncoder,             // Encoder for rgb crate types
    YCbCrPlanarEncoder,     // Encoder for planar YCbCr

    // Configuration
    Quality,                // Quality settings (ApproxJpegli, ApproxMozjpeg, etc.)
    PixelLayout,            // Pixel format for raw bytes
    ChromaSubsampling,      // 4:4:4, 4:2:0, 4:2:2, 4:4:0
    ColorMode,              // YCbCr, XYB, Grayscale
    DownsamplingMethod,     // Box, GammaAware, GammaAwareIterative

    // Cancellation
    Stop,                   // Trait for cancellation tokens
    Unstoppable,            // Use when no cancellation needed

    // Results
    Error, Result,          // Error handling
};

Three Entry Points

Method	Input Type	Use Case
encoder::EncoderConfig::encode_from_bytes	&[u8]	Raw byte buffers
encoder::EncoderConfig::encode_from_rgb	rgb crate types	Type-safe pixels
encoder::EncoderConfig::encode_from_ycbcr_planar	YCbCrPlanes	Video pipelines

Configuration Options

// YCbCr mode (standard JPEG - most compatible)
let config = EncoderConfig::ycbcr(85, ChromaSubsampling::Quarter)
    .progressive(true)                        // Progressive JPEG (~3% smaller)
    .sharp_yuv(true)                          // Better color edges (~3x slower)
    .icc_profile(bytes);                      // Attach ICC profile

// XYB mode (perceptual color space - better quality)
let config = EncoderConfig::xyb(85, XybSubsampling::BQuarter)
    .progressive(true);

// Grayscale mode
let config = EncoderConfig::grayscale(85);

// Quality can also use enum variants:
let config = EncoderConfig::ycbcr(Quality::ApproxSsim2(90.0), ChromaSubsampling::None);
let config = EncoderConfig::ycbcr(Quality::ApproxButteraugli(1.0), ChromaSubsampling::Quarter);

Decoder API

The decoder is in prerelease. Enable with features = ["decoder"].

#[cfg(feature = "decoder")]
use zenjpeg::decoder::{Decoder, DecodedImage};

let image = Decoder::new().decode(&jpeg_data)?;
let pixels: &[u8] = image.pixels();

Feature Flags

Feature	Default	Description	When to Use
decoder	❌ No	JPEG decoding - Enables zenjpeg::decoder module	Required for any decode operations
std	✅ Yes	Standard library support	Disable for no_std embedded targets
archmage-simd	✅ Yes	Safe SIMD via archmage (~10-20% faster)	Keep enabled for best performance
cms-lcms2	✅ Yes	ICC color management via lcms2	XYB decoding, wide-gamut images
cms-moxcms	❌ No	Pure Rust color management (alternative to lcms2)	no_std or avoid C dependencies
parallel	❌ No	Multi-threaded encoding via rayon	Large images (4K+), server workloads
ultrahdr	❌ No	UltraHDR HDR gain map support	Encoding/decoding HDR JPEGs
trellis	✅ Yes	Trellis quantization (mozjpeg-style)	Keep enabled for best compression
yuv	✅ Yes	SharpYUV chroma downsampling	Keep enabled for quality

Common Configurations

# Decode + encode (most common)
zenjpeg = { version = "0.6", features = ["decoder"] }

# Encode only (default)
zenjpeg = "0.6"

# High-performance server
zenjpeg = { version = "0.6", features = ["decoder", "parallel"] }

# Embedded / no_std
zenjpeg = { version = "0.6", default-features = false, features = ["cms-moxcms"] }

# UltraHDR support
zenjpeg = { version = "0.6", features = ["decoder", "ultrahdr"] }

Capabilities

• Baseline JPEG: Standard 8-bit JPEG encoding
• Progressive JPEG: Multi-scan encoding (~3% smaller files)
• XYB Color Space: Perceptually optimized for better quality
• Adaptive Quantization: Content-aware bit allocation
• 16-bit / f32 Input: High bit-depth source support
• Streaming API: Memory-efficient row-by-row encoding
• Parallel Encoding: Multi-threaded for large images

Modules

decoder

Decoder module is behind a feature flag.

encoder

JPEG encoder - public API.

heuristics

Resource estimation heuristics for encoding and decoding.

profile

Lightweight text-based profiling for encoder phases.

Macros

profile_block

Profile a block and return its value.

profile_scope

Profile a scope. Zero-cost when profile feature is disabled.