f67d38b35cc5
golden.rs
//! Golden-image testing: RGBA8 images, PNG I/O, difference metrics and reference checks.
//!
//! A golden test renders an image, then calls [`assert_golden`] with the path of a committed
//! reference PNG and a [`Tolerance`]. On mismatch the actual image and an amplified difference
//! image are written to `<workspace>/target/golden-failures/` for inspection.
//!
//! `FILMCRAFT_BLESS=1` (re)writes the reference instead of comparing, plus its `.attribution`
//! sidecar when missing (AGENTS.md §1). References must be produced by FilmCraft itself (original
//! work), be small (< [`MAX_GOLDEN_BYTES`]) and be listed in `ATTRIBUTION.md`.
use std::io::{BufReader, Cursor};
use std::path::{Path, PathBuf};
/// Size limit for a committed golden PNG.
pub const MAX_GOLDEN_BYTES: u64 = 50 * 1024;
/// An 8-bit RGBA image, row-major, no padding.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Rgba8 {
pub w: u32,
pub h: u32,
pub px: Vec<u8>,
}
impl Rgba8 {
pub fn new(w: u32, h: u32, px: Vec<u8>) -> Self {
assert_eq!(px.len(), w as usize * h as usize * 4, "pixel buffer size");
Self { w, h, px }
}
pub fn get(&self, x: u32, y: u32) -> [u8; 4] {
let i = (y as usize * self.w as usize + x as usize) * 4;
[self.px[i], self.px[i + 1], self.px[i + 2], self.px[i + 3]]
}
fn opaque(&self) -> bool {
self.px.as_chunks::<4>().0.iter().all(|p| p[3] == 255)
}
}
/// Encode as PNG (RGB when fully opaque, else RGBA), maximum compression.
pub fn encode_png(img: &Rgba8) -> Result<Vec<u8>, String> {
let mut out = Vec::new();
{
let mut enc = png::Encoder::new(&mut out, img.w, img.h);
let opaque = img.opaque();
enc.set_color(if opaque { png::ColorType::Rgb } else { png::ColorType::Rgba });
enc.set_depth(png::BitDepth::Eight);
enc.set_compression(png::Compression::High);
let mut w = enc.write_header().map_err(|e| e.to_string())?;
if opaque {
let rgb: Vec<u8> = img.px.as_chunks::<4>().0.iter().flat_map(|p| [p[0], p[1], p[2]]).collect();
w.write_image_data(&rgb).map_err(|e| e.to_string())?;
} else {
w.write_image_data(&img.px).map_err(|e| e.to_string())?;
}
w.finish().map_err(|e| e.to_string())?;
}
Ok(out)
}
/// Decode a PNG (8-bit gray/RGB/RGBA, palette expanded) to RGBA8.
pub fn decode_png(bytes: &[u8]) -> Result<Rgba8, String> {
let mut dec = png::Decoder::new(BufReader::new(Cursor::new(bytes)));
dec.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);
let mut r = dec.read_info().map_err(|e| e.to_string())?;
let mut buf = vec![0; r.output_buffer_size().ok_or("PNG too large")?];
let info = r.next_frame(&mut buf).map_err(|e| e.to_string())?;
let (w, h) = (info.width, info.height);
let n = w as usize * h as usize;
let px = match info.color_type {
png::ColorType::Rgba => buf[..n * 4].to_vec(),
png::ColorType::Rgb => buf[..n * 3].as_chunks::<3>().0.iter().flat_map(|p| [p[0], p[1], p[2], 255]).collect(),
png::ColorType::GrayscaleAlpha => buf[..n * 2].as_chunks::<2>().0.iter().flat_map(|p| [p[0], p[0], p[0], p[1]]).collect(),
png::ColorType::Grayscale => buf[..n].iter().flat_map(|&g| [g, g, g, 255]).collect(),
png::ColorType::Indexed => return Err("unexpanded palette PNG".into()),
};
Ok(Rgba8 { w, h, px })
}
pub fn read_png(path: &Path) -> Result<Rgba8, String> {
let bytes = std::fs::read(path).map_err(|e| format!("{}: {e}", path.display()))?;
decode_png(&bytes).map_err(|e| format!("{}: {e}", path.display()))
}
pub fn write_png(path: &Path, img: &Rgba8) -> Result<u64, String> {
let bytes = encode_png(img)?;
if let Some(d) = path.parent() {
std::fs::create_dir_all(d).map_err(|e| e.to_string())?;
}
std::fs::write(path, &bytes).map_err(|e| format!("{}: {e}", path.display()))?;
Ok(bytes.len() as u64)
}
/// Per-pixel difference statistics over all four channels (8-bit levels).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Diff {
/// Largest absolute channel difference.
pub max_abs: u8,
/// Mean absolute channel difference.
pub mean_abs: f64,
/// 99th percentile of the per-pixel maximum channel difference.
pub p99: u8,
/// PSNR in dB over all channels (`f64::INFINITY` when identical).
pub psnr: f64,
/// Pixels with any channel different.
pub differing: usize,
}
impl std::fmt::Display for Diff {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "PSNR {:.2} dB, max {}, p99 {}, mean {:.3}, {} pixels differ", self.psnr, self.max_abs, self.p99, self.mean_abs, self.differing)
}
}
/// Compare two images of equal size.
pub fn diff(a: &Rgba8, b: &Rgba8) -> Result<Diff, String> {
if (a.w, a.h) != (b.w, b.h) {
return Err(format!("size {}x{} vs {}x{}", a.w, a.h, b.w, b.h));
}
let mut hist = [0usize; 256];
let (mut sum, mut sq, mut max, mut differing) = (0u64, 0u64, 0u8, 0usize);
for (p, q) in a.px.as_chunks::<4>().0.iter().zip(b.px.as_chunks::<4>().0) {
let mut m = 0u8;
for k in 0..4 {
let d = p[k].abs_diff(q[k]);
sum += d as u64;
sq += d as u64 * d as u64;
m = m.max(d);
}
hist[m as usize] += 1;
max = max.max(m);
differing += (m > 0) as usize;
}
let pixels = (a.w as usize * a.h as usize).max(1);
let target = (pixels * 99).div_ceil(100);
let mut acc = 0;
let mut p99 = 0u8;
for (v, n) in hist.iter().enumerate() {
acc += n;
if acc >= target {
p99 = v as u8;
break;
}
}
let n = (pixels * 4) as f64;
let mse = sq as f64 / n;
let psnr = if mse == 0.0 { f64::INFINITY } else { 10.0 * (255.0f64 * 255.0 / mse).log10() };
Ok(Diff { max_abs: max, mean_abs: sum as f64 / n, p99, psnr, differing })
}
/// Acceptance thresholds; every set limit must hold.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Tolerance {
pub min_psnr: f64,
pub max_abs: u8,
pub p99: u8,
}
impl Tolerance {
/// Bit-exact.
pub const EXACT: Tolerance = Tolerance { min_psnr: f64::INFINITY, max_abs: 0, p99: 0 };
/// Default for CPU renders compared with CPU-made references: absorbs float differences
/// between platforms (FMA, SIMD widths, thread scheduling of reductions) but not real changes.
pub const RENDER: Tolerance = Tolerance { min_psnr: 45.0, max_abs: 12, p99: 2 };
pub fn accepts(&self, d: &Diff) -> bool {
d.psnr >= self.min_psnr && d.max_abs <= self.max_abs && d.p99 <= self.p99
}
}
/// Whether `FILMCRAFT_BLESS` asks to regenerate references.
pub fn blessing() -> bool {
std::env::var("FILMCRAFT_BLESS").is_ok_and(|v| matches!(v.trim().to_ascii_lowercase().as_str(), "1" | "true" | "yes" | "on"))
}
/// Where failing comparisons write `<name>.actual.png` / `<name>.diff.png`.
pub fn failures_dir() -> PathBuf {
crate::workspace_root().join("target").join("golden-failures")
}
/// Difference image: |a − b| per channel ×8, opaque.
pub fn diff_image(a: &Rgba8, b: &Rgba8) -> Rgba8 {
let px =
a.px.as_chunks::<4>()
.0
.iter()
.zip(b.px.as_chunks::<4>().0)
.flat_map(|(p, q)| {
let d = |k: usize| (p[k].abs_diff(q[k]) as u32 * 8).min(255) as u8;
let al = d(3);
[d(0).max(al), d(1).max(al), d(2).max(al), 255]
})
.collect();
Rgba8 { w: a.w, h: a.h, px }
}
/// Today's date (UTC) as YYYY-MM-DD, for attribution sidecars.
fn today() -> String {
let since = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap_or_default();
let (y, t) = utc_parts(since.as_secs());
// `{:04}` rather than `%Y`, which writes a `+` before years past 9999.
format!("{y:04}-{}", t.format("%m-%d"))
}
/// Unix seconds → (proleptic Gregorian year, the same wall-clock instant moved into chrono's range
/// by whole 400-year cycles). The Gregorian calendar repeats every 400 years (146_097 days), so
/// month and day come from chrono and only the year is carried, which keeps every input exact
/// instead of collapsing out-of-range years to the epoch. `secs` is `u64` (the clock is clamped at
/// the epoch before 1970), so `days` always fits an `i64`.
fn utc_parts(secs: u64) -> (i64, chrono::NaiveDateTime) {
use chrono::Datelike;
let (days, sod) = ((secs / 86_400) as i64, (secs % 86_400) as i64);
let (cycles, rest) = (days.div_euclid(146_097), days.rem_euclid(146_097));
// `rest + 719_163` (1970-01-01 is CE day 719_163) is always a valid CE day, and `sod` < 86_400.
let date = i32::try_from(rest + 719_163).ok().and_then(chrono::NaiveDate::from_num_days_from_ce_opt);
let time = u32::try_from(sod).ok().and_then(|s| chrono::NaiveTime::from_num_seconds_from_midnight_opt(s, 0));
match (date, time) {
(Some(d), Some(t)) => {
let y = i128::from(d.year()) + i128::from(cycles) * 400;
(i64::try_from(y).unwrap_or(i64::MAX), d.and_time(t))
}
_ => (1970, chrono::NaiveDateTime::default()), // unreachable
}
}
/// The attribution sidecar text for a generated golden image.
pub fn sidecar_text(file_name: &str, title: &str, generated_by: &str) -> String {
format!(
"asset: {file_name}\n\
title: {title}\n\
author: FilmCraft contributors\n\
source: original work (rendered by FilmCraft's own renderer from a procedurally generated project; no external media)\n\
license: MIT OR Apache-2.0\n\
license-file:\n\
added: {} by FilmCraft contributors (FILMCRAFT_BLESS=1)\n\
notes: Golden reference image generated by {generated_by}. Regenerate with FILMCRAFT_BLESS=1. Contains no Adobe artwork.\n",
today()
)
}
/// The `ATTRIBUTION.md` table row for a golden image at workspace-relative `rel`.
pub fn attribution_row(rel: &str, generated_by: &str) -> String {
format!("| `{rel}` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft ({generated_by}) | MIT OR Apache-2.0 |")
}
/// Compare `actual` with the golden PNG at `golden` (or bless it). `title` and `generated_by`
/// fill the attribution sidecar written on bless. Returns the difference on success.
pub fn check_golden(golden: &Path, actual: &Rgba8, tol: Tolerance, title: &str, generated_by: &str) -> Result<Diff, String> {
let name = golden.file_stem().map(|s| s.to_string_lossy().to_string()).unwrap_or_default();
if blessing() {
let size = write_png(golden, actual)?;
if size > MAX_GOLDEN_BYTES {
return Err(format!("{}: {size} bytes exceeds the {MAX_GOLDEN_BYTES}-byte golden limit; render smaller", golden.display()));
}
let side = PathBuf::from(format!("{}.attribution", golden.display()));
if !side.exists() {
let file = golden.file_name().map(|s| s.to_string_lossy().to_string()).unwrap_or_default();
std::fs::write(&side, sidecar_text(&file, title, generated_by)).map_err(|e| e.to_string())?;
}
let root = crate::workspace_root();
let rel = golden.strip_prefix(&root).unwrap_or(golden).to_string_lossy().replace('\\', "/");
let index = std::fs::read_to_string(root.join("ATTRIBUTION.md")).unwrap_or_default();
if !index.contains(&format!("`{rel}`")) {
eprintln!("golden {rel}: add this row to ATTRIBUTION.md:\n{}", attribution_row(&rel, generated_by));
}
eprintln!("blessed {rel} ({size} bytes)");
return Ok(Diff { max_abs: 0, mean_abs: 0.0, p99: 0, psnr: f64::INFINITY, differing: 0 });
}
let expected = read_png(golden).map_err(|e| format!("{e}\n(missing or unreadable golden; generate it with FILMCRAFT_BLESS=1)"))?;
let d = diff(&expected, actual).map_err(|e| format!("{}: {e}", golden.display()))?;
if tol.accepts(&d) {
return Ok(d);
}
let dir = failures_dir();
let a = dir.join(format!("{name}.actual.png"));
let _ = write_png(&a, actual);
let _ = write_png(&dir.join(format!("{name}.diff.png")), &diff_image(&expected, actual));
Err(format!(
"{}: {d} (tolerance: PSNR ≥ {} dB, max ≤ {}, p99 ≤ {}); actual and diff written to {}",
golden.display(),
tol.min_psnr,
tol.max_abs,
tol.p99,
dir.display()
))
}
/// [`check_golden`] that panics on failure.
pub fn assert_golden(golden: &Path, actual: &Rgba8, tol: Tolerance, title: &str, generated_by: &str) -> Diff {
match check_golden(golden, actual, tol, title, generated_by) {
Ok(d) => d,
Err(e) => panic!("golden mismatch: {e}"),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn ymd(secs: u64) -> String {
let (y, t) = utc_parts(secs);
format!("{y:04}-{}", t.format("%m-%d"))
}
#[test]
fn utc_parts_preserves_out_of_range_years() {
// `today()` uses `utc_parts`. Years far outside chrono's own range are preserved (the old
// hand-rolled civil-from-days kept them) rather than collapsing to the epoch.
assert_eq!(ymd(0), "1970-01-01");
assert_eq!(ymd(1_790_775_907), "2026-09-30");
assert_eq!(ymd(951_782_400), "2000-02-29"); // 2000 is a leap year
assert_eq!(ymd(253_402_300_800), "10000-01-01"); // just past chrono's range
assert_eq!(ymd(10_000_000_000_000), "318857-05-20");
assert_eq!(ymd(u64::MAX), "584554051223-11-09");
}
fn ramp(w: u32, h: u32, alpha: u8) -> Rgba8 {
let px = (0..w * h).flat_map(|i| [(i % w * 255 / w) as u8, (i / w * 255 / h) as u8, 77, alpha]).collect();
Rgba8::new(w, h, px)
}
#[test]
fn png_round_trip_rgb_and_rgba() {
for a in [255, 128] {
let img = ramp(37, 21, a);
let png = encode_png(&img).unwrap();
assert_eq!(decode_png(&png).unwrap(), img);
}
}
#[test]
fn diff_metrics() {
let a = ramp(10, 10, 255);
assert_eq!(diff(&a, &a).unwrap().psnr, f64::INFINITY);
let mut b = a.clone();
b.px[0] = b.px[0].wrapping_add(10); // one channel of one pixel
let d = diff(&a, &b).unwrap();
assert_eq!((d.max_abs, d.p99, d.differing), (10, 0, 1));
assert!((d.mean_abs - 10.0 / 400.0).abs() < 1e-12);
let mse: f64 = 100.0 / 400.0;
assert!((d.psnr - 10.0 * (255.0f64 * 255.0 / mse).log10()).abs() < 1e-9);
assert!(Tolerance::RENDER.accepts(&d));
assert!(!Tolerance::EXACT.accepts(&d));
assert!(diff(&a, &ramp(10, 11, 255)).is_err());
}
#[test]
fn check_golden_accepts_within_tolerance_and_reports_failures() {
if blessing() {
return;
}
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("ramp.png");
let img = ramp(32, 16, 255);
write_png(&path, &img).unwrap();
assert!(check_golden(&path, &img, Tolerance::EXACT, "t", "unit test").is_ok());
let mut near = img.clone();
near.px[5] += 1;
assert!(check_golden(&path, &near, Tolerance::RENDER, "t", "unit test").is_ok());
let mut far = img.clone();
far.px.iter_mut().step_by(4).for_each(|v| *v = 255 - *v);
let e = check_golden(&path, &far, Tolerance::RENDER, "t", "unit test").unwrap_err();
assert!(e.contains("PSNR"), "{e}");
assert!(check_golden(&dir.path().join("missing.png"), &img, Tolerance::RENDER, "t", "unit test").unwrap_err().contains("FILMCRAFT_BLESS"));
}
#[test]
fn date_and_sidecar_fields() {
let t = today();
assert_eq!(t.len(), 10);
assert!(t.starts_with("20"));
let s = sidecar_text("x.png", "X", "test y");
for f in ["asset:", "title:", "author:", "source:", "license:", "added:"] {
assert!(s.lines().any(|l| l.starts_with(f) && l.len() > f.len() + 2), "{f}");
}
}
}
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.