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: f32Positive, 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: OrientationImage orientation: how the decoder should rotate/flip the stored pixels
for display (default Orientation::Normal).
lossless: boolIf true, encode losslessly via the modular encoder. distance is then
ignored. RGB and alpha both round-trip bit-perfectly.
fill_invisible: boolSmooth 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: boolIf 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: boolEncode 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: boolExperimental: 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: boolExperimental: 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: f32HDR mastering black level in nits (ToneMapping min_nits). Default 0.
relative_to_max_display: boolToneMapping relative_to_max_display. Default false.
linear_below: f32ToneMapping linear_below (nits, or 0..1 if relative). Default 0.
num_threads: usize§speed: Speed§arbiter: ArbiterMetric the lossy encoder tunes for (see Arbiter). Default
Arbiter::Ssimulacra2.
decoding_speed: DecodingSpeedDecode-speed/density tradeoff for lossless encoding (see
DecodingSpeed). Ignored for lossy.
near_lossless: u16Near-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: boolCode 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: LossyModularLossy encoding arm selection (see LossyModular). Default Off.
ink_layer: boolExperimental: 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: boolExperimental: 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: boolProgressive 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: GroupOrderCodestream order of the lossy VarDCT groups (see GroupOrder).
Default GroupOrder::Scanline.
learned_rate: boolChoose 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: CodingTransformColor transform of lossy frames (see CodingTransform).
grain: GrainDecoder-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
impl EncodeConfig
Sourcepub fn with_distance(self, distance: f32) -> EncodeConfig
pub fn with_distance(self, distance: f32) -> EncodeConfig
Convenience builder with the given butteraugli distance and otherwise default settings (sRGB primaries, linear transfer).
Sourcepub fn with_quality(self, quality: f32) -> EncodeConfig
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.
Sourcepub fn with_color_encoding(self, enc: ColorEncoding) -> EncodeConfig
pub fn with_color_encoding(self, enc: ColorEncoding) -> EncodeConfig
Replace the color encoding (white point / primaries / transfer / intent).
Sourcepub fn with_intensity_target(self, nits: f32) -> EncodeConfig
pub fn with_intensity_target(self, nits: f32) -> EncodeConfig
Signal HDR peak display luminance (nits) in the tone-mapping metadata.
Sourcepub fn with_min_nits(self, nits: f32) -> EncodeConfig
pub fn with_min_nits(self, nits: f32) -> EncodeConfig
HDR mastering black level in nits (ToneMapping min_nits).
Sourcepub fn with_relative_to_max_display(self, rel: bool) -> EncodeConfig
pub fn with_relative_to_max_display(self, rel: bool) -> EncodeConfig
Set ToneMapping relative_to_max_display.
Sourcepub fn with_linear_below(self, v: f32) -> EncodeConfig
pub fn with_linear_below(self, v: f32) -> EncodeConfig
Set ToneMapping linear_below (nits, or 0..1 when relative).
Sourcepub fn with_icc_profile(self, icc: Vec<u8>) -> EncodeConfig
pub fn with_icc_profile(self, icc: Vec<u8>) -> EncodeConfig
Embed an ICC profile in the codestream (predicted + entropy-coded ICC stream).
Sourcepub fn with_exif(self, exif: Vec<u8>) -> EncodeConfig
pub fn with_exif(self, exif: Vec<u8>) -> EncodeConfig
Embed EXIF/TIFF metadata (raw TIFF bytes) via an Exif container box.
Sourcepub fn with_xmp(self, xmp: Vec<u8>) -> EncodeConfig
pub fn with_xmp(self, xmp: Vec<u8>) -> EncodeConfig
Embed an XMP packet via an uncompressed xml container box.
Sourcepub fn with_brotli_compression(
self,
compressor: Box<dyn BrotliCompression>,
) -> EncodeConfig
pub fn with_brotli_compression( self, compressor: Box<dyn BrotliCompression>, ) -> EncodeConfig
Compress EXIF and XMP metadata using a caller-provided Brotli encoder.
Sourcepub fn with_orientation(self, orientation: Orientation) -> EncodeConfig
pub fn with_orientation(self, orientation: Orientation) -> EncodeConfig
Set the image Orientation.
pub fn with_lossless(self, lossless: bool) -> EncodeConfig
Sourcepub fn with_fill_invisible(self, fill_invisible: bool) -> EncodeConfig
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.
Sourcepub fn with_alpha_distance(self, alpha_distance: f32) -> EncodeConfig
pub fn with_alpha_distance(self, alpha_distance: f32) -> EncodeConfig
Alpha distance of lossy frames (see EncodeConfig::alpha_distance);
0.0 keeps alpha lossless.
Sourcepub fn with_progressive(self, progressive: bool) -> EncodeConfig
pub fn with_progressive(self, progressive: bool) -> EncodeConfig
Enable progressive lossless. Only effective when lossless.
Sourcepub fn with_patches(self, patches: bool) -> EncodeConfig
pub fn with_patches(self, patches: bool) -> EncodeConfig
Enable exact patch-dictionary matching with full rate comparison.
Sourcepub fn with_splines(self, splines: bool) -> EncodeConfig
pub fn with_splines(self, splines: bool) -> EncodeConfig
Experimental spline coding for lossy VarDCT (see EncodeConfig::splines).
Requires the splines Cargo feature.
Sourcepub fn with_dots(self, dots: bool) -> EncodeConfig
pub fn with_dots(self, dots: bool) -> EncodeConfig
Experimental bright/dark dot coding for lossy VarDCT (see EncodeConfig::dots).
Requires the splines Cargo feature.
Sourcepub fn with_coding_transform(self, transform: CodingTransform) -> EncodeConfig
pub fn with_coding_transform(self, transform: CodingTransform) -> EncodeConfig
Code lossy frames in transform (see CodingTransform).
Sourcepub fn with_grain(self, grain: Grain) -> EncodeConfig
pub fn with_grain(self, grain: Grain) -> EncodeConfig
Decoder-side grain synthesis (see EncodeConfig::grain).
Sourcepub fn with_lossy_modular(self, mode: LossyModular) -> EncodeConfig
pub fn with_lossy_modular(self, mode: LossyModular) -> EncodeConfig
Select the lossy encoding arm (see LossyModular).
Sourcepub fn with_ink_layer(self, ink_layer: bool) -> EncodeConfig
pub fn with_ink_layer(self, ink_layer: bool) -> EncodeConfig
Experimental ink layer for cel and line art (see
EncodeConfig::ink_layer).
Sourcepub fn with_vector_layers(self, vector_layers: bool) -> EncodeConfig
pub fn with_vector_layers(self, vector_layers: bool) -> EncodeConfig
Experimental vector layers for flat-color art (see
EncodeConfig::vector_layers).
Sourcepub fn with_progressive_dc(self, progressive_dc: bool) -> EncodeConfig
pub fn with_progressive_dc(self, progressive_dc: bool) -> EncodeConfig
Code the lossy DC as a progressive DC frame (see
EncodeConfig::progressive_dc).
Sourcepub fn with_group_order(self, order: GroupOrder) -> EncodeConfig
pub fn with_group_order(self, order: GroupOrder) -> EncodeConfig
Store the lossy VarDCT groups in order (see GroupOrder).
Sourcepub fn with_progressive_dc_levels(self, levels: u32) -> EncodeConfig
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).
Sourcepub fn with_learned_rate(self, learned_rate: bool) -> EncodeConfig
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).
Sourcepub fn with_gain_map(self, gain_map: GainMap) -> EncodeConfig
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.
Sourcepub fn with_num_threads(self, n: usize) -> EncodeConfig
pub fn with_num_threads(self, n: usize) -> EncodeConfig
Set the worker-thread count (see EncodeConfig::num_threads).
Sourcepub fn with_decoding_speed(self, decoding_speed: DecodingSpeed) -> EncodeConfig
pub fn with_decoding_speed(self, decoding_speed: DecodingSpeed) -> EncodeConfig
Select the lossless decode-speed/density tradeoff (see DecodingSpeed).
Sourcepub fn with_near_lossless(self, max_error: u16) -> EncodeConfig
pub fn with_near_lossless(self, max_error: u16) -> EncodeConfig
Bound the per-channel error of a lossless encode (see
EncodeConfig::near_lossless).
Sourcepub fn with_upsampling(self, upsampling: bool) -> EncodeConfig
pub fn with_upsampling(self, upsampling: bool) -> EncodeConfig
Decoder-side nearest-neighbor upsampling of integer-upscaled content
(see EncodeConfig::upsampling).
Sourcepub fn with_arbiter(self, arbiter: Arbiter) -> EncodeConfig
pub fn with_arbiter(self, arbiter: Arbiter) -> EncodeConfig
Select the metric the lossy encoder tunes for (see Arbiter).
Sourcepub fn with_speed(self, speed: Speed) -> EncodeConfig
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
impl Clone for EncodeConfig
Source§fn clone(&self) -> EncodeConfig
fn clone(&self) -> EncodeConfig
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more