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
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();

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