Struct VarDctEncoder 

pub struct VarDctEncoder {

    pub distance: f32,
    pub optimize_codes: bool,
    pub enhanced_clustering: bool,
    pub use_ans: bool,
    pub cfl_enabled: bool,
    pub ac_strategy_enabled: bool,
    pub custom_orders: bool,
    pub force_strategy: Option<u8>,
    pub enable_noise: bool,
    pub enable_denoise: bool,
    pub enable_gaborish: bool,
    pub error_diffusion: bool,
    pub pixel_domain_loss: bool,
    pub enable_lz77: bool,
    pub lz77_method: Lz77Method,
    pub dc_tree_learning: bool,
    pub butteraugli_iters: u32,
    pub bit_depth_16: bool,
    pub icc_profile: Option<Vec<u8>>,
}

Tiny JPEG XL encoder.

This is a simplified VarDCT encoder based on libjxl-tiny that uses:

• Only DCT8, DCT8x16, DCT16x8 transforms
• Huffman or ANS entropy coding
• Default zig-zag coefficient order
• Fixed context tree for DC

Fields

distance: f32

Target distance (quality). 1.0 = visually lossless.

optimize_codes: bool

Use dynamic Huffman codes built from actual token frequencies. When true (default), uses a two-pass mode: collect tokens first, build optimal codes, then write. When false, uses pre-computed static codes (streaming, single-pass).

enhanced_clustering: bool

Use enhanced histogram clustering with pair merge refinement. Only effective when optimize_codes is true.

Note: The enhanced clustering algorithm was designed for ANS entropy coding and may not provide benefits (or may slightly increase size) when used with Huffman coding. This option is experimental.

use_ans: bool

Use ANS entropy coding instead of Huffman. Only effective when optimize_codes is true (requires two-pass mode). ANS typically produces 5-10% smaller files than Huffman.

cfl_enabled: bool

Enable chroma-from-luma (CfL) optimization. When true (default), computes per-tile ytox/ytob values via least-squares fitting. When false, uses ytox=0, ytob=0 (no chroma decorrelation).

ac_strategy_enabled: bool

Enable adaptive AC strategy selection (DCT8/DCT16x8/DCT8x16). When true (default), selects the best transform size per 16x16 block region. When false, uses DCT8 for all blocks.

custom_orders: bool

Enable custom coefficient ordering. When true (default when optimize_codes is true), reorders AC coefficients so frequently-zero positions appear last, reducing bitstream size. Only effective when optimize_codes is true (requires two-pass mode).

force_strategy: Option<u8>

Force a specific AC strategy for all blocks (for testing). When Some(strategy), uses that raw strategy code for all blocks that fit. None (default) uses normal strategy selection based on ac_strategy_enabled.

enable_noise: bool

Enable noise synthesis. When true, estimates noise parameters from the image and encodes them in the frame header. The decoder regenerates noise during rendering. Off by default (matching libjxl’s default).

enable_denoise: bool

Enable Wiener denoising pre-filter (requires enable_noise). When true, applies a conservative Wiener filter to remove estimated noise before encoding. The decoder re-adds noise from the encoded parameters. Provides 1-8% file size savings with near-zero Butteraugli quality impact. Off by default (libjxl does not have a denoising pre-filter).

enable_gaborish: bool

Enable gaborish inverse pre-filter. When true (default), applies a 5x5 sharpening kernel to XYB before DCT and signals gab=1 in the frame header. The decoder applies a 3x3 blur to compensate, reducing blocking artifacts. Matches the libjxl VarDCT encoder default.

error_diffusion: bool

Enable error diffusion in AC quantization. When true, spreads quantization error to neighboring coefficients in zigzag order, helping preserve smooth gradients at high compression. Off by default (modest quality improvement, slight performance cost).

pixel_domain_loss: bool

Enable pixel-domain loss calculation in AC strategy selection. When true, uses full libjxl’s pixel-domain loss model (IDCT error, per-pixel masking, 8th power norm). This provides better distance calibration matching cjxl’s output. When false (default), uses coefficient-domain loss (libjxl-tiny style). Note: Requires ac_strategy_enabled to have any effect.

enable_lz77: bool

Enable LZ77 backward references in entropy coding. When true, compresses token streams using LZ77 length+distance tokens. Only effective with two-pass mode (optimize_codes=true) and ANS (use_ans=true). Off by default — works for most cases but has known interactions with certain forced strategy combinations (DCT2x2, IDENTITY) that cause InvalidAnsStream.

lz77_method: Lz77Method

LZ77 method to use when enable_lz77 is true.

• Rle: Only matches consecutive identical values (fast, limited on photos)
• Greedy: Hash chain backward references (slower, 1-3% better on photos)

Default: Greedy (best compression)

dc_tree_learning: bool

Enable DC tree learning. When true, learns an optimal context tree for DC coding from image content instead of using the fixed GRADIENT_CONTEXT_LUT. DISABLED/BROKEN: The learned tree doesn’t correctly route AC metadata samples to contexts 0-10. Fixing requires parsing the static tree structure and splicing in the learned DC subtree while preserving AC metadata routing. Expected gain (~1.2% overall) doesn’t justify the complexity. See CLAUDE.md.

butteraugli_iters: u32

Number of butteraugli quantization loop iterations. When > 0, iteratively refines the per-block quant field using butteraugli perceptual distance feedback. Each iteration: encode → reconstruct → measure → adjust quant_field. AC strategy is kept fixed; only quant_field changes.

libjxl uses 2 iterations at effort 8, 4 at effort 9. Requires the butteraugli-loop feature.

Default: 0 (disabled)

bit_depth_16: bool

Whether the input has 16-bit samples. When true, the file header signals bit_depth=16 instead of 8. The actual VarDCT encoding is the same (XYB is always f32 internally), but the decoder uses this to reconstruct at the correct output bit depth.

icc_profile: Option<Vec<u8>>

ICC profile to embed in the codestream. When Some, writes has_icc=1 and encodes the profile after the file header.

Implementations

impl VarDctEncoder

pub fn new(distance: f32) -> Self

Create a new tiny encoder with the given distance.

pub fn encode( &self, width: usize, height: usize, linear_rgb: &[f32], alpha: Option<&[u8]>, ) -> Result<VarDctOutput>

Encode an image in linear sRGB format, optionally with an alpha channel.

Input should be 3 channels (RGB) of f32 values in [0, 1] range. Values outside [0, 1] are allowed for out-of-gamut colors.

If alpha is provided, it must be width * height bytes of u8 alpha values. Alpha is encoded as a modular extra channel alongside the VarDCT RGB data.

Trait Implementations

impl Default for VarDctEncoder

fn default() -> Self

Returns the “default value” for a type.