Module cms 

Color Management System (CMS) traits.

Defines the interface for ICC profile-based color transforms. When a CMS feature is enabled (e.g., cms-moxcms, cms-lcms2), the implementation provides ICC-to-ICC transforms. Named profile conversions (sRGB, P3, BT.2020) use hardcoded matrices and don’t require a CMS.

When codecs need a CMS

Most codecs don’t need to interact with the CMS directly. finalize_for_output handles CMS transforms internally when the OutputProfile requires one.

A codec needs CMS awareness only when:

• Decoding an image with an embedded ICC profile that doesn’t match any known CICP combination. The decoder extracts the ICC bytes and stores them on ColorContext. The CMS is used later (at encode or processing time), not during decode.

• Encoding with OutputProfile::Icc(custom_profile). The CMS builds a source→destination transform, which finalize_for_output applies row-by-row via RowTransform.

Implementing a CMS backend

To add a new CMS backend (e.g., wrapping Little CMS 2):

1. Implement ColorManagement on your backend struct.
2. build_transform should parse both ICC profiles, create an internal transform object, and return it as Box<dyn RowTransform>.
3. identify_profile should check if an ICC profile matches a known standard (sRGB, Display P3, etc.) and return the corresponding Cicp. This enables the fast path: if both source and destination are known profiles, hardcoded matrices are used instead of the CMS.
4. Feature-gate your implementation behind a cargo feature (e.g., cms-lcms2).

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
    }
}

No-op CMS

Codecs that don’t need ICC support can provide a no-op CMS whose build_transform always returns an error. This satisfies the type system while making it clear that ICC transforms are unsupported.

Traits

ColorManagement

Color management system interface.

RowTransform

Row-level color transform produced by a ColorManagement implementation.