Files
craft-libs/crates/cms/src/builtin.rs
T
Dylan M. Taylor 628a235ae5 craft-cms: the changes PhotoCraft made to its copy since extraction (#858)
* craft-cms: the changes PhotoCraft made to its copy since extraction

PhotoCraft kept editing crates/cms after craft-cms was extracted from it at
storytold/photocraft@b3222ee8. This ports its 41 commits up to
storytold/photocraft@0143b148 with a three-way merge per file, keeping the
changes craft-cms made on its own (Result-returning API, white preservation,
FOGRA39, named colours, profile ID).

Ported: the .3dl shaper, Mesh header, UTF-16 and .look fixes in lutfile; the
checked ICC offsets and the per-profile curve sample budget; same_bytes and the
byte-confirmed transform cache; the blocked matrix/TRC path and the 8-bit
first-stage table; GpuMatrixShaper; cicp_rgb; the ACEScg and Dot Gain 20 %
built-ins (the latter now the default gray); bisection for a table's flat ends;
PhotoCraft spelled with a capital C in the built-in descriptions, with the
shipped coated CMYK profile's bytes as PhotoCraft regenerated them.

Not taken, because craft-cms already does it another way: Curve::inverse_table
(inverse64_many), the effective-dimension loop in multilinear interpolation,
the curve-count and mluc checks, and the .cube DOMAIN writer.

The 8-bit first-stage table checks device white as the exact path does.

Refs #779

* craft-cms: Lut3d::from_fn

PhotoCraft's proof and HDR display tables are built from a chain of several
transforms, which it wrote into Lut3d's fields. Those are private here, so
from_fn samples any RGB function, with the same size bounds as from_transform.

Refs #779

* craft-cms: README names Lut3d::from_fn
2026-11-11 18:37:23 -05:00

453 lines
20 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Built-in profiles. All are generated by this crate from published colorimetric definitions
//! (primaries, white points, transfer functions) and dedicated to the public domain (CC0-1.0),
//! so documents that embed them carry no licence obligations. See the crate README.
use std::sync::OnceLock;
use crate::Intent;
use crate::curve::{Curve, srgb_trc};
use crate::math::{self, Mat3};
use crate::pipeline::Stage;
use crate::profile::{ColorSpace, Lut, LutKind, Pcs, Profile, ProfileClass};
/// Copyright tag text of every built-in profile. It is part of the profiles' bytes, so it keeps
/// the name of the crate that first generated them.
pub const COPYRIGHT: &str = "No copyright: CC0-1.0 public domain dedication. Generated by photocraft-cms.";
/// Description of [`Builtin::CoatedFogra39`]. "FOGRA39" identifies the reference data the
/// profile is fitted to; it implies no certification, approval or endorsement by Fogra.
pub const COATED_FOGRA39_DESCRIPTION: &str = "Coated FOGRA39 (fitted, craft-cms)";
/// Copyright tag text of [`Builtin::CoatedFogra39`].
pub const COATED_FOGRA39_COPYRIGHT: &str = "No copyright: CC0-1.0 public domain dedication. Generated by craft-cms, fitted to the FOGRA39 characterisation data (source: Fogra, www.fogra.org).";
/// Identifiers of the built-in profiles.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Builtin {
/// sRGB IEC 61966-2.1 (Rec. 709 primaries, D65, sRGB transfer function).
Srgb,
/// Display P3 (DCI-P3 primaries, D65, sRGB transfer function).
DisplayP3,
/// Adobe RGB (1998)-compatible: its published primaries, D65, gamma 563/256.
AdobeRgbCompat,
/// ProPhoto-compatible: ROMM RGB primaries, D50, gamma 1.8.
ProPhotoCompat,
/// sRGB primaries with a linear transfer function.
LinearSrgb,
/// ACEScg: AP1 primaries, the ACES white point (~D60), linear transfer. The ACES working space for CG renders.
AcesCg,
/// Rec. 2020 primaries, D65, Rec. 709 transfer function.
Rec2020,
/// Gray, gamma 2.2.
GrayGamma22,
/// Gray with the sRGB transfer function (sGray): gray `v` looks like RGB `(v, v, v)` in sRGB.
SGray,
/// Gray matching Photoshop's default working gray (Dot Gain 20 %) with our own curve: a pure
/// gamma of 1.732, fitted on Photoshop 27.11's RGB → Grayscale (sRGB 64 / 128 / 192 and pure red
/// become 46 / 105 / 177 / 107, all within 1 level). Not Adobe's profile.
DotGain20Compat,
/// CIE L*a*b* D50 identity (device Lab = PCS Lab, ICC v4 encoding).
LabD50,
/// Synthetic coated-offset CMYK (300 % total ink, medium GCR); see [`crate::synth`].
CoatedCmyk,
/// Coated offset CMYK fitted to Fogra's FOGRA39 characterisation data (ISO 12647-2:2004
/// Amd 1, paper type 1/2): 330 % total ink, medium GCR. The colours of documents whose
/// CMYK profile is Coated FOGRA39 or ISO Coated v2 (see [`Builtin::stand_in_for`]).
CoatedFogra39,
}
impl Builtin {
pub const ALL: [Builtin; 13] = [
Builtin::Srgb,
Builtin::DisplayP3,
Builtin::AdobeRgbCompat,
Builtin::ProPhotoCompat,
Builtin::LinearSrgb,
Builtin::AcesCg,
Builtin::Rec2020,
Builtin::GrayGamma22,
Builtin::SGray,
Builtin::DotGain20Compat,
Builtin::LabD50,
Builtin::CoatedCmyk,
Builtin::CoatedFogra39,
];
/// Stable identifier used by commands and settings.
pub fn id(self) -> &'static str {
match self {
Builtin::Srgb => "srgb",
Builtin::DisplayP3 => "display-p3",
Builtin::AdobeRgbCompat => "adobe-rgb-compat",
Builtin::ProPhotoCompat => "prophoto-compat",
Builtin::LinearSrgb => "linear-srgb",
Builtin::AcesCg => "aces-cg",
Builtin::Rec2020 => "rec2020",
Builtin::GrayGamma22 => "gray-gamma-2.2",
Builtin::SGray => "sgray",
Builtin::DotGain20Compat => "dot-gain-20-compat",
Builtin::LabD50 => "lab-d50",
Builtin::CoatedCmyk => "coated-cmyk",
Builtin::CoatedFogra39 => "coated-fogra39",
}
}
/// Profile description (the `desc` tag).
pub fn description(self) -> &'static str {
match self {
Builtin::Srgb => "sRGB IEC61966-2.1",
Builtin::DisplayP3 => "Display P3",
Builtin::AdobeRgbCompat => "Adobe RGB (1998)-compatible (PhotoCraft)",
Builtin::ProPhotoCompat => "ProPhoto RGB-compatible (ROMM primaries, PhotoCraft)",
Builtin::LinearSrgb => "Linear sRGB (PhotoCraft)",
Builtin::AcesCg => "ACEScg (AP1, linear, PhotoCraft)",
Builtin::Rec2020 => "Rec. ITU-R BT.2020 (PhotoCraft)",
Builtin::GrayGamma22 => "Gray Gamma 2.2 (PhotoCraft)",
Builtin::SGray => "sGray (sRGB tone curve, PhotoCraft)",
Builtin::DotGain20Compat => "Dot Gain 20%-compatible (gamma 1.732, PhotoCraft)",
Builtin::LabD50 => "Lab D50 identity (PhotoCraft)",
Builtin::CoatedCmyk => crate::synth::DESCRIPTION,
Builtin::CoatedFogra39 => COATED_FOGRA39_DESCRIPTION,
}
}
/// Looks up an id (case-insensitive; a few aliases and the descriptions are accepted).
pub fn from_id(s: &str) -> Option<Builtin> {
let n: String = s.to_ascii_lowercase().chars().filter(|c| c.is_ascii_alphanumeric()).collect();
let alias = match n.as_str() {
"srgb" | "srgbiec6196621" | "srgbiec61966" => Some(Builtin::Srgb),
"p3" | "displayp3" => Some(Builtin::DisplayP3),
"adobergb" | "adobergb1998" | "adobergbcompat" | "clayrgb" => Some(Builtin::AdobeRgbCompat),
"prophoto" | "prophotorgb" | "prophotocompat" | "romm" | "rommrgb" => Some(Builtin::ProPhotoCompat),
"linearsrgb" | "srgblinear" | "linear" => Some(Builtin::LinearSrgb),
"rec2020" | "bt2020" => Some(Builtin::Rec2020),
"gray" | "graygamma22" | "gamma22" => Some(Builtin::GrayGamma22),
"sgray" | "graysrgb" => Some(Builtin::SGray),
"dotgain20" | "dotgain20compat" | "dotgain" => Some(Builtin::DotGain20Compat),
"aces-cg" | "acescg" => Some(Builtin::AcesCg),
"lab" | "labd50" | "cielab" => Some(Builtin::LabD50),
"cmyk" | "coatedcmyk" | "defaultcmyk" | "photocraftcoatedcmyk" => Some(Builtin::CoatedCmyk),
"fogra39" | "coatedfogra39" => Some(Builtin::CoatedFogra39),
_ => None,
};
alias.or_else(|| Builtin::ALL.into_iter().find(|b| b.description().eq_ignore_ascii_case(s)))
}
/// The built-in whose own description (its `desc` tag) is `name`, compared ignoring case
/// and whitespace, e.g. "sRGB IEC61966-2.1" gives [`Builtin::Srgb`]. Only exact matches:
/// for a built-in that approximates another profile, see [`Builtin::stand_in_for`].
pub fn from_profile_name(name: &str) -> Option<Builtin> {
let n = profile_name_key(name);
Builtin::ALL.into_iter().find(|b| profile_name_key(b.description()) == n)
}
/// The built-in to use in place of a profile a document names (its `desc` tag) when the
/// profile's bytes are not available, compared ignoring case and whitespace.
///
/// * A built-in's own description gives that built-in ([`Builtin::from_profile_name`]).
/// * Profiles built on the FOGRA39 characterisation data give [`Builtin::CoatedFogra39`]
/// (330 % total ink, as ISO Coated v2): Adobe's "Coated FOGRA39 (ISO 12647-2:2004)" (also
/// seen as "Coated FOGRA39") and ECI's "ISO Coated v2 (ECI)", which is made from
/// FOGRA39L, the same data.
/// * "ISO Coated v2 300% (ECI)" and every other name give `None`: the built-in would
/// separate to more ink than that profile allows.
///
/// The result is an approximation for display and separation. It describes the named
/// profile's printed colours, but its separations (black generation, ink distribution) are
/// not the named profile's. Prefer the document's own ICC bytes whenever it carries them.
pub fn stand_in_for(name: &str) -> Option<Builtin> {
const FOGRA39: [&str; 3] = ["Coated FOGRA39 (ISO 12647-2:2004)", "Coated FOGRA39", "ISO Coated v2 (ECI)"];
Builtin::from_profile_name(name).or_else(|| {
let n = profile_name_key(name);
FOGRA39.iter().any(|f| profile_name_key(f) == n).then_some(Builtin::CoatedFogra39)
})
}
/// The profile (built once per process).
pub fn profile(self) -> &'static Profile {
static CELLS: [OnceLock<Profile>; 13] = [const { OnceLock::new() }; 13];
// `ALL` lists the variants in declaration order (checked by `all_in_declaration_order`),
// so the discriminant is the cell index.
CELLS[self as usize].get_or_init(|| build(self))
}
}
/// A profile description for comparison: lowercase, without whitespace.
fn profile_name_key(s: &str) -> String {
s.chars().filter(|c| !c.is_whitespace()).flat_map(char::to_lowercase).collect()
}
/// The default profile for a colour space: sRGB, Dot Gain 20 %-compatible gray (Photoshop's default
/// working gray), the coated CMYK profile, Lab D50.
pub fn default_for(cs: ColorSpace) -> Option<&'static Profile> {
Some(match cs {
ColorSpace::Rgb => Builtin::Srgb.profile(),
ColorSpace::Gray => Builtin::DotGain20Compat.profile(),
ColorSpace::Cmyk => Builtin::CoatedCmyk.profile(),
ColorSpace::Lab => Builtin::LabD50.profile(),
_ => return None,
})
}
pub fn srgb() -> &'static Profile {
Builtin::Srgb.profile()
}
/// Gray with a linear tone curve: what a grayscale OpenEXR holds. Not a [`Builtin`], as it is
/// only assigned to such files, never offered as a working space.
pub fn linear_gray() -> &'static Profile {
static PROFILE: OnceLock<Profile> = OnceLock::new();
PROFILE.get_or_init(|| gray("Linear Gray (PhotoCraft)", Curve::Gamma(1.0)))
}
/// The ICC D65 used for the RGB spaces (chromaticity 0.3127, 0.3290).
const D65: [f64; 3] = math::xy_to_xyz(math::D65_XY);
/// A built-in RGB space: its RGB → XYZ matrix (relative to `white`) and white point.
#[derive(Clone, Copy)]
struct RgbSpace {
matrix: Mat3,
white: [f64; 3],
}
/// A built-in RGB space from primary chromaticities and a white point, evaluated in a constant
/// so that primaries that are not independent fail the build.
macro_rules! rgb_space {
($prim:expr, $white:expr) => {
match math::rgb_to_xyz_matrix($prim[0], $prim[1], $prim[2], $white) {
Some(matrix) => RgbSpace { matrix, white: $white },
None => panic!("built-in primaries are independent"),
}
};
}
const SRGB_SPACE: RgbSpace = rgb_space!([[0.64, 0.33], [0.30, 0.60], [0.15, 0.06]], D65);
const P3_SPACE: RgbSpace = rgb_space!([[0.680, 0.320], [0.265, 0.690], [0.150, 0.060]], D65);
const ADOBE_SPACE: RgbSpace = rgb_space!([[0.64, 0.33], [0.21, 0.71], [0.15, 0.06]], D65);
const ROMM_SPACE: RgbSpace = rgb_space!([[0.7347, 0.2653], [0.1596, 0.8404], [0.0366, 0.0001]], math::D50);
const BT2020_SPACE: RgbSpace = rgb_space!([[0.708, 0.292], [0.170, 0.797], [0.131, 0.046]], D65);
/// ACEScg: the AP1 primaries with the ACES white point (~D60, xy 0.32168/0.33767, the ACES 2065-1 neutral).
const AP1_SPACE: RgbSpace = rgb_space!([[0.713, 0.293], [0.165, 0.830], [0.128, 0.044]], math::xy_to_xyz([0.32168, 0.33767]));
/// Colorant matrix adapted to D50 and quantized to s15Fixed16, with each row nudged so that
/// RGB (1, 1, 1) maps exactly to the stored D50 white (keeps neutrals neutral).
fn colorants(space: RgbSpace) -> (Mat3, Option<Mat3>) {
let RgbSpace { matrix: m, white } = space;
let d50 = math::d50_quantized();
let adapt =
if (white[0] - math::D50[0]).abs() < 1e-3 && (white[2] - math::D50[2]).abs() < 1e-3 { None } else { Some(math::bradford(white, math::D50)) };
let m50 = match &adapt {
Some(a) => math::mul(a, &m),
None => {
// White already (nearly) D50: scale rows onto the exact PCS white.
let s = math::apply(&m, [1.0, 1.0, 1.0]);
let mut o = m;
for (i, row) in o.iter_mut().enumerate() {
for v in row.iter_mut() {
*v *= math::D50[i] / s[i];
}
}
o
}
};
let mut q = m50.map(|row| row.map(math::s15f16_round));
for (i, row) in q.iter_mut().enumerate() {
let err = d50[i] - row.iter().sum::<f64>();
let k = (0..3).max_by(|a, b| row[*a].abs().total_cmp(&row[*b].abs())).unwrap_or(0);
row[k] = math::s15f16_round(row[k] + err);
}
(q, adapt.map(|a| a.map(|row| row.map(math::s15f16_round))))
}
fn rgb(desc: &str, space: RgbSpace, trc: Curve) -> Profile {
let (m, chad) = colorants(space);
Profile {
version: (4, 0x30),
class: ProfileClass::Display,
color_space: ColorSpace::Rgb,
pcs: Pcs::Xyz,
rendering_intent: Intent::Perceptual,
description: desc.into(),
copyright: COPYRIGHT.into(),
white_point: math::d50_quantized(),
black_point: None,
chad,
matrix: Some(m),
trc: Some([trc.clone(), trc.clone(), trc]),
gray_trc: None,
a2b: [None, None, None],
b2a: [None, None, None],
bytes: None,
hash: Default::default(),
}
.with_encoded_bytes()
}
fn gray(desc: &str, trc: Curve) -> Profile {
Profile {
version: (4, 0x30),
class: ProfileClass::Display,
color_space: ColorSpace::Gray,
pcs: Pcs::Xyz,
rendering_intent: Intent::Perceptual,
description: desc.into(),
copyright: COPYRIGHT.into(),
white_point: math::d50_quantized(),
black_point: None,
chad: None,
matrix: None,
trc: None,
gray_trc: Some(trc),
a2b: [None, None, None],
b2a: [None, None, None],
bytes: None,
hash: Default::default(),
}
.with_encoded_bytes()
}
fn lab() -> Profile {
let ident = || Lut { kind: LutKind::Ab, inputs: 3, outputs: 3, stages: vec![Stage::Curves(vec![Curve::Identity; 3])] };
Profile {
version: (4, 0x30),
class: ProfileClass::ColorSpace,
color_space: ColorSpace::Lab,
pcs: Pcs::Lab,
rendering_intent: Intent::Perceptual,
description: Builtin::LabD50.description().into(),
copyright: COPYRIGHT.into(),
white_point: math::d50_quantized(),
black_point: None,
chad: None,
matrix: None,
trc: None,
gray_trc: None,
a2b: [Some(ident()), None, None],
b2a: [Some(ident()), None, None],
bytes: None,
hash: Default::default(),
}
.with_encoded_bytes()
}
/// The shipped FOGRA39 profile (generated by `tests/fogra39.rs`; regenerate with
/// `CRAFT_CMS_REGEN_PROFILES=1 cargo test -p craft-cms --release --test fogra39`).
pub const COATED_FOGRA39_ICC: &[u8] = include_bytes!("../profiles/craft-coated-fogra39.icc");
/// The shipped synthetic CMYK profile (generated by [`crate::synth::coated_cmyk`]; regenerate
/// with `CRAFT_CMS_REGEN_PROFILES=1 cargo test -p craft-cms --release regen`).
pub const COATED_CMYK_ICC: &[u8] = include_bytes!("../profiles/photocraft-coated-cmyk.icc");
/// Rec. 709 OETF inverse: V = 1.099 L^0.45 − 0.099 (L ≥ 0.018), 4.5 L below.
fn rec709_trc() -> Curve {
let a = 1.099;
Curve::Parametric { kind: 3, p: [1.0 / 0.45, 1.0 / a, (a - 1.0) / a, 1.0 / 4.5, 0.081, 0.0, 0.0] }
}
/// The RGB profile for an ITU-T H.273 (CICP) colour description, as a HEIF `nclx` or a video
/// stream declares it: BT.709, BT.2020 or P3-D65 primaries (codes 1, 9, 12) with the sRGB,
/// BT.709, linear or gamma 2.2/2.8 transfer (13; 1, 6, 14, 15; 8; 4; 5). `linear` means the
/// samples were already decoded to linear light, which is how PQ and HLG (16, 18) images are
/// held, since no ICC curve represents those transfers. `None` for anything else.
pub fn cicp_rgb(primaries: u16, transfer: u16, linear: bool) -> Option<Profile> {
let (prim, name) = match primaries {
1 => (SRGB_SPACE, "BT.709"),
9 => (BT2020_SPACE, "Rec. ITU-R BT.2020"),
12 => (P3_SPACE, "Display P3"),
_ => return None,
};
let transfer = if linear { 8 } else { transfer };
let builtin = match (primaries, transfer) {
(1, 13) => Some(Builtin::Srgb),
(1, 8) => Some(Builtin::LinearSrgb),
(12, 13) => Some(Builtin::DisplayP3),
(9, 1 | 6 | 14 | 15) => Some(Builtin::Rec2020),
_ => None,
};
if let Some(b) = builtin {
return Some(b.profile().clone());
}
let (trc, curve) = match transfer {
8 => (Curve::Gamma(1.0), "linear"),
13 => (srgb_trc(), "sRGB curve"),
1 | 6 | 14 | 15 => (rec709_trc(), "BT.709 curve"),
4 => (Curve::Gamma(2.2), "gamma 2.2"),
5 => (Curve::Gamma(2.8), "gamma 2.8"),
_ => return None,
};
Some(rgb(&format!("{name} {curve} (PhotoCraft)"), prim, trc))
}
fn build(b: Builtin) -> Profile {
match b {
Builtin::Srgb => rgb(b.description(), SRGB_SPACE, srgb_trc()),
Builtin::DisplayP3 => rgb(b.description(), P3_SPACE, srgb_trc()),
Builtin::AdobeRgbCompat => rgb(b.description(), ADOBE_SPACE, Curve::Gamma(563.0 / 256.0)),
Builtin::ProPhotoCompat => rgb(b.description(), ROMM_SPACE, Curve::Gamma(1.8)),
Builtin::LinearSrgb => rgb(b.description(), SRGB_SPACE, Curve::Gamma(1.0)),
Builtin::AcesCg => rgb(b.description(), AP1_SPACE, Curve::Gamma(1.0)),
Builtin::Rec2020 => rgb(b.description(), BT2020_SPACE, rec709_trc()),
Builtin::GrayGamma22 => gray(b.description(), Curve::Gamma(2.2)),
Builtin::SGray => gray(b.description(), srgb_trc()),
Builtin::DotGain20Compat => gray(b.description(), Curve::Gamma(1.732)),
Builtin::LabD50 => lab(),
// The shipped bytes are `synth::coated_cmyk()` (checked by the `regen` test).
Builtin::CoatedCmyk => shipped_cmyk(COATED_CMYK_ICC, b),
// The fit needs the measurement data, which only the tests have; the `fogra39` tests
// check that the shipped bytes parse.
Builtin::CoatedFogra39 => shipped_cmyk(COATED_FOGRA39_ICC, b),
}
}
/// A shipped CMYK profile. Should its bytes ever fail to parse, the synthetic coated profile
/// is generated instead, and failing that a CMYK profile without tables stands in (transforms
/// refuse it with an error) rather than crash.
fn shipped_cmyk(bytes: &[u8], b: Builtin) -> Profile {
Profile::parse(bytes).or_else(|_| crate::synth::coated_cmyk()).unwrap_or_else(|_| Profile {
version: (4, 0x30),
class: ProfileClass::Output,
color_space: ColorSpace::Cmyk,
pcs: Pcs::Lab,
rendering_intent: Intent::Perceptual,
description: b.description().into(),
copyright: COPYRIGHT.into(),
white_point: math::d50_quantized(),
black_point: None,
chad: None,
matrix: None,
trc: None,
gray_trc: None,
a2b: [None, None, None],
b2a: [None, None, None],
bytes: None,
hash: Default::default(),
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cicp_maps_onto_the_builtins_and_linear_bt2020() {
let desc = |p: Option<Profile>| p.map(|p| p.description);
assert_eq!(desc(cicp_rgb(1, 13, false)), Some(Builtin::Srgb.description().to_string()));
assert_eq!(desc(cicp_rgb(12, 13, false)), Some(Builtin::DisplayP3.description().to_string()));
assert_eq!(desc(cicp_rgb(9, 14, false)), Some(Builtin::Rec2020.description().to_string()));
assert_eq!(desc(cicp_rgb(1, 18, true)), Some(Builtin::LinearSrgb.description().to_string()));
// An HLG BT.2020 image decoded to linear light: BT.2020's colorants, a linear curve.
let hlg = cicp_rgb(9, 18, true).unwrap();
assert_eq!(hlg.trc, Some([Curve::Gamma(1.0), Curve::Gamma(1.0), Curve::Gamma(1.0)]));
assert_eq!(hlg.matrix, Builtin::Rec2020.profile().matrix);
assert!(hlg.description.contains("BT.2020") && hlg.description.contains("linear"), "{}", hlg.description);
assert!(Profile::parse(&hlg.to_bytes()).is_ok(), "encodes as a valid ICC profile");
// HLG and PQ have no ICC curve; unknown primaries have no profile.
assert!(cicp_rgb(9, 18, false).is_none());
assert!(cicp_rgb(9, 16, false).is_none());
assert!(cicp_rgb(2, 13, false).is_none());
assert!(cicp_rgb(u16::MAX, u16::MAX, true).is_none());
}
}