use thiserror::Error;
#[inline]
fn xorshift64(state: &mut u64) -> u64 {
*state ^= *state << 13;
*state ^= *state >> 7;
*state ^= *state << 17;
*state
}
#[inline]
fn xorshift_f32(state: &mut u64) -> f32 {
(xorshift64(state) >> 32) as f32 / u32::MAX as f32
}
#[inline]
fn sample_normal(state: &mut u64) -> f32 {
let u1 = xorshift_f32(state).max(1e-10);
let u2 = xorshift_f32(state);
(-2.0 * u1.ln()).sqrt() * (std::f32::consts::TAU * u2).cos()
}
#[derive(Debug, Error)]
pub enum FilmGrainError {
#[error("Invalid film grain config: {0}")]
InvalidConfig(String),
#[error("Invalid image: {0}")]
InvalidImage(String),
#[error("Image is empty (zero width or height)")]
EmptyImage,
}
#[derive(Debug, Clone)]
pub struct FilmGrainConfig {
pub intensity: f32,
pub grain_size: f32,
pub luminance_scaling: bool,
pub chroma_fraction: f32,
pub seed: u64,
pub clip_output: bool,
}
impl Default for FilmGrainConfig {
fn default() -> Self {
Self {
intensity: 0.05,
grain_size: 1.5,
luminance_scaling: true,
chroma_fraction: 0.3,
seed: 42,
clip_output: true,
}
}
}
impl FilmGrainConfig {
pub fn validate(&self) -> Result<(), FilmGrainError> {
if self.intensity < 0.0 {
return Err(FilmGrainError::InvalidConfig(format!(
"intensity must be >= 0, got {}",
self.intensity
)));
}
if self.grain_size < 1.0 {
return Err(FilmGrainError::InvalidConfig(format!(
"grain_size must be >= 1.0, got {}",
self.grain_size
)));
}
if !(0.0..=1.0).contains(&self.chroma_fraction) {
return Err(FilmGrainError::InvalidConfig(format!(
"chroma_fraction must be in [0, 1], got {}",
self.chroma_fraction
)));
}
Ok(())
}
pub fn cinematic() -> Self {
Self {
intensity: 0.08,
grain_size: 2.0,
luminance_scaling: true,
chroma_fraction: 0.2,
seed: 42,
clip_output: true,
}
}
pub fn fine() -> Self {
Self {
intensity: 0.03,
grain_size: 1.0,
luminance_scaling: true,
chroma_fraction: 0.1,
seed: 42,
clip_output: true,
}
}
pub fn heavy() -> Self {
Self {
intensity: 0.15,
grain_size: 3.0,
luminance_scaling: true,
chroma_fraction: 0.5,
seed: 42,
clip_output: true,
}
}
}
#[inline]
pub fn grain_scale_fn(luminance: f32) -> f32 {
let l = luminance.clamp(0.0, 1.0);
4.0 * l * (1.0 - l)
}
#[inline]
pub fn film_luminance(r: f32, g: f32, b: f32) -> f32 {
0.2126 * r + 0.7152 * g + 0.0722 * b
}
fn bilinear_upsample(
src: &[f32],
src_w: usize,
src_h: usize,
dst_w: usize,
dst_h: usize,
preserve_variance: bool,
) -> Vec<f32> {
let mut dst = vec![0.0_f32; dst_w * dst_h];
for dy in 0..dst_h {
for dx in 0..dst_w {
let sx = dx as f32 * (src_w as f32 - 1.0) / (dst_w as f32 - 1.0).max(1.0);
let sy = dy as f32 * (src_h as f32 - 1.0) / (dst_h as f32 - 1.0).max(1.0);
let x0 = sx.floor() as usize;
let y0 = sy.floor() as usize;
let x1 = (x0 + 1).min(src_w.saturating_sub(1));
let y1 = (y0 + 1).min(src_h.saturating_sub(1));
let tx = sx - x0 as f32;
let ty = sy - y0 as f32;
let v00 = src[y0 * src_w + x0];
let v10 = src[y0 * src_w + x1];
let v01 = src[y1 * src_w + x0];
let v11 = src[y1 * src_w + x1];
let w00 = (1.0 - tx) * (1.0 - ty);
let w10 = tx * (1.0 - ty);
let w01 = (1.0 - tx) * ty;
let w11 = tx * ty;
let mut value = w00 * v00 + w10 * v10 + w01 * v01 + w11 * v11;
if preserve_variance {
let weight_sq_sum = w00 * w00 + w10 * w10 + w01 * w01 + w11 * w11;
if weight_sq_sum > 0.0 {
value /= weight_sq_sum.sqrt();
}
}
dst[dy * dst_w + dx] = value;
}
}
dst
}
pub fn generate_grain_map(width: usize, height: usize, config: &FilmGrainConfig) -> Vec<f32> {
let grain_w = ((width as f32 / config.grain_size).max(1.0)) as usize;
let grain_h = ((height as f32 / config.grain_size).max(1.0)) as usize;
let mut state = config.seed.wrapping_add(0x5851F42D4C957F2D);
if state == 0 {
state = 0x6C62272E07BB0142;
}
let n_grain = grain_w * grain_h;
let mut grain_small = Vec::with_capacity(n_grain);
for _ in 0..n_grain {
grain_small.push(sample_normal(&mut state));
}
if grain_w == width && grain_h == height {
grain_small
} else {
bilinear_upsample(&grain_small, grain_w, grain_h, width, height, true)
}
}
#[inline]
fn chroma_seed(base_seed: u64, channel_idx: u64) -> u64 {
base_seed
.wrapping_add(channel_idx.wrapping_mul(0x9E3779B97F4A7C15))
.wrapping_add(0xD1B54A32D192ED03)
}
#[inline]
fn stream_seed(base_seed: u64, tag: u64) -> u64 {
let mut z = base_seed.wrapping_add(tag.wrapping_mul(0x9E37_79B9_7F4A_7C15));
z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
z ^ (z >> 31)
}
#[inline]
fn config_with_seed(config: &FilmGrainConfig, seed: u64) -> FilmGrainConfig {
FilmGrainConfig {
seed,
..config.clone()
}
}
pub fn apply_film_grain(
image: &[f32],
width: usize,
height: usize,
config: &FilmGrainConfig,
) -> Result<Vec<f32>, FilmGrainError> {
if width == 0 || height == 0 {
return Err(FilmGrainError::EmptyImage);
}
let expected = width * height * 3;
if image.len() != expected {
return Err(FilmGrainError::InvalidImage(format!(
"expected {} bytes for {}×{}×3, got {}",
expected,
width,
height,
image.len()
)));
}
let n_pixels = width * height;
let g_luma = generate_grain_map(width, height, config);
let use_chroma = config.chroma_fraction > 0.0;
let g_r: Vec<f32>;
let g_g: Vec<f32>;
let g_b: Vec<f32>;
if use_chroma {
g_r = generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(config.seed, 1)),
);
g_g = generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(config.seed, 2)),
);
g_b = generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(config.seed, 3)),
);
} else {
g_r = Vec::new();
g_g = Vec::new();
g_b = Vec::new();
}
let cf = config.chroma_fraction;
let lf = 1.0 - cf;
let chroma_norm = (lf * lf + cf * cf).sqrt();
let mut out = Vec::with_capacity(expected);
for pi in 0..n_pixels {
let base = pi * 3;
let r = image[base];
let g = image[base + 1];
let b = image[base + 2];
let lum = film_luminance(r, g, b);
let sigma = if config.luminance_scaling {
config.intensity * grain_scale_fn(lum)
} else {
config.intensity
};
let luma_noise = g_luma[pi] * sigma;
let (r_noise, g_noise, b_noise) = if use_chroma {
(
(luma_noise * lf + g_r[pi] * sigma * cf) / chroma_norm,
(luma_noise * lf + g_g[pi] * sigma * cf) / chroma_norm,
(luma_noise * lf + g_b[pi] * sigma * cf) / chroma_norm,
)
} else {
(luma_noise, luma_noise, luma_noise)
};
let out_r = r + r_noise;
let out_g = g + g_noise;
let out_b = b + b_noise;
if config.clip_output {
out.push(out_r.clamp(0.0, 1.0));
out.push(out_g.clamp(0.0, 1.0));
out.push(out_b.clamp(0.0, 1.0));
} else {
out.push(out_r);
out.push(out_g);
out.push(out_b);
}
}
Ok(out)
}
pub fn apply_film_grain_rgba(
image: &[f32],
width: usize,
height: usize,
config: &FilmGrainConfig,
) -> Result<Vec<f32>, FilmGrainError> {
if width == 0 || height == 0 {
return Err(FilmGrainError::EmptyImage);
}
let expected = width * height * 4;
if image.len() != expected {
return Err(FilmGrainError::InvalidImage(format!(
"expected {} bytes for {}×{}×4, got {}",
expected,
width,
height,
image.len()
)));
}
let n_pixels = width * height;
let mut rgb = Vec::with_capacity(n_pixels * 3);
for pi in 0..n_pixels {
let base = pi * 4;
rgb.push(image[base]);
rgb.push(image[base + 1]);
rgb.push(image[base + 2]);
}
let grained_rgb = apply_film_grain(&rgb, width, height, config)?;
let mut out = Vec::with_capacity(expected);
for pi in 0..n_pixels {
let rb = pi * 3;
let ab = pi * 4;
out.push(grained_rgb[rb]);
out.push(grained_rgb[rb + 1]);
out.push(grained_rgb[rb + 2]);
out.push(image[ab + 3]);
}
Ok(out)
}
const BASE_STREAM_TAG: u64 = 0;
#[inline]
fn frame_stream_tag(frame_idx: usize) -> u64 {
(frame_idx as u64).wrapping_add(1)
}
pub fn apply_film_grain_frame(
image: &[f32],
width: usize,
height: usize,
frame_idx: usize,
config: &FilmGrainConfig,
) -> Result<Vec<f32>, FilmGrainError> {
let frame_seed = stream_seed(config.seed, frame_stream_tag(frame_idx));
let frame_config = config_with_seed(config, frame_seed);
apply_film_grain(image, width, height, &frame_config)
}
pub fn apply_film_grain_sequence(
images: &[Vec<f32>],
width: usize,
height: usize,
config: &FilmGrainConfig,
temporal_coherence: f32,
) -> Result<Vec<Vec<f32>>, FilmGrainError> {
if !(0.0..=1.0).contains(&temporal_coherence) {
return Err(FilmGrainError::InvalidConfig(format!(
"temporal_coherence must be in [0, 1], got {}",
temporal_coherence
)));
}
if images.is_empty() {
return Ok(Vec::new());
}
let base_seed = stream_seed(config.seed, BASE_STREAM_TAG);
let base_cfg = config_with_seed(config, base_seed);
let base_grain = generate_grain_map(width, height, &base_cfg);
let use_chroma = config.chroma_fraction > 0.0;
let base_gr = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(base_seed, 1)),
)
} else {
Vec::new()
};
let base_gg = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(base_seed, 2)),
)
} else {
Vec::new()
};
let base_gb = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(config, chroma_seed(base_seed, 3)),
)
} else {
Vec::new()
};
images
.iter()
.enumerate()
.map(|(frame_idx, image)| {
if width == 0 || height == 0 {
return Err(FilmGrainError::EmptyImage);
}
let expected = width * height * 3;
if image.len() != expected {
return Err(FilmGrainError::InvalidImage(format!(
"frame {}: expected {} bytes for {}×{}×3, got {}",
frame_idx,
expected,
width,
height,
image.len()
)));
}
let n_pixels = width * height;
let frame_seed = stream_seed(config.seed, frame_stream_tag(frame_idx));
let frame_cfg = config_with_seed(config, frame_seed);
let frame_grain = generate_grain_map(width, height, &frame_cfg);
let frame_gr = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(&frame_cfg, chroma_seed(frame_seed, 1)),
)
} else {
Vec::new()
};
let frame_gg = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(&frame_cfg, chroma_seed(frame_seed, 2)),
)
} else {
Vec::new()
};
let frame_gb = if use_chroma {
generate_grain_map(
width,
height,
&config_with_seed(&frame_cfg, chroma_seed(frame_seed, 3)),
)
} else {
Vec::new()
};
let tc = temporal_coherence;
let fi = 1.0 - tc;
let temporal_norm = (tc * tc + fi * fi).sqrt();
let cf = config.chroma_fraction;
let lf = 1.0 - cf;
let chroma_norm = (lf * lf + cf * cf).sqrt();
let mut out = Vec::with_capacity(expected);
for pi in 0..n_pixels {
let base = pi * 3;
let r = image[base];
let g = image[base + 1];
let b = image[base + 2];
let lum = film_luminance(r, g, b);
let sigma = if config.luminance_scaling {
config.intensity * grain_scale_fn(lum)
} else {
config.intensity
};
let g_luma = (tc * base_grain[pi] + fi * frame_grain[pi]) / temporal_norm;
let luma_noise = g_luma * sigma;
let (r_noise, g_noise, b_noise) = if use_chroma {
let gr = (tc * base_gr[pi] + fi * frame_gr[pi]) / temporal_norm;
let gg = (tc * base_gg[pi] + fi * frame_gg[pi]) / temporal_norm;
let gb = (tc * base_gb[pi] + fi * frame_gb[pi]) / temporal_norm;
(
(luma_noise * lf + gr * sigma * cf) / chroma_norm,
(luma_noise * lf + gg * sigma * cf) / chroma_norm,
(luma_noise * lf + gb * sigma * cf) / chroma_norm,
)
} else {
(luma_noise, luma_noise, luma_noise)
};
let out_r = r + r_noise;
let out_g = g + g_noise;
let out_b = b + b_noise;
if config.clip_output {
out.push(out_r.clamp(0.0, 1.0));
out.push(out_g.clamp(0.0, 1.0));
out.push(out_b.clamp(0.0, 1.0));
} else {
out.push(out_r);
out.push(out_g);
out.push(out_b);
}
}
Ok(out)
})
.collect()
}
#[derive(Debug, Clone)]
pub struct GrainStats {
pub mean_grain: f32,
pub std_grain: f32,
pub snr: f32,
pub mean_lum_before: f32,
pub mean_lum_after: f32,
}
pub fn compute_grain_stats(
original: &[f32],
grained: &[f32],
width: usize,
height: usize,
) -> Result<GrainStats, FilmGrainError> {
if width == 0 || height == 0 {
return Err(FilmGrainError::EmptyImage);
}
let expected = width * height * 3;
if original.len() != expected {
return Err(FilmGrainError::InvalidImage(format!(
"original: expected {}, got {}",
expected,
original.len()
)));
}
if grained.len() != expected {
return Err(FilmGrainError::InvalidImage(format!(
"grained: expected {}, got {}",
expected,
grained.len()
)));
}
let n = expected as f32;
let n_pixels = (width * height) as f32;
let mut sum_abs_grain = 0.0_f64;
let mut sum_grain = 0.0_f64;
let mut sum_grain_sq = 0.0_f64;
let mut sum_lum_before = 0.0_f64;
let mut sum_lum_after = 0.0_f64;
let n_pixels_usize = width * height;
for pi in 0..n_pixels_usize {
let base = pi * 3;
let gr_elem = [
grained[base] - original[base],
grained[base + 1] - original[base + 1],
grained[base + 2] - original[base + 2],
];
for &g in &gr_elem {
sum_abs_grain += g.abs() as f64;
sum_grain += g as f64;
sum_grain_sq += (g * g) as f64;
}
let or_ = original[base];
let og = original[base + 1];
let ob = original[base + 2];
sum_lum_before += film_luminance(or_, og, ob) as f64;
let gr = grained[base];
let gg = grained[base + 1];
let gb = grained[base + 2];
sum_lum_after += film_luminance(gr, gg, gb) as f64;
}
let mean_grain = (sum_abs_grain / n as f64) as f32;
let mean_g = (sum_grain / n as f64) as f32;
let variance = ((sum_grain_sq / n as f64) - (mean_g * mean_g) as f64).max(0.0);
let std_grain = variance.sqrt() as f32;
let mean_lum_before = (sum_lum_before / n_pixels as f64) as f32;
let mean_lum_after = (sum_lum_after / n_pixels as f64) as f32;
let snr = mean_lum_before / (std_grain + 1e-8);
Ok(GrainStats {
mean_grain,
std_grain,
snr,
mean_lum_before,
mean_lum_after,
})
}
#[cfg(test)]
mod tests {
use super::*;
fn approx_eq(a: f32, b: f32, tol: f32) -> bool {
(a - b).abs() <= tol
}
#[test]
fn test_grain_scale_fn_zero() {
assert!(approx_eq(grain_scale_fn(0.0), 0.0, 1e-6));
}
#[test]
fn test_grain_scale_fn_one() {
assert!(approx_eq(grain_scale_fn(1.0), 0.0, 1e-6));
}
#[test]
fn test_grain_scale_fn_midpoint() {
assert!(approx_eq(grain_scale_fn(0.5), 1.0, 1e-6));
}
#[test]
fn test_grain_scale_fn_clamps_negative() {
assert!(approx_eq(grain_scale_fn(-1.0), grain_scale_fn(0.0), 1e-6));
}
#[test]
fn test_grain_scale_fn_clamps_above_one() {
assert!(approx_eq(grain_scale_fn(2.0), grain_scale_fn(1.0), 1e-6));
}
#[test]
fn test_film_luminance_pure_red() {
assert!(approx_eq(film_luminance(1.0, 0.0, 0.0), 0.2126, 1e-4));
}
#[test]
fn test_film_luminance_pure_green() {
assert!(approx_eq(film_luminance(0.0, 1.0, 0.0), 0.7152, 1e-4));
}
#[test]
fn test_film_luminance_pure_blue() {
assert!(approx_eq(film_luminance(0.0, 0.0, 1.0), 0.0722, 1e-4));
}
#[test]
fn test_film_luminance_white() {
assert!(approx_eq(film_luminance(1.0, 1.0, 1.0), 1.0, 1e-4));
}
#[test]
fn test_film_luminance_black() {
assert!(approx_eq(film_luminance(0.0, 0.0, 0.0), 0.0, 1e-6));
}
#[test]
fn test_config_validate_default_is_valid() {
assert!(FilmGrainConfig::default().validate().is_ok());
}
#[test]
fn test_config_validate_negative_intensity() {
let cfg = FilmGrainConfig {
intensity: -0.1,
..FilmGrainConfig::default()
};
assert!(cfg.validate().is_err());
}
#[test]
fn test_config_validate_grain_size_below_one() {
let cfg = FilmGrainConfig {
grain_size: 0.5,
..FilmGrainConfig::default()
};
assert!(cfg.validate().is_err());
}
#[test]
fn test_config_validate_chroma_fraction_above_one() {
let cfg = FilmGrainConfig {
chroma_fraction: 1.5,
..FilmGrainConfig::default()
};
assert!(cfg.validate().is_err());
}
#[test]
fn test_config_validate_chroma_fraction_negative() {
let cfg = FilmGrainConfig {
chroma_fraction: -0.1,
..FilmGrainConfig::default()
};
assert!(cfg.validate().is_err());
}
#[test]
fn test_config_cinematic_has_positive_intensity() {
assert!(FilmGrainConfig::cinematic().intensity > 0.0);
}
#[test]
fn test_config_cinematic_is_valid() {
assert!(FilmGrainConfig::cinematic().validate().is_ok());
}
#[test]
fn test_config_fine_is_valid() {
assert!(FilmGrainConfig::fine().validate().is_ok());
}
#[test]
fn test_config_heavy_is_valid() {
assert!(FilmGrainConfig::heavy().validate().is_ok());
}
#[test]
fn test_generate_grain_map_correct_size() {
let cfg = FilmGrainConfig::default();
let map = generate_grain_map(16, 12, &cfg);
assert_eq!(map.len(), 16 * 12);
}
#[test]
fn test_generate_grain_map_coarse_correct_size() {
let cfg = FilmGrainConfig {
grain_size: 4.0,
..FilmGrainConfig::default()
};
let map = generate_grain_map(32, 24, &cfg);
assert_eq!(map.len(), 32 * 24);
}
#[test]
fn test_generate_grain_map_different_seeds() {
let cfg1 = FilmGrainConfig {
seed: 1,
..FilmGrainConfig::default()
};
let cfg2 = FilmGrainConfig {
seed: 999,
..FilmGrainConfig::default()
};
let m1 = generate_grain_map(16, 16, &cfg1);
let m2 = generate_grain_map(16, 16, &cfg2);
let n_diff = m1.iter().zip(m2.iter()).filter(|(a, b)| a != b).count();
assert!(n_diff > 0, "Maps with different seeds should differ");
}
#[test]
fn test_generate_grain_map_mean_near_zero() {
let cfg = FilmGrainConfig::default();
let map = generate_grain_map(64, 64, &cfg);
let mean: f32 = map.iter().sum::<f32>() / map.len() as f32;
assert!(mean.abs() < 0.2, "grain map mean too far from 0: {}", mean);
}
#[test]
fn test_apply_grain_empty_width() {
let cfg = FilmGrainConfig::default();
let result = apply_film_grain(&[], 0, 4, &cfg);
assert!(matches!(result, Err(FilmGrainError::EmptyImage)));
}
#[test]
fn test_apply_grain_empty_height() {
let cfg = FilmGrainConfig::default();
let result = apply_film_grain(&[], 4, 0, &cfg);
assert!(matches!(result, Err(FilmGrainError::EmptyImage)));
}
#[test]
fn test_apply_grain_wrong_length() {
let cfg = FilmGrainConfig::default();
let image = vec![0.5_f32; 10]; let result = apply_film_grain(&image, 4, 4, &cfg);
assert!(matches!(result, Err(FilmGrainError::InvalidImage(_))));
}
#[test]
fn test_apply_grain_zero_intensity_no_change() {
let cfg = FilmGrainConfig {
intensity: 0.0,
..FilmGrainConfig::default()
};
let image: Vec<f32> = (0..4 * 4 * 3).map(|i| i as f32 / 48.0).collect();
let result = apply_film_grain(&image, 4, 4, &cfg).expect("should succeed");
for (orig, out) in image.iter().zip(result.iter()) {
assert!(
approx_eq(*orig, *out, 1e-6) || out.clamp(0.0, 1.0) == *out,
"zero intensity should not change values"
);
}
}
#[test]
fn test_apply_grain_adds_noise() {
let cfg = FilmGrainConfig {
intensity: 0.2,
luminance_scaling: false,
..FilmGrainConfig::default()
};
let image = vec![0.5_f32; 8 * 8 * 3];
let result = apply_film_grain(&image, 8, 8, &cfg).expect("should succeed");
let n_changed = image
.iter()
.zip(result.iter())
.filter(|(a, b)| a != b)
.count();
assert!(n_changed > 0, "grain should change at least one pixel");
}
#[test]
fn test_apply_grain_clip_output_in_range() {
let cfg = FilmGrainConfig {
intensity: 0.5,
clip_output: true,
luminance_scaling: false,
..FilmGrainConfig::default()
};
let image: Vec<f32> = (0..8 * 8 * 3)
.map(|i| if i % 2 == 0 { 0.01 } else { 0.99 })
.collect();
let result = apply_film_grain(&image, 8, 8, &cfg).expect("should succeed");
for &v in &result {
assert!(
(0.0..=1.0).contains(&v),
"clipped output out of range: {}",
v
);
}
}
#[test]
fn test_apply_grain_preserves_dimensions() {
let w = 10;
let h = 7;
let cfg = FilmGrainConfig::default();
let image = vec![0.5_f32; w * h * 3];
let result = apply_film_grain(&image, w, h, &cfg).expect("should succeed");
assert_eq!(result.len(), w * h * 3);
}
#[test]
fn test_apply_grain_rgba_alpha_unchanged() {
let w = 4;
let h = 4;
let cfg = FilmGrainConfig {
intensity: 0.2,
..FilmGrainConfig::default()
};
let mut image = vec![0.5_f32; w * h * 4];
for pi in 0..(w * h) {
image[pi * 4 + 3] = pi as f32 / (w * h) as f32;
}
let result = apply_film_grain_rgba(&image, w, h, &cfg).expect("should succeed");
for pi in 0..(w * h) {
let expected_alpha = pi as f32 / (w * h) as f32;
assert!(
approx_eq(result[pi * 4 + 3], expected_alpha, 1e-6),
"alpha changed at pixel {}",
pi
);
}
}
#[test]
fn test_apply_grain_frame_different_frames() {
let w = 8;
let h = 8;
let cfg = FilmGrainConfig {
intensity: 0.1,
luminance_scaling: false,
chroma_fraction: 0.0,
..FilmGrainConfig::default()
};
let image = vec![0.5_f32; w * h * 3];
let f0 = apply_film_grain_frame(&image, w, h, 0, &cfg).expect("frame 0");
let f1 = apply_film_grain_frame(&image, w, h, 1, &cfg).expect("frame 1");
let n_diff = f0.iter().zip(f1.iter()).filter(|(a, b)| a != b).count();
assert!(n_diff > 0, "frames 0 and 1 should have different grain");
}
#[test]
fn test_apply_grain_sequence_output_count() {
let w = 4;
let h = 4;
let cfg = FilmGrainConfig::default();
let frames: Vec<Vec<f32>> = (0..5).map(|_| vec![0.5_f32; w * h * 3]).collect();
let result =
apply_film_grain_sequence(&frames, w, h, &cfg, 0.5).expect("sequence should succeed");
assert_eq!(result.len(), 5);
}
#[test]
fn test_apply_grain_sequence_full_coherence_same_grain() {
let w = 8;
let h = 8;
let cfg = FilmGrainConfig {
intensity: 0.1,
luminance_scaling: false,
chroma_fraction: 0.0,
..FilmGrainConfig::default()
};
let frames: Vec<Vec<f32>> = (0..3).map(|_| vec![0.5_f32; w * h * 3]).collect();
let result =
apply_film_grain_sequence(&frames, w, h, &cfg, 1.0).expect("sequence should succeed");
for i in 1..result.len() {
let n_diff = result[0]
.iter()
.zip(result[i].iter())
.filter(|(a, b)| a != b)
.count();
assert_eq!(
n_diff, 0,
"frame {} should be identical to frame 0 at tc=1.0",
i
);
}
}
#[test]
fn test_apply_grain_sequence_no_coherence_different_grain() {
let w = 8;
let h = 8;
let cfg = FilmGrainConfig {
intensity: 0.2,
luminance_scaling: false,
chroma_fraction: 0.0,
..FilmGrainConfig::default()
};
let frames: Vec<Vec<f32>> = (0..3).map(|_| vec![0.5_f32; w * h * 3]).collect();
let result =
apply_film_grain_sequence(&frames, w, h, &cfg, 0.0).expect("sequence should succeed");
let n_diff_01 = result[0]
.iter()
.zip(result[1].iter())
.filter(|(a, b)| a != b)
.count();
assert!(n_diff_01 > 0, "frames 0 and 1 should differ at tc=0.0");
}
#[test]
fn test_grain_stats_same_image() {
let w = 8;
let h = 8;
let image: Vec<f32> = (0..w * h * 3)
.map(|i| (i as f32) / (w * h * 3) as f32)
.collect();
let stats = compute_grain_stats(&image, &image, w, h).expect("should succeed");
assert!(approx_eq(stats.mean_grain, 0.0, 1e-6));
assert!(stats.snr > 1.0);
}
#[test]
fn test_grain_stats_with_grain() {
let w = 8;
let h = 8;
let cfg = FilmGrainConfig {
intensity: 0.1,
luminance_scaling: false,
clip_output: false,
chroma_fraction: 0.0,
..FilmGrainConfig::default()
};
let original = vec![0.5_f32; w * h * 3];
let grained = apply_film_grain(&original, w, h, &cfg).expect("should succeed");
let stats = compute_grain_stats(&original, &grained, w, h).expect("should succeed");
assert!(
stats.mean_grain > 0.0,
"grained image should have non-zero mean grain"
);
}
#[test]
fn test_luminance_scaling_affects_output() {
let w = 8;
let h = 8;
let base_cfg = FilmGrainConfig {
intensity: 0.1,
chroma_fraction: 0.0,
clip_output: false,
..FilmGrainConfig::default()
};
let cfg_scaled = FilmGrainConfig {
luminance_scaling: true,
..base_cfg.clone()
};
let cfg_flat = FilmGrainConfig {
luminance_scaling: false,
..base_cfg.clone()
};
let image: Vec<f32> = (0..w * h * 3)
.map(|i| (i as f32) / (w * h * 3) as f32)
.collect();
let out_scaled = apply_film_grain(&image, w, h, &cfg_scaled).expect("scaled");
let out_flat = apply_film_grain(&image, w, h, &cfg_flat).expect("flat");
let n_diff = out_scaled
.iter()
.zip(out_flat.iter())
.filter(|(a, b)| (*a - *b).abs() > 1e-7)
.count();
assert!(
n_diff > 0,
"luminance_scaling should produce different output"
);
}
#[test]
fn test_grain_size_smoothness() {
let w = 32;
let h = 32;
let cfg_fine = FilmGrainConfig {
grain_size: 1.0,
..FilmGrainConfig::default()
};
let cfg_coarse = FilmGrainConfig {
grain_size: 3.0,
..FilmGrainConfig::default()
};
let fine_map = generate_grain_map(w, h, &cfg_fine);
let coarse_map = generate_grain_map(w, h, &cfg_coarse);
let tv_fine: f32 = fine_map.windows(2).map(|p| (p[1] - p[0]).abs()).sum();
let tv_coarse: f32 = coarse_map.windows(2).map(|p| (p[1] - p[0]).abs()).sum();
assert!(
tv_coarse < tv_fine,
"coarser grain should have lower total variation ({} >= {})",
tv_coarse,
tv_fine
);
}
fn measured_grain_std(original: &[f32], grained: &[f32]) -> f32 {
let diffs: Vec<f32> = grained
.iter()
.zip(original.iter())
.map(|(&g, &o)| g - o)
.collect();
let n = diffs.len() as f32;
let mean: f32 = diffs.iter().sum::<f32>() / n;
let variance: f32 = diffs.iter().map(|&d| (d - mean).powi(2)).sum::<f32>() / n;
variance.sqrt()
}
#[test]
fn test_grain_std_tracks_intensity_across_grain_size() {
let w = 64;
let h = 64;
let intensity = 0.1_f32;
for &grain_size in &[1.0_f32, 1.5, 2.0, 3.0, 4.0] {
let cfg = FilmGrainConfig {
intensity,
grain_size,
luminance_scaling: false,
chroma_fraction: 0.0,
clip_output: false, ..FilmGrainConfig::default()
};
let original = vec![0.5_f32; w * h * 3];
let grained = apply_film_grain(&original, w, h, &cfg).expect("grain ok");
let std = measured_grain_std(&original, &grained);
assert!(
(std - intensity).abs() < intensity * 0.15,
"grain_size={grain_size}: measured std {std} should track intensity \
{intensity} (within 15%), ratio = {}",
std / intensity
);
}
}
#[test]
fn test_grain_std_tracks_intensity_across_chroma_fraction() {
let w = 64;
let h = 64;
let intensity = 0.1_f32;
for &chroma_fraction in &[0.0_f32, 0.25, 0.5, 0.75, 1.0] {
let cfg = FilmGrainConfig {
intensity,
grain_size: 1.0, luminance_scaling: false,
chroma_fraction,
clip_output: false,
..FilmGrainConfig::default()
};
let original = vec![0.5_f32; w * h * 3];
let grained = apply_film_grain(&original, w, h, &cfg).expect("grain ok");
let std = measured_grain_std(&original, &grained);
assert!(
(std - intensity).abs() < intensity * 0.15,
"chroma_fraction={chroma_fraction}: measured std {std} should track \
intensity {intensity} (within 15%), ratio = {}",
std / intensity
);
}
}
#[test]
fn test_sequence_base_and_frame_grain_streams_are_independent() {
let w = 32;
let h = 32;
let cfg = FilmGrainConfig {
intensity: 0.1,
grain_size: 1.0,
luminance_scaling: false,
chroma_fraction: 0.0,
clip_output: false,
..FilmGrainConfig::default()
};
let frames: Vec<Vec<f32>> = (0..2).map(|_| vec![0.5_f32; w * h * 3]).collect();
let base_only = apply_film_grain_sequence(&frames, w, h, &cfg, 1.0).expect("tc=1 ok");
let frame_only = apply_film_grain_sequence(&frames, w, h, &cfg, 0.0).expect("tc=0 ok");
let noise_base: Vec<f32> = base_only[0]
.iter()
.zip(frames[0].iter())
.map(|(&g, &o)| g - o)
.collect();
let noise_frame: Vec<f32> = frame_only[0]
.iter()
.zip(frames[0].iter())
.map(|(&g, &o)| g - o)
.collect();
let identical = noise_base
.iter()
.zip(noise_frame.iter())
.all(|(a, b)| (a - b).abs() < 1e-9);
assert!(
!identical,
"frame 0's own grain map must not be the shared base grain map"
);
let n = noise_base.len() as f32;
let mean_a = noise_base.iter().sum::<f32>() / n;
let mean_b = noise_frame.iter().sum::<f32>() / n;
let mut cov = 0.0_f32;
let mut var_a = 0.0_f32;
let mut var_b = 0.0_f32;
for (&a, &b) in noise_base.iter().zip(noise_frame.iter()) {
let da = a - mean_a;
let db = b - mean_b;
cov += da * db;
var_a += da * da;
var_b += db * db;
}
let corr = cov / (var_a.sqrt() * var_b.sqrt() + 1e-12);
assert!(
corr.abs() < 0.1,
"base and frame-0 grain must be uncorrelated, got r = {corr}"
);
}
#[test]
fn test_grain_std_tracks_intensity_across_temporal_coherence() {
let w = 64;
let h = 64;
let intensity = 0.1_f32;
for &tc in &[0.0_f32, 0.25, 0.5, 0.75, 1.0] {
let cfg = FilmGrainConfig {
intensity,
grain_size: 1.0,
luminance_scaling: false,
chroma_fraction: 0.0,
clip_output: false,
..FilmGrainConfig::default()
};
let frames: Vec<Vec<f32>> = (0..2).map(|_| vec![0.5_f32; w * h * 3]).collect();
let result =
apply_film_grain_sequence(&frames, w, h, &cfg, tc).expect("sequence grain ok");
let std = measured_grain_std(&frames[0], &result[0]);
assert!(
(std - intensity).abs() < intensity * 0.15,
"temporal_coherence={tc}: measured std {std} should track intensity \
{intensity} (within 15%), ratio = {}",
std / intensity
);
}
}
#[test]
fn test_apply_grain_rgba_wrong_length() {
let cfg = FilmGrainConfig::default();
let image = vec![0.5_f32; 10]; let result = apply_film_grain_rgba(&image, 4, 4, &cfg);
assert!(matches!(result, Err(FilmGrainError::InvalidImage(_))));
}
#[test]
fn test_apply_grain_sequence_invalid_coherence() {
let w = 4;
let h = 4;
let cfg = FilmGrainConfig::default();
let frames = vec![vec![0.5_f32; w * h * 3]];
let result = apply_film_grain_sequence(&frames, w, h, &cfg, 1.5);
assert!(matches!(result, Err(FilmGrainError::InvalidConfig(_))));
}
#[test]
fn test_apply_grain_sequence_empty_input() {
let cfg = FilmGrainConfig::default();
let result =
apply_film_grain_sequence(&[], 4, 4, &cfg, 0.5).expect("empty sequence should succeed");
assert!(result.is_empty());
}
}