Skip to content

LightCraft: An open-source non-destructive photo editor written by scratch in pure Rust

LRC-PRINT-JOB: print colour transform (printer / paper profiles, intent, black point compensation, print adjustment)

Atmik Shetty068caf361c49
diff --git a/crates/codecs/src/lib.rs b/crates/codecs/src/lib.rs
index c96c5334a..9886e8064 100644
--- a/crates/codecs/src/lib.rs
+++ b/crates/codecs/src/lib.rs
@@ -31,6 +31,7 @@ mod jxl;
mod jxl_encode;
mod other;
mod png_codec;
+pub mod print;
pub mod proof;
mod psd;
mod sniff;
diff --git a/crates/codecs/src/print.rs b/crates/codecs/src/print.rs
new file mode 100644
index 000000000..560e2710d
--- /dev/null
+++ b/crates/codecs/src/print.rs
@@ -0,0 +1,375 @@
+//! Print colour: a composed print page (16-bit RGB encoded with the BT.2020 / BT.709 curve, as the
+//! `Rec2020` output space renders it) to the samples a print-ready file carries, in the colour space
+//! of the chosen printer / paper profile.
+//!
+//! - **Target**: a printer / paper ICC profile (RGB, CMYK or grey; matrix or LUT based) converts the
+//! page to the device's own values. When the printer manages colour instead, the page is sent in a
+//! well-known RGB space (sRGB, Adobe RGB) and that space's profile travels with it.
+//! - **Rendering intent**: perceptual or relative colorimetric, as for soft proofing ([`ProofIntent`]).
+//! - **Black point compensation** (relative colorimetric only): the darkest colour the device holds is
+//! measured by a round trip of black through the profile, and the page's linear values are scaled
+//! so its black lands there instead of every shadow below it clipping to the same ink. Linear
+//! Rec.2020 is linear in XYZ, so with source black 0 and white 1 this is the published BPC mapping
+//! `Y' = Y·(1 − Yb) + Yb` for a neutral destination black. Perceptual tables carry their own black
+//! mapping and are left alone.
+//! - **Print adjustment**: brightness and contrast (−100..100) for prints that come out darker or
+//! flatter than the screen, on the sRGB-encoded values with black and white held. It is not shown
+//! on screen (the print is what it corrects).
+//!
+//! Everything before the profile conversion is per channel, so it folds into one 65,536-entry table
+//! indexed by the 16-bit sample; the conversion itself is moxcms's.
+//!
+//! Sources: ICC.1:2022 (rendering intents, profile classes); Adobe Systems, "Adobe Black Point
+//! Compensation" (2006, public white paper) for the black point mapping. Own design otherwise.
+
+use std::sync::Arc;
+
+use moxcms::{ColorProfile, DataColorSpace, Layout, RenderingIntent, TransformExecutor, TransformOptions};
+
+use crate::display::MAX_PROFILE_BYTES;
+use crate::proof::ProofIntent;
+use crate::space::{NamedSpace, Trc};
+
+/// Where a print's colours go.
+#[derive(Clone, Debug, PartialEq)]
+pub enum PrintTarget {
+ /// The printer manages colour: the page is sent in this RGB space, with its profile embedded.
+ Managed(NamedSpace),
+ /// A printer / paper ICC profile: the page is converted to the device's values.
+ Profile(Arc<Vec<u8>>),
+}
+
+/// How the page is rendered into the target.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct PrintColor {
+ pub intent: ProofIntent,
+ /// Map the page's black to the device's darkest (relative colorimetric only).
+ pub black_point_compensation: bool,
+ /// −100..100; 0 leaves the page as rendered.
+ pub brightness: f32,
+ /// −100..100; 0 leaves the page as rendered.
+ pub contrast: f32,
+}
+
+impl Default for PrintColor {
+ fn default() -> Self {
+ PrintColor { intent: ProofIntent::Perceptual, black_point_compensation: true, brightness: 0.0, contrast: 0.0 }
+ }
+}
+
+/// Pixels per conversion batch: bounds the temporary float buffers whatever the page size.
+const BATCH: usize = 1 << 16;
+
+/// The darkest black point compensation will lift the page's black to. A profile whose round trip
+/// says more is broken or not a print profile; leave the page alone rather than wash it out.
+const MAX_BLACK: f32 = 0.5;
+
+type Executor = Arc<dyn TransformExecutor<f32> + Send + Sync>;
+
+/// A page conversion, built once per print job and applied to every page.
+pub struct PrintTransform {
+ forward: Executor,
+ layout: Layout,
+ channels: usize,
+ icc: Arc<Vec<u8>>,
+ /// 16-bit sample → linear Rec.2020 after the print adjustment and black point compensation.
+ pre: Vec<f32>,
+ black: f32,
+ description: Option<String>,
+}
+
+impl std::fmt::Debug for PrintTransform {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("PrintTransform")
+ .field("channels", &self.channels)
+ .field("black", &self.black)
+ .field("description", &self.description)
+ .finish_non_exhaustive()
+ }
+}
+
+fn guarded<T>(f: impl FnOnce() -> Option<T>) -> Option<T> {
+ std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)).ok().flatten()
+}
+
+fn rendering_intent(intent: ProofIntent) -> RenderingIntent {
+ match intent {
+ ProofIntent::Perceptual => RenderingIntent::Perceptual,
+ ProofIntent::Relative => RenderingIntent::RelativeColorimetric,
+ }
+}
+
+/// A slider value as a finite fraction in −1..1 (NaN and infinities count as 0).
+fn amount(v: f32) -> f32 {
+ if v.is_finite() { (v / 100.0).clamp(-1.0, 1.0) } else { 0.0 }
+}
+
+/// The print adjustment on one sRGB-encoded value (0..1): brightness bends the mid-tones with a
+/// power curve, contrast steepens (or flattens) them with `e − k·sin(2πe)/2π`, which keeps black,
+/// mid grey and white where they are and stays monotonic for |k| < 1.
+pub fn print_adjust(e: f32, brightness: f32, contrast: f32) -> f32 {
+ let e = if e.is_finite() { e.clamp(0.0, 1.0) } else { 0.0 };
+ let (b, c) = (amount(brightness), amount(contrast));
+ let e = if b != 0.0 { e.powf(2f32.powf(-0.5 * b)) } else { e };
+ let k = 0.6 * c;
+ let tau = std::f32::consts::TAU;
+ (e - k * (tau * e).sin() / tau).clamp(0.0, 1.0)
+}
+
+impl PrintTransform {
+ /// Build the conversion for a target. Errors say what's wrong with the profile; nothing here
+ /// panics on a hostile one.
+ pub fn new(target: &PrintTarget, color: &PrintColor) -> Result<PrintTransform, String> {
+ let icc = match target {
+ PrintTarget::Managed(n) => Arc::new(crate::icc::write_named(*n)),
+ PrintTarget::Profile(bytes) => Arc::clone(bytes),
+ };
+ if icc.len() > MAX_PROFILE_BYTES {
+ return Err("the profile is too large".into());
+ }
+ let dev = guarded(|| ColorProfile::new_from_slice(&icc).ok()).ok_or("not a valid ICC profile")?;
+ let (layout, channels) = match dev.color_space {
+ DataColorSpace::Rgb => (Layout::Rgb, 3),
+ DataColorSpace::Cmyk => (Layout::Rgba, 4),
+ DataColorSpace::Gray => (Layout::Gray, 1),
+ _ => return Err("only RGB, CMYK and grey printer profiles can be printed to".into()),
+ };
+ let lin = crate::icc::linear_rec2020_profile();
+ let opts = |i| TransformOptions { rendering_intent: i, ..TransformOptions::default() };
+ let forward: Executor = guarded(|| lin.create_transform_f32(Layout::Rgb, &dev, layout, opts(rendering_intent(color.intent))).ok())
+ .ok_or("can't convert to this profile")?;
+
+ let black = if color.black_point_compensation && color.intent == ProofIntent::Relative {
+ let back: Executor = guarded(|| dev.create_transform_f32(layout, &lin, Layout::Rgb, opts(RenderingIntent::RelativeColorimetric)).ok())
+ .ok_or("can't convert from this profile")?;
+ device_black(&forward, &back, channels)
+ } else {
+ 0.0
+ };
+
+ let decode = Trc::Rec709.lut16();
+ let (b, c) = (color.brightness, color.contrast);
+ let adjust = amount(b) != 0.0 || amount(c) != 0.0;
+ let pre = decode
+ .iter()
+ .map(|&lin| {
+ let lin = if adjust {
+ let e = lightcraft_color::transfer::linear_to_srgb(lin.clamp(0.0, 1.0));
+ lightcraft_color::transfer::srgb_to_linear(print_adjust(e, b, c))
+ } else {
+ lin.clamp(0.0, 1.0)
+ };
+ lin * (1.0 - black) + black
+ })
+ .collect();
+ let description = crate::icc::parse(&icc).and_then(|i| i.description);
+ Ok(PrintTransform { forward, layout, channels, icc, pre, black, description })
+ }
+
+ /// Samples per pixel of the converted page: 3 (RGB), 4 (CMYK) or 1 (grey).
+ pub fn channels(&self) -> usize {
+ self.channels
+ }
+
+ /// The profile the converted samples are in: embed it with them.
+ pub fn icc(&self) -> &Arc<Vec<u8>> {
+ &self.icc
+ }
+
+ /// Whether the samples are CMYK (PDF readers show CMYK images inverted unless told otherwise,
+ /// so writers need to know).
+ pub fn is_cmyk(&self) -> bool {
+ self.layout == Layout::Rgba
+ }
+
+ /// The linear black black point compensation lifts the page's black to (0 when off).
+ pub fn black(&self) -> f32 {
+ self.black
+ }
+
+ /// The profile's description, for the job's settings and error messages.
+ pub fn description(&self) -> Option<&str> {
+ self.description.as_deref()
+ }
+
+ /// Convert a page: `rgb` is interleaved 16-bit RGB in the BT.2020 / BT.709 encoding; the result
+ /// is interleaved 16-bit device samples ([`PrintTransform::channels`] per pixel).
+ pub fn apply(&self, rgb: &[u16]) -> Result<Vec<u16>, String> {
+ if !rgb.len().is_multiple_of(3) {
+ return Err("the page isn't whole RGB pixels".into());
+ }
+ let pixels = rgb.len() / 3;
+ let ch = self.channels;
+ let out_len = pixels.checked_mul(ch).ok_or("the page is too large")?;
+ let mut out = vec![0u16; out_len];
+ let run = |src: &[u16], dst: &mut [u16]| -> Option<()> {
+ let lin: Vec<f32> = src.iter().map(|&v| self.pre.get(usize::from(v)).copied().unwrap_or(0.0)).collect();
+ let mut dev = vec![0f32; dst.len()];
+ self.forward.transform(&lin, &mut dev).ok()?;
+ for (d, v) in dst.iter_mut().zip(dev) {
+ let v = if v.is_finite() { v.clamp(0.0, 1.0) } else { 0.0 };
+ *d = (v * 65535.0 + 0.5) as u16;
+ }
+ Some(())
+ };
+ let src = rgb.chunks(BATCH * 3);
+ let dst = out.chunks_mut(BATCH * ch);
+ #[cfg(feature = "parallel")]
+ let ok = {
+ use rayon::prelude::*;
+ let pairs: Vec<_> = src.zip(dst).collect();
+ pairs.into_par_iter().all(|(s, d)| guarded(|| run(s, d)).is_some())
+ };
+ #[cfg(not(feature = "parallel"))]
+ let ok = src.zip(dst).all(|(s, d)| guarded(|| run(s, d)).is_some());
+ if ok { Ok(out) } else { Err("the profile's tables can't be applied".into()) }
+ }
+}
+
+/// The darkest the device holds, as linear Rec.2020 luminance: black there and back, relative
+/// colorimetric both ways (for a device that reaches true black, 0).
+fn device_black(forward: &Executor, back: &Executor, channels: usize) -> f32 {
+ let mut device = vec![0f32; channels];
+ let mut lin = [0f32; 3];
+ let ok = guarded(|| {
+ forward.transform(&[0.0; 3], &mut device).ok()?;
+ back.transform(&device, &mut lin).ok()
+ });
+ if ok.is_none() {
+ return 0.0;
+ }
+ // BT.2020 luminance weights
+ let y = 0.2627 * lin[0] + 0.6780 * lin[1] + 0.0593 * lin[2];
+ if y.is_finite() { y.clamp(0.0, MAX_BLACK) } else { 0.0 }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use moxcms::ToneReprCurve;
+
+ /// A page of one 16-bit pixel per linear grey level.
+ fn greys(levels: &[f32]) -> Vec<u16> {
+ levels.iter().flat_map(|&l| [(Trc::Rec709.from_linear(l) * 65535.0).round() as u16; 3]).collect()
+ }
+
+ fn convert(target: &PrintTarget, color: PrintColor, levels: &[f32]) -> Vec<u16> {
+ PrintTransform::new(target, &color).unwrap().apply(&greys(levels)).unwrap()
+ }
+
+ /// An RGB print profile whose ink can't get darker than linear 0.03: device 0 is 3 % grey.
+ fn raised_black_profile() -> Arc<Vec<u8>> {
+ let mut p = ColorProfile::new_from_slice(&crate::icc::write_named(NamedSpace::Srgb)).unwrap();
+ let (g, e) = (2.2f32, 0.03f32);
+ let a = (1.0 - e).powf(1.0 / g);
+ // ICC parametric type 4: Y = (aX + b)^g + e for X >= d, Y = cX + f below
+ let trc = ToneReprCurve::Parametric(vec![g, a, 0.0, 0.0, 0.0, e, e]);
+ p.red_trc = Some(trc.clone());
+ p.green_trc = Some(trc.clone());
+ p.blue_trc = Some(trc);
+ Arc::new(p.encode().unwrap())
+ }
+
+ #[test]
+ fn managed_srgb_keeps_black_grey_and_white() {
+ let t = PrintTransform::new(&PrintTarget::Managed(NamedSpace::Srgb), &PrintColor::default()).unwrap();
+ assert_eq!(t.channels(), 3);
+ assert_eq!(crate::icc::parse(t.icc()).and_then(|i| i.named), Some(NamedSpace::Srgb));
+ let out = t.apply(&greys(&[0.0, 0.18, 1.0])).unwrap();
+ let mid = (lightcraft_color::transfer::linear_to_srgb(0.18) * 65535.0) as i32;
+ assert!(out[..3].iter().all(|&v| v < 64), "{out:?}");
+ assert!(out[3..6].iter().all(|&v| (i32::from(v) - mid).abs() < 300), "{out:?} vs {mid}");
+ assert!(out[6..].iter().all(|&v| v > 65400), "{out:?}");
+ }
+
+ #[test]
+ fn adobe_rgb_target_embeds_its_profile() {
+ let t = PrintTransform::new(&PrintTarget::Managed(NamedSpace::AdobeRgb), &PrintColor::default()).unwrap();
+ assert_eq!(crate::icc::parse(t.icc()).and_then(|i| i.named), Some(NamedSpace::AdobeRgb));
+ // a saturated Rec.2020 green is outside Adobe RGB: it comes out at the space's edge, not wrapped
+ let px = [0u16, 65535, 0];
+ let out = t.apply(&px).unwrap();
+ assert!(out[1] > 60000 && out[0] < 8000 && out[2] < 8000, "{out:?}");
+ }
+
+ #[test]
+ fn brightness_lifts_the_mid_tones_and_holds_the_ends() {
+ let target = PrintTarget::Managed(NamedSpace::Srgb);
+ let levels = [0.0, 0.18, 1.0];
+ let plain = convert(&target, PrintColor::default(), &levels);
+ let bright = convert(&target, PrintColor { brightness: 50.0, ..PrintColor::default() }, &levels);
+ let dark = convert(&target, PrintColor { brightness: -50.0, ..PrintColor::default() }, &levels);
+ assert!(bright[3] > plain[3] + 2000 && dark[3] + 2000 < plain[3], "{dark:?} {plain:?} {bright:?}");
+ for v in [&plain, &bright, &dark] {
+ assert!(v[0] < 64 && v[6] > 65400, "{v:?}");
+ }
+ }
+
+ #[test]
+ fn contrast_spreads_shadows_and_highlights_and_stays_monotonic() {
+ let target = PrintTarget::Managed(NamedSpace::Srgb);
+ let levels = [0.03, 0.6];
+ let plain = convert(&target, PrintColor::default(), &levels);
+ let more = convert(&target, PrintColor { contrast: 60.0, ..PrintColor::default() }, &levels);
+ assert!(more[0] < plain[0] && more[3] > plain[3], "{plain:?} {more:?}");
+ for c in [-100.0, 100.0] {
+ for b in [-100.0, 100.0] {
+ let ramp: Vec<f32> = (0..=64).map(|i| i as f32 / 64.0).map(|e| print_adjust(e, b, c)).collect();
+ assert!(ramp.windows(2).all(|w| w[1] >= w[0]), "b {b} c {c}: {ramp:?}");
+ assert!(ramp[0] == 0.0 && (ramp[64] - 1.0).abs() < 1e-6);
+ }
+ }
+ }
+
+ #[test]
+ fn black_point_compensation_keeps_shadow_detail_above_the_inks_black() {
+ let target = PrintTarget::Profile(raised_black_profile());
+ let shadows = [0.0, 0.006, 0.012, 0.018, 0.024, 0.5, 1.0];
+ let relative = PrintColor { intent: ProofIntent::Relative, black_point_compensation: false, ..PrintColor::default() };
+ let clipped = convert(&target, relative, &shadows);
+ let kept = convert(&target, PrintColor { black_point_compensation: true, ..relative }, &shadows);
+ let reds = |v: &[u16]| v.chunks(3).map(|p| p[0]).collect::<Vec<_>>();
+ let (clipped, kept) = (reds(&clipped), reds(&kept));
+ // everything below the ink's black prints as (within rounding) the same device value without
+ // compensation …
+ assert!(clipped[..5].iter().all(|&v| v <= clipped[0] + 16), "{clipped:?}");
+ // … and as distinct, rising values with it; white still prints as white
+ assert!(kept[..5].windows(2).all(|w| w[1] > w[0]) && kept[4] > kept[0] + 1000, "{kept:?}");
+ assert!(kept[6] > 65400 && clipped[6] > 65400, "{kept:?} {clipped:?}");
+ let t = PrintTransform::new(&target, &PrintColor { black_point_compensation: true, ..relative }).unwrap();
+ assert!((t.black() - 0.03).abs() < 0.01, "{}", t.black());
+ }
+
+ #[test]
+ fn black_point_compensation_is_relative_colorimetric_only() {
+ let target = PrintTarget::Profile(raised_black_profile());
+ let levels = [0.0, 0.01, 0.2];
+ let with = convert(&target, PrintColor { intent: ProofIntent::Perceptual, black_point_compensation: true, ..PrintColor::default() }, &levels);
+ let without =
+ convert(&target, PrintColor { intent: ProofIntent::Perceptual, black_point_compensation: false, ..PrintColor::default() }, &levels);
+ assert_eq!(with, without);
+ let t = PrintTransform::new(&target, &PrintColor { intent: ProofIntent::Perceptual, ..PrintColor::default() }).unwrap();
+ assert_eq!(t.black(), 0.0);
+ }
+
+ #[test]
+ fn hostile_input_is_an_error_not_a_panic() {
+ let color = PrintColor::default();
+ assert!(PrintTransform::new(&PrintTarget::Profile(Arc::new(vec![])), &color).is_err());
+ assert!(PrintTransform::new(&PrintTarget::Profile(Arc::new(vec![0u8; 400])), &color).is_err());
+ assert!(PrintTransform::new(&PrintTarget::Profile(Arc::new(vec![0u8; MAX_PROFILE_BYTES + 1])), &color).is_err());
+ let good = crate::icc::write_named(NamedSpace::DisplayP3);
+ for i in (0..good.len()).step_by(7) {
+ let mut b = good.clone();
+ b[i] ^= 0x5a;
+ if let Ok(t) = PrintTransform::new(&PrintTarget::Profile(Arc::new(b)), &PrintColor { intent: ProofIntent::Relative, ..color }) {
+ let _ = t.apply(&greys(&[0.0, 0.5, 1.0]));
+ }
+ }
+ let t = PrintTransform::new(&PrintTarget::Managed(NamedSpace::Srgb), &PrintColor { brightness: f32::NAN, contrast: f32::INFINITY, ..color })
+ .unwrap();
+ assert!(t.apply(&[1, 2]).is_err(), "half a pixel");
+ assert_eq!(t.apply(&greys(&[0.18])).unwrap(), convert(&PrintTarget::Managed(NamedSpace::Srgb), color, &[0.18]));
+ assert!(print_adjust(f32::NAN, 50.0, 50.0).is_finite());
+ }
+}