Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

9.7 KB
Raw Blame
//! Bounded optical data and original f64 dielectric transport oracles. Units are mm.
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
#[path = "subsurface.rs"]
pub mod subsurface;
use subsurface::Subsurface;

use crate::surface::{SurfaceError, unit_direction};

#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Transmission {
    model: Option<crate::glass_model::GlassModel>,
    absorption_per_mm: Vec3,
    thin_wall_thickness_mm: Option<f64>,
    shadow_transmission: bool,
    subsurface: Option<Subsurface>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TransmissionError {
    Model,
    Absorption,
    Scattering,
    Distance,
    Thickness,
    Angle,
    Ior,
    Direction,
}
impl std::fmt::Display for TransmissionError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Model => "glass model requires finite bounded roughness, dispersion and optical film parameters",
            Self::Scattering => "subsurface scattering requires a closed medium, finite scattering 0..100/mm, HG anisotropy -0.95..0.95 and disabled straight shadow transmission",
            Self::Absorption => "absorption_per_mm must be finite RGB coefficients in [0, 100] per mm",
            Self::Distance => "geometric absorption distance must be finite and nonnegative",
            Self::Thickness => "thin-sheet thickness must be finite and in [0, 10000] mm",
            Self::Angle => "incident cosine must be finite and in [0, 1]",
            Self::Ior => "medium IOR must be finite and in [1, 3]",
            Self::Direction => "incident direction must face the finite nonzero interface normal",
        })
    }
}
impl std::error::Error for TransmissionError {}

impl Transmission {
    pub fn new(absorption_per_mm: Vec3, thin_wall_thickness_mm: Option<f64>) -> Result<Self, TransmissionError> {
        if !absorption_per_mm.is_finite()
            || ![absorption_per_mm.x, absorption_per_mm.y, absorption_per_mm.z].into_iter().all(|v| (0.0..=100.0).contains(&v))
        {
            return Err(TransmissionError::Absorption);
        }
        if thin_wall_thickness_mm.is_some_and(|v| !v.is_finite() || !(0.0..=10000.0).contains(&v)) {
            return Err(TransmissionError::Thickness);
        }
        Ok(Self { model: None, absorption_per_mm, thin_wall_thickness_mm, shadow_transmission: thin_wall_thickness_mm.is_some(), subsurface: None })
    }
    pub fn with_model(mut self, model: crate::glass_model::GlassModel) -> Result<Self, TransmissionError> {
        model.validate(1.5).map_err(|_| TransmissionError::Model)?;
        self.model = Some(model);
        Ok(self)
    }
    pub fn model(self) -> Option<crate::glass_model::GlassModel> {
        self.model
    }
    /// Thin sheets enable straight shadow transmission by default; solids opt in.
    pub fn with_shadow_transmission(mut self, enabled: bool) -> Self {
        self.shadow_transmission = enabled;
        self
    }
    pub fn with_subsurface(mut self, subsurface: Subsurface) -> Result<Self, TransmissionError> {
        subsurface.validate()?;
        if self.thin_wall_thickness_mm.is_some() || (subsurface.active() && self.shadow_transmission) {
            return Err(TransmissionError::Scattering);
        }
        self.subsurface = Some(subsurface);
        Ok(self)
    }
    pub fn subsurface(self) -> Option<Subsurface> {
        self.subsurface
    }
    pub fn shadow_transmission(self) -> bool {
        self.shadow_transmission
    }
    pub fn thin_wall_thickness_mm(self) -> Option<f64> {
        self.thin_wall_thickness_mm
    }
    pub fn extinction(self) -> Vec3 {
        self.absorption_per_mm
    }
    pub fn attenuation(self, distance_mm: f64) -> Result<Vec3, TransmissionError> {
        if !distance_mm.is_finite() || distance_mm < 0.0 {
            return Err(TransmissionError::Distance);
        }
        let s = self.extinction();
        Ok(Vec3::new((-s.x * distance_mm).exp(), (-s.y * distance_mm).exp(), (-s.z * distance_mm).exp()))
    }
}

#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Fresnel {
    pub s: f64,
    pub p: f64,
    /// None at total internal reflection.
    pub transmitted_cosine: Option<f64>,
}
impl Fresnel {
    pub fn reflectance(self) -> f64 {
        (self.s + self.p) * 0.5
    }
}

/// Exact unpolarized power reflectance at a lossless dielectric interface.
pub fn fresnel(cosine: f64, incident_ior: f64, transmitted_ior: f64) -> Result<Fresnel, TransmissionError> {
    if !cosine.is_finite() || !(0.0..=1.0).contains(&cosine) {
        return Err(TransmissionError::Angle);
    }
    if [incident_ior, transmitted_ior].into_iter().any(|v| !v.is_finite() || !(1.0..=3.0).contains(&v)) {
        return Err(TransmissionError::Ior);
    }
    if incident_ior == transmitted_ior {
        return Ok(Fresnel { s: 0.0, p: 0.0, transmitted_cosine: Some(cosine) });
    }
    let eta = incident_ior / transmitted_ior;
    let sin2 = eta * eta * (1.0 - cosine * cosine).max(0.0);
    if sin2 >= 1.0 {
        return Ok(Fresnel { s: 1.0, p: 1.0, transmitted_cosine: None });
    }
    let ct = (1.0 - sin2).sqrt();
    let rs = (incident_ior * cosine - transmitted_ior * ct) / (incident_ior * cosine + transmitted_ior * ct);
    let rp = (transmitted_ior * cosine - incident_ior * ct) / (transmitted_ior * cosine + incident_ior * ct);
    Ok(Fresnel { s: rs * rs, p: rp * rp, transmitted_cosine: Some(ct) })
}

/// Incident direction points toward the surface; normal points into the incident medium.
pub fn refract(incident: Vec3, normal: Vec3, incident_ior: f64, transmitted_ior: f64) -> Result<Option<Vec3>, TransmissionError> {
    let direction_error = |_: SurfaceError| TransmissionError::Direction;
    let d = unit_direction(incident).map_err(direction_error)?;
    let n = unit_direction(normal).map_err(direction_error)?;
    let cosine = -d.dot(n);
    if cosine < 0.0 {
        return Err(TransmissionError::Direction);
    }
    let cosine = cosine.min(1.0);
    let f = fresnel(cosine, incident_ior, transmitted_ior)?;
    if incident_ior == transmitted_ior {
        return Ok(Some(d));
    }
    Ok(f.transmitted_cosine.map(|ct| {
        let eta = incident_ior / transmitted_ior;
        d * eta + n * (eta * cosine - ct)
    }))
}

/// Incoherent parallel slab, including all repeated internal reflections. The two
/// external media have the same IOR. Returns linear RGB (reflectance, transmittance).
pub fn slab(
    transmission: Transmission,
    thickness_mm: f64,
    cosine: f64,
    outside_ior: f64,
    inside_ior: f64,
) -> Result<(Vec3, Vec3), TransmissionError> {
    if !thickness_mm.is_finite() || !(0.0..=10000.0).contains(&thickness_mm) {
        return Err(TransmissionError::Thickness);
    }
    let f = fresnel(cosine, outside_ior, inside_ior)?;
    let Some(ct) = f.transmitted_cosine else {
        return Ok((Vec3::new(1.0, 1.0, 1.0), Vec3::ZERO));
    };
    // A zero-thickness sheet has zero optical distance, including matched-index
    // exact grazing. Positive thickness without a crossing has no finite path.
    let distance = if thickness_mm == 0.0 {
        0.0
    } else if ct > 0.0 {
        thickness_mm / ct
    } else {
        return Err(TransmissionError::Angle);
    };
    let a = transmission.attenuation(distance)?;
    let channel = |r: f64, a: f64| {
        let denominator = 1.0 - r * r * a * a;
        if denominator <= 0.0 {
            return (1.0, 0.0);
        }
        (r + (1.0 - r).powi(2) * r * a * a / denominator, (1.0 - r).powi(2) * a / denominator)
    };
    // A parallel slab preserves polarization. Sum each geometric series before
    // averaging s/p, rather than repeatedly applying the unpolarized mean.
    let average = |a: f64| {
        let (rs, ts) = channel(f.s, a);
        let (rp, tp) = channel(f.p, a);
        ((rs + rp) * 0.5, (ts + tp) * 0.5)
    };
    let (rx, tx) = average(a.x);
    let (ry, ty) = average(a.y);
    let (rz, tz) = average(a.z);
    Ok((Vec3::new(rx, ry, rz), Vec3::new(tx, ty, tz)))
}

/// Explicit straight-through solid shadow approximation. Both interface losses
/// use reciprocal external-angle Fresnel; `distance_mm` is the actual geometric
/// entry/exit interval. This omits refraction and repeated internal reflections.
pub fn solid_shadow(transmission: Transmission, distance_mm: f64, entry_cosine: f64, exit_cosine: f64, ior: f64) -> Result<Vec3, TransmissionError> {
    let entry = fresnel(entry_cosine, 1.0, ior)?.reflectance();
    let exit = fresnel(exit_cosine, 1.0, ior)?.reflectance();
    Ok(transmission.attenuation(distance_mm)? * ((1.0 - entry) * (1.0 - exit)))
}

#[cfg(test)]
mod shadow_tests {
    use super::*;
    #[test]
    fn defaults_and_reciprocal_solid_shadow_match_analytic_beer() {
        let sigma = Vec3::new(-0.5_f64.ln(), -0.8_f64.ln(), 0.0);
        let solid = Transmission::new(sigma, None).unwrap();
        let sheet = Transmission::new(sigma, Some(1.0)).unwrap();
        assert!(!solid.shadow_transmission());
        assert!(sheet.shadow_transmission());
        assert!(solid.with_shadow_transmission(true).shadow_transmission());
        assert!(!sheet.with_shadow_transmission(false).shadow_transmission());
        assert!((solid_shadow(solid, 1.0, 1.0, 1.0, 1.5).unwrap() - Vec3::new(0.5, 0.8, 1.0) * 0.96 * 0.96).len() < 1e-14);
        assert_eq!(solid_shadow(solid, 1.0, 0.2, 0.8, 1.5).unwrap(), solid_shadow(solid, 1.0, 0.8, 0.2, 1.5).unwrap());
        for ior in [1.0, 1.5, 3.0] {
            for cosine in [0.0, 0.02, 0.5, 1.0] {
                let shadow = solid_shadow(solid, 1.0, cosine, cosine, ior).unwrap();
                assert!(shadow.is_finite() && shadow.x >= 0.0 && shadow.z <= 1.0);
            }
        }
        assert!(solid_shadow(solid, f64::NAN, 1.0, 1.0, 1.5).is_err());
    }
}

#[cfg(test)]
#[path = "dielectric_oracle_tests.rs"]
mod tests;