SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Original bounded rough-dielectric, Cauchy dispersion and lossless thin-film math.
//!
//! The representative RGB wavelengths below define a three-band approximation,
//! not a sampled spectrum or a colour-matching-function integration. Equations:
//! Heitz (2018), https://jcgt.org/published/0007/04/01/paper.pdf (GGX VNDF);
//! Walter et al. (2007), https://www.graphics.cornell.edu/~bjw/microfacetbsdf.pdf
//! (refraction half-vector and Jacobian); Belcour and Barla (2017),
//! https://hal.science/hal-01518344/document (Airy interference). No source code
//! from those publications is incorporated here.
//! Shading-normal measures follow Veach (1997), sections 5.3.3--5.3.4:
//! https://graphics.stanford.edu/papers/veach_thesis/thesis.pdf.
use crate::{surface::unit_direction, transmission};
use serde::{Deserialize, Serialize};
use solidcore_record::Vec3;
use solidcraft_geom::Vec3Geom;
use std::f64::consts::{PI, TAU};
/// Fixed R, G, B representative bands. Thin films can alias in this approximation.
pub const WAVELENGTHS_NM: [f64; 3] = [610.0, 550.0, 460.0];
pub const MIN_WAVELENGTH_NM: f64 = 380.0;
pub const MAX_WAVELENGTH_NM: f64 = 780.0;
/// Fraunhofer wavelengths used for nd and vd; SCHOTT TIE-29, Table 1.
pub const D_LINE_NM: f64 = 587.5618;
pub const F_LINE_NM: f64 = 486.1327;
pub const C_LINE_NM: f64 = 656.2725;
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Dispersion {
pub abbe_number: f64,
}
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ThinFilm {
pub ior: f64,
pub thickness_nm: f64,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct GlassModel {
pub roughness: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub dispersion: Option<Dispersion>,
#[serde(skip_serializing_if = "Option::is_none")]
pub thin_film: Option<ThinFilm>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum GlassModelError {
Roughness,
Dispersion,
Film,
Ior,
Wavelength,
Angle,
Direction,
Sample,
Numerical,
}
impl std::fmt::Display for GlassModelError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::Roughness => "Glass roughness must be finite in [0, 1] with representable GGX width and peak",
Self::Dispersion => "Glass dispersion requires a finite Abbe number in [5, 200] and IOR in [1, 3] over 380..780 nm",
Self::Film => "Glass thin film requires finite IOR in [1, 3] and thickness in [0, 100000] nm",
Self::Ior => "Glass interface IOR must be finite in [1, 3]",
Self::Wavelength => "Glass wavelength must be finite in [380, 780] nm",
Self::Angle => "Glass incident cosine must be finite in [0, 1]",
Self::Direction => "Glass directions must be finite and nonzero; the normal must face the incident medium",
Self::Sample => "Glass sample coordinates must be finite in [0, 1)",
Self::Numerical => "Glass interface cannot be represented with finite nonnegative transport and density",
})
}
}
impl std::error::Error for GlassModelError {}
pub type Result<T> = std::result::Result<T, GlassModelError>;
/// One sampled radiance-transport continuation. `weight` is f*|cos(out)|/pdf,
/// including Fresnel branch selection and the transmitted radiance IOR ratio.
/// For delta events `pdf` is a discrete branch probability, not sr^-1. For the
/// index-matched coated transmission singularity it is conditional on the sampled
/// visible facet; delta paths must not use it as a continuous MIS density.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct InterfaceSample {
pub direction: Vec3,
pub weight: f64,
pub pdf: f64,
pub crosses: bool,
pub delta: bool,
}
/// Continuous interface value and matching full mixture density per solid angle.
/// `evaluate` returns the BSDF; `evaluate_projected` includes outgoing projected
/// cosine in `value`. Delta lobes return zero in this measure.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct InterfaceEvaluation {
pub value: f64,
pub pdf: f64,
}
fn valid_ior(ior: f64) -> bool {
ior.is_finite() && (1.0..=3.0).contains(&ior)
}
fn wavelength(value: f64) -> Result<()> {
if value.is_finite() && (MIN_WAVELENGTH_NM..=MAX_WAVELENGTH_NM).contains(&value) { Ok(()) } else { Err(GlassModelError::Wavelength) }
}
fn direction(value: Vec3) -> Result<Vec3> {
unit_direction(value).map_err(|_| GlassModelError::Direction)
}
// Compute positive products as a mantissa and a separate binary exponent. This
// preserves finite ratios when numerator and denominator products would both
// underflow, and refuses a genuinely unrepresentable positive result.
fn positive_ratio(numerator: &[f64], denominator: &[f64]) -> Result<f64> {
let mut mantissa = 1.0;
let mut exponent = 0_i32;
for (values, divide) in [(numerator, false), (denominator, true)] {
for &value in values {
if !value.is_finite() || value <= 0.0 {
return Err(GlassModelError::Numerical);
}
let (scaled, adjustment) = if value < f64::MIN_POSITIVE { (value * 4503599627370496.0, -52) } else { (value, 0) };
let bits = scaled.to_bits();
let power = ((bits >> 52) & 0x7ff) as i32 - 1023 + adjustment;
let fraction = f64::from_bits((bits & 0x000f_ffff_ffff_ffff) | 0x3ff0_0000_0000_0000);
if divide {
mantissa /= fraction;
exponent -= power;
} else {
mantissa *= fraction;
exponent += power;
}
while mantissa >= 2.0 {
mantissa *= 0.5;
exponent += 1;
}
while mantissa < 1.0 {
mantissa *= 2.0;
exponent -= 1;
}
}
}
let value = if exponent < -1022 {
(mantissa * 2.0_f64.powi(exponent + 1074)) * f64::from_bits(1)
} else if exponent <= 1023 {
mantissa * 2.0_f64.powi(exponent)
} else {
return Err(GlassModelError::Numerical);
};
if value.is_finite() && value > 0.0 { Ok(value) } else { Err(GlassModelError::Numerical) }
}
/// Adjoint shading-normal correction for a photon continuation. `incident`
/// travels toward the interface, `outgoing` travels away; normals describe a
/// fixed facet model. Remove the radiance transmission (ni/nt)^2 first. This is
/// |wo.ns| |wi.ng| / (|wo.ng| |wi.ns|), with wo=-incident and wi=outgoing.
/// Exact tangent projections have zero measure and return zero; invalid vectors
/// and a nonrepresentable positive ratio are errors, never epsilon-clamped.
pub fn importance_normal_correction(incident: Vec3, outgoing: Vec3, shading_normal: Vec3, geometric_normal: Vec3) -> Result<f64> {
let wo = -direction(incident)?;
let wi = direction(outgoing)?;
let ns = direction(shading_normal)?;
let ng = direction(geometric_normal)?;
let a = wo.dot(ns).abs();
let b = wi.dot(ng).abs();
let c = wo.dot(ng).abs();
let d = wi.dot(ns).abs();
if a == 0.0 || b == 0.0 || c == 0.0 || d == 0.0 {
return Ok(0.0);
}
positive_ratio(&[a, b], &[c, d])
}
/// Convert photon flux per geometric area to a shading-normal BSDF measure.
/// `incoming_light` points from the receiver toward the photon's previous point.
/// Multiply the surface density estimate by f * this ratio, without an extra
/// cosine: the deposited flux already includes geometric projected incidence.
pub fn surface_normal_measure(incoming_light: Vec3, shading_normal: Vec3, geometric_normal: Vec3) -> Result<f64> {
let incoming = direction(incoming_light)?;
let ns = direction(shading_normal)?;
let ng = direction(geometric_normal)?;
let numerator = incoming.dot(ns).abs();
let denominator = incoming.dot(ng).abs();
if numerator == 0.0 || denominator == 0.0 {
return Ok(0.0);
}
positive_ratio(&[numerator], &[denominator])
}
/// Uniform sphere kernel for a photon map gathered at an analog camera
/// scattering collision: 3/(4*pi*r^3*sigma_s), in inverse mm^2. Light collision
/// density is sigma_s times fluence; camera free-flight sampling already
/// includes sigma_s, so it must be divided out here. Multiply by the phase
/// function and photon flux. A ray-marched volume estimator has another measure.
pub fn volume_photon_kernel(radius_mm: f64, sigma_s_per_mm: f64) -> Result<f64> {
if !radius_mm.is_finite() || radius_mm <= 0.0 || !sigma_s_per_mm.is_finite() || sigma_s_per_mm <= 0.0 {
return Err(GlassModelError::Numerical);
}
positive_ratio(&[3.0], &[4.0 * PI, radius_mm, radius_mm, radius_mm, sigma_s_per_mm])
}
impl GlassModel {
fn controls(self) -> Result<()> {
let alpha = self.roughness * self.roughness;
let peak_root = 1.0 / (alpha * PI.sqrt());
if !self.roughness.is_finite()
|| !(0.0..=1.0).contains(&self.roughness)
|| (self.roughness > 0.0 && (alpha == 0.0 || alpha * alpha == 0.0 || !(peak_root * peak_root).is_finite()))
{
return Err(GlassModelError::Roughness);
}
if self.dispersion.is_some_and(|d| !d.abbe_number.is_finite() || !(5.0..=200.0).contains(&d.abbe_number)) {
return Err(GlassModelError::Dispersion);
}
if self.thin_film.is_some_and(|f| !valid_ior(f.ior) || !f.thickness_nm.is_finite() || !(0.0..=100000.0).contains(&f.thickness_nm)) {
return Err(GlassModelError::Film);
}
Ok(())
}
pub fn validate(self, base_ior: f64) -> Result<()> {
self.controls()?;
if !valid_ior(base_ior) {
return Err(GlassModelError::Ior);
}
// Two-term normal Cauchy dispersion is monotone, so endpoints prove the
// complete bounded wavelength domain without silently clamping an IOR.
for nm in [MIN_WAVELENGTH_NM, MAX_WAVELENGTH_NM] {
if !valid_ior(self.cauchy(base_ior, nm)) {
return Err(GlassModelError::Dispersion);
}
}
Ok(())
}
pub fn spectral(self) -> bool {
self.dispersion.is_some() || self.thin_film.is_some_and(|film| film.thickness_nm > 0.0)
}
pub fn is_identity(self) -> bool {
self.roughness == 0.0 && self.dispersion.is_none() && self.thin_film.is_none_or(|film| film.thickness_nm == 0.0)
}
fn cauchy(self, base_ior: f64, nm: f64) -> f64 {
let Some(dispersion) = self.dispersion else { return base_ior };
let inverse_square = |nm: f64| 1.0 / (nm * nm);
let b = ((base_ior - 1.0) / dispersion.abbe_number) / (inverse_square(F_LINE_NM) - inverse_square(C_LINE_NM));
base_ior + b * (inverse_square(nm) - inverse_square(D_LINE_NM))
}
/// Two-term Cauchy approximation anchored at nd, with vd=(nd-1)/(nF-nC).
/// Abbe number alone is not a measured Sellmeier model for a named glass.
pub fn ior(self, base_ior: f64, wavelength_nm: f64) -> Result<f64> {
wavelength(wavelength_nm)?;
self.validate(base_ior)?;
Ok(self.cauchy(base_ior, wavelength_nm))
}
/// Lossless single-layer coherent Airy response. ni/nt are the actual IORs
/// at the supplied wavelength; dispersion is resolved by the caller. The
/// substrate's Snell cosine is preserved even when the film is evanescent.
pub fn fresnel(self, cosine: f64, ni: f64, nt: f64, wavelength_nm: f64) -> Result<transmission::Fresnel> {
self.controls()?;
wavelength(wavelength_nm)?;
if !cosine.is_finite() || !(0.0..=1.0).contains(&cosine) {
return Err(GlassModelError::Angle);
}
if !valid_ior(ni) || !valid_ior(nt) {
return Err(GlassModelError::Ior);
}
let bare = transmission::fresnel(cosine, ni, nt).map_err(|_| GlassModelError::Numerical)?;
let Some(film) = self.thin_film.filter(|film| film.thickness_nm > 0.0) else { return Ok(bare) };
if film.ior == ni || film.ior == nt || bare.transmitted_cosine.is_none() {
return Ok(bare);
}
if cosine == 0.0 {
return Ok(transmission::Fresnel { s: 1.0, p: 1.0, transmitted_cosine: bare.transmitted_cosine });
}
let transverse_square = ni * ni * (1.0 - cosine * cosine).max(0.0);
let film_longitudinal_square = film.ior * film.ior - transverse_square;
let qf = if film_longitudinal_square >= 0.0 {
Complex::real(film_longitudinal_square.sqrt())
} else {
Complex { re: 0.0, im: (-film_longitudinal_square).sqrt() }
};
let qi = ni * cosine;
let qt = nt * bare.transmitted_cosine.ok_or(GlassModelError::Numerical)?;
let k = TAU * film.thickness_nm / wavelength_nm;
let polarized = |p: bool| -> Result<f64> {
let (yi, yt, factor) = if p { (qi / (ni * ni), qt / (nt * nt), film.ior * film.ior) } else { (qi, qt, 1.0) };
let phase = qf.scale(k);
let amplitude = if phase.norm_square() < 1e-6 {
// Transfer matrix written with sin(delta)/qf. Its power series
// remains finite at the exact film critical angle qf=0, where
// the direct Airy quotient otherwise becomes 0/0.
let z2 = phase.mul(phase);
let z4 = z2.mul(z2);
let z6 = z4.mul(z2);
let a = Complex::real(1.0).sub(z2.scale(0.5)).add(z4.scale(1.0 / 24.0)).sub(z6.scale(1.0 / 720.0));
let sinc = Complex::real(1.0).sub(z2.scale(1.0 / 6.0)).add(z4.scale(1.0 / 120.0)).sub(z6.scale(1.0 / 5040.0));
let b = sinc.minus_i().scale(k * factor);
let c = sinc.minus_i().scale(k * film_longitudinal_square / factor);
let common = b.scale(yi * yt);
a.scale(yi - yt).add(common).sub(c).div(a.scale(yi + yt).add(common).add(c))?
} else {
let yf = qf.scale(1.0 / factor);
let r01 = Complex::real(yi).sub(yf).div(Complex::real(yi).add(yf))?;
let r12 = yf.sub(Complex::real(yt)).div(yf.add(Complex::real(yt)))?;
let decay = (-2.0 * phase.im).exp();
let (sine, cosine) = (2.0 * phase.re).sin_cos();
let propagation = Complex { re: decay * cosine, im: decay * sine };
let second = r12.mul(propagation);
r01.add(second).div(Complex::real(1.0).add(r01.mul(second)))?
};
let power = amplitude.norm_square();
if !power.is_finite() || !(0.0..=1.0 + 1e-10).contains(&power) {
return Err(GlassModelError::Numerical);
}
// Only the roundoff of a lossless power sum can exceed one here.
Ok(power.min(1.0))
};
Ok(transmission::Fresnel { s: polarized(false)?, p: polarized(true)?, transmitted_cosine: bare.transmitted_cosine })
}
/// Isotropic GGX visible-normal sampling. Incident points toward the surface;
/// macro_normal points into its incident medium. uniforms are facet-u,
/// facet-v, Fresnel branch. A returned None is an actual zero contribution;
/// retrying until a sample passes would change the estimator.
pub fn sample(
self,
incident: Vec3,
macro_normal: Vec3,
ni: f64,
nt: f64,
wavelength_nm: f64,
uniforms: [f64; 3],
) -> Result<Option<InterfaceSample>> {
self.controls()?;
wavelength(wavelength_nm)?;
if !valid_ior(ni) || !valid_ior(nt) {
return Err(GlassModelError::Ior);
}
if uniforms.into_iter().any(|u| !u.is_finite() || !(0.0..1.0).contains(&u)) {
return Err(GlassModelError::Sample);
}
let d = direction(incident)?;
let n = direction(macro_normal)?;
let v = -d;
let cv = v.dot(n);
if cv < 0.0 {
return Err(GlassModelError::Direction);
}
let smooth = self.roughness == 0.0 || (ni == nt && self.thin_film.is_none_or(|f| f.thickness_nm == 0.0 || f.ior == ni));
let m = if smooth {
n
} else {
if cv == 0.0 {
return Ok(None);
}
visible_normal(v, n, self.roughness * self.roughness, [uniforms[0], uniforms[1]])?
};
let vm = v.dot(m).clamp(0.0, 1.0);
let fresnel = self.fresnel(vm, ni, nt, wavelength_nm)?;
let reflected = uniforms[2] < fresnel.reflectance() || fresnel.transmitted_cosine.is_none();
let (out, probability, crosses) = if reflected {
(direction(d + m * (2.0 * vm))?, fresnel.reflectance(), false)
} else {
let out = transmission::refract(d, m, ni, nt).map_err(|_| GlassModelError::Numerical)?.ok_or(GlassModelError::Numerical)?;
(direction(out)?, 1.0 - fresnel.reflectance(), true)
};
let cl = out.dot(n);
if !smooth && ((!crosses && cl <= 0.0) || (crosses && cl >= 0.0)) {
return Ok(None);
}
let radiance = if crosses { (ni / nt).powi(2) } else { 1.0 };
let delta = smooth || (crosses && ni == nt);
let weight = if smooth { radiance } else { smith_ratio(cv, cl.abs(), self.roughness * self.roughness) * radiance };
let pdf = if delta { probability } else { self.evaluate(d, out, n, ni, nt, wavelength_nm)?.pdf };
if !weight.is_finite() || weight < 0.0 || !pdf.is_finite() || pdf <= 0.0 {
return Err(GlassModelError::Numerical);
}
Ok(Some(InterfaceSample { direction: out, weight, pdf, crosses, delta }))
}
/// Continuous radiance BSDF and complete reflection/transmission PDF for the
/// same VNDF/Fresnel mixture as sample. Rough transmission uses Walter's
/// half-vector Jacobian and the radiance (ni/nt)^2 transport conversion.
pub fn evaluate(self, incident: Vec3, outgoing: Vec3, macro_normal: Vec3, ni: f64, nt: f64, wavelength_nm: f64) -> Result<InterfaceEvaluation> {
self.evaluate_measure(incident, outgoing, macro_normal, ni, nt, wavelength_nm, false)
}
/// Continuous radiance BSDF times the outgoing projected cosine, with the
/// same complete mixture PDF as `evaluate`. This is the direct-light
/// integrand and avoids dividing by a tiny outgoing cosine only to multiply
/// it back. Discrete lobes remain zero in this solid-angle measure.
pub fn evaluate_projected(
self,
incident: Vec3,
outgoing: Vec3,
macro_normal: Vec3,
ni: f64,
nt: f64,
wavelength_nm: f64,
) -> Result<InterfaceEvaluation> {
self.evaluate_measure(incident, outgoing, macro_normal, ni, nt, wavelength_nm, true)
}
#[allow(clippy::too_many_arguments)]
fn evaluate_measure(
self,
incident: Vec3,
outgoing: Vec3,
macro_normal: Vec3,
ni: f64,
nt: f64,
wavelength_nm: f64,
projected: bool,
) -> Result<InterfaceEvaluation> {
self.controls()?;
// This also validates the actual wavelength/IORs on all zero-lobe paths.
self.fresnel(1.0, ni, nt, wavelength_nm)?;
let v = -direction(incident)?;
let l = direction(outgoing)?;
let n = direction(macro_normal)?;
let cv = v.dot(n);
let cl = l.dot(n);
if cv < 0.0 {
return Err(GlassModelError::Direction);
}
if self.roughness == 0.0 || cv == 0.0 || cl == 0.0 || (cl < 0.0 && ni == nt) {
return Ok(InterfaceEvaluation::default());
}
let sum = if cl > 0.0 { v + l } else { v * ni + l * nt };
let mut m = direction(sum)?;
if m.dot(n) < 0.0 {
m = -m;
}
let vm = v.dot(m);
let lm = l.dot(m);
if vm <= 0.0 || (cl > 0.0 && lm <= 0.0) || (cl < 0.0 && lm >= 0.0) {
return Ok(InterfaceEvaluation::default());
}
let alpha = self.roughness * self.roughness;
let d = ggx_distribution(m, n, alpha);
let g1 = smith_g1(cv, alpha);
let g2 = g1 * smith_ratio(cv, cl.abs(), alpha);
let visible_pdf = d * (2.0 * vm / (cv + smith_root(cv, alpha)));
let f = self.fresnel(vm.min(1.0), ni, nt, wavelength_nm)?.reflectance();
let outgoing_measure = if projected { 1.0 } else { cl.abs() };
let result = if cl > 0.0 {
InterfaceEvaluation { value: d * (f * g2 / (4.0 * cv * outgoing_measure)), pdf: visible_pdf * (f / (4.0 * vm)) }
} else {
let denominator = ni * vm + nt * lm;
if denominator == 0.0 {
return Ok(InterfaceEvaluation::default());
}
let jacobian = nt * nt * lm.abs() / (denominator * denominator);
InterfaceEvaluation {
value: d * ((1.0 - f) * g2 * (vm * lm).abs() * ni * ni / (cv * outgoing_measure * denominator * denominator)),
pdf: (1.0 - f) * visible_pdf * jacobian,
}
};
if !result.value.is_finite() || !result.pdf.is_finite() || result.value < 0.0 || result.pdf < 0.0 {
return Err(GlassModelError::Numerical);
}
Ok(result)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn close(actual: f64, expected: f64, tolerance: f64) {
assert!((actual - expected).abs() <= tolerance, "{actual} differs from {expected} by more than {tolerance}");
}
fn film(ior: f64, thickness_nm: f64) -> GlassModel {
GlassModel { thin_film: Some(ThinFilm { ior, thickness_nm }), ..Default::default() }
}
fn radical_inverse(mut bits: u32) -> f64 {
bits = bits.reverse_bits();
f64::from(bits) / 4294967296.0
}
#[test]
fn hard_directional_normal_ggx_response_matches_independent_peak_and_projected_measure() {
for roughness in [0.05_f64, 0.2, 0.7, 1.0] {
let model = GlassModel { roughness, ..Default::default() };
// At normal reflection h=n, G=1, D=1/(pi*r^4), F=((1-1.5)/(1+1.5))^2.
let expected = 0.04 / (4.0 * PI * roughness.powi(4));
let value = model.evaluate_projected(-Vec3::Z, Vec3::Z, Vec3::Z, 1.0, 1.5, 550.0).unwrap();
close(value.value / expected, 1.0, 2e-15);
close(value.pdf / expected, 1.0, 2e-15);
for uniforms in [[0.01, 0.3, 0.0], [0.1, 0.4, 0.9], [0.4, 0.7, 0.5]] {
if let Some(sample) = model.sample(-Vec3::Z, Vec3::Z, 1.0, 1.5, 550.0, uniforms).unwrap() {
let projected = model.evaluate_projected(-Vec3::Z, sample.direction, Vec3::Z, 1.0, 1.5, 550.0).unwrap();
let unprojected = model.evaluate(-Vec3::Z, sample.direction, Vec3::Z, 1.0, 1.5, 550.0).unwrap();
close(projected.value / projected.pdf, sample.weight, 3e-13);
close(projected.value / (unprojected.value * sample.direction.z.abs()), 1.0, 3e-13);
assert_eq!(projected.pdf, unprojected.pdf);
}
}
}
// This peak fits in f64 even though squaring the GGX denominator does not.
let tiny = GlassModel { roughness: 1e-50, ..Default::default() };
let value = tiny.evaluate_projected(-Vec3::Z, Vec3::Z, Vec3::Z, 1.0, 1.5, 550.0).unwrap();
close(value.value / (0.01 / PI * 1e200), 1.0, 2e-15);
assert_eq!(GlassModel { roughness: 1e-80, ..Default::default() }.validate(1.5), Err(GlassModelError::Roughness));
}
#[test]
fn adjoint_normal_and_flux_area_measures_match_fixed_facet_geometry() {
let ng = Vec3::Z;
let ns = Vec3::new(0.6, 0.0, 0.8);
let wo = Vec3::new(0.0, 0.6, 0.8);
let wi = Vec3::new(-0.8, 0.0, 0.6);
// Independent scalar dot products: wo.ns=.64, wi.ng=.6,
// wo.ng=.8, wi.ns=0. Exact cancellation must survive near grazing too.
assert_eq!(importance_normal_correction(-wo, wi, ns, ng).unwrap(), 0.0);
let wi = Vec3::new(0.8, 0.0, 0.6);
let correction = importance_normal_correction(-wo, wi, ns, ng).unwrap();
close(correction, (0.64 * 0.6) / (0.8 * 0.96), 2e-16);
let reverse = importance_normal_correction(-wi, wo, ns, ng).unwrap();
close(correction * reverse, 1.0, 3e-16);
close(surface_normal_measure(wi, ns, ng).unwrap(), 0.96 / 0.6, 3e-16);
// A planar photon count already measures wi.ng; the ratio converts it
// into wi.ns once, rather than adding a second cosine to deposited flux.
let geometric_irradiance = 7.0 * 0.6;
close(geometric_irradiance * surface_normal_measure(wi, ns, ng).unwrap(), 7.0 * 0.96, 2e-15);
for normal in [Vec3::Z, -Vec3::Z] {
close(importance_normal_correction(-wo, wi, normal, ng).unwrap(), 1.0, 0.0);
}
let grazing = Vec3::new(1.0, 0.0, 1e-300);
close(importance_normal_correction(-grazing, grazing, Vec3::X, Vec3::Z).unwrap(), 1.0, 0.0);
close(importance_normal_correction(-grazing, grazing, Vec3::Z, Vec3::Z).unwrap(), 1.0, 0.0);
let opposite_grazing = Vec3::new(1e-300, 0.0, 1.0);
assert_eq!(importance_normal_correction(-grazing, opposite_grazing, Vec3::X, Vec3::Z), Err(GlassModelError::Numerical));
close(importance_normal_correction(-wo * 1e300, wi * 1e300, ns * 1e300, ng * 1e300).unwrap(), correction, 3e-16);
assert_eq!(surface_normal_measure(Vec3::X, Vec3::Z, Vec3::Z).unwrap(), 0.0);
assert_eq!(surface_normal_measure(Vec3::ZERO, ns, ng), Err(GlassModelError::Direction));
assert_eq!(importance_normal_correction(Vec3::new(f64::NAN, 0.0, 0.0), wi, ns, ng), Err(GlassModelError::Direction));
}
#[test]
fn analog_volume_photon_measure_has_correct_density_units_and_sigma_cancellation() {
let radius = 2.5_f64;
let sigma = 0.2;
let ball_volume = 4.0 * PI * radius.powi(3) / 3.0;
let kernel = volume_photon_kernel(radius, sigma).unwrap();
close(kernel * ball_volume * sigma, 1.0, 2e-16);
// A homogeneous field with fluence Phi deposits sigma*Phi collisions per
// volume; an isotropic analog camera collision must recover Phi/(4*pi).
let fluence = 11.0;
let isotropic_phase = 1.0 / (4.0 * PI);
close(kernel * (sigma * fluence * ball_volume) * isotropic_phase, fluence * isotropic_phase, 3e-16);
close(volume_photon_kernel(radius * 2.0, sigma).unwrap() * 8.0, kernel, 0.0);
close(volume_photon_kernel(radius, sigma * 2.0).unwrap() * 2.0, kernel, 0.0);
close(volume_photon_kernel(1e100, 1e-300).unwrap(), 3.0 / (4.0 * PI), 2e-16);
// Unit conversion mm -> metre: radius /1000 and sigma *1000; an
// inverse-area estimator consequently gains 10^6, without changing flux.
close(volume_photon_kernel(radius / 1000.0, sigma * 1000.0).unwrap() / kernel, 1e6, 3e-10);
for (r, s) in [(0.0, sigma), (-1.0, sigma), (f64::INFINITY, sigma), (radius, 0.0), (radius, f64::NAN), (1e-200, sigma)] {
assert_eq!(volume_photon_kernel(r, s), Err(GlassModelError::Numerical));
}
}
#[test]
fn photon_hg_receiver_angle_uses_physical_forward_propagation() {
let medium = crate::transmission::subsurface::Subsurface { scattering_per_mm: 0.2, anisotropy: 0.6 };
let incoming_light = Vec3::Z; // The photon's physical travel is -Z.
let camera_incident = Vec3::Z; // The scattered travel toward the eye is -Z.
let forward_cosine = camera_incident.dot(incoming_light);
let backward_cosine = (-camera_incident).dot(incoming_light);
let forward = medium.phase(forward_cosine).unwrap();
let backward = medium.phase(backward_cosine).unwrap();
let g = medium.anisotropy;
close(forward, (1.0 + g) / (4.0 * PI * (1.0 - g).powi(2)), 2e-15);
close(backward, (1.0 - g) / (4.0 * PI * (1.0 + g).powi(2)), 2e-17);
close(forward / backward, ((1.0 + g) / (1.0 - g)).powi(3), 2e-13);
assert!(forward > backward);
}
#[test]
fn one_record_uniform_receiver_reservoir_is_unbiased_for_every_bounded_path_length() {
// Count all replacement decisions exactly, without Monte Carlo or a
// production reservoir helper: stage k has k equally likely outcomes,
// one replaces the record and k-1 retain it. At k<=16, k! fits in u64.
let mut histories = vec![1_u64];
let mut total = 1_u64;
for k in 1..=16_usize {
if k > 1 {
for count in &mut histories {
*count *= (k - 1) as u64;
}
histories.push(total);
total *= k as u64;
}
assert_eq!(histories.iter().copied().sum::<u64>(), total);
let mut expected_numerator = 0_u128;
let mut reference_sum = 0_u128;
for (index, &count) in histories.iter().enumerate() {
assert_eq!(count * k as u64, total);
let flux = (index + 2).pow(2) as u128;
let receiver_response = (3 * index + 1) as u128;
reference_sum += flux * receiver_response;
expected_numerator += u128::from(count) * k as u128 * flux * receiver_response;
}
assert_eq!(expected_numerator, u128::from(total) * reference_sum);
// Dividing by launched paths rather than retained records also
// preserves zero-deposit paths: append one empty launch explicitly.
close(expected_numerator as f64 / total as f64 / 2.0, reference_sum as f64 / 2.0, 0.0);
}
}
#[test]
fn bounded_models_round_trip_and_refuse_hostile_values() {
let model = GlassModel {
roughness: 0.3,
dispersion: Some(Dispersion { abbe_number: 60.0 }),
thin_film: Some(ThinFilm { ior: 1.38, thickness_nm: 285.0 }),
};
model.validate(1.5).unwrap();
assert_eq!(serde_json::from_value::<GlassModel>(serde_json::to_value(model).unwrap()).unwrap(), model);
assert_eq!(serde_json::from_str::<GlassModel>("{}").unwrap(), GlassModel::default());
assert!(serde_json::from_str::<GlassModel>(r#"{"roughnes":0.5}"#).is_err());
assert!(serde_json::from_str::<GlassModel>(r#"{"dispersion":{"abbe_number":40,"unknown":0}}"#).is_err());
for roughness in [-1.0, f64::NAN, f64::INFINITY, 1.1, f64::MIN_POSITIVE] {
assert_eq!(GlassModel { roughness, ..Default::default() }.validate(1.5), Err(GlassModelError::Roughness));
}
for abbe_number in [0.0, 4.99, 200.1, f64::NAN, f64::INFINITY] {
assert_eq!(
GlassModel { dispersion: Some(Dispersion { abbe_number }), ..Default::default() }.validate(1.5),
Err(GlassModelError::Dispersion)
);
}
for bad in [
ThinFilm { ior: 0.99, thickness_nm: 10.0 },
ThinFilm { ior: 1.4, thickness_nm: -1.0 },
ThinFilm { ior: 1.4, thickness_nm: f64::NAN },
ThinFilm { ior: 1.4, thickness_nm: 100001.0 },
] {
assert_eq!(GlassModel { thin_film: Some(bad), ..Default::default() }.validate(1.5), Err(GlassModelError::Film));
}
assert!(!film(1.4, 0.0).spectral());
assert!(film(1.4, 1.0).spectral());
assert!(film(1.4, 0.0).is_identity());
assert!(GlassModel { dispersion: Some(Dispersion { abbe_number: 100.0 }), ..Default::default() }.spectral());
}
#[test]
fn cauchy_fit_matches_independent_abbe_definition_and_visible_ordering() {
for (nd, vd) in [(1.33, 55.0), (1.5, 60.0), (1.8, 25.0), (2.0, 12.0)] {
let model = GlassModel { dispersion: Some(Dispersion { abbe_number: vd }), ..Default::default() };
close(model.ior(nd, D_LINE_NM).unwrap(), nd, 1e-15);
let f = model.ior(nd, F_LINE_NM).unwrap();
let c = model.ior(nd, C_LINE_NM).unwrap();
close((nd - 1.0) / (f - c), vd, 2e-11);
let [r, g, b] = WAVELENGTHS_NM.map(|nm| model.ior(nd, nm).unwrap());
assert!(b > g && g > r);
for nm in [MIN_WAVELENGTH_NM, MAX_WAVELENGTH_NM] {
close(model.ior(1.0, nm).unwrap(), 1.0, 0.0);
}
}
let strong = GlassModel { dispersion: Some(Dispersion { abbe_number: 5.0 }), ..Default::default() };
assert_eq!(strong.validate(3.0), Err(GlassModelError::Dispersion));
assert_eq!(strong.ior(1.5, 1000.0), Err(GlassModelError::Wavelength));
}
#[test]
fn no_film_and_zero_thickness_preserve_bare_fresnel_exactly() {
for (ni, nt) in [(1.0, 1.5), (1.5, 1.0), (1.5, 1.5)] {
for cosine in [0.0, 0.001, 0.3, 0.8, 1.0] {
let bare = transmission::fresnel(cosine, ni, nt).unwrap();
for model in [GlassModel::default(), film(1.38, 0.0), film(ni, 500.0), film(nt, 500.0)] {
assert_eq!(model.fresnel(cosine, ni, nt, 550.0).unwrap(), bare);
}
}
}
let brewster_cosine = (1.5_f64).atan().cos();
let brewster = GlassModel::default().fresnel(brewster_cosine, 1.0, 1.5, 550.0).unwrap();
assert!(brewster.p < 1e-30 && brewster.s > 0.1);
assert_eq!(film(1.38, 500.0).fresnel(0.3, 1.5, 1.0, 550.0).unwrap().transmitted_cosine, None);
}
#[test]
fn airy_quarter_wave_antireflection_and_periodicity_match_analytic_limits() {
let nf = 1.5_f64.sqrt();
let quarter = film(nf, 550.0 / (4.0 * nf));
let response = quarter.fresnel(1.0, 1.0, 1.5, 550.0).unwrap();
assert!(response.s < 1e-28 && response.p < 1e-28);
for cosine in [0.2, 0.6, 1.0] {
let cosine_film = (1.0 - (1.0 - cosine * cosine) / 1.38_f64.powi(2)).sqrt();
let period = 550.0 / (2.0 * 1.38 * cosine_film);
let a = film(1.38, 285.0).fresnel(cosine, 1.0, 1.5, 550.0).unwrap();
let b = film(1.38, 285.0 + period).fresnel(cosine, 1.0, 1.5, 550.0).unwrap();
close(a.s, b.s, 2e-14);
close(a.p, b.p, 2e-14);
assert_eq!(a.transmitted_cosine, transmission::fresnel(cosine, 1.0, 1.5).unwrap().transmitted_cosine);
}
}
#[test]
fn film_evanescence_tunnels_and_critical_angle_is_continuous() {
let thin = film(1.0, 1e-5).fresnel(0.5, 1.5, 1.5, 550.0).unwrap();
let medium = film(1.0, 100.0).fresnel(0.5, 1.5, 1.5, 550.0).unwrap();
let thick = film(1.0, 100000.0).fresnel(0.5, 1.5, 1.5, 550.0).unwrap();
assert!(thin.reflectance() < 1e-12);
assert!(medium.reflectance() > 0.1 && medium.reflectance() < 1.0);
close(thick.s, 1.0, 1e-14);
close(thick.p, 1.0, 1e-14);
let critical_cosine = 5.0_f64.sqrt() / 3.0;
let at = film(1.0, 200.0).fresnel(critical_cosine, 1.5, 1.5, 550.0).unwrap();
for offset in [-1e-9, 1e-9] {
let near = film(1.0, 200.0).fresnel(critical_cosine + offset, 1.5, 1.5, 550.0).unwrap();
close(at.s, near.s, 1e-7);
close(at.p, near.p, 1e-7);
}
assert!(at.s.is_finite() && at.p.is_finite());
}
#[test]
fn film_power_is_bounded_and_reciprocal_at_matching_optical_angles() {
for thickness in [1e-8, 50.0, 285.0, 10000.0, 100000.0] {
for nm in WAVELENGTHS_NM {
for cosine in [0.01, 0.2, 0.7, 1.0] {
let model = film(1.1, thickness);
let forward = model.fresnel(cosine, 1.0, 1.5, nm).unwrap();
assert!((0.0..=1.0).contains(&forward.s) && (0.0..=1.0).contains(&forward.p));
let reverse = model.fresnel(forward.transmitted_cosine.unwrap(), 1.5, 1.0, nm).unwrap();
close(forward.s, reverse.s, 1e-10);
close(forward.p, reverse.p, 1e-10);
}
}
}
}
#[test]
fn rough_sampling_weights_equal_continuous_bsdf_over_full_pdf() {
for roughness in [0.12, 0.5, 1.0] {
for (ni, nt) in [(1.0, 1.5), (1.5, 1.0)] {
for cosine in [0.2, 0.7, 1.0] {
let incident = Vec3::new((1.0_f64 - cosine * cosine).sqrt(), 0.0, -cosine);
let model = GlassModel { roughness, thin_film: Some(ThinFilm { ior: 1.38, thickness_nm: 270.0 }), ..Default::default() };
let mut accepted = 0;
for i in 0..2048_u32 {
let random =
[(f64::from(i) + 0.5) / 2048.0, radical_inverse(i), radical_inverse(i.wrapping_mul(1664525).wrapping_add(1013904223))];
if let Some(sample) = model.sample(incident, Vec3::Z, ni, nt, 550.0, random).unwrap() {
assert!(!sample.delta);
assert_eq!(sample.crosses, sample.direction.z < 0.0);
let eval = model.evaluate(incident, sample.direction, Vec3::Z, ni, nt, 550.0).unwrap();
close(sample.pdf, eval.pdf, sample.pdf * 1e-12 + 1e-14);
close(sample.weight, eval.value * sample.direction.z.abs() / eval.pdf, sample.weight * 2e-8 + 1e-10);
assert!(sample.weight >= 0.0 && sample.weight <= (ni / nt).powi(2).max(1.0) * (1.0 + 1e-12));
accepted += 1;
}
}
assert!(accepted > 200);
}
}
}
}
#[test]
fn visible_normal_density_integrates_to_one_and_rough_furnace_cannot_gain_energy() {
let nz = 256_u32;
let np = 512_u32;
let solid_angle = TAU / f64::from(nz * np);
for alpha in [0.3, 0.7, 1.0] {
for cosine in [0.2, 0.7, 1.0] {
let v = Vec3::new((1.0_f64 - cosine * cosine).sqrt(), 0.0, cosine);
let mut integral = 0.0;
for z in 0..nz {
let z = (f64::from(z) + 0.5) / f64::from(nz);
let radius = (1.0 - z * z).sqrt();
for phi in 0..np {
let (s, c) = (TAU * (f64::from(phi) + 0.5) / f64::from(np)).sin_cos();
let m = Vec3::new(radius * c, radius * s, z);
integral += ggx_distribution(m, Vec3::Z, alpha) * smith_g1(cosine, alpha) * v.dot(m).max(0.0) / cosine;
}
}
close(integral * solid_angle, 1.0, 0.002);
let model = GlassModel { roughness: alpha.sqrt(), ..Default::default() };
let mut furnace = 0.0;
for i in 0..8192_u32 {
let random =
[(f64::from(i) + 0.5) / 8192.0, radical_inverse(i), radical_inverse(i.wrapping_mul(1664525).wrapping_add(1013904223))];
if let Some(sample) = model.sample(-v, Vec3::Z, 1.0, 1.5, 550.0, random).unwrap() {
furnace += sample.weight * if sample.crosses { 1.5 * 1.5 } else { 1.0 };
}
}
assert!((0.45..=1.000000001).contains(&(furnace / 8192.0)), "rough single-scattering furnace={}", furnace / 8192.0);
}
}
}
#[test]
fn matched_indices_and_zero_roughness_retain_discrete_physical_limits() {
let incident = direction(Vec3::new(0.8, 0.0, -0.6)).unwrap();
for roughness in [0.0, 0.5, 1.0] {
let model = GlassModel { roughness, ..Default::default() };
let sample = model.sample(incident, Vec3::Z, 1.5, 1.5, 550.0, [0.7, 0.2, 0.1]).unwrap().unwrap();
assert!(sample.delta && sample.crosses);
close(sample.weight, 1.0, 0.0);
close((sample.direction - incident).len(), 0.0, 1e-15);
}
let model = GlassModel::default();
let reflected = model.sample(incident, Vec3::Z, 1.0, 1.5, 550.0, [0.0; 3]).unwrap().unwrap();
assert!(reflected.delta && !reflected.crosses);
close(reflected.weight, 1.0, 0.0);
let transmitted = model.sample(incident, Vec3::Z, 1.0, 1.5, 550.0, [0.9; 3]).unwrap().unwrap();
assert!(transmitted.delta && transmitted.crosses);
close(transmitted.weight, 1.0 / 2.25, 1e-15);
assert_eq!(model.sample(incident, Vec3::Z, 1.0, 1.5, 550.0, [1.0, 0.0, 0.0]), Err(GlassModelError::Sample));
}
}
fn visible_normal(v: Vec3, n: Vec3, alpha: f64, u: [f64; 2]) -> Result<Vec3> {
let tangent = direction(if n.z.abs() < 0.9 { Vec3::Z.cross(n) } else { Vec3::X.cross(n) })?;
let bitangent = n.cross(tangent);
let stretched = direction(Vec3::new(alpha * v.dot(tangent), alpha * v.dot(bitangent), v.dot(n)))?;
let side = if stretched.x == 0.0 && stretched.y == 0.0 { Vec3::X } else { direction(Vec3::new(-stretched.y, stretched.x, 0.0))? };
let vertical = stretched.cross(side);
let radius = u[0].sqrt();
let (sine, cosine) = (TAU * u[1]).sin_cos();
let x = radius * cosine;
let mix = 0.5 * (1.0 + stretched.z);
let y = (1.0 - mix) * (1.0 - x * x).max(0.0).sqrt() + mix * radius * sine;
let height = (1.0 - x * x - y * y).max(0.0).sqrt();
let hemisphere = side * x + vertical * y + stretched * height;
let local = direction(Vec3::new(alpha * hemisphere.x, alpha * hemisphere.y, hemisphere.z.max(0.0)))?;
direction(tangent * local.x + bitangent * local.y + n * local.z)
}
fn ggx_distribution(m: Vec3, n: Vec3, alpha: f64) -> f64 {
let cosine = m.dot(n);
if cosine <= 0.0 {
return 0.0;
}
let sine = m.cross(n);
let denominator = sine.dot(sine) + alpha * alpha * cosine * cosine;
let root = (alpha / denominator) / PI.sqrt();
root * root
}
fn smith_root(cosine: f64, alpha: f64) -> f64 {
(cosine * cosine + alpha * alpha * (1.0 - cosine * cosine).max(0.0)).sqrt()
}
fn smith_g1(cosine: f64, alpha: f64) -> f64 {
2.0 * cosine / (cosine + smith_root(cosine, alpha))
}
fn smith_ratio(cv: f64, cl: f64, alpha: f64) -> f64 {
if cv <= 0.0 || cl <= 0.0 {
return 0.0;
}
let sv = smith_root(cv, alpha);
let sl = smith_root(cl, alpha);
cl * (cv + sv) / (sv * cl + sl * cv)
}
#[derive(Clone, Copy)]
struct Complex {
re: f64,
im: f64,
}
impl Complex {
fn real(re: f64) -> Self {
Self { re, im: 0.0 }
}
fn add(self, b: Self) -> Self {
Self { re: self.re + b.re, im: self.im + b.im }
}
fn sub(self, b: Self) -> Self {
Self { re: self.re - b.re, im: self.im - b.im }
}
fn scale(self, b: f64) -> Self {
Self { re: self.re * b, im: self.im * b }
}
fn mul(self, b: Self) -> Self {
Self { re: self.re * b.re - self.im * b.im, im: self.re * b.im + self.im * b.re }
}
fn minus_i(self) -> Self {
Self { re: self.im, im: -self.re }
}
fn norm_square(self) -> f64 {
self.re * self.re + self.im * self.im
}
fn div(self, b: Self) -> Result<Self> {
let denominator = b.norm_square();
if !denominator.is_finite() || denominator <= 0.0 {
return Err(GlassModelError::Numerical);
}
let value = Self { re: (self.re * b.re + self.im * b.im) / denominator, im: (self.im * b.re - self.re * b.im) / denominator };
if !value.re.is_finite() || !value.im.is_finite() {
return Err(GlassModelError::Numerical);
}
Ok(value)
}
}