zencodec

zencodec is the shared trait crate that defines the common API for all zen* image codecs.

zencodec contains no pixel encoding or decoding logic — that lives in the individual codec crates. It does include shared metadata parsing needed for nearly every image format: pixel-descriptor derivation from CICP/ICC metadata (with identification delegated to zenpixels::icc, covering 163 RGB + 18 grayscale web-corpus profiles), EXIF orientation extraction, ISO 21496-1 gain map parsing and serialization, and format detection via magic bytes. no_std compatible (requires alloc), forbid(unsafe_code).

Import as zencodec — use zencodec::encode, zencodec::decode, etc.

Crates in the zen* family

Architecture

Every codec follows a three-layer pattern:

Config     →  reusable, Clone + Send + Sync, 'static — consumed by job()
Job        →  per-operation, owns config + stop token + limits + metadata
Executor   →  borrows pixel data or file bytes, consumes self to produce output

ENCODE:  EncoderConfig → EncodeJob → Encoder / AnimationFrameEncoder
DECODE:  DecoderConfig → DecodeJob<'a> → Decode / StreamingDecode / AnimationFrameDecoder

Config lives in a struct and gets shared across threads. A web server keeps one JpegEncoderConfig at quality 85 for all requests and clones it per-request. Calling job() consumes the config — clone first if you need it again. Job owns its config, cancellation token, resource limits, and metadata. Executor borrows pixels or bytes and consumes itself to produce output.

Each layer also has object-safe Dyn* variants for codec-agnostic dispatch:

DynEncoderConfig → DynEncodeJob → DynEncoder / DynAnimationFrameEncoder
DynDecoderConfig → DynDecodeJob → DynDecoder / DynStreamingDecoder / DynAnimationFrameDecoder

Blanket impls generate the dyn API automatically — codec authors implement the generic traits and get dyn dispatch for free.

Quick Example

use std::borrow::Cow;
use zenjpeg::{JpegEncoderConfig, JpegDecoderConfig};
use zencodec::encode::{EncoderConfig, EncodeJob, Encoder};
use zencodec::decode::{DecoderConfig, DecodeJob, Decode};

// Encode. `with_generic_quality` is the codec-agnostic knob on a calibrated
// 0.0..=100.0 scale (NOT 0.0..=1.0); higher is better. Read it back with
// `generic_quality()` — `None` means the codec has no quality dial.
let config = JpegEncoderConfig::new().with_generic_quality(85.0);
// (assuming pixels: PixelSlice from your pipeline)
let output = config.job().encoder()?.encode(pixels.as_slice())?;
let jpeg_bytes = output.into_vec();

// Decode
let config = JpegDecoderConfig::new();
let decoded = config.job().decoder(Cow::Borrowed(&jpeg_bytes), &[])?.decode()?;
let pixels = decoded.into_buffer();

Untrusted input: limits, cancellation, errors

Two server-critical knobs — ResourceLimits and a cancellation StopToken — are attached to the job, not the config: DecodeJob/EncodeJob expose .with_limits(limits) and .with_stop(token) (both consume-and-return-self builders), so the per-request job carries them while the shared config stays immutable. Everything below is on the root: use zencodec::{ResourceLimits, StopToken};.

Constructing ResourceLimits

ResourceLimits is a plain struct with pub Option<_> fields — build it three ways:

use zencodec::ResourceLimits;

// 1. Server preset. `for_untrusted_input()` fills generous-but-bounded caps:
//    max_pixels 120 MP/frame, max_total_pixels 200 MP (all frames),
//    max_width/max_height 16384 each, max_memory_bytes 1 GiB,
//    max_input_bytes 256 MiB, max_frames 65 536, max_animation_ms 1 hour.
//    (`Default`/`none()` is the OPPOSITE — every field `None`, i.e. UNLIMITED;
//    use that only for trusted input.) Tighten any field with a `with_*` builder:
let limits = ResourceLimits::for_untrusted_input()
    .with_max_pixels(4_000_000)          // 4 MP cap for a thumbnail service
    .with_max_memory(256 * 1024 * 1024); // 256 MiB

// 2. From scratch off the unlimited default, set only what you need:
let limits = ResourceLimits::none()
    .with_max_pixels(16_000_000)         // pixels = width × height (per frame)
    .with_max_input_bytes(8 * 1024 * 1024); // bytes of encoded input (decode)

// 3. Direct field set (every field is public):
let mut limits = ResourceLimits::default();
limits.max_width = Some(8192);           // pixels
limits.max_height = Some(8192);          // pixels

Units: max_pixels / max_total_pixels are pixel counts (width × height, the latter ×frame_count); max_width / max_height are pixels; max_memory_bytes, max_input_bytes, max_output_bytes are bytes; max_frames a count; max_animation_ms milliseconds. A None field means that dimension is unchecked.

ResourceLimits also carries an allocation-fallibility preference, prefer_fallible_allocations (an AllocPreference: CodecDefault / Fallible / Infallible). CodecDefault (the default) lets each codec choose — decoders favour the fallible try_reserve path on untrusted input, encoders the faster infallible vec!; for_untrusted_input() presets Fallible. Override with .with_prefer_fallible_allocations(AllocPreference::Fallible).

Constructing a cancellation StopToken

StopToken is re-exported from the almost-enough crate (cargo add almost-enough). Make a Stopper (cheap, Clone, 8 bytes), erase it into a StopToken, hold a clone of the Stopper to fire later from any thread:

use zencodec::StopToken;

let stopper = almost_enough::Stopper::new();
let token = StopToken::new(stopper.clone()); // or: stopper.clone().into()

// Fire from a deadline / client-disconnect watcher — `cancel()` signals every clone:
std::thread::spawn({
    let stopper = stopper.clone();
    move || { /* on timeout or disconnect: */ stopper.cancel(); }
});
// (For a no-op token when you don't need cancellation, use `zencodec::Unstoppable`.)

End-to-end: decode untrusted bytes with a limit + a stop token

.with_limits() and .with_stop() chain onto the job before you ask for the decoder. probe() (also on the job) is an O(header) parse — validate against the limits before the codec allocates pixels, then attach both to the real decode:

use std::borrow::Cow;
use zencodec::{ResourceLimits, StopToken, CodecErrorExt};
use zencodec::decode::{DecoderConfig, DecodeJob, Decode};

let limits = ResourceLimits::for_untrusted_input().with_max_memory(256 * 1024 * 1024);
let stopper = almost_enough::Stopper::new();
let token = StopToken::new(stopper.clone());

// 1. Probe the header and reject oversized inputs before any pixel allocation.
let info = config.clone().job().probe(bytes)?;
limits.check_image_info(&info)?; // -> Err(LimitExceeded) if too big

// 2. Attach BOTH to the job, then decode. Order is free; `decoder()` consumes the job.
let decoded = config.job()
    .with_limits(limits)
    .with_stop(token)
    .decoder(Cow::Borrowed(bytes), &[])? // &[] = native pixel format
    .decode()?;
let pixels = decoded.into_buffer();

.with_stop() is honored only by codecs whose DecodeCapabilities::stop() is true; on others it is a silent no-op (the decode still completes correctly, just not interruptibly). check_image_info only sees what the header reports — keep the max_memory_bytes cap so a codec that under-reports still can't over-allocate.

Classifying a codec's error for an HTTP response

Each codec keeps its OWN opaque error type (there is no shared CodecError). Classify one without naming the concrete enum, via CodecErrorExt:

match config.job().decoder(Cow::Borrowed(bytes), &[]) {
    Ok(_decoder) => { /* _decoder.decode()? */ }
    Err(e) => {
        if let Some(limit) = e.limit_exceeded() {
            eprintln!("resource limit: {limit}"); // -> HTTP 413
        } else if e.unsupported_operation().is_some() {
            eprintln!("unsupported"); // -> HTTP 415
        } else {
            eprintln!("malformed input: {e}"); // -> HTTP 400
        }
    }
}

Key Design Decisions

Color management is not the codec's job. Decoders return native pixels with ICC/CICP metadata. Encoders accept pixels as-is and embed the provided metadata. The caller handles CMS transforms.

Format negotiation over conversion. Decoders take a ranked &[PixelDescriptor] preference list and pick the first they can produce without lossy conversion. Pass &[] for native format.

Capabilities over try/catch. Codecs declare their capabilities as const EncodeCapabilities / DecodeCapabilities structs. Check before calling instead of catching UnsupportedOperation errors.

Pixel types from zenpixels. All pixel interchange types (PixelSlice, PixelBuffer, PixelDescriptor, etc.) are defined in the zenpixels crate. All zen* crates depend on zenpixels directly.

Metadata Retention

Re-encode and recompress pipelines need to decide what metadata survives. Metadata::filtered applies a MetadataPolicy, so callers never hand-parse EXIF:

use zencodec::{MetadataPolicy, MetadataFields, IccRetention, exif::{ExifPolicy, Retention}};

// Decode → filter → re-encode. `Web` (recommended for publishing) keeps the ICC profile
// (unless a redundant sRGB), EXIF orientation + rights, and CICP/HDR color
// signaling — and strips GPS, timestamps, camera info, thumbnail, and XMP.
let kept = decoded_meta.filtered(&MetadataPolicy::Web);

// Presets: PreserveExact (keep all, incl. duplicate sRGB), Preserve (drop dup
// sRGB), Web, ColorAndRotation (only what places pixels), Custom.
let minimal = decoded_meta.filtered(&MetadataPolicy::ColorAndRotation);

// Per-field control — drop only the thumbnail, keep everything else:
let policy = MetadataPolicy::Custom(
    MetadataFields::KEEP_ALL.with_exif(ExifPolicy::KEEP_ALL.with_thumbnail(Retention::Discard)),
);
let no_thumb = decoded_meta.filtered(&policy);

MetadataFields encapsulates EXIF in an ExifPolicy with seven keep/discard categories — orientation, rights, thumbnail, gps, datetimes, camera, other — and three-way ICC handling (IccRetention::{Drop, KeepNonSrgb, Keep}). EXIF passes through byte-unchanged (zero-copy) when no category is dropped, and is rewritten — offsets recomputed — only when pruning. CICP/HDR are color signaling (dropping them changes displayed pixels), so the presets keep them; a Custom policy can drop them. The structured parser/editor is public as zencodec::exif::Exif (parse → filtered/edit → to_bytes) for direct EXIF work — including setting Copyright/Artist (set_copyright / set_artist, with a TextEncoding choice of Exif 2.x ASCII or Exif 3.0 UTF-8) and Orientation (set_orientation, insert-or-replace).

Privacy is an explicit choice — enforced at compile time. Retention is a transient decision made when you hand metadata to the encoder, not a field stored on Metadata. The blessed path is job.with_metadata_policy(meta, MetadataPolicy::Web) (privacy-safe: strips camera/GPS, keeps orientation + rights) or PreserveExact (verbatim). The old unguarded with_metadata(meta) still works but is #[deprecated] — the compiler warns at every call site that picks no policy, so you can't propagate metadata without choosing retention by accident. It's a compile-time nudge, not a semver break: existing code keeps compiling, but the warning points you at the safe call. The filter runs before the codec sees the record, so a codec only ever receives exactly what the policy kept. The carried bytes stay untouched until then, so you can still pull metadata.exif out, edit it with any EXIF library, and put it back via with_exif.

To stamp rights in one line — Metadata::none().with_copyright("© 2026 You") builds (or merges into) the EXIF blob (ASCII); or build it directly with Exif::new(TextEncoding::Ascii).set_copyright(…) → to_bytes() — Exif::new requires the Exif 2.x-vs-3.0 field-type choice (type 129 is read by almost nothing, so it's never a silent default).

Metadata retention, color emission, and orientation are the three correctness signals an encode has to get right; docs/correctness-model.md describes how the framework resolves each one before the codec runs so a codec can't quietly clobber it. The zencodec-testkit crate verifies a codec honors that contract — check_metadata_no_leak re-parses the embedded EXIF to prove a policy's drops actually happened, and check_cross_path_pixel_equivalence diffs every feeding mode.

Color Emission

The encode-side dual of color resolution: which color carriers (ICC vs CICP) should an encode write? resolve_color_emit decides — a pure, no_std, CMS-free function of the source color, the target's carrier capabilities, and a policy:

use zencodec::{resolve_color_emit, ColorEmitPolicy, IccDisposition};

let plan = resolve_color_emit(&source_color, &target_caps, ColorEmitPolicy::Balanced);
// plan.cicp: Option<Cicp>   — write this CICP (JXL/AVIF/HEIC nclx, PNG cICP) if the format carries it
// plan.icc:  IccDisposition — KeepSource | SynthesizeFrom(Cicp) | Drop

ColorEmitPolicy picks the tradeoff: Compatibility (widest reader support), Balanced (default — CICP where it's a spec-mandated safe sole carrier, an ICC companion otherwise), Compact (smallest — prefer CICP, drop the ICC), Verbatim (carry the source's signals unchanged), or Custom(ColorEmitFields). A target advertises its carriers via EncodeCapabilities::{cicp_is_valid_carrier, cicp_safe_sole_carrier}. The plan never emits a redundant SynthesizeFrom(sRGB); a codec lowers a SynthesizeFrom through zenpixels-convert's transfer-aware synthesize_icc_for_cicp (a bundled const profile, or — with its cms-moxcms feature — a generated one) so an HDR transfer is never mis-tagged with an SDR profile and color is never silently dropped. The names carry the emit direction so they can't be confused with the decode-side SourceColor. Design + rejected alternatives: docs/color-emit-model.md.

What's in this crate

zencodec has no feature flags. The full API is always available.

Limitations

• Contains no codec logic — traits, types, and format detection only.
• ImageFormat enum is not extensible at runtime (the Custom variant requires a &'static definition).
• Always no_std + alloc (no std feature gate).

MSRV

Rust 1.88+, 2024 edition.

Image tech I maintain

* as of 2026

General Rust awesomeness

archmage · magetypes · enough · whereat · zenbench · cargo-copter

And other projects · GitHub @imazen · GitHub @lilith · lib.rs/~lilith · NuGet (over 30 million downloads / 87 packages)

License

Apache-2.0 OR MIT