Crate pixo

Crate pixo 

Source
Expand description

§pixo

A minimal-dependency, high-performance image compression library with PNG and JPEG encoders written entirely in Rust.

  • PNG: All filter types, DEFLATE compressor, palette quantization, buffer reuse helpers, and presets from fast to max compression.
  • JPEG: Baseline & progressive encoding, optimized Huffman tables, trellis quantization, and buffer reuse helpers.
  • Performance: Optional SIMD and parallel fast paths, tuned defaults, optimal DEFLATE for final packing, and small WASM output.
  • Docs-first: Conceptual guides (PNG, JPEG, DEFLATE, DCT, quantization, performance) are embedded directly in rustdoc under guides.

§Quickstart

use pixo::{png, jpeg, ColorType};
use pixo::png::PngOptions;
use pixo::jpeg::JpegOptions;

// PNG: 3x1 RGB pixels (red, green, blue)
let png_pixels = vec![255, 0, 0, 0, 255, 0, 0, 0, 255];
let png_opts = PngOptions::builder(3, 1).color_type(ColorType::Rgb).build();
let png_bytes = png::encode(&png_pixels, &png_opts)?;
assert!(!png_bytes.is_empty());

// JPEG: 1x1 RGB pixel
let jpg_pixels = vec![255, 0, 0];
let jpg_opts = JpegOptions::builder(1, 1).color_type(ColorType::Rgb).quality(85).build();
let jpg_bytes = jpeg::encode(&jpg_pixels, &jpg_opts)?;
assert!(!jpg_bytes.is_empty());

§Custom options (PNG)

use pixo::png::{encode, FilterStrategy, PngOptions};
use pixo::ColorType;

let pixels = vec![255, 0, 0, 0, 255, 0, 0, 0, 255];
let options = PngOptions::builder(3, 1)
    .color_type(ColorType::Rgb)
    .preset(1) // balanced: compression level 6, adaptive filters + lossless opts
    .filter_strategy(FilterStrategy::Adaptive)
    .optimize_alpha(true)
    .build();
let png_bytes = encode(&pixels, &options)?;
assert!(!png_bytes.is_empty());

§Custom options (JPEG)

use pixo::jpeg::{encode, JpegOptions};
use pixo::ColorType;

let pixels = vec![255, 0, 0];
let options = JpegOptions::max(1, 1, 85); // progressive + trellis + optimized Huffman
let jpg_bytes = encode(&pixels, &options)?;
assert!(!jpg_bytes.is_empty());

§Image resizing

use pixo::{resize, ColorType, ResizeAlgorithm, ResizeOptions};

// 4x4 RGBA image -> 2x2 using Lanczos3 (highest quality)
let pixels = vec![128u8; 4 * 4 * 4];
let options = ResizeOptions::builder(4, 4)
    .dst(2, 2)
    .color_type(ColorType::Rgba)
    .algorithm(ResizeAlgorithm::Lanczos3)
    .build();
let resized = resize::resize(&pixels, &options)?;
assert_eq!(resized.len(), 2 * 2 * 4);

§Buffer reuse

use pixo::{jpeg, png, ColorType};
use pixo::png::PngOptions;
use pixo::jpeg::JpegOptions;

let pixels = vec![255, 0, 0, 0, 255, 0]; // 2 RGB pixels

let mut png_buf = Vec::new();
let png_opts = PngOptions::builder(2, 1).color_type(ColorType::Rgb).build();
png::encode_into(&mut png_buf, &pixels, &png_opts)?;

let mut jpg_buf = Vec::new();
let jpg_opts = JpegOptions::balanced(2, 1, 85);
jpeg::encode_into(&mut jpg_buf, &pixels, &jpg_opts)?;

assert!(!png_buf.is_empty() && !jpg_buf.is_empty());

§Feature flags

  • simd (default): Enable SIMD-accelerated kernels with runtime detection.
  • parallel (default): Parallel row-level filtering in PNG via rayon.
  • wasm: WebAssembly bindings (see guides::wasm).
  • cli: Command-line encoder (see guides::cli).

§Guides inside rustdoc

§When to use which format

  • PNG: sharp UI, screenshots, graphics; lossless and optionally palette-quantized.
  • JPEG: photographs and gradients; choose quality + subsampling to trade size for fidelity.

§Safety and performance notes

  • Unsafe is only compiled when simd or wasm is enabled; otherwise forbid(unsafe_code) is applied.
  • Prefer encode_into variants when encoding repeatedly to reuse allocations.
  • For smallest PNGs, use PngOptions::max(w, h) (slow) or enable auto quantization for lossy palette outputs.
  • For smallest JPEGs, use JpegOptions::max(w, h, quality) which enables optimized Huffman, progressive scans, and trellis quantization.

Re-exports§

pub use color::ColorType;
pub use error::Error;
pub use error::Result;
pub use resize::ResizeAlgorithm;
pub use resize::ResizeOptions;

Modules§

bits
Bit-level I/O utilities for binary encoding.
color
Color type definitions and conversions.
compress
Compression algorithms.
decodecli
Image decoders for PNG and JPEG formats.
error
Error types for the pixo library.
guides
High-level and conceptual guides rendered inside rustdoc.
jpeg
JPEG encoder implementation.
png
PNG encoder implementation.
resize
Image resizing algorithms.
simdsimd
SIMD acceleration module for performance-critical operations.
wasmwasm
WebAssembly bindings for pixo.