zentone 0.1.0

HDR to SDR tone mapping: classical curves (Reinhard, ACES, AgX, BT.2408, filmic), plus experimental adaptive and streaming tonemappers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Display-referred SDR↔HDR signal-level conversion utilities.
//!
//! These are NOT tone mappers — they're linear scaling and gamma
//! corrections for placing SDR content into an HDR container (or
//! vice versa) while preserving display appearance.
//!
//! Reference: BT.2408-8 §5.1 (display-referred SDR→HDR mapping).
//!
//! The three key conversions:
//!
//! 1. **100→203 cd/m² linear scaling** (§5.1.1): multiply by 2.03.
//!    Maps SDR peak white (BT.1886 100 cd/m²) to HDR Reference White
//!    (BT.2408 203 cd/m²).
//!
//! 2. **OOTF gamma adjustment** (§5.1.3.2): `L_out = L_in^1.15`.
//!    Compensates for the perceptual difference between viewing
//!    SDR at 100 cd/m² vs 203 cd/m². BBC + ARIB subjective tests
//!    confirmed 1.15–1.16 independently.
//!
//! 3. **203↔100 gamma correction** (BT.2408 Annex 11): `L_out = L_in^(1/1.08)`.
//!    Preserves shadow detail at the perceivable black threshold
//!    (0.02 cd/m²) when converting between the two SDR reference
//!    white standards.

use crate::math::powf;

/// Scale SDR linear light from 100 cd/m² peak to 203 cd/m² peak.
///
/// This is a pure linear scaling: `output = input * 2.03`.
/// BT.2408 §5.1.1.
#[inline]
pub fn scale_100_to_203(linear: f32) -> f32 {
    linear * 2.03
}

/// Scale HDR linear light from 203 cd/m² peak to 100 cd/m² peak.
#[inline]
pub fn scale_203_to_100(linear: f32) -> f32 {
    linear / 2.03
}

/// Apply the OOTF gamma adjustment for SDR→HDR appearance matching.
///
/// `L_out = L_in^gamma` where `gamma` is typically 1.15 (BBC) or
/// 1.16 (ARIB). BT.2408 §5.1.3.2.
///
/// Use after [`scale_100_to_203`] to produce an HDR signal that
/// subjectively matches the SDR appearance on a 203 cd/m² display.
#[inline]
pub fn ootf_gamma_adjust(linear: f32, gamma: f32) -> f32 {
    if linear <= 0.0 {
        return 0.0;
    }
    powf(linear, gamma)
}

/// Apply the 203↔100 cd/m² gamma correction (BT.2408 Annex 11).
///
/// `gamma = 1/1.08 ≈ 0.926`. Preserves shadow detail at the
/// perceivable black threshold (0.02 cd/m²).
///
/// Use when the SDR base targets 100 cd/m² but the gain map system
/// assumes 203 cd/m² (or vice versa).
#[inline]
pub fn gamma_203_to_100(linear: f32) -> f32 {
    if linear <= 0.0 {
        return 0.0;
    }
    powf(linear, 1.0 / 1.08)
}

/// Inverse of [`gamma_203_to_100`].
#[inline]
pub fn gamma_100_to_203(linear: f32) -> f32 {
    if linear <= 0.0 {
        return 0.0;
    }
    powf(linear, 1.08)
}

/// BT.2408 recommended OOTF gamma for BBC viewing conditions.
pub const OOTF_GAMMA_BBC: f32 = 1.15;

/// BT.2408 recommended OOTF gamma for ARIB viewing conditions.
pub const OOTF_GAMMA_ARIB: f32 = 1.16;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn scale_roundtrip() {
        let v = 0.5_f32;
        let up = scale_100_to_203(v);
        let back = scale_203_to_100(up);
        assert!((back - v).abs() < 1e-6);
    }

    #[test]
    fn scale_203_at_peak() {
        let out = scale_100_to_203(1.0);
        assert!((out - 2.03).abs() < 1e-5);
    }

    #[test]
    fn ootf_at_unity() {
        // gamma^1.0 = 1.0 for any gamma
        let out = ootf_gamma_adjust(1.0, OOTF_GAMMA_BBC);
        assert!((out - 1.0).abs() < 1e-5);
    }

    #[test]
    fn ootf_darkens_midtones() {
        // gamma > 1 → mid-gray gets darker
        let out = ootf_gamma_adjust(0.5, OOTF_GAMMA_BBC);
        assert!(out < 0.5, "OOTF should darken mid-gray: {out}");
    }

    #[test]
    fn gamma_203_100_roundtrip() {
        let v = 0.3_f32;
        let down = gamma_203_to_100(v);
        let back = gamma_100_to_203(down);
        assert!((back - v).abs() < 1e-5, "roundtrip: {back} vs {v}");
    }

    #[test]
    fn gamma_preserves_black() {
        assert_eq!(gamma_203_to_100(0.0), 0.0);
        assert_eq!(gamma_100_to_203(0.0), 0.0);
    }
}