Struct ImageInfo 

#[non_exhaustive]
pub struct ImageInfo {

    pub width: u32,
    pub height: u32,
    pub format: ImageFormat,
    pub has_alpha: bool,
    pub is_progressive: bool,
    pub sequence: ImageSequence,
    pub supplements: Supplements,
    pub gain_map: GainMapPresence,
    pub orientation: Orientation,
    pub resolution: Option<Resolution>,
    pub source_color: SourceColor,
    pub embedded_metadata: EmbeddedMetadata,
    pub source_encoding: Option<Arc<dyn SourceEncodingDetails>>,
    pub warnings: Vec<String>,
}

Image metadata obtained from probing or decoding.

Field scope by sequence type

Field	Single	Animation	Multi
width, height	The image	Canvas size	Primary image only
has_alpha	The image	Canvas alpha	Primary image only
orientation	The image	Canvas orientation	Primary image only
source_color	The image	Overall color info	Primary image only
embedded_metadata	The image	Container-level	Primary image only

For Multi, other images may have completely different dimensions, color spaces, and metadata. Per-image information requires a future MultiPageDecoder or the codec’s native API.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

width: u32

Image width in pixels.

height: u32

Image height in pixels.

format: ImageFormat

Detected image format.

has_alpha: bool

Whether the image has an alpha channel.

is_progressive: bool

Whether the source encoding uses progressive or interlaced scan order.

True for progressive JPEG (SOF2), interlaced PNG (Adam7), and interlaced GIF. False for all other formats and non-interlaced variants. This is a file-level structural property detectable from headers (cheap probe).

Used by DecodePolicy::allow_progressive to reject progressive/interlaced input.

sequence: ImageSequence

What kind of image sequence the file contains.

For Single, all fields describe the one image. For Animation, width/height are the canvas size. For Multi, width/height describe the primary image only.

supplements: Supplements

Supplemental content alongside the primary image(s).

Pyramids, gain maps, depth maps, and other auxiliary data.

gain_map: GainMapPresence

Gain map detection state.

Three-state: Unknown (not yet probed), Absent (definitively none), or Available (metadata parsed). When Available, the gain map image pixels are NOT included — only the metadata and dimensions.

orientation: Orientation

EXIF orientation (1-8).

When a codec applies orientation during decode (rotating the pixel data), this is set to Identity and width/height reflect the display dimensions.

When orientation is NOT applied, width/height are the stored dimensions and this field tells the caller what transform to apply. Use display_width() / display_height() to get effective display dimensions regardless.

resolution: Option<Resolution>

Physical pixel resolution (DPI).

From JPEG JFIF density, PNG pHYs, TIFF resolution tags, BMP pels-per-meter, etc. None if the file doesn’t specify resolution.

source_color: SourceColor

Source color description (CICP, ICC, bit depth, HDR metadata).

embedded_metadata: EmbeddedMetadata

Embedded non-color metadata (EXIF, XMP).

source_encoding: Option<Arc<dyn SourceEncodingDetails>>

Source encoding details (quality estimate, encoder fingerprint, etc.).

Populated by codecs that can detect how the image was encoded. Use source_encoding_details() for the generic interface and codec_details::<T>() for codec-specific fields.

Skipped by PartialEq (trait objects aren’t comparable).

warnings: Vec<String>

Non-fatal diagnostic messages from probing or decoding.

Populated when the operation succeeded but encountered unusual conditions (e.g., metadata located beyond the fast-path probe cap, permissive parsing recovered from structural issues).

Implementations

impl ImageInfo

pub fn new(width: u32, height: u32, format: ImageFormat) -> Self

Create a new ImageInfo with the given dimensions and format.

Other fields default to no alpha, single image, no metadata. Use the with_* builder methods to set them.

pub fn with_alpha(self, has_alpha: bool) -> Self

Set whether the image has alpha.

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

Set whether the source uses progressive or interlaced scan order.

pub fn with_sequence(self, sequence: ImageSequence) -> Self

Set the image sequence type.

pub fn with_supplements(self, supplements: Supplements) -> Self

Set supplemental content flags.

pub fn with_gain_map(self, gain_map: GainMapPresence) -> Self

Set gain map detection state.

pub fn with_resolution(self, resolution: Resolution) -> Self

Set physical pixel resolution.

pub fn is_animation(&self) -> bool

Whether this file contains animation.

Convenience for matches!(self.sequence, ImageSequence::Animation { .. }).

pub fn is_multi_image(&self) -> bool

Whether this file contains multiple independent images.

pub fn has_additional_images(&self) -> bool

Whether Decode returns only one of multiple images in this file.

True for both animation and multi-image. When true, Decode returns the primary image and additional images require specialized decoders.

pub fn frame_count(&self) -> Option<u32>

Frame/image count from the sequence, if known.

pub fn with_bit_depth(self, bit_depth: u8) -> Self

Set the bit depth (bits per channel). Convenience for source_color.bit_depth.

pub fn with_channel_count(self, channel_count: u8) -> Self

Set the channel count. Convenience for source_color.channel_count.

pub fn with_cicp(self, cicp: Cicp) -> Self

Set the CICP color description. Convenience for source_color.cicp.

pub fn with_content_light_level(self, clli: ContentLightLevel) -> Self

Set the Content Light Level Info. Convenience for source_color.content_light_level.

pub fn with_mastering_display(self, mdcv: MasteringDisplay) -> Self

Set the Mastering Display Color Volume. Convenience for source_color.mastering_display.

pub fn with_icc_profile(self, icc: impl Into<Arc<[u8]>>) -> Self

Set the ICC color profile. Convenience for source_color.icc_profile.

Accepts Vec<u8>, &[u8], or Arc<[u8]>.

pub fn with_exif(self, exif: impl Into<Arc<[u8]>>) -> Self

Set the EXIF metadata. Convenience for embedded_metadata.exif.

Accepts Vec<u8>, &[u8], or Arc<[u8]>.

pub fn with_xmp(self, xmp: impl Into<Arc<[u8]>>) -> Self

Set the XMP metadata. Convenience for embedded_metadata.xmp.

Accepts Vec<u8>, &[u8], or Arc<[u8]>.

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

Set the EXIF orientation.

pub fn with_source_color(self, source_color: SourceColor) -> Self

Set the source color description.

pub fn with_embedded_metadata(self, embedded_metadata: EmbeddedMetadata) -> Self

Set the embedded metadata.

pub fn with_source_encoding_details<T: SourceEncodingDetails + 'static>( self, details: T, ) -> Self

Attach source encoding details (quality estimate, codec-specific probe data).

The concrete type must implement SourceEncodingDetails — typically a codec’s probe type (e.g. WebPProbe, JpegProbe).

pub fn source_encoding_details(&self) -> Option<&dyn SourceEncodingDetails>

Source encoding details, if available.

Returns the generic interface for querying source quality and losslessness. Downcast to the codec-specific type via codec_details::<T>().

pub fn with_warning(self, msg: String) -> Self

Add a single warning message.

pub fn with_warnings(self, msgs: Vec<String>) -> Self

Replace warnings with the given list.

pub fn warnings(&self) -> &[String]

Non-fatal diagnostic messages.

pub fn has_warnings(&self) -> bool

Whether any warnings were recorded.

pub fn display_width(&self) -> u32

Display width after applying EXIF orientation.

For orientations 5-8 (90/270 rotation), this returns height. For orientations 1-4, this returns width.

pub fn display_height(&self) -> u32

Display height after applying EXIF orientation.

For orientations 5-8 (90/270 rotation), this returns width. For orientations 1-4, this returns height.

pub fn transfer_function(&self) -> TransferFunction

Derive the transfer function from CICP metadata.

Delegates to SourceColor::transfer_function().

Use this to resolve a zenpixels::PixelDescriptor’s unknown transfer function:

let desc = pixels.descriptor().with_transfer(info.transfer_function());

pub fn color_primaries(&self) -> ColorPrimaries

Derive the color primaries from CICP metadata.

Delegates to SourceColor::color_primaries().

pub fn metadata(&self) -> Metadata

Get embedded metadata for roundtrip encode.

Clones Arc-backed byte buffers (cheap ref-count bump).

Trait Implementations

impl Clone for ImageInfo

fn clone(&self) -> ImageInfo

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ImageInfo

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

Formats the value using the given formatter.

impl From<&ImageInfo> for Metadata

fn from(info: &ImageInfo) -> Self

Converts to this type from the input type.

impl PartialEq for ImageInfo

Manual PartialEq — skips source_encoding (trait objects aren’t comparable).

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.