Files
craft-libs/crates/cms/README.md
T
aiongg 1f0d815477 craft-cms: map device white to device white on every path
With a LUT destination, sRGB white came out as 0.3-0.5 % C/M/Y through
Transform::eval and precise float conversions: the legacy Lab encoding
puts L* 100 at 0.996 and a* = 0 at 0.50001, between the BToA grid
nodes, and fix_white only patched the device-link node, so only the
table paths were right.

Transform: for every intent but absolute colorimetric (and proofs
without paper simulation), a pixel equal to the source's device white
gives exactly the destination's device white. fix_white still sets the
device-link node; the paths that do not read that node exactly (the
exact pipeline, float interpolation, and 8-bit lookups when white is no
node) compare each pixel with white once. No other colour changes.
device_white(Lab) had a* = b* = 0.5; Lab white is 128/255 in the v4
encoding, which is no node of the 33-point grid, so Lab sources take
the per-pixel check there too.

Profile: synth::CmykParams::white_on_node maps no ink to exactly
L* 100, a* = b* = 0 in the AToB and gives the BToA tables input curves
that put that white on a node holding no ink. The Coated FOGRA39
profile is regenerated with it and separates PCS white to 2e-5 ink
(was 0.5 %), so the step into white is as smooth as its neighbours.
The default parameters and the Photocraft profile are unchanged; its
white still falls between nodes, so its last grey step into white is
up to about 0.4 % C larger than the one before, as with lcms's
white-node fix, and the test allows that for this profile.

FOGRA39 accuracy against 16a66e1: AToB against the patches unchanged
(mean 0.07, p95 0.18, max 0.53 ΔE00), reference sRGB values unchanged
(max 0.76), Lab -> CMYK -> Lab p95 1.04 -> 1.07, max 2.54 -> 2.55
(mean 0.24).
2026-10-13 01:50:14 +00:00

9.7 KiB
Raw Blame History

Craft CMS

craft-cms is a pure-Rust ICC colour management module for the Craft suite: profile parsing and writing, transforms between profiles, rendering intents, black point compensation, soft proofing, gamut checks, 3D LUTs and a set of built-in profiles. No C, no unsafe, and no dependency on other craft-libs crates. Implemented from the public ICC.1:2010 (v4.3) and ICC.1:2001-04 (v2) specifications, CIE 15, and Adobe's published black point compensation paper.

Extracted from PhotoCraft's crates/cms at b3222ee (refs #36).

API

use craft_cms::{Builtin, Intent, Profile, Transform};

let src = Profile::parse(&icc_bytes)?;                    // v2/v4: matrix/TRC, gray TRC, mft1/mft2/mAB/mBA
let dst = Builtin::CoatedCmyk.profile();
let t = Transform::new(&src, dst, Intent::RelativeColorimetric, /*bpc*/ true)?;
t.convert_u8(&rgba8, 4, &mut cmyka8, 5, /*copy alpha*/ true)?;  // also convert_u16 / convert_f32 / apply (in place)
let mut out = [0.0; 4];
t.eval(&[1.0, 0.0, 0.0], &mut out)?;                       // exact single colour

Calls never panic on caller input: strides below the channel count, buffers that are not whole pixels, a destination with fewer pixels than the source, slices shorter than the channel count and out-of-range table or LUT dimensions return CmsError::InvalidArgument. Buffers are checked once per call, before any pixel is written.

  • Transform::proof(src, proof, display, intent, bpc, simulate_paper): soft-proof chain.
  • GamutCheck::new(src, proof, ΔE): out-of-gamut test (gamut warning).
  • Lut3d::from_transform(&t, 33)?.to_rgba16f_bytes(): display transform as a 3D texture.
  • transform::cached(src, dst, opts): process-wide transform cache.
  • lutfile::parse(name, bytes) / lutfile::write_cube(&lut): .cube, .3dl and .look LUT files; lutfile::builtin(id) returns generated looks (lutfile::BUILTIN).
  • Profile::to_bytes(): original bytes of parsed profiles (byte-exact), or an ICC v4.3 encoding.
  • Builtin::from_profile_name(desc): the built-in for a profile a document names (see Selecting by profile name).
  • Profile::same_colors(&other): the same colour space whatever the encoding (every sample of a device grid within ΔE 0.5 through both), e.g. Photoshop's sRGB IEC61966-2.1 and the built-in sRGB. content_hash() compares bytes and suits cache keys only.

Evaluation

  • Exact path: a float stage pipeline (curves, matrices, CLUTs, Lab↔XYZ, PCS encodings, BPC / absolute scaling). Float buffers use it by default (TransformOptions::precise_float).
  • Integer buffers: matrix/TRC chains use per-code input tables + matrix + output tables indexed by x^(1/4) (accurate near black even for pure gamma curves); chains containing a CLUT are sampled into a device link (33³ for 3 inputs, 17⁴ for 4, 4096 for 1) evaluated with tetrahedral interpolation (4D: linear on the first input between two tetrahedra); purely analytic chains (e.g. Lab ↔ RGB) are evaluated exactly. Buffers ≥ 16k pixels run on rayon (native only).
  • Rendering intents: AToB0/1/2 and BToA0/1/2 by intent with AToB0/BToA0 fallback; absolute colorimetric scales by media white (wtpt; v2 display profiles treated as D50; a zero, negative or non-finite white is refused with CmsError::Invalid); BPC uses neutral black points (Y only) mapped linearly in XYZ.
  • White: except in absolute colorimetric (and soft proofs that simulate paper), the source's device white comes out as exactly the destination's (no ink, or 1.0) on every path. LUT profiles rarely put white on a grid node, so the device link's white node is set to it and the exact and float paths compare each pixel with white; all other colours are left as the profiles give them. With a profile whose white falls between its nodes (coated-cmyk: 0.4 % C), the last step to white is that much larger than its neighbours.

Built-in profiles (all CC0-1.0, generated by this crate)

The profile descriptions and copyright text keep the PhotoCraft names they were first published with, so profiles embedded in existing files still match byte for byte.

id description
srgb sRGB IEC61966-2.1 (Rec. 709 primaries, D65 Bradford-adapted, sRGB TRC)
display-p3 Display P3
adobe-rgb-compat Adobe RGB (1998)-compatible (published primaries, gamma 563/256)
prophoto-compat ProPhoto-compatible (ROMM primaries, D50, gamma 1.8)
linear-srgb sRGB primaries, linear
rec2020 Rec. 2020 primaries, Rec. 709 OETF
gray-gamma-2.2, sgray gray gamma 2.2; gray with the sRGB curve (default gray working space)
lab-d50 Lab identity (v4 encoding)
coated-cmyk Photocraft Coated CMYK (synthetic, 300% TAC, medium GCR): default CMYK
coated-fogra39 Coated FOGRA39 (fitted, craft-cms): fitted to Fogra's FOGRA39 data, 330% TAC, medium GCR

The CMYK profiles

Adobe's CMYK profiles (U.S. Web Coated SWOP, Coated FOGRA39) are proprietary, and the freely downloadable characterisation-based profiles (ECI/FOGRA, colord, Ghostscript) carry redistribution conditions or unclear licences, so this crate generates its own. Both share the separation code in src/synth.rs: GCR black generation (starts at 20 % gray component, K max 95 %), a bounded least-squares CMY solve under the total ink limit, and perceptual tables with L* black-point scaling and soft chroma compression against a sampled gamut boundary.

coated-cmyk (profiles/photocraft-coated-cmyk.icc, 237 KB, AToB 11⁴ lut16, BToA 21³ lut16) comes from a Yule–Nielsen modified Neugebauer model (n = 2) over the 16 overprints with ISO 12647-2 coated-paper Lab aims for paper/C/M/Y/RGB overprints, parabolic dot gain (14 % CMY, 17 % K at 50 %) and a 300 % ink limit. It is a plausible coated-offset profile, not a measured characterisation: its midtones are darker than FOGRA39 (mean ΔE00 6.7 against the FOGRA39 patches, oranges such as 0/50/100/0 about 5 ΔE00 off).

coated-fogra39 (profiles/craft-coated-fogra39.icc, 713 KB, AToB 11⁴ lut16, BToA 33³ lut16, 330 % ink limit) reproduces the colours of documents set up for Coated FOGRA39 or ISO Coated v2. It is fitted to Fogra's FOGRA39 characterisation data (tests/data/FOGRA39.txt, 1617 IT8.7/4 patches, CMYK with D50 XYZ and Lab; ISO 12647-2:2004 Amd 1 offset on paper type 1/2): a Yule–Nielsen modified Neugebauer model with free overprints, per-ink tone curves and a fitted n (1.45) is solved by least squares against all patches (mean ΔE00 1.1 on its own), then a Gaussian-kernel ridge regression of the remaining Lab errors over CMYK (σ = 0.2, λ = 0.01) corrects it before the AToB table is sampled, with no ink mapped to exactly L* 100, a* = b* = 0. The BToA tables invert that AToB table; their input curves put that white on a grid node holding no ink (CmykParams::white_on_node), so the profile separates PCS white to within 2·10⁻⁵ ink on its own.

Through the AToB, relative colorimetric, against the 1617 FOGRA39 patches mean ΔE00 p95 max
coated-fogra39 0.07 0.18 0.53
coated-fogra39 fit, against the 10 % of patches held out of it 0.11 0.32 0.79
coated-cmyk 6.67 13.4 16.1

Lab → CMYK → Lab through the profile (relative colorimetric) returns colours inside the gamut within mean ΔE00 0.24 (p95 1.07, max 2.55). Converted to sRGB (relative colorimetric with black point compensation), process solids, overprints and oranges land within 0.8 ΔE00 of reference values for Coated FOGRA39 (tests/fogra39.rs).

"FOGRA39" identifies the reference data the profile is fitted to; it does not imply certification, approval or endorsement by Fogra. The data file is Fogra's, distributed unmodified with Fogra identified as the source as Fogra's terms require (see NOTICE); it is left out of the published crate, as only the tests read it.

Regenerate the profiles with

CRAFT_CMS_REGEN_PROFILES=1 cargo test -p craft-cms --release --test regen --test fogra39

Use your printer's profile for production print.

Selecting by profile name

Builtin::from_profile_name maps the profile description a document carries to a built-in, ignoring case and whitespace:

Name in the document Built-in
Coated FOGRA39 (ISO 12647-2:2004), Coated FOGRA39 coated-fogra39
ISO Coated v2 (ECI), ISO Coated v2 300% (ECI) coated-fogra39
each built-in's own description (e.g. sRGB IEC61966-2.1) that built-in
anything else None

ECI's ISO Coated v2 profiles are made from FOGRA39L, the same characterisation data as Adobe's Coated FOGRA39, so they describe the same printed colours; only their separations (ink limit, black generation) differ.

Display transforms

Page-layout and image editors usually convert CMYK for display with relative colorimetric and black point compensation. To match them, keep BPC on (the TransformOptions default):

let cmyk = Builtin::from_profile_name(&doc_profile_name).unwrap_or(Builtin::CoatedFogra39);
let t = Transform::new(cmyk.profile(), Builtin::Srgb.profile(), Intent::RelativeColorimetric, /*bpc*/ true)?;
// or: transform::cached(src, dst, TransformOptions::default())

Not implemented / approximate

  • v4.4 mpet (multiProcessElements, D2Bx/B2Dx) tags, named colour, device link and abstract profiles as transform endpoints, chad-based adaptation of v2 absolute colorimetry.
  • BPC destination black uses the BToA/AToB round trip directly (Adobe's curve fit for ill-behaved LUT profiles is not implemented); v2/v4 perceptual reference black mixing is not modelled beyond the PRMG black for v4 LUT profiles.
  • Profile ID (MD5) is not computed when writing (left zero, which the spec allows).