Skip to main content

EncodeConfig

Struct EncodeConfig 

Source
pub struct EncodeConfig {
Show 36 fields pub distance: f32, pub color_encoding: ColorEncoding, pub icc_profile: Option<Vec<u8>>, pub exif: Option<Vec<u8>>, pub xmp: Option<Vec<u8>>, pub brotli_compression: Option<Arc<dyn BrotliCompression>>, pub orientation: Orientation, pub lossless: bool, pub fill_invisible: bool, pub alpha_distance: Option<f32>, pub progressive: bool, pub patches: bool, pub splines: bool, pub dots: bool, pub progressive_passes: Option<u32>, pub progressive_shifts: Option<Vec<u32>>, pub intensity_target: Option<f32>, pub min_nits: f32, pub relative_to_max_display: bool, pub linear_below: f32, pub num_threads: usize, pub speed: Speed, pub arbiter: Arbiter, pub decoding_speed: DecodingSpeed, pub near_lossless: u16, pub upsampling: bool, pub lossy_modular: LossyModular, pub ink_layer: bool, pub vector_layers: bool, pub progressive_dc: bool, pub progressive_dc_levels: Option<u32>, pub group_order: GroupOrder, pub learned_rate: bool, pub gain_map: Option<GainMap>, pub coding_transform: CodingTransform, pub grain: Grain,
}

Fields§

§distance: f32

Positive, finite lossy distance, clamped to a minimum of 0.05. Ignored when lossless is true.

§color_encoding: ColorEncoding§icc_profile: Option<Vec<u8>>§exif: Option<Vec<u8>>

EXIF/TIFF metadata to embed via an Exif container box. Forces the output into the JXL container form. Raw TIFF bytes (no “Exif\0\0” prefix).

§xmp: Option<Vec<u8>>

XMP packet to embed via an xml container box, or a brob box when a Brotli implementation is supplied. Forces the output into container form.

§brotli_compression: Option<Arc<dyn BrotliCompression>>

Optional Brotli encoder for EXIF and XMP metadata boxes.

When set, metadata is emitted in brob boxes. When absent, it remains in uncompressed Exif and xml boxes.

§orientation: Orientation

Image orientation: how the decoder should rotate/flip the stored pixels for display (default Orientation::Normal).

§lossless: bool

If true, encode losslessly via the modular encoder. distance is then ignored. RGB and alpha both round-trip bit-perfectly.

§fill_invisible: bool

Smooth color samples underneath fully transparent pixels before lossy encoding, using libjxl’s neighbor fill. Alpha and partially transparent source samples are unchanged by this preprocessing. Defaults to true. Ignored for lossless encoding and CMYK images.

§alpha_distance: Option<f32>

Distance of the alpha channel in lossy frames, in the units of distance. None (the default) codes alpha at the frame distance; Some(0.0) keeps it lossless. Lossy alpha is a quantized Squeeze pyramid; the encoder keeps lossless alpha wherever that is no larger, so solid and hard-edged alpha stays exact. Values are clamped to 0.0..=25.0; NaN means lossless. Ignored when lossless is true.

§progressive: bool

If true (and lossless), use the progressive Squeeze transform: a low-res preview that refines to bit-exact. Works at any size (single- and multi-group) and with alpha.

For lossy (!lossless) encoding, true selects 2-pass progressive VarDCT (equivalent to progressive_passes = Some(2)).

§patches: bool

Encode repeated content through the JPEG XL patch dictionary: glyphs and other small marks on flat backgrounds at any position, and repeated grid-aligned tiles. Supported for both lossless Modular and lossy VarDCT encoding. Lossless keeps patches only when they reduce the final size; lossy takes a plan on its coverage, since the patched frame is also the sharper one, and photographic content finds none.

§splines: bool

Experimental: detect thin curvilinear structures (wires, veins, ink lines) and code them as JPEG XL splines next to the lossy VarDCT image. Every spline passes a rate-distortion test against the VarDCT cost of the same pixels. Slow speed and the default decoding speed only; costs encode time and some decode time. Requires the splines Cargo feature. Defaults to false.

§dots: bool

Experimental: detect isolated bright or dark spots and code them as signed Gaussian dots drawn from a small template atlas (additive patches), next to the lossy VarDCT image. Dots, templates and the whole set pass rate-distortion tests; unprofitable sets fall back to VarDCT. Slow speed and the default decoding speed only; costs encode time. Requires the splines Cargo feature. Defaults to false.

§progressive_passes: Option<u32>

Number of VarDCT passes for lossy progressive encoding. None falls back to progressive (2 passes if set, else 1). Some(1) = single pass; Some(n) for n in 2..=4 = n-pass progressive with an automatic coarse-to-fine bit-shift schedule ([n-1, .., 1, 0]). Values above 4 are clamped (the per-pass shift field is 2 bits with no downsampling). Ignored when lossless. Overridden by progressive_shifts if set.

§progressive_shifts: Option<Vec<u32>>

Explicit per-pass coefficient-shift schedule for lossy progressive encoding, overriding progressive_passes. The length is the pass count; each entry is the decoder left-shift for that pass (0..=3). A larger pass-0 shift makes the first (preview) pass smaller and coarser. Must end in 0 and contain only values 0..=3; otherwise it is ignored. Examples: [1,0] (default 2-pass), [2,0] / [3,0] (coarser thumbnail then full), [2,1,0] (3-step ramp). Ignored when lossless.

§intensity_target: Option<f32>

HDR luminance signaling. When Some(nits), the codestream’s tone-mapping metadata declares this peak display luminance (intensity_target), e.g. 10000.0 for PQ/HDR10 or a measured mastering peak. None leaves the SDR default. Must be > 0.

§min_nits: f32

HDR mastering black level in nits (ToneMapping min_nits). Default 0.

§relative_to_max_display: bool

ToneMapping relative_to_max_display. Default false.

§linear_below: f32

ToneMapping linear_below (nits, or 0..1 if relative). Default 0.

§num_threads: usize§speed: Speed§arbiter: Arbiter

Metric the lossy encoder tunes for (see Arbiter). Default Arbiter::Ssimulacra2.

§decoding_speed: DecodingSpeed

Decode-speed/density tradeoff for lossless encoding (see DecodingSpeed). Ignored for lossy.

§near_lossless: u16

Near-lossless bound for lossless encodes: the maximum absolute error per channel, in input code values. 0 (default) keeps every sample exact. Alpha always stays exact. Ignored for lossy.

§upsampling: bool

Code integer-upscaled content at its cell grid and let the decoder scale it back with a nearest-neighbor kernel: a lossless image whose 2x2, 4x4 or 8x8 cells are all one color (pixel art, a 2x asset) is coded at a half, quarter or eighth of its size, and such a region inside an image becomes a layer blended over the rest, which then gains an opaque alpha channel. Exact. The search costs about 30 ms per megapixel. Defaults to false. Ignored for lossy and progressive encodes.

§lossy_modular: LossyModular

Lossy encoding arm selection (see LossyModular). Default Off.

§ink_layer: bool

Experimental: lift line/text colors into one palette frame with coverage alpha, blended over a VarDCT base that is free under the ink. Source color and edge statistics select the decomposition before the base and ink frames are encoded once. Supports 8-bit RGB/RGBA in XYB; non-opaque pixels stay in the base and retain their original alpha. Layered RGB declares an opaque alpha channel. Lossless and progressive DC ignore it. Defaults to false.

§vector_layers: bool

Experimental: flat-color art with antialiased edges is split in one pass into a lossless palette base and a lossless coverage frame (kBlend) that carries the antialiasing; other images are coded as usual. 8-bit RGB input only; the output is near-lossless and independent of distance. Defaults to false.

§progressive_dc: bool

Progressive DC for lossy VarDCT: the 1:8 DC image is coded as its own squeezed modular frame ahead of the main frame, so a decoder can show previews refining from 1:256 to 1:8 before any AC data arrives. Costs some size. XYB frames without alpha only; other frames ignore it. Defaults to false.

§progressive_dc_levels: Option<u32>

Squeeze levels of the progressive DC frame, finest first; each level halves the preview resolution. None (default) squeezes down to an 8x8 preview. Some(n) keeps the n finest levels, clamped to between one and the most the image allows; fewer levels give fewer, larger previews. A single level costs noticeably more size; two or more cost about the same as the full pyramid. Used only with progressive_dc.

§group_order: GroupOrder

Codestream order of the lossy VarDCT groups (see GroupOrder). Default GroupOrder::Scanline.

§learned_rate: bool

Choose VarDCT transforms by what each candidate costs under the image’s own coefficient statistics instead of a fixed rate model. Patterned and synthetic content compresses much better; photographs are about unchanged. Takes effect at Speed::Slow and above, where it costs encode time. Defaults to true.

§gain_map: Option<GainMap>

Optional HDR gain map (see GainMap). When set, the gain map is encoded as a second JPEG XL codestream and shipped in a jhgm container box together with its ISO 21496-1 metadata. Forces the output into the JXL container form.

§coding_transform: CodingTransform

Color transform of lossy frames (see CodingTransform).

§grain: Grain

Decoder-side grain synthesis over lossy VarDCT frames (see Grain). The decoder adds fine high-passed noise scaled per intensity; the frame carries only the 8-point strength table. Lossy modular frames and lossless encodes ignore it. Default Grain::Off.

Implementations§

Source§

impl EncodeConfig

Source

pub fn with_distance(self, distance: f32) -> EncodeConfig

Convenience builder with the given butteraugli distance and otherwise default settings (sRGB primaries, linear transfer).

Source

pub fn with_quality(self, quality: f32) -> EncodeConfig

Convenience builder with quality on a libjpeg-like 0..=100 scale. See distance_from_quality for the mapping.

Source

pub fn with_color_encoding(self, enc: ColorEncoding) -> EncodeConfig

Replace the color encoding (white point / primaries / transfer / intent).

Source

pub fn with_intensity_target(self, nits: f32) -> EncodeConfig

Signal HDR peak display luminance (nits) in the tone-mapping metadata.

Source

pub fn with_min_nits(self, nits: f32) -> EncodeConfig

HDR mastering black level in nits (ToneMapping min_nits).

Source

pub fn with_relative_to_max_display(self, rel: bool) -> EncodeConfig

Set ToneMapping relative_to_max_display.

Source

pub fn with_linear_below(self, v: f32) -> EncodeConfig

Set ToneMapping linear_below (nits, or 0..1 when relative).

Source

pub fn with_icc_profile(self, icc: Vec<u8>) -> EncodeConfig

Embed an ICC profile in the codestream (predicted + entropy-coded ICC stream).

Source

pub fn with_exif(self, exif: Vec<u8>) -> EncodeConfig

Embed EXIF/TIFF metadata (raw TIFF bytes) via an Exif container box.

Source

pub fn with_xmp(self, xmp: Vec<u8>) -> EncodeConfig

Embed an XMP packet via an uncompressed xml container box.

Source

pub fn with_brotli_compression( self, compressor: Box<dyn BrotliCompression>, ) -> EncodeConfig

Compress EXIF and XMP metadata using a caller-provided Brotli encoder.

Source

pub fn with_orientation(self, orientation: Orientation) -> EncodeConfig

Set the image Orientation.

Source

pub fn with_lossless(self, lossless: bool) -> EncodeConfig

Source

pub fn with_fill_invisible(self, fill_invisible: bool) -> EncodeConfig

Enable invisible-color preprocessing (see EncodeConfig::fill_invisible). Enabled by default; set to false to retain the original hidden colors as input to lossy encoding.

Source

pub fn with_alpha_distance(self, alpha_distance: f32) -> EncodeConfig

Alpha distance of lossy frames (see EncodeConfig::alpha_distance); 0.0 keeps alpha lossless.

Source

pub fn with_progressive(self, progressive: bool) -> EncodeConfig

Enable progressive lossless. Only effective when lossless.

Source

pub fn with_patches(self, patches: bool) -> EncodeConfig

Enable exact patch-dictionary matching with full rate comparison.

Source

pub fn with_splines(self, splines: bool) -> EncodeConfig

Experimental spline coding for lossy VarDCT (see EncodeConfig::splines). Requires the splines Cargo feature.

Source

pub fn with_dots(self, dots: bool) -> EncodeConfig

Experimental bright/dark dot coding for lossy VarDCT (see EncodeConfig::dots). Requires the splines Cargo feature.

Source

pub fn with_coding_transform(self, transform: CodingTransform) -> EncodeConfig

Code lossy frames in transform (see CodingTransform).

Source

pub fn with_grain(self, grain: Grain) -> EncodeConfig

Decoder-side grain synthesis (see EncodeConfig::grain).

Source

pub fn with_lossy_modular(self, mode: LossyModular) -> EncodeConfig

Select the lossy encoding arm (see LossyModular).

Source

pub fn with_ink_layer(self, ink_layer: bool) -> EncodeConfig

Experimental ink layer for cel and line art (see EncodeConfig::ink_layer).

Source

pub fn with_vector_layers(self, vector_layers: bool) -> EncodeConfig

Experimental vector layers for flat-color art (see EncodeConfig::vector_layers).

Source

pub fn with_progressive_dc(self, progressive_dc: bool) -> EncodeConfig

Code the lossy DC as a progressive DC frame (see EncodeConfig::progressive_dc).

Source

pub fn with_group_order(self, order: GroupOrder) -> EncodeConfig

Store the lossy VarDCT groups in order (see GroupOrder).

Source

pub fn with_progressive_dc_levels(self, levels: u32) -> EncodeConfig

Limit the progressive DC frame to its levels finest squeeze levels (see EncodeConfig::progressive_dc_levels).

Source

pub fn with_learned_rate(self, learned_rate: bool) -> EncodeConfig

Price VarDCT transform candidates by the image’s own coefficient statistics (see EncodeConfig::learned_rate).

Source

pub fn with_gain_map(self, gain_map: GainMap) -> EncodeConfig

Attach an HDR gain map (see GainMap). It is encoded as its own JPEG XL codestream and written into a jhgm container box.

Source

pub fn with_num_threads(self, n: usize) -> EncodeConfig

Set the worker-thread count (see EncodeConfig::num_threads).

Source

pub fn with_decoding_speed(self, decoding_speed: DecodingSpeed) -> EncodeConfig

Select the lossless decode-speed/density tradeoff (see DecodingSpeed).

Source

pub fn with_near_lossless(self, max_error: u16) -> EncodeConfig

Bound the per-channel error of a lossless encode (see EncodeConfig::near_lossless).

Source

pub fn with_upsampling(self, upsampling: bool) -> EncodeConfig

Decoder-side nearest-neighbor upsampling of integer-upscaled content (see EncodeConfig::upsampling).

Source

pub fn with_arbiter(self, arbiter: Arbiter) -> EncodeConfig

Select the metric the lossy encoder tunes for (see Arbiter).

Source

pub fn with_speed(self, speed: Speed) -> EncodeConfig

Select the encode-speed/density tradeoff (see Speed). Speed::Slow and Speed::ExtraSlow also turn on EncodeConfig::patches and EncodeConfig::vector_layers; Speed::Medium and above turn on EncodeConfig::ink_layer.

Trait Implementations§

Source§

impl Clone for EncodeConfig

Source§

fn clone(&self) -> EncodeConfig

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for EncodeConfig

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl Default for EncodeConfig

Source§

fn default() -> EncodeConfig

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.