5a24289898fd
tone.rs
//! Tone shaping in display (sRGB-encoded) space: the tone profiles, the tone sliders, and the
//! lab-scanner look of a lifted toe (fade) and a soft shoulder (glow).
use crate::{Params, finite};
/// The tone profiles: three families, as lab-style negative conversion software offers them.
///
/// - **Linear**: a flat, neutral start, a straight line between the black and white points;
/// `Deep` darkens the mid-tones, `Flat` lifts black and lowers white a little.
/// - **Cinematic**: smooth, low-contrast mid-tones and shadows with strong highlight
/// separation, the look of scanned cine film; `Flat` lifts the toe further, `Rich` adds
/// contrast.
/// - **Lab**: the contrast of a lab scanner, tones close to clipping. `Standard` is the
/// default; the others change the steepness on one side or both.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Tone {
Linear,
LinearDeep,
LinearFlat,
Cinematic,
CinematicFlat,
CinematicRich,
LabSoft,
#[default]
LabStandard,
LabHard,
LabHighlightSoft,
LabHighlightHard,
LabShadowSoft,
LabShadowHard,
}
/// A profile's shape: logistic steepness on the shadow and highlight sides (0 = straight),
/// a black lift, a white ceiling and a mid-tone gamma.
#[derive(Clone, Copy, Debug, PartialEq)]
struct Profile {
k_lo: f32,
k_hi: f32,
lift: f32,
ceiling: f32,
gamma: f32,
}
impl Tone {
/// Every profile with its parameter name, in menu order.
pub const ALL: [(Tone, &'static str); 13] = [
(Tone::Linear, "linear"),
(Tone::LinearDeep, "linear_deep"),
(Tone::LinearFlat, "linear_flat"),
(Tone::Cinematic, "cinematic"),
(Tone::CinematicFlat, "cinematic_flat"),
(Tone::CinematicRich, "cinematic_rich"),
(Tone::LabSoft, "lab_soft"),
(Tone::LabStandard, "lab_standard"),
(Tone::LabHard, "lab_hard"),
(Tone::LabHighlightSoft, "lab_highlight_soft"),
(Tone::LabHighlightHard, "lab_highlight_hard"),
(Tone::LabShadowSoft, "lab_shadow_soft"),
(Tone::LabShadowHard, "lab_shadow_hard"),
];
pub fn parse(s: &str) -> Option<Self> {
Self::ALL.iter().find(|(_, name)| *name == s).map(|(t, _)| *t)
}
pub fn name(self) -> &'static str {
Self::ALL.iter().find(|(t, _)| *t == self).map_or("linear", |(_, name)| name)
}
/// The profile's mid-tone gamma (> 1 darkens), applied with brightness by the converter.
pub fn gamma(self) -> f32 {
self.profile().gamma
}
fn profile(self) -> Profile {
let p = |k_lo, k_hi, lift, ceiling, gamma| Profile { k_lo, k_hi, lift, ceiling, gamma };
match self {
Self::Linear => p(0.0, 0.0, 0.0, 1.0, 1.0),
Self::LinearDeep => p(0.0, 0.0, 0.0, 1.0, 1.15),
Self::LinearFlat => p(0.0, 0.0, 0.04, 0.97, 1.0),
Self::Cinematic => p(1.5, 3.5, 0.03, 1.0, 0.95),
Self::CinematicFlat => p(1.0, 2.5, 0.06, 0.98, 0.95),
Self::CinematicRich => p(2.5, 4.5, 0.0, 1.0, 1.05),
Self::LabSoft => p(2.5, 2.5, 0.0, 1.0, 1.0),
Self::LabStandard => p(4.0, 4.0, 0.0, 1.0, 1.0),
Self::LabHard => p(6.0, 6.0, 0.0, 1.0, 1.0),
Self::LabHighlightSoft => p(4.0, 2.0, 0.0, 1.0, 1.0),
Self::LabHighlightHard => p(4.0, 6.5, 0.0, 1.0, 1.0),
Self::LabShadowSoft => p(2.0, 4.0, 0.0, 1.0, 1.0),
Self::LabShadowHard => p(6.5, 4.0, 0.0, 1.0, 1.0),
}
}
}
/// Steepness the contrast slider adds at ±50.
const CONTRAST_STEEPNESS: f32 = 4.0;
/// Steepest logistic allowed.
const MAX_STEEPNESS: f32 = 10.0;
/// The folded tone curve of one conversion.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Curve {
/// Logistic steepness on the shadow and highlight sides; both ≤ 0 means "towards flat"
/// by `−k / MAX_STEEPNESS`.
k_lo: f32,
k_hi: f32,
lights: f32,
darks: f32,
/// Black lift (positive fade and the profile's lift) and shadow expansion (negative fade).
lift: f32,
expand_lows: f32,
ceiling: f32,
/// Highlight compression (positive glow) and expansion (negative glow).
glow: f32,
expand_highs: f32,
soft_highs: f32,
soft_lows: f32,
}
impl Curve {
pub fn new(p: &Params) -> Self {
let prof = p.tone.profile();
let contrast = finite(p.contrast, 0.0).clamp(-50.0, 50.0) / 50.0 * CONTRAST_STEEPNESS;
let fade = finite(p.fade, 0.0).clamp(-100.0, 100.0) / 100.0;
let glow = finite(p.glow, 0.0).clamp(-100.0, 100.0) / 100.0;
Self {
k_lo: (prof.k_lo + contrast).clamp(-MAX_STEEPNESS, MAX_STEEPNESS),
k_hi: (prof.k_hi + contrast).clamp(-MAX_STEEPNESS, MAX_STEEPNESS),
lights: finite(p.lights, 0.0).clamp(-50.0, 50.0) / 100.0,
darks: finite(p.darks, 0.0).clamp(-50.0, 50.0) / 100.0,
lift: prof.lift + fade.max(0.0) * 0.2,
expand_lows: (-fade).max(0.0) * 2.0,
ceiling: prof.ceiling,
glow: glow.max(0.0) * 2.0,
expand_highs: (-glow).max(0.0) * 2.0,
soft_highs: finite(p.soft_highs, 0.0).clamp(0.0, 100.0) / 100.0 * 2.0,
soft_lows: finite(p.soft_lows, 0.0).clamp(0.0, 100.0) / 100.0 * 2.0,
}
}
/// True when the curve changes nothing, so a host can skip the encode / decode around it.
pub fn is_identity(&self) -> bool {
self.k_lo.abs() <= 1e-6
&& self.k_hi.abs() <= 1e-6
&& self.lights == 0.0
&& self.darks == 0.0
&& self.lift <= 0.0
&& self.expand_lows <= 0.0
&& self.ceiling >= 1.0
&& self.glow <= 0.0
&& self.expand_highs <= 0.0
&& self.soft_highs <= 0.0
&& self.soft_lows <= 0.0
}
/// `x` (sRGB-encoded, 0..1) through the curve, 0..1.
pub fn apply(&self, x: f32) -> f32 {
let mut y = finite(x, 0.0).clamp(0.0, 1.0);
// The contrast S: one symmetric logistic per side (each pinned at 0, ½ and 1), blended
// across the middle so the join is smooth and mid-grey stays where it is.
if (self.k_lo - self.k_hi).abs() <= 1e-6 {
y = s_curve(y, self.k_lo);
} else {
let w = smoothstep((y - 0.3) / 0.4);
y = s_curve(y, self.k_lo) * (1.0 - w) + s_curve(y, self.k_hi) * w;
}
// Bumps centred on the shadows (⅓) and highlights (⅔), zero at both ends.
y += self.darks * 3.0 * y * (1.0 - y) * (1.0 - y);
y += self.lights * 3.0 * y * y * (1.0 - y);
y = y.clamp(0.0, 1.0);
// Shadow and highlight tonality: expansion steepens an end, compression softens it.
if self.expand_lows > 0.0 {
y = remap(y, 0.0, 0.5, |t| compress_top(t, self.expand_lows));
}
if self.expand_highs > 0.0 {
y = remap(y, 0.5, 1.0, |t| compress_bottom(t, self.expand_highs));
}
if self.glow > 0.0 {
y = remap(y, 0.5, 1.0, |t| compress_top(t, self.glow));
}
if self.soft_lows > 0.0 {
y = remap(y, 0.0, 0.3, |t| compress_bottom(t, self.soft_lows));
}
if self.soft_highs > 0.0 {
y = remap(y, 0.7, 1.0, |t| compress_top(t, self.soft_highs));
}
// Lift and ceiling last, so black and white land where the profile and fade say.
if self.lift > 0.0 || self.ceiling < 1.0 {
y = self.lift + y * (self.ceiling - self.lift);
}
y.clamp(0.0, 1.0)
}
}
fn sigmoid(x: f32) -> f32 {
1.0 / (1.0 + libm::expf(-x))
}
/// A symmetric contrast curve through (0, 0), (½, ½) and (1, 1): a logistic of steepness `k`
/// when `k > 0`, a pull towards flat when `k < 0`, identity at 0.
fn s_curve(y: f32, k: f32) -> f32 {
if k > 1e-6 {
let half = sigmoid(k * 0.5) - 0.5;
(0.5 + 0.5 * (sigmoid(k * (y - 0.5)) - 0.5) / half).clamp(0.0, 1.0)
} else if k < -1e-6 {
y + (0.5 - y) * (-k / MAX_STEEPNESS)
} else {
y
}
}
fn smoothstep(x: f32) -> f32 {
let x = x.clamp(0.0, 1.0);
x * x * (3.0 - 2.0 * x)
}
/// `t` in 0..1 with its slope reduced towards 1 (Reinhard with the white point kept at 1).
fn compress_top(t: f32, a: f32) -> f32 {
t * (1.0 + a) / (1.0 + a * t)
}
/// `t` in 0..1 with its slope reduced towards 0.
fn compress_bottom(t: f32, a: f32) -> f32 {
1.0 - compress_top(1.0 - t, a)
}
/// `y` with `f` applied to the part of it inside `lo..hi` (unchanged outside).
fn remap(y: f32, lo: f32, hi: f32, f: impl Fn(f32) -> f32) -> f32 {
if y <= lo || y >= hi {
return y;
}
lo + f((y - lo) / (hi - lo)) * (hi - lo)
}
#[cfg(test)]
mod tests {
use super::*;
fn curve(p: Params) -> Curve {
Curve::new(&p)
}
fn linear() -> Params {
Params { tone: Tone::Linear, ..Params::default() }
}
#[test]
fn names_round_trip_and_default_is_lab_standard() {
for (tone, name) in Tone::ALL {
assert_eq!(Tone::parse(name), Some(tone));
assert_eq!(tone.name(), name);
}
assert_eq!(Tone::parse("lab"), None);
assert_eq!(Tone::default(), Tone::LabStandard);
assert_eq!(Params::default().tone, Tone::LabStandard);
}
#[test]
fn linear_profile_is_identity_and_every_profile_is_monotonic_and_pinned() {
let c = curve(linear());
assert!(c.is_identity());
for x in [0.0, 0.25, 0.5, 0.75, 1.0] {
assert!((c.apply(x) - x).abs() < 1e-6);
}
for (tone, name) in Tone::ALL {
let c = curve(Params { tone, ..Params::default() });
let mut last = -1.0;
for i in 0..=200 {
let y = c.apply(i as f32 / 200.0);
assert!(y >= last - 1e-5, "{name} not monotonic at {i}: {y} < {last}");
last = y;
}
let lo = c.apply(0.0);
let hi = c.apply(1.0);
assert!((0.0..=0.07).contains(&lo) && (0.96..=1.0).contains(&hi), "{name}: ends {lo} {hi}");
if tone != Tone::Linear && tone != Tone::LinearDeep {
assert!(!c.is_identity(), "{name}");
}
}
}
#[test]
fn lab_profiles_order_by_steepness_on_each_side() {
let at = |tone, x: f32| curve(Params { tone, ..Params::default() }).apply(x);
assert!(at(Tone::LabHard, 0.25) < at(Tone::LabStandard, 0.25) && at(Tone::LabStandard, 0.25) < at(Tone::LabSoft, 0.25));
assert!(at(Tone::LabHard, 0.75) > at(Tone::LabStandard, 0.75) && at(Tone::LabStandard, 0.75) > at(Tone::LabSoft, 0.75));
// Highlight-side variants leave the shadows where Standard has them, and mid-grey stays put.
assert!((at(Tone::LabHighlightHard, 0.15) - at(Tone::LabStandard, 0.15)).abs() < 1e-5);
assert!((at(Tone::LabHighlightSoft, 0.5) - 0.5).abs() < 1e-5 && (at(Tone::LabShadowHard, 0.5) - 0.5).abs() < 1e-5);
assert!(at(Tone::LabHighlightHard, 0.85) > at(Tone::LabStandard, 0.85));
assert!(at(Tone::LabHighlightSoft, 0.85) < at(Tone::LabStandard, 0.85));
assert!(at(Tone::LabShadowHard, 0.15) < at(Tone::LabStandard, 0.15));
assert!(at(Tone::LabShadowSoft, 0.15) > at(Tone::LabStandard, 0.15));
// Cinematic: flatter shadows than Lab Standard, a lifted toe, separated highlights.
assert!(at(Tone::Cinematic, 0.0) > 0.0 && at(Tone::Cinematic, 0.2) > at(Tone::LabStandard, 0.2));
assert!(Tone::LinearDeep.gamma() > 1.0 && Tone::Cinematic.gamma() < 1.0 && Tone::LabStandard.gamma() == 1.0);
assert!(at(Tone::LinearFlat, 0.0) > 0.0 && at(Tone::LinearFlat, 1.0) < 1.0);
}
#[test]
fn contrast_slider_adds_and_removes_steepness() {
let more = curve(Params { contrast: 30.0, ..Params::default() }).apply(0.25);
let standard = curve(Params::default()).apply(0.25);
let less = curve(Params { contrast: -50.0, ..linear() }).apply(0.25);
assert!(more < standard, "{more} {standard}");
assert!(less > 0.25, "negative contrast on a straight line flattens: {less}");
assert!(curve(Params { contrast: -50.0, ..linear() }).apply(0.0) > 0.0);
}
#[test]
fn lights_darks_fade_glow_and_soft_ends_act_where_they_should() {
let lin = linear();
let darks = curve(Params { darks: 50.0, ..lin });
assert!(darks.apply(0.3) > 0.3 && (darks.apply(0.3) - 0.3) > (darks.apply(0.9) - 0.9), "darks lift the low end most");
let lights = curve(Params { lights: -50.0, ..lin });
assert!(lights.apply(0.7) < 0.7 && (0.7 - lights.apply(0.7)) > (0.1 - lights.apply(0.1)), "lights act on the high end");
let fade = curve(Params { fade: 100.0, ..lin });
assert!((fade.apply(0.0) - 0.2).abs() < 1e-6 && (fade.apply(1.0) - 1.0).abs() < 1e-6);
let unfade = curve(Params { fade: -100.0, ..lin });
assert!(unfade.apply(0.1) > 0.1 && unfade.apply(0.0) == 0.0 && (unfade.apply(0.5) - 0.5).abs() < 1e-6, "negative fade steepens the shadows");
let glow = curve(Params { glow: 100.0, ..lin });
assert!(glow.apply(0.75) > 0.75 && (glow.apply(1.0) - 1.0).abs() < 1e-6 && (glow.apply(0.5) - 0.5).abs() < 1e-6);
assert!(glow.apply(0.99) - glow.apply(0.9) < 0.09, "the shoulder compresses the top");
let unglow = curve(Params { glow: -100.0, ..lin });
assert!(unglow.apply(0.75) < 0.75 && (unglow.apply(1.0) - 1.0).abs() < 1e-6, "negative glow expands the highlights");
let soft = curve(Params { soft_highs: 100.0, soft_lows: 100.0, ..lin });
assert!((soft.apply(0.5) - 0.5).abs() < 1e-6 && soft.apply(0.85) > 0.85 && soft.apply(0.15) < 0.15);
assert!(soft.apply(0.02) < 0.02 * 0.6 && (1.0 - soft.apply(0.98)) < 0.02 * 0.6, "flatter at both ends");
assert!(curve(Params { fade: f32::NAN, glow: f32::INFINITY, darks: -1e9, ..lin }).apply(f32::NAN).is_finite());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.