mozjpeg-rs

Pure Rust JPEG encoder based on Mozilla's mozjpeg, featuring trellis quantization for optimal compression.

Encoder Only

mozjpeg-rs is a JPEG encoder only. It does not decode JPEG files.

For decoding, use one of these excellent crates:

Why mozjpeg-rs?

Choose mozjpeg-rs when you want:

• Memory-safe JPEG encoding without C dependencies
• Smaller files than libjpeg-turbo (trellis quantization)
• Simple integration via Cargo

Choose C mozjpeg when you need:

• Maximum baseline encoding speed (SIMD-optimized entropy coding)
• Established C ABI for FFI
• Arithmetic coding (rarely used)

Compression Results vs C mozjpeg

Tested on CID22 corpus (209 images, 512x512), 4:2:0 subsampling, fast-yuv enabled. Six encoder configurations across four quality levels. Positive delta = Rust files are larger; negative = Rust files are smaller.

Reproduce with: cargo test --release --test parity_benchmark -- --nocapture

Configs: Baseline = huffman opt only. +Trellis = AC trellis. Full = AC trellis + DC trellis + deringing. Max Compression = Full + optimize_scans: true. All others use optimize_scans: false. All use force_baseline: true.

Key findings:

• With trellis at Q75, Rust produces smaller files than C (-0.15% to -0.24%)
• Without trellis, the consistent +0.21% gap comes from fast-yuv color conversion (±1 level rounding)
• Without optimize_scans, all configs stay within ±0.25% average, worst-case per-image deviation under 1%
• With optimize_scans (Max Compression), within ±0.4% average — different scan search heuristics find different local optima
• Visual quality (SSIMULACRA2, Butteraugli) is equivalent at all settings

Usage

use mozjpeg_rs::{Encoder, Subsampling};

// Default: trellis quantization + Huffman optimization
let jpeg = Encoder::new()
    .quality(85)
    .encode_rgb(&pixels, width, height)?;

// Maximum compression: progressive + trellis + deringing
let jpeg = Encoder::max_compression()
    .quality(85)
    .encode_rgb(&pixels, width, height)?;

// Fastest: no optimizations (libjpeg-turbo compatible output)
let jpeg = Encoder::fastest()
    .quality(85)
    .encode_rgb(&pixels, width, height)?;

// Custom configuration
let jpeg = Encoder::new()
    .quality(75)
    .progressive(true)
    .subsampling(Subsampling::S420)
    .optimize_huffman(true)
    .encode_rgb(&pixels, width, height)?;

Features

• Trellis quantization - Rate-distortion optimized coefficient selection (AC + DC)
• Progressive JPEG - Multi-scan encoding with spectral selection
• Huffman optimization - 2-pass encoding for optimal entropy coding
• Overshoot deringing - Reduces ringing artifacts at sharp edges
• Chroma subsampling - 4:4:4, 4:2:2, 4:2:0 modes
• Safe Rust - #![deny(unsafe_code)] with exceptions only for SIMD intrinsics

Encoder Settings Matrix

All combinations of settings are supported and tested:

Presets:

• Encoder::new() - Trellis (AC+DC) + Huffman optimization + Deringing
• Encoder::max_compression() - Above + Progressive + optimize_scans
• Encoder::fastest() - No optimizations (libjpeg-turbo compatible)

Quantization Tables

use mozjpeg_rs::{Encoder, QuantTableIdx};

let jpeg = Encoder::new()
    .qtable(QuantTableIdx::Robidoux)  // or .quant_tables()
    .encode_rgb(&pixels, width, height)?;

Method Aliases

For CLI-style naming (compatible with rimage conventions):

Performance

Benchmarked on 512x768 image, 20 iterations, release mode:

Note: C mozjpeg's baseline encoding is typically faster with its hand-optimized SIMD entropy coding. The benchmark numbers above reflect mozjpeg-sys from crates.io which may not have all optimizations enabled.

SIMD Support

mozjpeg-rs uses multiversion for automatic vectorization by default. Optional hand-written SIMD intrinsics are available:

[dependencies]
mozjpeg-rs = { version = "0.2", features = ["simd-intrinsics"] }

In benchmarks, the difference is minimal (~2%) as multiversion autovectorization works well for DCT and color conversion.

Differences from C mozjpeg

mozjpeg-rs aims for compatibility with C mozjpeg but has some differences:

Why multipass (use_scans_in_trellis) is not implemented

C mozjpeg's multipass option makes trellis quantization "scan-aware" for progressive encoding by optimizing low and high frequency AC coefficients separately. Benchmarks on the test corpus (Q85, progressive) show this is a poor tradeoff:

Multipass produces larger files, is slower, and provides no perceptible quality improvement.

Where does the remaining gap come from?

The consistent +0.21% gap in non-trellis modes comes from the fast-yuv feature, which uses the yuv crate for SIMD color conversion (AVX-512/AVX2/SSE/NEON). It has ±1 level rounding differences vs C mozjpeg's color conversion, producing slightly different DCT coefficients. This is invisible after JPEG quantization. Without fast-yuv, Rust matches or beats C at all quality levels.

With trellis enabled, Rust's trellis optimizer finds slightly better rate-distortion tradeoffs at Q75, producing smaller files than C.

Matching C mozjpeg output exactly

For near byte-identical output to C mozjpeg, use baseline mode with matching settings:

1. Use baseline (non-progressive) mode with Huffman optimization
2. Match all encoder settings via TestEncoderConfig
3. Use the same quantization tables (Robidoux/ImageMagick, the default for both)

The FFI comparison tests in tests/ffi_comparison.rs verify component-level parity.

Development

Running CI Locally

# Format check
cargo fmt --all -- --check

# Clippy lints
cargo clippy --workspace --all-targets -- -D warnings

# Build
cargo build --workspace

# Unit tests
cargo test --lib

# Codec comparison tests
cargo test --test codec_comparison

# FFI validation tests (requires mozjpeg-sys from crates.io)
cargo test --test ffi_validation

Reproduce Benchmarks

# Fetch test corpus (CID22 images)
./scripts/fetch-corpus.sh

# Run full corpus comparison
cargo run --release --example full_corpus_test

# Run pareto benchmark
cargo run --release --example pareto_benchmark

Test Coverage

# Install cargo-llvm-cov
cargo install cargo-llvm-cov

# Generate coverage report
cargo llvm-cov --lib --html

# Open report
open target/llvm-cov/html/index.html

License

BSD-3-Clause - Same license as the original mozjpeg.

Acknowledgments

Based on Mozilla's mozjpeg, which builds on libjpeg-turbo and the Independent JPEG Group's libjpeg.

AI-Generated Code Notice

This crate was developed with significant assistance from Claude (Anthropic). While the code has been tested against the C mozjpeg reference implementation and passes 248 tests including FFI validation, not all code has been manually reviewed or human-audited.

Before using in production:

• Review critical code paths for your use case
• Run your own validation against expected outputs
• Consider the encoder's test suite coverage for your specific requirements

The FFI comparison tests in tests/ffi_comparison.rs and tests/ffi_validation.rs provide confidence in correctness by comparing outputs against C mozjpeg.