Skip to content

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

13.4 KB
Raw Blame
//! Runtime rectangular emitters and constant environment radiance. Coordinates are
//! world-space millimetres; radiance is linear RGB. Saved setups reuse these bounds.
use super::{DirectionalLightOptions, ErrorCode, JobError, Result};
use serde::{Deserialize, Serialize};
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;

pub const MAX_AREA_LIGHTS: usize = 4;

/// A one-sided rectangle: `center + u*s + v*t`, with s,t in [-1,1].
/// Its emitting normal is `u cross v`; u and v are orthogonal half-edges.
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AreaLight {
    pub center: [f64; 3],
    pub u: [f64; 3],
    pub v: [f64; 3],
    pub radiance: [f64; 3],
}

fn vector(a: [f64; 3]) -> Vec3 {
    let [x, y, z] = a;
    Vec3::new(x, y, z)
}

impl AreaLight {
    pub fn validate(self) -> Result<()> {
        let u = vector(self.u);
        let v = vector(self.v);
        let ul = u.len();
        let vl = v.len();
        if self.center.into_iter().any(|x| !x.is_finite() || x.abs() > 1e9)
            || self.u.into_iter().chain(self.v).any(|x| !x.is_finite())
            || !(1e-4..=1e6).contains(&ul)
            || !(1e-4..=1e6).contains(&vl)
            || u.dot(v).abs() > 1e-6 * ul * vl
            || self.radiance.into_iter().any(|x| !x.is_finite() || !(0.0..=1e6).contains(&x))
        {
            return Err(JobError::new(
                ErrorCode::InvalidRequest,
                "area light requires finite center, orthogonal half-edges of 0.0001..1000000 mm and radiance 0..1000000",
            ));
        }
        Ok(())
    }

    pub fn area(self) -> f64 {
        4.0 * vector(self.u).cross(vector(self.v)).len()
    }
}

/// Uniform-radiance finite angular disk at infinity. Direction points toward the sun.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Sun {
    pub direction: [f64; 3],
    pub angular_radius_rad: f64,
    pub radiance: [f64; 3],
}
impl Sun {
    pub fn validate(self) -> Result<()> {
        if self.direction.iter().any(|x| !x.is_finite())
            || !(1e-8..=1e8).contains(&vector(self.direction).len())
            || !self.angular_radius_rad.is_finite()
            || !(0.001..=std::f64::consts::FRAC_PI_2).contains(&self.angular_radius_rad)
            || self.radiance.iter().any(|x| !x.is_finite() || !(0.0..=1e8).contains(x))
        {
            return Err(JobError::new(
                ErrorCode::InvalidRequest,
                "sun requires finite nonzero direction, radius 0.001..pi/2 radians and radiance 0..100000000",
            ));
        }
        Ok(())
    }
    pub fn solid_angle(self) -> f64 {
        4.0 * std::f64::consts::PI * (0.5 * self.angular_radius_rad).sin().powi(2)
    }
    pub fn direction(self) -> Vec3 {
        let d = vector(self.direction);
        d / d.len()
    }
}

/// A small copyable light list, serialized as an ordinary bounded JSON array.
#[derive(Clone, Copy, Debug, PartialEq, Default)]
pub struct AreaLights {
    entries: [AreaLight; MAX_AREA_LIGHTS],
    len: usize,
}

impl AreaLights {
    pub fn new(lights: &[AreaLight]) -> Result<Self> {
        if lights.len() > MAX_AREA_LIGHTS {
            return Err(JobError::new(ErrorCode::InvalidRequest, "at most four area lights are supported"));
        }
        let mut result = Self::default();
        for (slot, light) in result.entries.iter_mut().zip(lights) {
            light.validate()?;
            *slot = *light;
        }
        result.len = lights.len();
        Ok(result)
    }

    pub fn iter(&self) -> impl Iterator<Item = &AreaLight> {
        self.entries.iter().take(self.len)
    }
}

impl Serialize for AreaLights {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
        serializer.collect_seq(self.iter())
    }
}

impl<'de> Deserialize<'de> for AreaLights {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        struct Visitor;
        impl<'de> serde::de::Visitor<'de> for Visitor {
            type Value = AreaLights;
            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("an array of at most four rectangular area lights")
            }
            fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<Self::Value, A::Error> {
                let mut result = AreaLights::default();
                while let Some(light) = seq.next_element::<AreaLight>()? {
                    let slot =
                        result.entries.get_mut(result.len).ok_or_else(|| serde::de::Error::custom("at most four area lights are supported"))?;
                    light.validate().map_err(serde::de::Error::custom)?;
                    *slot = light;
                    result.len += 1;
                }
                Ok(result)
            }
        }
        deserializer.deserialize_seq(Visitor)
    }
}

pub const MAX_DIRECTIONAL_LIGHTS: usize = 8;

/// Copyable hard directional sources. The optional finite Sun shares the same
/// eight-source family limit, but keeps its separate angular-radiance contract.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct DirectionalLights {
    entries: [DirectionalLightOptions; MAX_DIRECTIONAL_LIGHTS],
    len: usize,
}
impl Default for DirectionalLights {
    fn default() -> Self {
        Self { entries: [DirectionalLightOptions { direction: [0.0, 0.0, 1.0], color: [0.0; 3], intensity: 0.0 }; MAX_DIRECTIONAL_LIGHTS], len: 0 }
    }
}
impl DirectionalLights {
    pub fn new(lights: &[DirectionalLightOptions]) -> Result<Self> {
        if lights.len() > MAX_DIRECTIONAL_LIGHTS {
            return Err(JobError::new(ErrorCode::InvalidRequest, "at most eight directional lights including the Sun"));
        }
        let mut result = Self::default();
        for (slot, light) in result.entries.iter_mut().zip(lights) {
            light.validate()?;
            *slot = *light;
        }
        result.len = lights.len();
        Ok(result)
    }
    pub fn iter(&self) -> impl Iterator<Item = &DirectionalLightOptions> {
        self.entries.iter().take(self.len)
    }
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }
}
impl Serialize for DirectionalLights {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
        serializer.collect_seq(self.iter())
    }
}
impl<'de> Deserialize<'de> for DirectionalLights {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        struct Visitor;
        impl<'de> serde::de::Visitor<'de> for Visitor {
            type Value = DirectionalLights;
            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("an array of at most eight hard directional lights")
            }
            fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<Self::Value, A::Error> {
                let mut result = DirectionalLights::default();
                while let Some(light) = seq.next_element::<DirectionalLightOptions>()? {
                    let slot = result.entries.get_mut(result.len).ok_or_else(|| serde::de::Error::custom("at most eight directional lights"))?;
                    light.validate().map_err(serde::de::Error::custom)?;
                    *slot = light;
                    result.len += 1;
                }
                Ok(result)
            }
        }
        deserializer.deserialize_seq(Visitor)
    }
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StudioLighting {
    pub sun: Option<Sun>,
    #[serde(skip_serializing_if = "DirectionalLights::is_empty")]
    pub directional_lights: DirectionalLights,
    #[serde(skip_serializing_if = "super::PunctualLights::is_empty")]
    pub punctual_lights: super::PunctualLights,
    pub environment: [f64; 3],
    pub area_lights: AreaLights,
}

impl StudioLighting {
    pub fn validate(self) -> Result<()> {
        if self.directional_lights.iter().count() + usize::from(self.sun.is_some()) > MAX_DIRECTIONAL_LIGHTS {
            return Err(JobError::new(ErrorCode::InvalidRequest, "at most eight directional lights including the Sun"));
        }
        for light in self.directional_lights.iter() {
            light.validate()?;
        }
        for light in self.punctual_lights.iter() {
            light.validate_gpu()?;
        }
        if let Some(sun) = self.sun {
            sun.validate()?;
        }
        if self.environment.into_iter().any(|x| !x.is_finite() || !(0.0..=1e6).contains(&x)) {
            return Err(JobError::new(ErrorCode::InvalidRequest, "environment radiance must be finite and 0..1000000"));
        }
        for light in self.area_lights.iter() {
            light.validate()?;
        }
        Ok(())
    }
}

/// Output-only transform, after linear accumulation and exposure, before sRGB.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ToneMap {
    #[default]
    Reinhard,
    AcesFitted,
}

impl ToneMap {
    pub fn map(self, linear: f64) -> f64 {
        let x = linear.max(0.0);
        match self {
            Self::Reinhard => x / (1.0 + x),
            // Narkowicz (2016), published rational approximation to the ACES RRT/ODT.
            // This is a per-channel fit, not the full ACES colour-management pipeline.
            // https://knarkowicz.wordpress.com/2016/01/06/aces-filmic-tone-mapping-curve/
            Self::AcesFitted => ((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14)).clamp(0.0, 1.0),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn light() -> AreaLight {
        AreaLight { center: [0.0, 0.0, 4.0], u: [2.0, 0.0, 0.0], v: [0.0, -3.0, 0.0], radiance: [5.0; 3] }
    }

    #[test]
    fn bounded_lights_validate_geometry_and_round_trip() {
        let lights = AreaLights::new(&[light(); 4]).unwrap();
        assert_eq!(light().area(), 24.0);
        assert_eq!(serde_json::from_str::<AreaLights>(&serde_json::to_string(&lights).unwrap()).unwrap(), lights);
        assert!(AreaLights::new(&[light(); 5]).is_err());
        assert!(serde_json::from_str::<AreaLights>(&serde_json::to_string(&vec![light(); 5]).unwrap()).is_err());
        for bad in [
            AreaLight { u: [0.0; 3], ..light() },
            AreaLight { v: [1.0, 1.0, 0.0], ..light() },
            AreaLight { radiance: [-1.0; 3], ..light() },
            AreaLight { center: [f64::NAN; 3], ..light() },
        ] {
            assert!(bad.validate().is_err());
        }
        assert!(StudioLighting { environment: [f64::INFINITY; 3], ..Default::default() }.validate().is_err());
    }

    #[test]
    fn finite_sun_validates_and_integrates_its_solid_angle() {
        let sun = Sun { direction: [0.0, 0.0, 2.0], angular_radius_rad: 0.2, radiance: [3.0; 3] };
        sun.validate().unwrap();
        assert_eq!(sun.direction(), Vec3::Z);
        assert!((sun.solid_angle() - 2.0 * std::f64::consts::PI * (1.0 - 0.2_f64.cos())).abs() < 1e-14);
        for radius in [0.0, 0.00001, f64::NAN, 2.0] {
            assert!(Sun { angular_radius_rad: radius, ..sun }.validate().is_err());
        }
        assert!(Sun { direction: [0.0; 3], ..sun }.validate().is_err());
    }

    #[test]
    fn filmic_is_bounded_monotone_and_preserves_black() {
        assert_eq!(ToneMap::default(), ToneMap::Reinhard);
        assert_eq!(ToneMap::AcesFitted.map(0.0), 0.0);
        assert!((ToneMap::AcesFitted.map(1.0) - 0.8037974683544302).abs() < 1e-14);
        let mut previous = 0.0;
        for i in 0..1000 {
            let value = ToneMap::AcesFitted.map(f64::from(i) / 100.0);
            assert!((previous..=1.0).contains(&value));
            previous = value;
        }
    }
    #[test]
    fn hard_directional_list_is_bounded_copyable_and_preserves_authored_values() {
        fn is_copy<T: Copy>() {}
        is_copy::<StudioLighting>();
        let light = DirectionalLightOptions { direction: [f64::MIN_POSITIVE, 0.0, 0.0], color: [0.25, 0.5, 1.0], intensity: 0.0 };
        let list = DirectionalLights::new(&[light; 8]).unwrap();
        assert_eq!(list.iter().count(), 8);
        assert_eq!(serde_json::from_value::<DirectionalLights>(serde_json::to_value(list).unwrap()).unwrap(), list);
        assert!(DirectionalLights::new(&[light; 9]).is_err());
        assert!(serde_json::from_value::<DirectionalLights>(serde_json::json!(vec![light; 9])).is_err());
        for bad in [
            DirectionalLightOptions { direction: [0.0; 3], ..light },
            DirectionalLightOptions { color: [-0.1, 0.0, 0.0], ..light },
            DirectionalLightOptions { intensity: 64.01, ..light },
        ] {
            assert!(DirectionalLights::new(&[bad]).is_err());
        }
        let sun = Sun { direction: [0.0, 0.0, 1.0], angular_radius_rad: 0.02, radiance: [1.0; 3] };
        assert!(StudioLighting { sun: Some(sun), directional_lights: list, ..Default::default() }.validate().is_err());
        assert!(
            StudioLighting { sun: Some(sun), directional_lights: DirectionalLights::new(&[light; 7]).unwrap(), ..Default::default() }
                .validate()
                .is_ok()
        );
        let legacy: StudioLighting = serde_json::from_str(r#"{"sun":null,"environment":[0.1,0.2,0.3],"area_lights":[]}"#).unwrap();
        assert!(legacy.directional_lights.is_empty());
        assert!(serde_json::to_value(legacy).unwrap().get("directional_lights").is_none());
    }
}