Zenpixels

https://docs.rs/zenpixels/
Admin
Zenpixels provides pixel format interchange types for Rust image codecs, offering a type system to...
Tokens:910,965
Snippets:6,715
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Implement a CMS backend

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/cms.rs.html?search=

Example implementation of the ColorManagement trait for a custom CMS backend.

```rust
struct MyLcms2;

impl ColorManagement for MyLcms2 {
    type Error = lcms2::Error;

    fn build_transform(
        &self,
        src_icc: &[u8],
        dst_icc: &[u8],
    ) -> Result<Box<dyn RowTransform>, Self::Error> {
        let src = lcms2::Profile::new_icc(src_icc)?;
        let dst = lcms2::Profile::new_icc(dst_icc)?;
        let xform = lcms2::Transform::new(&src, &dst, ...)?;
        Ok(Box::new(Lcms2RowTransform(xform)))
    }

    fn identify_profile(&self, icc: &[u8]) -> Option<Cicp> {
        // Fast: check MD5 hash against known profiles
        // Slow: parse TRC+matrix, compare within tolerance
        None
    }
}
```

--------------------------------

### HDR Quantization Setup

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/hdr.rs.html?search=

Internal utility to validate pixel formats and transfer functions before PQ quantization.

```rust
fn quantize_setup(
    px: &PixelSlice<'_>,
    target: PixelDescriptor,
) -> Result<(PixelDescriptor, DiffuseWhite, u32, u32), At<ConvertError>> {
    let diffuse_white = px
        .color_context()
        .and_then(|c| c.diffuse_white)
        .unwrap_or(DiffuseWhite::BT2408);
    let desc = px.descriptor();
    let src = match desc.pixel_format() {
        PixelFormat::RgbF32 => PixelDescriptor::RGBF32_LINEAR,
        PixelFormat::RgbaF32 => PixelDescriptor::RGBAF32_LINEAR,
        _ => return Err(whereat::at!(ConvertError::NoMatch { source: desc })),
    }
    .with_primaries(target.primaries);
    if desc.transfer != TransferFunction::Linear {
        return Err(whereat::at!(ConvertError::UnsupportedTransfer {
            from: desc.transfer,
            to: TransferFunction::Linear,
        }));
    }
    // The pipeline anchors PQ at 1.0 = 10000 cd/m²; only PQ targets are handled.
    if target.transfer != TransferFunction::Pq {
        return Err(whereat::at!(ConvertError::NoPath {
            from: desc,
            to: target,
        }));
    }
    let w = px.width();
    let h = px.rows();
    if w == 0 || h == 0 {
        return Err(whereat::at!(ConvertError::InvalidWidth(w)));
    }
    Ok((src, diffuse_white, w, h))
}
```

--------------------------------

### HDR HLG U16 to Linear F32 Setup

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/converter.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes descriptors for HLG U16 to linear F32 conversion.

```rust
    #[test]
    fn hlg_u16_to_linear_f32_roundtrip() {
        let hlg_u16 = PixelDescriptor::new(
            ChannelType::U16,
            ChannelLayout::Rgb,
            None,
            TransferFunction::Hlg,
        );
        let lin_f32 = PixelDescriptor::new(
            ChannelType::F32,
            ChannelLayout::Rgb,
            None,
            TransferFunction::Linear,
        );
        let src16: [u16; 3] = [0, 32768, 65535];
```

--------------------------------

### Get pixel descriptor

Source: https://docs.rs/zenpixels/latest/src/zenpixels/descriptor.rs.html?search=

Retrieves the base pixel descriptor for the format.

```rust
    /// Base descriptor with `Unknown` transfer and BT.709 primaries.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn descriptor(self) -> PixelDescriptor {
        match self {
            Self::Rgb8 => PixelDescriptor::RGB8,
            Self::Rgba8 => PixelDescriptor::RGBA8,
```

--------------------------------

### Initialize MasteringDisplay

Source: https://docs.rs/zenpixels/latest/src/zenpixels/hdr.rs.html?search=

Shows how to create a MasteringDisplay instance with specific color primaries and luminance values.

```rust
#[test]
fn mastering_display_new() {
    let md = MasteringDisplay::new(
        [[0.68, 0.32], [0.265, 0.69], [0.15, 0.06]],
        [0.3127, 0.329],
        1000.0,
        0.001,
    );
    assert_eq!(md.max_luminance, 1000.0);
    assert_eq!(md.min_luminance, 0.001);
}
```

--------------------------------

### Test ColorContext Initialization and Profile Source

Source: https://docs.rs/zenpixels/latest/src/zenpixels/color.rs.html

Demonstrates creating ColorContext from various sources and extracting the profile source.

```rust
#[test]
fn color_context_from_icc() {
    let ctx = ColorContext::from_icc(vec![10, 20, 30]);
    assert!(ctx.icc.is_some());
    assert_eq!(ctx.icc.as_deref(), Some(&[10u8, 20, 30][..]));
    assert!(ctx.cicp.is_none());
}

#[test]
#[allow(deprecated)]
fn color_context_from_icc_and_cicp() {
    let ctx = ColorContext::from_icc_and_cicp(vec![1, 2], Cicp::BT2100_PQ);
    assert!(ctx.icc.is_some());
    assert_eq!(ctx.cicp, Some(Cicp::BT2100_PQ));
}

#[test]
fn color_context_profile_source_icc_only() {
    let ctx = ColorContext::from_icc(vec![42]);
    let src = ctx.as_profile_source().unwrap();
    assert_eq!(src, ColorProfileSource::Icc(&[42]));
}

#[test]
fn color_context_profile_source_none() {
    let ctx = ColorContext {
        icc: None,
        cicp: None,
        diffuse_white: None,
    };
    assert!(ctx.as_profile_source().is_none());
}
```

--------------------------------

### Get Pixel Descriptor

Source: https://docs.rs/zenpixels/latest/src/zenpixels/descriptor.rs.html

Retrieves the base pixel descriptor for the format.

```rust
    /// Base descriptor with `Unknown` transfer and BT.709 primaries.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn descriptor(self) -> PixelDescriptor {
        match self {
            Self::Rgb8 => PixelDescriptor::RGB8,
```

--------------------------------

### Construct a Conversion Plan

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/convert.rs.html

Initializes a conversion plan with default PQ scaling parameters.

```rust
fn build(from: PixelDescriptor, to: PixelDescriptor, steps: Vec<ConvertStep>) -> Self {
        Self {
            from,
            to,
            steps,
            pq_anchor_scale: 1.0,
        }
    }
```

--------------------------------

### Get human-readable name

Source: https://docs.rs/zenpixels/latest/src/zenpixels/descriptor.rs.html?search=

Returns a short string representation of the pixel format.

```rust
    /// Short human-readable name.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Rgb8 => "RGB8",
            Self::Rgba8 => "RGBA8",
            Self::Rgb16 => "RGB16",
            Self::Rgba16 => "RGBA16",
            Self::RgbF32 => "RgbF32",
            Self::RgbaF32 => "RgbaF32",
            Self::Gray8 => "Gray8",
            Self::Gray16 => "Gray16",
            Self::GrayF32 => "GrayF32",
            Self::GrayA8 => "GrayA8",
            Self::GrayA16 => "GrayA16",
            Self::GrayAF32 => "GrayAF32",
            Self::Bgra8 => "BGRA8",
            Self::Rgbx8 => "RGBX8",
            Self::Bgrx8 => "BGRX8",
            Self::OklabF32 => "OklabF32",
            Self::OklabaF32 => "OklabaF32",
            Self::Cmyk8 => "CMYK8",
            Self::RgbF16 => "RgbF16",
            Self::RgbaF16 => "RgbaF16",
            Self::GrayF16 => "GrayF16",
            Self::GrayAF16 => "GrayAF16",
            _ => "Unknown",
        }
    }
```

--------------------------------

### Instantiate and Verify MasteringDisplay

Source: https://docs.rs/zenpixels/latest/src/zenpixels/hdr.rs.html?search=std%3A%3Avec

Shows how to create a MasteringDisplay instance with specific color primaries and luminance values, and how to access reference constants.

```rust
    #[test]
    fn mastering_display_new() {
        let md = MasteringDisplay::new(
            [[0.68, 0.32], [0.265, 0.69], [0.15, 0.06]],
            [0.3127, 0.329],
            1000.0,
            0.001,
        );
        assert_eq!(md.max_luminance, 1000.0);
        assert_eq!(md.min_luminance, 0.001);
    }
```

```rust
    #[test]
    fn mastering_display_constants() {
        assert_eq!(MasteringDisplay::HDR10_REFERENCE.max_luminance, 10000.0);
        assert_eq!(MasteringDisplay::DISPLAY_P3_1000.max_luminance, 1000.0);
    }
```

--------------------------------

### Create a traced error

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.At.html

Example of creating a traced error using the at() function.

```rust
use whereat::{at, At};

#[derive(Debug)]
enum MyError { Oops }

// Create a traced error using at() function
let err: At<MyError> = at(MyError::Oops);
assert_eq!(err.frame_count(), 1);
```

--------------------------------

### Implement Pixel for Rgbx

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/buffer/trait.Pixel.html

Example implementation of the Pixel trait for the Rgbx type.

```rust
impl Pixel for Rgbx {
    const DESCRIPTOR: PixelDescriptor = PixelDescriptor::RGBX8
}
```

--------------------------------

### Construct ConvertOptions instances

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/policy/struct.ConvertOptions.html?search=

Demonstrates creating ConvertOptions using strict, permissive, or custom builder patterns.

```rust
use zenpixels::{ConvertOptions, AlphaPolicy, DepthPolicy};

// Forbid all lossy operations (safe default)
let strict = ConvertOptions::forbid_lossy();

// Allow common lossy operations with sensible defaults
let permissive = ConvertOptions::permissive();

// Customize from a preset
let custom = ConvertOptions::permissive()
    .with_alpha_policy(AlphaPolicy::CompositeOnto { r: 255, g: 255, b: 255 })
    .with_depth_policy(DepthPolicy::Truncate);
```

--------------------------------

### Implement Pixel for Bgrx

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/buffer/trait.Pixel.html

Example implementation of the Pixel trait for the Bgrx type.

```rust
impl Pixel for Bgrx {
    const DESCRIPTOR: PixelDescriptor = PixelDescriptor::BGRX8
}
```

--------------------------------

### Conversion Plan Construction

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/convert.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a conversion plan with default PQ scaling parameters.

```rust
    fn build(from: PixelDescriptor, to: PixelDescriptor, steps: Vec<ConvertStep>) -> Self {
        Self {
            from,
            to,
            steps,
            pq_anchor_scale: 1.0,
        }
    }
```

--------------------------------

### Verify Gamut Clamping with ZenCmsLite

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/cms_lite.rs.html?search=

Demonstrates setting up a source-to-destination color transform and verifying that output values remain non-negative.

```rust
let cms = ZenCmsLite;
        let src = ColorProfileSource::Named(NamedProfile::DisplayP3);
        let dst = ColorProfileSource::Named(NamedProfile::Srgb);
        let transform = cms
            .build_source_transform(src, dst, PixelFormat::RgbF32, PixelFormat::RgbF32)
            .unwrap()
            .unwrap();

        let src_px: [f32; 3] = [0.0, 1.0, 0.0];
        let mut dst_px = [0.0f32; 3];
        transform.transform_row(
            bytemuck::cast_slice(&src_px),
            bytemuck::cast_slice_mut(&mut dst_px),
            1,
        );
        assert!(
            dst_px[0] >= 0.0,
            "clamped path should not produce negatives: {}",
            dst_px[0]
        );
```

--------------------------------

### Manage Load-Bearing Report State

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/load_bearing.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples for checking the analysis state of a LoadBearingReport.

```rust
    #[test]
    fn default_report_is_fully_unanalyzed() {
        // With per-field Option semantics, the default report is
        // "nothing was checked" — every field is None. apply_to on a
        // None-only report is identity (no Some(false) signals).
        let r = LoadBearingReport::default();
        assert_eq!(r.uses_alpha, None);
        assert_eq!(r.uses_chroma, None);
        assert_eq!(r.uses_low_bits, None);
        assert!(!r.any_analyzed());
    }
```

```rust
    #[test]
    fn any_analyzed_fires_when_at_least_one_field_set() {
        let mut r = LoadBearingReport::default();
        assert!(!r.any_analyzed());
        r.uses_alpha = Some(true);
        assert!(r.any_analyzed(), "any_analyzed fires for any Some");
        r.uses_alpha = None;
        r.uses_low_bits = Some(false);
        assert!(r.any_analyzed(), "any_analyzed fires on low-bits too");
    }
```

--------------------------------

### MasteringDisplay Instantiation and Constants

Source: https://docs.rs/zenpixels/latest/src/zenpixels/hdr.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a MasteringDisplay and access predefined HDR constants.

```rust
let md = MasteringDisplay::new(
    [[0.68, 0.32], [0.265, 0.69], [0.15, 0.06]],
    [0.3127, 0.329],
    1000.0,
    0.001,
);
assert_eq!(md.max_luminance, 1000.0);
assert_eq!(md.min_luminance, 0.001);
```

```rust
assert_eq!(MasteringDisplay::HDR10_REFERENCE.max_luminance, 10000.0);
assert_eq!(MasteringDisplay::DISPLAY_P3_1000.max_luminance, 1000.0);
```

--------------------------------

### Get channel selection map

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/load_bearing.rs.html?search=u32+-%3E+bool

Retrieves the channel selection map for layout transitions.

```rust
fn selection_map(src_layout: ChannelLayout, dst_layout: ChannelLayout) -> Option<&'static [usize]> {
    static IDENTITY: [usize; 4] = [0, 1, 2, 3];
    Some(match (src_layout, dst_layout) {

```

--------------------------------

### Instantiate and Verify ContentLightLevel

Source: https://docs.rs/zenpixels/latest/src/zenpixels/hdr.rs.html?search=std%3A%3Avec

Demonstrates creating a new ContentLightLevel instance and verifying its default state.

```rust
    #[test]
    fn content_light_level_new() {
        let cll = ContentLightLevel::new(1000, 500);
        assert_eq!(cll.max_content_light_level, 1000);
        assert_eq!(cll.max_frame_average_light_level, 500);
    }
```

```rust
    #[test]
    fn content_light_level_default() {
        let cll = ContentLightLevel::default();
        assert_eq!(cll.max_content_light_level, 0);
        assert_eq!(cll.max_frame_average_light_level, 0);
    }
```

--------------------------------

### Handle Dimension Mismatch in from_pixels_erased

Source: https://docs.rs/zenpixels/latest/src/zenpixels/buffer.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of a test case for dimension mismatch in from_pixels_erased.

```rust
let pixels: Vec<Rgb<u8>> = vec![Rgb { r: 1, g: 2, b: 3 }];
```

--------------------------------

### Implement ConvertOptions Methods

Source: https://docs.rs/zenpixels/latest/src/zenpixels/policy.rs.html?search=

Methods for creating default configurations and modifying conversion policies.

```rust
impl ConvertOptions {
    /// Forbid all lossy operations.
    ///
    /// - Alpha removal: forbidden (returns error)
    /// - Depth reduction: forbidden (returns error)
    /// - RGB→Gray: forbidden (returns error)
    /// - Gray→RGB: broadcast (lossless)
    ///
    /// Use this as a starting point when you want to ensure no data loss,
    /// then selectively relax with `with_*` methods.
    pub const fn forbid_lossy() -> Self {
        Self {
            gray_expand: GrayExpand::Broadcast,
            alpha_policy: AlphaPolicy::Forbid,
            depth_policy: DepthPolicy::Forbid,
            luma: None,
            clip_out_of_gamut: true,
        }
    }

    /// Allow common lossy operations with sensible defaults.
    ///
    /// - Alpha removal: discard only if all pixels are opaque
    /// - Depth reduction: round to nearest
    /// - RGB→Gray: BT.709 luma coefficients
    /// - Gray→RGB: broadcast (lossless)
    pub const fn permissive() -> Self {
        Self {
            gray_expand: GrayExpand::Broadcast,
            alpha_policy: AlphaPolicy::DiscardIfOpaque,
            depth_policy: DepthPolicy::Round,
            luma: Some(LumaCoefficients::Bt709),
            clip_out_of_gamut: true,
        }
    }

    /// Set the alpha removal policy.
    pub const fn with_alpha_policy(mut self, policy: AlphaPolicy) -> Self {
        self.alpha_policy = policy;
        self
    }

    /// Set the depth reduction policy.
    pub const fn with_depth_policy(mut self, policy: DepthPolicy) -> Self {
        self.depth_policy = policy;
        self
    }

    /// Set the grayscale expansion method.
    pub const fn with_gray_expand(mut self, expand: GrayExpand) -> Self {
        self.gray_expand = expand;
        self
    }

    /// Set whether f32 transfer conversions clamp to [0, 1] (`true`, default)
    /// or preserve extended-range values via sign-preserving transfers
    /// (`false`). u8/u16 outputs always clip.
    pub const fn with_clip_out_of_gamut(mut self, clip: bool) -> Self {
        self.clip_out_of_gamut = clip;
        self
    }

    /// Set the luma coefficients for RGB→Gray conversion.
    ///
    /// Pass `None` to forbid RGB→Gray conversion.
    pub const fn with_luma(mut self, luma: Option<LumaCoefficients>) -> Self {
        self.luma = luma;
        self
    }
}
```

--------------------------------

### Alpha Premultiplication Test

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/converter.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initial setup for testing straight to premultiplied alpha conversion.

```rust
    #[test]
    fn straight_to_premul_u8() {
        let straight = PixelDescriptor::RGBA8_SRGB;
```

--------------------------------

### ConvertPlan Creation Methods

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.ConvertPlan.html?search=

Methods to initialize a conversion plan, optionally with explicit policy enforcement.

```rust
pub fn new( from: PixelDescriptor, to: PixelDescriptor, ) -> Result<Self, At<ConvertError>>
```

```rust
pub fn new_explicit( from: PixelDescriptor, to: PixelDescriptor, options: &ConvertOptions, ) -> Result<Self, At<ConvertError>>
```

--------------------------------

### Get nominal channel bits

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/negotiate.rs.html?search=std%3A%3Avec

Returns the nominal precision bits for a given channel type.

```rust
/// Nominal precision bits for a channel type (for ordering, not bit-exact).
///
/// F16 has 10 mantissa bits (~3.3 decimal digits) — between U8 (8 bits) and
/// U16 (16 bits).
#[allow(unreachable_patterns)] // non_exhaustive: future variants
pub(crate) fn channel_bits(ct: ChannelType) -> u16 {
    match ct {
        ChannelType::U8 => 8,
        ChannelType::F16 => 11, // 10 mantissa + 1 implicit
        ChannelType::U16 => 16,
        ChannelType::F32 => 32,
        _ => 0,
    }
}
```

--------------------------------

### Create a new ConvertPlan

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.ConvertPlan.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a conversion plan between two pixel descriptors. Panics if CMYK color models are used.

```rust
pub fn new( from: PixelDescriptor, to: PixelDescriptor, ) -> Result<Self, At<ConvertError>>
```

--------------------------------

### Check PixelBuffer properties

Source: https://docs.rs/zenpixels/latest/src/zenpixels/buffer.rs.html?search=std%3A%3Avec

Examples for checking alpha channel presence and grayscale status of a PixelBuffer.

```rust
#[test]
fn pixel_buffer_has_alpha_rgba8() {
    let buf = PixelBuffer::new(2, 2, PixelDescriptor::RGBA8_SRGB);
    assert!(buf.has_alpha());
}

#[test]
fn pixel_buffer_has_alpha_rgb8_false() {
    let buf = PixelBuffer::new(2, 2, PixelDescriptor::RGB8_SRGB);
    assert!(!buf.has_alpha());
}

#[test]
fn pixel_buffer_is_grayscale_gray8() {
    let buf = PixelBuffer::new(2, 2, PixelDescriptor::GRAY8_SRGB);
    assert!(buf.is_grayscale());
}

#[test]
fn pixel_buffer_is_grayscale_rgb8_false() {
    let buf = PixelBuffer::new(2, 2, PixelDescriptor::RGB8_SRGB);
    assert!(!buf.is_grayscale());
}
```

--------------------------------

### Reduce Pixel Formats

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/load_bearing.rs.html

Examples of reducing high-precision formats to lower-precision ones when data allows.

```rust
    #[test]
    fn rgba16_bit_replicated_reduces_to_rgba8() {
        let bytes: Vec<u8> = (0..4)
            .flat_map(|i| {
                let r = (i * 60) as u8;
                let g = (i * 30 + 10) as u8;
                let b = (i * 80 + 5) as u8;
                let a = 0xFF;
                [r, r, g, g, b, b, a, a]
            })
            .collect();
        let slice = make_slice(&bytes, 4, 1, PixelFormat::Rgba16);
        let r = slice.determine_load_bearing();
        // analyzed bool removed
        assert_eq!(r.uses_low_bits, Some(false));
        assert_eq!(r.uses_alpha, Some(false));
        let target = r.apply_to(&slice.descriptor());
        assert_eq!(target.format, PixelFormat::Rgb8);
    }
```

```rust
    #[test]
    fn rgba16_actual_high_precision_keeps_u16() {
        let bytes: Vec<u8> = (0..4)
            .flat_map(|i| {
                let r_lo = (i * 17 + 1) as u8;
                let r_hi = (i * 60) as u8;
                [r_hi, r_lo, 0, 0, 0, 0, 0xFF, 0xFF]
            })
            .collect();
        let slice = make_slice(&bytes, 4, 1, PixelFormat::Rgba16);
        let r = slice.determine_load_bearing();
        assert_eq!(r.uses_low_bits, Some(true));
    }
```

--------------------------------

### Convert Buffer with Anchor

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/adapt.rs.html?search=

Demonstrates converting linear pixel data to PQ-encoded format using an anchor point for brightness scaling.

```rust
        // already PQ-absolute (the prior behavior). 1.0 linear → PQ code 65535.
        let (lin, target) = pq16_target();
        let out = convert_buffer_with_anchor(
            &gray_rgb_f32(&[1.0]),
            1,
            1,
            packed_stride(1, lin),
            lin,
            target,
            DiffuseWhite::new(10_000.0),
        )
        .unwrap();
        let ob = out.as_slice().as_strided_bytes();
        assert_eq!(u16::from_ne_bytes([ob[0], ob[1]]), 65535);
    }
```

--------------------------------

### Demonstrate incorrect metadata handling

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/output.rs.html

An example of a common bug where pixel data and metadata diverge.

```rust
// BUG: pixels and metadata can diverge
let pixels = convert_to_p3(&buffer);
let metadata = OutputMetadata { icc: Some(srgb_icc), .. };
// ^^^ pixels are Display P3 but metadata says sRGB — wrong!
```

--------------------------------

### sub_rows_mut

Source: https://docs.rs/zenpixels/latest/src/zenpixels/buffer.rs.html?search=

Borrows a mutable sub-range of rows starting at `y` with a specified `count`. Panics if the range is out of bounds.

```APIDOC
pub fn sub_rows_mut(&mut self, y: u32, count: u32) -> PixelSliceMut<'_, P>
```

--------------------------------

### PixelDescriptor constructors

Source: https://docs.rs/zenpixels/latest/src/zenpixels/descriptor.rs.html

Examples of creating PixelDescriptor instances using full parameters or from existing pixel formats.

```rust
#[test]
    fn new_full_constructor() {
        let desc = PixelDescriptor::new_full(
            ChannelType::U8,
            ChannelLayout::Rgb,
            None,
            TransferFunction::Srgb,
            ColorPrimaries::DisplayP3,
        );
        assert_eq!(desc.primaries, ColorPrimaries::DisplayP3);
        assert_eq!(desc.transfer(), TransferFunction::Srgb);
    }

    #[test]
    fn from_pixel_format_constructor() {
        let desc = PixelDescriptor::from_pixel_format(PixelFormat::Rgba8);
        assert_eq!(desc.layout(), ChannelLayout::Rgba);
        assert_eq!(desc.transfer(), TransferFunction::Unknown);
        assert_eq!(desc.primaries, ColorPrimaries::Bt709);
    }
```

--------------------------------

### Perform Color Transformation with ZenCmsLite

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/cms_lite.rs.html?search=std%3A%3Avec

Demonstrates building a source-to-destination color transform and applying it to a pixel buffer.

```rust
let cms = ZenCmsLite;
let src = ColorProfileSource::Named(NamedProfile::DisplayP3);
let dst = ColorProfileSource::Named(NamedProfile::Srgb);
let transform = cms
    .build_source_transform(src, dst, PixelFormat::RgbF32, PixelFormat::RgbF32)
    .unwrap()
    .unwrap();

let src_px: [f32; 3] = [0.0, 1.0, 0.0];
let mut dst_px = [0.0f32; 3];
transform.transform_row(
    bytemuck::cast_slice(&src_px),
    bytemuck::cast_slice_mut(&mut dst_px),
    1,
);
```

--------------------------------

### Testing ColorProfileSource

Source: https://docs.rs/zenpixels/latest/src/zenpixels/color.rs.html?search=u32+-%3E+bool

Examples for creating and verifying ColorProfileSource variants including Named, CICP, and ICC profiles.

```rust
#[test]
    fn color_profile_source_named() {
        let src = ColorProfileSource::Named(NamedProfile::DisplayP3);
        assert_eq!(src, ColorProfileSource::Named(NamedProfile::DisplayP3));
        assert_ne!(src, ColorProfileSource::Named(NamedProfile::Srgb));
    }
```

```rust
#[test]
    fn color_profile_source_cicp() {
        let src = ColorProfileSource::Cicp(Cicp::BT2100_PQ);
        assert_eq!(src, ColorProfileSource::Cicp(Cicp::BT2100_PQ));
    }
```

```rust
#[test]
    fn color_profile_source_icc() {
        let data: &[u8] = &[1, 2, 3];
        let src = ColorProfileSource::Icc(data);
        assert_eq!(src, ColorProfileSource::Icc(&[1, 2, 3]));
    }
```

```rust
#[test]
    fn color_profile_source_debug_clone() {
        let src = ColorProfileSource::Named(NamedProfile::Srgb);
        let s = alloc::format!("{src:?}");
        assert!(s.contains("Named"));
        let src2 = src.clone();
        assert_eq!(src, src2);
    }
```

--------------------------------

### MasteringDisplay Constants and Constructor

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/hdr/struct.MasteringDisplay.html?search=

Predefined reference displays and a constructor for creating new MasteringDisplay instances.

```rust
pub const HDR10_REFERENCE: MasteringDisplay
```

```rust
pub const DISPLAY_P3_1000: MasteringDisplay
```

```rust
pub const fn new( primaries_xy: [[f32; 2]; 3], white_point_xy: [f32; 2], max_luminance: f32, min_luminance: f32, ) -> MasteringDisplay
```

--------------------------------

### Test ColorContext Initialization

Source: https://docs.rs/zenpixels/latest/src/zenpixels/color.rs.html?search=std%3A%3Avec

Demonstrates creating ColorContext from ICC data and combined ICC/CICP sources.

```rust
    #[test]
    fn color_context_from_icc() {
        let ctx = ColorContext::from_icc(vec![10, 20, 30]);
        assert!(ctx.icc.is_some());
        assert_eq!(ctx.icc.as_deref(), Some(&[10u8, 20, 30][..]));
        assert!(ctx.cicp.is_none());
    }
```

```rust
    #[test]
    #[allow(deprecated)]
    fn color_context_from_icc_and_cicp() {
        let ctx = ColorContext::from_icc_and_cicp(vec![1, 2], Cicp::BT2100_PQ);
        assert!(ctx.icc.is_some());
        assert_eq!(ctx.cicp, Some(Cicp::BT2100_PQ));
    }
```

--------------------------------

### Using ResultAtExt for Location Tracking

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/trait.ResultAtExt.html

Example demonstrating how to use the at() method to propagate errors with location information.

```rust
use whereat::{at, At, ResultAtExt};

#[derive(Debug)]
enum MyError { Oops }

fn inner() -> Result<(), At<MyError>> {
    Err(at(MyError::Oops))
}

fn outer() -> Result<(), At<MyError>> {
    inner().at()?;
    Ok(())
}
```

--------------------------------

### Determine Layout Conversion Steps

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/convert.rs.html?search=

Maps a source channel layout to a target layout, returning the necessary conversion steps.

```rust
fn layout_steps(from: ChannelLayout, to: ChannelLayout) -> Vec<ConvertStep> {
    if from == to {
        return Vec::new();
    }
    match (from, to) {
        (ChannelLayout::Bgra, ChannelLayout::Rgba) | (ChannelLayout::Rgba, ChannelLayout::Bgra) => {
            vec![ConvertStep::SwizzleBgraRgba]
        }
        (ChannelLayout::Rgb, ChannelLayout::Rgba) => vec![ConvertStep::AddAlpha],
        (ChannelLayout::Rgb, ChannelLayout::Bgra) => {
            // Single fused SIMD pass (garb::bytes::rgb_to_bgra). For non-u8
            // channel types `apply_step_u8` falls back to AddAlpha+Swizzle.
            vec![ConvertStep::RgbToBgra]
        }
        (ChannelLayout::Rgba, ChannelLayout::Rgb) => vec![ConvertStep::DropAlpha],
        (ChannelLayout::Bgra, ChannelLayout::Rgb) => {
            // BGRA -> RGBA -> RGB: swizzle then drop alpha.
            vec![ConvertStep::SwizzleBgraRgba, ConvertStep::DropAlpha]
        }
        (ChannelLayout::Gray, ChannelLayout::Rgb) => vec![ConvertStep::GrayToRgb],
        (ChannelLayout::Gray, ChannelLayout::Rgba) => vec![ConvertStep::GrayToRgba],
        (ChannelLayout::Gray, ChannelLayout::Bgra) => {
            // Gray -> RGBA -> BGRA: expand then swizzle.
            vec![ConvertStep::GrayToRgba, ConvertStep::SwizzleBgraRgba]
        }
```

--------------------------------

### Decode and Metadata Extraction

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of decoding raw pixels into a PixelBuffer and constructing color context metadata.

```rust
// Decode raw pixels
let pixels: Vec<u8> = my_codec_decode(&file_bytes)?;
let desc = PixelDescriptor::RGB8_SRGB;
let buffer = PixelBuffer::from_vec(pixels, width, height, desc)?;

// Extract color metadata for CMS integration
let color_ctx = match (icc_chunk, cicp_chunk) {
    (Some(icc), Some(cicp)) =>
        Some(Arc::new(ColorContext::from_icc_and_cicp(icc, cicp))),
    (Some(icc), None) =>
        Some(Arc::new(ColorContext::from_icc(icc))),
    (None, Some(cicp)) =>
        Some(Arc::new(ColorContext::from_cicp(cicp))),
    (None, None) => None,
};

// Track provenance for re-encoding decisions
let origin = ColorOrigin::from_icc_and_cicp(icc, cicp);
// or: ColorOrigin::from_icc(icc)
// or: ColorOrigin::from_cicp(cicp)
// or: ColorOrigin::from_gama_chrm()  // PNG gAMA+cHRM
```

--------------------------------

### macro_rules! at

Source: https://docs.rs/zenpixels/latest/zenpixels/macro.at.html

The at macro is used to wrap an error with crate metadata, requiring prior setup of crate information.

```APIDOC
## macro_rules! at

### Description
Wraps an error with crate metadata for repository links. Requires `define_at_crate_info!()` or a custom `at_crate_info()` function to be defined in the crate.

### Usage
```rust
use whereat::{at, At};

fn find_user(id: u64) -> Result<String, At<MyError>> {
    if id == 0 {
        return Err(at!(MyError::NotFound));
    }
    Ok(format!("User {}", id))
}
```
```

--------------------------------

### Determine Layout Conversion Steps

Source: https://docs.rs/zenpixels-convert/latest/src/zenpixels_convert/convert.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Maps a source channel layout to a target layout, returning the necessary conversion steps.

```rust
fn layout_steps(from: ChannelLayout, to: ChannelLayout) -> Vec<ConvertStep> {
    if from == to {
        return Vec::new();
    }
    match (from, to) {
        (ChannelLayout::Bgra, ChannelLayout::Rgba) | (ChannelLayout::Rgba, ChannelLayout::Bgra) => {
            vec![ConvertStep::SwizzleBgraRgba]
        }
        (ChannelLayout::Rgb, ChannelLayout::Rgba) => vec![ConvertStep::AddAlpha],
        (ChannelLayout::Rgb, ChannelLayout::Bgra) => {
            // Single fused SIMD pass (garb::bytes::rgb_to_bgra). For non-u8
            // channel types `apply_step_u8` falls back to AddAlpha+Swizzle.
            vec![ConvertStep::RgbToBgra]
        }
        (ChannelLayout::Rgba, ChannelLayout::Rgb) => vec![ConvertStep::DropAlpha],
        (ChannelLayout::Bgra, ChannelLayout::Rgb) => {
            // BGRA -> RGBA -> RGB: swizzle then drop alpha.
            vec![ConvertStep::SwizzleBgraRgba, ConvertStep::DropAlpha]
        }
        (ChannelLayout::Gray, ChannelLayout::Rgb) => vec![ConvertStep::GrayToRgb],
        (ChannelLayout::Gray, ChannelLayout::Rgba) => vec![ConvertStep::GrayToRgba],
        (ChannelLayout::Gray, ChannelLayout::Bgra) => {
            // Gray -> RGBA -> BGRA: expand then swizzle.
            vec![ConvertStep::GrayToRgba, ConvertStep::SwizzleBgraRgba]
        }
    }
```

--------------------------------

### ConvertOptions Configuration Methods

Source: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/policy/struct.ConvertOptions.html

Methods to initialize and configure conversion policies for image processing.

```APIDOC
## ConvertOptions Methods

### forbid_lossy()
Returns a `ConvertOptions` instance where all lossy operations are forbidden. Use this as a base to ensure no data loss.

### permissive()
Returns a `ConvertOptions` instance with common lossy operations enabled using sensible defaults.

### with_alpha_policy(policy: AlphaPolicy)
Sets the alpha removal policy.

### with_depth_policy(policy: DepthPolicy)
Sets the depth reduction policy.

### with_gray_expand(expand: GrayExpand)
Sets the grayscale expansion method.

### with_clip_out_of_gamut(clip: bool)
Sets whether f32 transfer conversions clamp to [0, 1] (default true) or preserve extended-range values.

### with_luma(luma: Option<LumaCoefficients>)
Sets the luma coefficients for RGB to Gray conversion. Pass `None` to forbid RGB to Gray conversion.
```
Tokens:
Raw