SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Optional original CPU visibility core and opaque direct-image integration.
//!
//! Original Rust implementation from elementary slab, barycentric and binary-tree
//! mathematics. Geometry is already world-space, in millimetres. No B-rep kernel
//! or third-party ray-tracer implementation is used. See `docs/render-raytrace-core.md`.
use crate::job::CancelToken;
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
mod aging;
mod anisotropic_faces;
pub mod area;
mod box_certificate;
mod bvh;
mod celestial;
mod denoise;
pub mod dielectric;
pub mod emission;
mod glass_mesh;
mod glass_volume;
pub mod image;
mod indirect;
pub(crate) mod legacy_certificates;
pub mod lighting;
mod origin;
pub mod prepared;
mod progressive;
pub mod punctual;
pub mod reflection;
pub use bvh::{BuildLimits, BuildProgress, Bvh, BvhBuilder, MAX_DEPTH, MAX_MEMORY_BYTES, MAX_TRIANGLES};
/// Finite coordinate admission, not a CAD accuracy guarantee.
pub const MAX_COORDINATE_MM: f64 = 1e12;
/// Maximum finite ray interval endpoint in millimetres.
pub const MAX_DISTANCE_MM: f64 = 4e12;
/// Maximum work charged to one explicitly owned budget.
pub const MAX_WORK: u64 = 1_000_000_000;
/// Maximum incremental builder operations in one call.
pub const MAX_BUILD_STEP: usize = 4096;
/// Structured failures; exhausting work never returns a truncated hit result.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TraceError {
InvalidInput(&'static str),
MemoryLimit,
AllocationFailed,
WorkLimit,
Cancelled,
BuildIncomplete,
Internal(&'static str),
}
impl std::fmt::Display for TraceError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::InvalidInput(reason) => write!(f, "invalid ray tracing input: {reason}"),
Self::MemoryLimit => f.write_str("ray tracing memory admission exceeded"),
Self::AllocationFailed => f.write_str("ray tracing allocation failed"),
Self::WorkLimit => f.write_str("ray tracing work budget exhausted"),
Self::Cancelled => f.write_str("ray tracing cancelled"),
Self::BuildIncomplete => f.write_str("ray tracing BVH build is incomplete"),
Self::Internal(reason) => write!(f, "invalid ray tracing internal state: {reason}"),
}
}
}
impl std::error::Error for TraceError {}
pub type Result<T> = std::result::Result<T, TraceError>;
fn check_cancel(cancel: &CancelToken) -> Result<()> {
if cancel.is_cancelled() { Err(TraceError::Cancelled) } else { Ok(()) }
}
/// Caller-owned cumulative work; can span many rays in one image job.
#[derive(Debug)]
pub struct WorkBudget {
limit: u64,
used: u64,
}
impl WorkBudget {
pub fn new(limit: u64) -> Result<Self> {
if limit == 0 || limit > crate::job::MAX_CPU_WORK {
return Err(TraceError::InvalidInput("work limit outside 1..=MAX_WORK"));
}
Ok(Self { limit, used: 0 })
}
pub fn used(&self) -> u64 {
self.used
}
pub fn remaining(&self) -> u64 {
self.limit - self.used
}
fn tick(&mut self, cancel: &CancelToken) -> Result<()> {
self.charge(1, cancel)
}
fn charge(&mut self, units: u64, cancel: &CancelToken) -> Result<()> {
check_cancel(cancel)?;
self.used = self.used.checked_add(units).filter(|used| *used <= self.limit).ok_or(TraceError::WorkLimit)?;
Ok(())
}
}
fn bounded(point: Vec3) -> bool {
point.is_finite() && [point.x, point.y, point.z].into_iter().all(|v| v.abs() <= MAX_COORDINATE_MM)
}
fn unit(vector: Vec3) -> Option<Vec3> {
let scale = vector.x.abs().max(vector.y.abs()).max(vector.z.abs());
if !vector.is_finite() || scale == 0.0 {
return None;
}
let scaled = vector / scale;
Some(scaled / scaled.len2().sqrt())
}
fn component(vector: Vec3, axis: usize) -> f64 {
match axis {
0 => vector.x,
1 => vector.y,
_ => vector.z,
}
}
/// Admitted ray with a unit direction and closed finite distance interval.
/// No implicit origin offset, back-face culling or fixed world-space epsilon.
#[derive(Clone, Copy, Debug)]
pub struct Ray {
origin: Vec3,
direction: Vec3,
min: f64,
max: f64,
}
impl Ray {
pub fn new(origin: Vec3, direction: Vec3, min: f64, max: f64) -> Result<Self> {
if !bounded(origin) || !min.is_finite() || !max.is_finite() || min < 0.0 || min > max || max > MAX_DISTANCE_MM {
return Err(TraceError::InvalidInput("ray origin or distance interval"));
}
let direction = unit(direction).ok_or(TraceError::InvalidInput("finite nonzero ray direction required"))?;
Ok(Self { origin, direction, min, max })
}
pub fn origin(self) -> Vec3 {
self.origin
}
pub fn direction(self) -> Vec3 {
self.direction
}
pub fn interval(self) -> [f64; 2] {
[self.min, self.max]
}
pub fn at(self, distance: f64) -> Result<Vec3> {
if !distance.is_finite() || distance < self.min || distance > self.max {
return Err(TraceError::InvalidInput("distance outside admitted ray interval"));
}
Ok(self.origin + self.direction * distance)
}
}
/// Conservative world-space box; empty boxes exist only inside the builder.
#[derive(Clone, Copy, Debug)]
pub struct Bounds {
min: Vec3,
max: Vec3,
}
impl Bounds {
pub fn new(min: Vec3, max: Vec3) -> Result<Self> {
if !bounded(min) || !bounded(max) || min.x > max.x || min.y > max.y || min.z > max.z {
return Err(TraceError::InvalidInput("finite ordered bounding box required"));
}
Ok(Self { min, max })
}
pub fn min(self) -> Vec3 {
self.min
}
pub fn max(self) -> Vec3 {
self.max
}
fn empty() -> Self {
Self { min: Vec3::new(f64::INFINITY, f64::INFINITY, f64::INFINITY), max: Vec3::new(f64::NEG_INFINITY, f64::NEG_INFINITY, f64::NEG_INFINITY) }
}
fn include(self, other: Self) -> Self {
Self { min: self.min.min(other.min), max: self.max.max(other.max) }
}
fn point(point: Vec3) -> Self {
Self { min: point, max: point }
}
/// Closed slab overlap. Parallel (including signed-zero) components never divide.
pub fn intersect(self, ray: &Ray) -> Option<[f64; 2]> {
self.clip(ray, ray.max)
}
fn clip(self, ray: &Ray, maximum: f64) -> Option<[f64; 2]> {
let (mut near, mut far) = (ray.min, ray.max.min(maximum));
for axis in 0..3 {
let (lo, hi, origin, direction) =
(component(self.min, axis), component(self.max, axis), component(ray.origin, axis), component(ray.direction, axis));
if direction == 0.0 {
if origin < lo || origin > hi {
return None;
}
} else {
// Division may produce infinity for an almost-parallel ray; the
// finite caller interval clips it. No reciprocal times zero.
let a = (lo - origin) / direction;
let b = (hi - origin) / direction;
near = near.max(a.min(b));
far = far.min(a.max(b));
if near > far {
return None;
}
}
}
Some([near, far])
}
}
/// Validated triangle. Coincident/collinear vertices are retained but never hit.
#[derive(Clone, Copy, Debug)]
pub struct Triangle {
vertices: [Vec3; 3],
normal: Option<Vec3>,
}
impl Triangle {
pub fn new(vertices: [Vec3; 3]) -> Result<Self> {
if !vertices.into_iter().all(bounded) {
return Err(TraceError::InvalidInput("triangle vertex coordinates"));
}
let [a, b, c] = vertices;
let ab = b - a;
let ac = c - a;
let scale = [ab.x, ab.y, ab.z, ac.x, ac.y, ac.z].into_iter().map(f64::abs).fold(0.0, f64::max);
let normal = if scale == 0.0 { None } else { unit((ab / scale).cross(ac / scale)) };
Ok(Self { vertices, normal })
}
pub fn vertices(self) -> [Vec3; 3] {
self.vertices
}
pub fn geometric_normal(self) -> Option<Vec3> {
self.normal
}
pub fn bounds(self) -> Bounds {
let [a, b, c] = self.vertices;
let min = a.min(b).min(c);
let max = a.max(b).max(c);
// One representable outward step, not a fixed millimetre epsilon.
Bounds {
min: Vec3::new(min.x.next_down(), min.y.next_down(), min.z.next_down()),
max: Vec3::new(max.x.next_up(), max.y.next_up(), max.z.next_up()),
}
}
fn centroid(self) -> Vec3 {
let [a, b, c] = self.vertices;
a / 3.0 + b / 3.0 + c / 3.0
}
/// Two-sided closed-edge barycentric intersection by dominant-direction shear.
/// At equal distance the BVH's input ordinal resolves the tie. Zero projected
/// area is a miss, including geometry collapsed by f64 arithmetic.
pub fn intersect(self, ray: &Ray) -> Option<TriangleHit> {
let normal = self.normal?;
let d = ray.direction;
let kz = if d.x.abs() >= d.y.abs() && d.x.abs() >= d.z.abs() {
0
} else if d.y.abs() >= d.z.abs() {
1
} else {
2
};
let kx = (kz + 1) % 3;
let ky = (kx + 1) % 3;
let dominant = component(d, kz);
let sx = component(d, kx) / dominant;
let sy = component(d, ky) / dominant;
let projected = self.vertices.map(|v| {
let delta = v - ray.origin;
let z = component(delta, kz);
[component(delta, kx) - sx * z, component(delta, ky) - sy * z, z / dominant]
});
let [[ax, ay, _], [bx, by, _], [cx, cy, _]] = projected;
let weights = [bx * cy - by * cx, cx * ay - cy * ax, ax * by - ay * bx];
let [u, v, w] = weights;
if (u < 0.0 || v < 0.0 || w < 0.0) && (u > 0.0 || v > 0.0 || w > 0.0) {
return None;
}
let determinant = u + v + w;
if determinant == 0.0 {
return None;
}
let barycentric = weights.map(|value| value / determinant);
// Solve depth from the geometric plane, independently of the closed-edge
// shear weights. Weighted depths along another ray axis can cancel large
// tangential terms into a positive self-hit, even for an outward ray.
// This also matters for evaluated CAD faces that differ from a coordinate
// plane by a few ULPs; they must not rely on the exact-axis shortcut.
// Exact coordinate planes retain their direct interval arithmetic.
let axis_plane = (0..3).find_map(|axis| {
let [a, b, c] = self.vertices.map(|point| component(point, axis));
(a == b && b == c).then_some((axis, a))
});
let distance = if let Some((axis, coordinate)) = axis_plane {
(coordinate - component(ray.origin, axis)) / component(d, axis)
} else {
normal.dot(self.vertices[0] - ray.origin) / normal.dot(d)
};
if !distance.is_finite() || distance < ray.min || distance > ray.max {
return None;
}
Some(TriangleHit { distance, barycentric, geometric_normal: normal, front_face: d.dot(normal) < 0.0 })
}
}
/// Geometric hit, without material/shading-normal or persistent topology identity.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct TriangleHit {
pub distance: f64,
pub barycentric: [f64; 3],
pub geometric_normal: Vec3,
pub front_face: bool,
}
/// Captured input ordinal, not a CAD face identifier. RT2 owns the appearance mapping.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Hit {
pub primitive_index: usize,
pub geometry: TriangleHit,
}
#[cfg(test)]
mod planar_shadow_tests;
#[cfg(test)]
mod tests;