ultrahdr-core 0.5.0

//! Reference parity tests against libultrahdr and libavif goldens.
//!
//! Goldens originate in `zentone/reference-checks/golden/` and are produced
//! by standalone C++ extractions of the reference implementations:
//!
//! - `libultrahdr_apply_gain.csv` — `applyGainLUT` at libultrahdr `8cbc983`
//! - `libultrahdr_compute_gain.csv` — `computeGain` at libultrahdr `8cbc983`
//! - `libavif_apply_gain.csv` — `avifGetGainMapWeight` + `avifApplyGainPixel`
//!   at libavif `58b3459`
//!
//! Per project policy these CSVs are checked in alongside the tests so the
//! crate is self-contained at publish time.
//!
//! ## Convention notes
//!
//! libultrahdr historically stored gain range in **linear** units
//! (`min_content_boost`, `max_content_boost`); libavif and ISO 21496-1 use
//! **log2**. Our [`GainMapMetadata`] uses log2. The libultrahdr golden was
//! produced with `min_boost=1.0, max_boost=4.0` linear; we feed our impl
//! `min=0.0, max=2.0` log2 to match.
//!
//! The `2.3 log2` clamp libultrahdr applies in `computeGain` when
//! `sdr < 2/255` is documented in the compute test: we **do not** match it.
//! Our compute path uses configurable `min_boost` / `max_boost` clamps via
//! [`GainMapConfig`]; users who need libultrahdr's near-black clamp set
//! `max_boost = 2^2.3 ≈ 4.925`.

use ultrahdr_core::gainmap::apply::calculate_weight;
use ultrahdr_core::{GainMapChannel, GainMapMetadata};

/// Maximum tolerated absolute error vs goldens. Tighter than 1e-6 across
/// every CSV row in practice; this is the published budget.
const TOLERANCE: f32 = 1e-5;

const GOLDEN_LIBULTRAHDR_APPLY: &str = include_str!("data/libultrahdr_apply_gain.csv");
const GOLDEN_LIBAVIF: &str = include_str!("data/libavif_apply_gain.csv");
const GOLDEN_LIBULTRAHDR_COMPUTE: &str = include_str!("data/libultrahdr_compute_gain.csv");

/// Strip `# ...` comment lines and split each remaining line on commas.
fn rows(csv: &str) -> impl Iterator<Item = Vec<&str>> {
    csv.lines()
        .map(str::trim)
        .filter(|l| !l.is_empty() && !l.starts_with('#'))
        .map(|l| l.split(',').map(str::trim).collect::<Vec<_>>())
}

/// Build metadata that matches both reference implementations' apply tests.
///
/// Range is `[gain_min_log2, gain_max_log2]`, gamma 1, offsets 1/64 — the
/// fixed parameters baked into the C++ extractors. `headroom_*` fields
/// don't affect [`apply_gain_row_presampled`]; they're irrelevant here.
fn apply_metadata(gain_min_log2: f64, gain_max_log2: f64) -> GainMapMetadata {
    let ch = GainMapChannel {
        min: gain_min_log2,
        max: gain_max_log2,
        gamma: 1.0,
        base_offset: 1.0 / 64.0,
        alternate_offset: 1.0 / 64.0,
    };
    let mut md = GainMapMetadata::default();
    md.channels = [ch; 3];
    md.base_hdr_headroom = 0.0;
    md.alternate_hdr_headroom = gain_max_log2;
    md.use_base_color_space = true;
    md
}

/// Closed-form per-pixel apply. Mirrors `GainMapLut::new` (gamma + log2
/// expansion + weight scaling) followed by `apply_gain_row_presampled`,
/// computed in float without going through the byte LUT — so the test
/// exercises the formula, not the 8-bit quantization.
fn apply_one(metadata: &GainMapMetadata, weight: f32, gain_norm: f32, base: f32) -> f32 {
    let ch = &metadata.channels[0];
    let log_min_natural = (ch.min * core::f64::consts::LN_2) as f32;
    let log_max_natural = (ch.max * core::f64::consts::LN_2) as f32;
    let gamma_undo = if ch.gamma != 1.0 && ch.gamma > 0.0 {
        gain_norm.powf(1.0 / ch.gamma as f32)
    } else {
        gain_norm
    };
    let log_gain = log_min_natural + gamma_undo * (log_max_natural - log_min_natural);
    let linear_gain = (log_gain * weight).exp();
    (base + ch.base_offset as f32) * linear_gain - ch.alternate_offset as f32
}

#[test]
fn libultrahdr_apply_gain_parity() {
    // CSV header reports min_boost=1.0 max_boost=4.0 (linear) → log2 [0, 2].
    let metadata = apply_metadata(0.0, 2.0);

    let mut tested = 0;
    let mut max_err = 0.0f32;
    for row in rows(GOLDEN_LIBULTRAHDR_APPLY) {
        // CSV has two sections: 6-col (weighted single-channel) and 9-col
        // (multi-channel). We only test the 6-col section here.
        if row.len() != 6 {
            continue;
        }
        // Skip the column-name row of the 6-col section.
        let Ok(weight): Result<f32, _> = row[0].parse() else {
            continue;
        };
        let gain_norm: f32 = row[1].parse().unwrap();
        let base: f32 = row[2].parse().unwrap();
        let expected_r: f32 = row[3].parse().unwrap();
        let expected_g: f32 = row[4].parse().unwrap();
        let expected_b: f32 = row[5].parse().unwrap();

        let out = apply_one(&metadata, weight, gain_norm, base);
        for (label, expected) in [("R", expected_r), ("G", expected_g), ("B", expected_b)] {
            let err = (out - expected).abs();
            assert!(
                err < TOLERANCE,
                "libultrahdr apply mismatch on row {row:?} channel {label}: got {out}, want {expected}, err {err}",
            );
            max_err = max_err.max(err);
        }
        tested += 1;
    }
    assert!(tested > 50, "too few rows tested: {tested}");
    eprintln!("libultrahdr_apply: {tested} rows, max_err={max_err:.3e}");
}

#[test]
fn libavif_weight_parity() {
    let mut tested = 0;
    let mut max_err = 0.0f32;
    for row in rows(GOLDEN_LIBAVIF) {
        // libavif CSV has two sections; only the weight section has 4 cols
        // with the column header `base_headroom_log2,...,weight`.
        if row.len() != 4 {
            continue;
        }
        if row[0] == "base_headroom_log2" {
            continue;
        }
        // Skip rows that are actually `gain,base,r,g,b` from the second section
        // (caught by `gain` column header, but defensive).
        let Ok(base): Result<f32, _> = row[0].parse() else {
            continue;
        };
        let alt: f32 = row[1].parse().unwrap();
        let display: f32 = row[2].parse().unwrap();
        let expected: f32 = row[3].parse().unwrap();

        // Our calculate_weight takes display_boost (linear) — convert back.
        let display_boost = (display as f64).exp2() as f32;
        let mut metadata = GainMapMetadata::default();
        metadata.base_hdr_headroom = base as f64;
        metadata.alternate_hdr_headroom = alt as f64;
        let got = calculate_weight(display_boost, &metadata);

        let err = (got - expected).abs();
        assert!(
            err < TOLERANCE,
            "libavif weight mismatch on row {row:?}: got {got}, want {expected}, err {err}",
        );
        max_err = max_err.max(err);
        tested += 1;
    }
    assert!(tested >= 5, "too few rows tested: {tested}");
    eprintln!("libavif_weight: {tested} rows, max_err={max_err:.3e}");
}

#[test]
fn libavif_apply_gain_parity() {
    // libavif's apply core uses gainMapMin=0 gainMapMax=2 (log2), gamma=1,
    // offsets=1/64, weight=1 — same metadata as the libultrahdr golden.
    let metadata = apply_metadata(0.0, 2.0);

    let mut tested = 0;
    let mut max_err = 0.0f32;
    for row in rows(GOLDEN_LIBAVIF) {
        // Apply section: 5 columns `gain,base,out_r,out_g,out_b`.
        if row.len() != 5 {
            continue;
        }
        if row[0] == "gain" {
            continue;
        }
        let Ok(gain_norm): Result<f32, _> = row[0].parse() else {
            continue;
        };
        let base: f32 = row[1].parse().unwrap();
        let expected_r: f32 = row[2].parse().unwrap();
        let expected_g: f32 = row[3].parse().unwrap();
        let expected_b: f32 = row[4].parse().unwrap();

        let out = apply_one(&metadata, 1.0, gain_norm, base);
        for (label, expected) in [("R", expected_r), ("G", expected_g), ("B", expected_b)] {
            let err = (out - expected).abs();
            assert!(
                err < TOLERANCE,
                "libavif apply mismatch on row {row:?} channel {label}: got {out}, want {expected}, err {err}",
            );
            max_err = max_err.max(err);
        }
        tested += 1;
    }
    assert!(tested >= 30, "too few rows tested: {tested}");
    eprintln!("libavif_apply: {tested} rows, max_err={max_err:.3e}");
}

#[test]
fn libultrahdr_compute_gain_documented_divergence() {
    // libultrahdr's `computeGain` clamps `log2(gain) → 2.3` when
    // `sdr < 2/255`. This is a writer-side policy specific to libultrahdr,
    // not part of ISO 21496-1.
    //
    // Our `compute_and_encode_gain` uses configurable `min_boost` /
    // `max_boost` clamps from `GainMapConfig` instead. At default
    // `max_boost = 8.0` (≈log2 3.0), values libultrahdr would clamp to
    // 2.3 we clamp to 3.0 — strictly *more* permissive.
    //
    // This test reads the golden, recomputes the raw `log2(hdr/sdr)`
    // value (no clamp), and asserts:
    //   - For rows where sdr ≥ 2/255: golden equals raw log2 exactly
    //     (proving libultrahdr only diverges at the near-black threshold).
    //   - For rows where sdr <  2/255: golden is exactly 2.3 (proving
    //     the documented clamp). We emit a warning count, not a failure,
    //     so this test serves as living documentation of the divergence.

    let two_over_255 = 2.0 / 255.0;
    let mut clamped = 0;
    let mut unclamped_checked = 0;
    for row in rows(GOLDEN_LIBULTRAHDR_COMPUTE) {
        if row.len() != 3 {
            continue;
        }
        if row[0] == "sdr" {
            continue;
        }
        let sdr: f32 = row[0].parse().unwrap();
        let hdr: f32 = row[1].parse().unwrap();
        let gain_log2: f32 = row[2].parse().unwrap();

        if sdr < two_over_255 {
            // libultrahdr clamps; assert that's what the golden shows.
            // Negative-gain rows (very dark hdr too) are also clamped on
            // the `min_log2` side via libultrahdr's own min/max — we just
            // skip those, the 2.3 ceiling is what matters here.
            if gain_log2 == 2.3f32 {
                clamped += 1;
            }
            continue;
        }
        // Our path doesn't clamp, so the raw formula must match.
        let raw = ((hdr + 1e-7) / (sdr + 1e-7)).log2();
        let err = (raw - gain_log2).abs();
        // libultrahdr also has a 1e-7 epsilon in its formula; rounding
        // through f32 keeps us within ~1e-5.
        assert!(
            err < 1e-3,
            "compute mismatch on row {row:?}: raw={raw}, golden={gain_log2}, err={err}",
        );
        unclamped_checked += 1;
    }
    assert!(
        unclamped_checked > 30,
        "too few unclamped rows: {unclamped_checked}"
    );
    assert!(clamped > 5, "no clamped rows seen: {clamped}");
    eprintln!(
        "libultrahdr_compute: {unclamped_checked} unclamped rows match raw formula, \
         {clamped} rows demonstrate the libultrahdr-specific 2.3 near-black clamp",
    );
}

#[test]
fn cross_check_libultrahdr_libavif_agree_on_apply() {
    // The two CSVs were extracted from independent C++ codebases (Google's
    // libultrahdr vs AOMediaCodec's libavif) but with metadata configured
    // to be the same physical gain (1× to 4× boost, offsets 1/64, gamma 1).
    // For every shared `(gain, base)` point at weight=1, the two implementations
    // must produce the same output — this is the cross-check that proves
    // both reference impls agree on the math, and so does ours.

    use std::collections::HashMap;
    let metadata = apply_metadata(0.0, 2.0);

    // Index libavif apply rows by (gain, base) → out_r.
    let mut avif: HashMap<(u32, u32), f32> = HashMap::new();
    for row in rows(GOLDEN_LIBAVIF) {
        if row.len() != 5 {
            continue;
        }
        if row[0] == "gain" {
            continue;
        }
        let Ok(g): Result<f32, _> = row[0].parse() else {
            continue;
        };
        let b: f32 = row[1].parse().unwrap();
        let r: f32 = row[2].parse().unwrap();
        // Hash by bit pattern (avoid f32 hash issues).
        avif.insert((g.to_bits(), b.to_bits()), r);
    }

    let mut shared = 0;
    for row in rows(GOLDEN_LIBULTRAHDR_APPLY) {
        if row.len() != 6 {
            continue;
        }
        let Ok(weight): Result<f32, _> = row[0].parse() else {
            continue;
        };
        if (weight - 1.0).abs() > 1e-6 {
            continue;
        }
        let gain: f32 = row[1].parse().unwrap();
        let base: f32 = row[2].parse().unwrap();
        let uhdr_r: f32 = row[3].parse().unwrap();
        if let Some(&avif_r) = avif.get(&(gain.to_bits(), base.to_bits())) {
            let err = (uhdr_r - avif_r).abs();
            assert!(
                err < TOLERANCE,
                "uhdr vs avif disagree at gain={gain}, base={base}: uhdr={uhdr_r} avif={avif_r}",
            );
            // And our computed value must also match both.
            let ours = apply_one(&metadata, 1.0, gain, base);
            let err_ours = (ours - uhdr_r).abs();
            assert!(
                err_ours < TOLERANCE,
                "ours diverges at gain={gain}, base={base}"
            );
            shared += 1;
        }
    }
    assert!(shared >= 5, "too few shared (gain,base) points: {shared}");
    eprintln!("cross_check: {shared} shared (gain, base) points agree across all three impls");
}