SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Original relative point/spot response. Coordinates/reference distances are mm.
//! No lumen, lux, watts, measured CCT, IES or glTF photometry is implied.
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
use super::{Ray, Result, TraceError, bounded, lighting::MAX_LIGHT_INTENSITY, prepared::SharedHit, unit};
/// Explicit preview lower bound, not a geometry/self-intersection epsilon.
pub const MIN_SOURCE_DISTANCE_MM: f64 = 0.001;
pub const MAX_REFERENCE_DISTANCE_MM: f64 = 1.0e6;
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SpotCone {
axis: Vec3,
inner_cos: f64,
outer_cos: f64,
}
impl SpotCone {
/// Emitted world axis points FROM the light. Half-cones are radians.
/// Distinct representable cosine bounds are required, including at zero.
pub fn new(axis: Vec3, inner: f64, outer: f64) -> Result<Self> {
let axis = unit(axis).ok_or(TraceError::InvalidInput("spot emitted axis"))?;
if !inner.is_finite() || !outer.is_finite() || inner < 0.0 || inner >= outer || outer > std::f64::consts::FRAC_PI_2 {
return Err(TraceError::InvalidInput("spot half-cones require 0 <= inner < outer <= pi/2"));
}
let inner_cos = inner.cos();
let outer_cos = outer.cos();
if inner_cos <= outer_cos {
return Err(TraceError::InvalidInput("spot cosine feather is unrepresentable"));
}
Ok(Self { axis, inner_cos, outer_cos })
}
fn weight(self, emitted_direction: Vec3) -> f64 {
let cosine = self.axis.dot(emitted_direction);
let t = ((cosine - self.outer_cos) / (self.inner_cos - self.outer_cos)).clamp(0.0, 1.0);
// Smoothstep in cosine space; zero slope at both cone boundaries.
t * t * (3.0 - 2.0 * t)
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PunctualLight {
position: Vec3,
color: Vec3,
intensity: f64,
reference_mm: f64,
minimum_mm: f64,
cone: Option<SpotCone>,
}
#[derive(Clone, Copy, Debug)]
pub struct PunctualSample {
pub direction: Vec3,
pub incident_linear_srgb: Vec3,
position: Vec3,
pub omitted: Option<OmittedSample>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OmittedSample {
NearSource,
RadianceLimit,
}
impl PunctualLight {
/// Intensity equals the relative on-axis incident value at reference_mm.
/// Distances below minimum_mm contribute zero with a recorded diagnostic.
/// The inverse-square response is not silently clamped.
pub fn new(position: Vec3, color: Vec3, intensity: f64, reference_mm: f64, minimum_mm: f64, cone: Option<SpotCone>) -> Result<Self> {
if !bounded(position) || !color.is_finite() || [color.x, color.y, color.z].into_iter().any(|x| !(0.0..=1.0).contains(&x)) {
return Err(TraceError::InvalidInput("punctual position or linear sRGB colour"));
}
if !intensity.is_finite()
|| !(0.0..=MAX_LIGHT_INTENSITY).contains(&intensity)
|| !reference_mm.is_finite()
|| !(MIN_SOURCE_DISTANCE_MM..=MAX_REFERENCE_DISTANCE_MM).contains(&reference_mm)
|| !minimum_mm.is_finite()
|| !(MIN_SOURCE_DISTANCE_MM..=reference_mm).contains(&minimum_mm)
{
return Err(TraceError::InvalidInput("punctual relative intensity or explicit reference/minimum distances"));
}
Ok(Self { position, color, intensity, reference_mm, minimum_mm, cone })
}
pub fn sample(self, hit_position: Vec3) -> Result<PunctualSample> {
if !bounded(hit_position) {
return Err(TraceError::InvalidInput("punctual hit position"));
}
let delta = self.position - hit_position;
let distance = delta.len();
if !distance.is_finite() || distance < self.minimum_mm {
return Ok(PunctualSample {
direction: Vec3::Z,
incident_linear_srgb: Vec3::ZERO,
position: self.position,
omitted: Some(OmittedSample::NearSource),
});
}
let direction = delta / distance;
let cone = self.cone.map_or(1.0, |cone| cone.weight(-direction));
let ratio = self.reference_mm / distance;
let incident_linear_srgb = self.color * (self.intensity * ratio * ratio * cone);
if super::lighting::validate_radiance(incident_linear_srgb).is_err() {
return Ok(PunctualSample {
direction,
incident_linear_srgb: Vec3::ZERO,
position: self.position,
omitted: Some(OmittedSample::RadianceLimit),
});
}
Ok(PunctualSample { direction, incident_linear_srgb, position: self.position, omitted: None })
}
}
impl PunctualSample {
/// Re-aim from the common robust geometric offset, then exclude the source.
/// An offset that crossed the source contributes zero; no backwards/unbounded ray.
pub fn shadow_ray(self, hit: SharedHit<'_>) -> Result<Option<Ray>> {
let origin = hit.spawn(self.direction)?.origin();
let delta = self.position - origin;
let distance = delta.len();
if !distance.is_finite() || distance <= 0.0 || delta.dot(self.direction) <= 0.0 {
return Ok(None);
}
let far = distance.next_down();
if far <= 0.0_f64.next_up() {
return Ok(None);
}
Ray::new(origin, delta, 0.0_f64.next_up(), far).map(Some)
}
}
#[cfg(test)]
#[path = "punctual_tests.rs"]
mod tests;