Skip to content

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

11.7 KB
Raw Blame
//! Original analytic passive staging, separate from engineering geometry. Panels
//! are finite, two-sided, non-emissive diffuse rectangles in world millimetres.
//! They are appended only to a captured render scene, after conservative clearance.
use crate::{
    ProductMesh, ProductScene,
    job::{CancelToken, ErrorCode, JobError, Result},
    surface::OpaqueSurface,
};
use serde::{Deserialize, Serialize};
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
use solidcraft_geom::{Aabb3, Mesh};
use std::{collections::BTreeSet, fmt, sync::Arc};

pub const MAX_STAGE_PANELS: usize = 32;
fn invalid(message: impl Into<String>) -> JobError {
    JobError::new(ErrorCode::InvalidRequest, message)
}
fn v(a: [f64; 3]) -> Vec3 {
    Vec3::new(a[0], a[1], a[2])
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StagePanel {
    pub id: String,
    pub center_mm: [f64; 3],
    pub half_u_mm: [f64; 3],
    pub half_v_mm: [f64; 3],
    pub reflectance_linear: [f64; 3],
}
impl StagePanel {
    pub fn validate(&self) -> Result<()> {
        let (u, vv) = (v(self.half_u_mm), v(self.half_v_mm));
        let (ul, vl) = (u.len(), vv.len());
        if self.id.is_empty()
            || self.id.len() > 64
            || !self.id.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_'))
            || !v(self.center_mm).is_finite()
            || !u.is_finite()
            || !vv.is_finite()
            || !(1e-4..=1e6).contains(&ul)
            || !(1e-4..=1e6).contains(&vl)
            || u.dot(vv).abs() > 1e-8 * ul * vl
            || self.reflectance_linear.iter().any(|x| !x.is_finite() || !(0.0..=1.0).contains(x))
        {
            return Err(invalid("stage panel requires bounded identity, finite orthogonal half-edges and linear reflectance 0..1"));
        }
        for p in self.corners() {
            if !p.is_finite() || [p.x, p.y, p.z].iter().any(|x| x.abs() > 1e9) {
                return Err(invalid("stage panel corner exceeds world bounds"));
            }
        }
        Ok(())
    }
    pub fn corners(&self) -> [Vec3; 4] {
        let (c, u, vv) = (v(self.center_mm), v(self.half_u_mm), v(self.half_v_mm));
        [c - u - vv, c + u - vv, c + u + vv, c - u + vv]
    }
    /// Rectangle/AABB separating axes, not a B-rep contact or collision oracle.
    /// Touching or ambiguous clearance refuses; an AABB false positive is explicit.
    pub fn separated_from(&self, bounds: Aabb3) -> Result<bool> {
        self.validate()?;
        if bounds.is_empty() {
            return Ok(true);
        }
        if !bounds.min.is_finite() || !bounds.max.is_finite() {
            return Err(invalid("nonfinite stage subject bounds"));
        }
        let (u, vv) = (v(self.half_u_mm), v(self.half_v_mm));
        let delta = v(self.center_mm) - bounds.center();
        let half = (bounds.max - bounds.min) * 0.5;
        let axes = [
            Vec3::X,
            Vec3::Y,
            Vec3::Z,
            u.cross(vv),
            u.cross(Vec3::X),
            u.cross(Vec3::Y),
            u.cross(Vec3::Z),
            vv.cross(Vec3::X),
            vv.cross(Vec3::Y),
            vv.cross(Vec3::Z),
        ];
        for axis in axes {
            let length = axis.len();
            if length <= 1e-20 {
                continue;
            }
            let box_radius = axis.x.abs() * half.x + axis.y.abs() * half.y + axis.z.abs() * half.z;
            let panel_radius = axis.dot(u).abs() + axis.dot(vv).abs();
            if delta.dot(axis).abs() > box_radius + panel_radius + 1e-7 * length {
                return Ok(true);
            }
        }
        Ok(false)
    }
    fn mesh(&self) -> Result<ProductMesh> {
        self.validate()?;
        let u = v(self.half_u_mm);
        let vv = v(self.half_v_mm);
        let normal = u.cross(vv).normalized().ok_or_else(|| invalid("degenerate stage panel"))?;
        let surface = OpaqueSurface::new(v(self.reflectance_linear), 0.0, 1.0, 1.0).map_err(|e| invalid(e.to_string()))?;
        let mut mesh = Mesh::default();
        mesh.positions.try_reserve_exact(4).map_err(|_| invalid("could not reserve stage vertices"))?;
        mesh.normals.try_reserve_exact(4).map_err(|_| invalid("could not reserve stage normals"))?;
        mesh.triangles.try_reserve_exact(2).map_err(|_| invalid("could not reserve stage triangles"))?;
        mesh.tri_face.try_reserve_exact(2).map_err(|_| invalid("could not reserve stage face tags"))?;
        mesh.positions.extend(self.corners());
        mesh.normals.extend([normal; 4]);
        mesh.triangles.extend([[0, 1, 2], [0, 2, 3]]);
        mesh.tri_face.extend([0, 0]);
        // The surface carries exact linear reflectance. This display colour is not
        // used as an additional multiplier by PBR consumers.
        let color = self.reflectance_linear.map(solidcraft_geom::srgb::encode8);
        Ok(ProductMesh {
            name: format!("__render_stage__/{}", self.id),
            mesh: Arc::new(mesh),
            color,
            opacity: 1.0,
            surface: Some(surface),
            transmission: None,
            faces: Vec::new(),
        })
    }
}
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
#[serde(transparent)]
pub struct Stage(Vec<StagePanel>);
impl Stage {
    pub fn new(panels: Vec<StagePanel>) -> Result<Self> {
        let stage = Self(panels);
        stage.validate()?;
        Ok(stage)
    }
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
    pub fn len(&self) -> usize {
        self.0.len()
    }
    pub fn iter(&self) -> impl Iterator<Item = &StagePanel> {
        self.0.iter()
    }
    pub fn validate(&self) -> Result<()> {
        if self.len() > MAX_STAGE_PANELS || self.0.capacity() > MAX_STAGE_PANELS {
            return Err(invalid("at most 32 stage panels and reserved slots"));
        }
        let mut seen = BTreeSet::new();
        for panel in &self.0 {
            panel.validate()?;
            if !seen.insert(&panel.id) {
                return Err(invalid("duplicate stage panel id"));
            }
        }
        Ok(())
    }
    /// Atomic with respect to the captured scene. Product ordinals are preserved.
    pub fn append_to(&self, scene: &mut ProductScene, cancel: &CancelToken) -> Result<()> {
        self.validate()?;
        cancel.check()?;
        if self.is_empty() {
            return Ok(());
        }
        if scene.meshes.len() > crate::job::MAX_CPU_BODIES {
            return Err(invalid("stage subject exceeds the body admission ceiling"));
        }
        // Mesh bounds walk vertices: compute them once, not once for every card.
        let mut bounds = Vec::new();
        bounds.try_reserve_exact(scene.meshes.len()).map_err(|_| invalid("could not reserve stage clearance bounds"))?;
        for body in &scene.meshes {
            cancel.check()?;
            bounds.push(body.mesh.bounds());
        }
        let mut addition = Vec::new();
        addition.try_reserve_exact(self.len()).map_err(|_| invalid("could not reserve passive stage"))?;
        for panel in &self.0 {
            cancel.check()?;
            let name = format!("__render_stage__/{}", panel.id);
            for (body, bounds) in scene.meshes.iter().zip(&bounds) {
                cancel.check()?;
                if body.name == name {
                    return Err(invalid("stage panel identity conflicts with a product body"));
                }
                if !panel.separated_from(*bounds)? {
                    return Err(invalid(format!(
                        "stage panel {} intersects or touches product bounds for {}; move it explicitly",
                        panel.id, body.name
                    )));
                }
            }
            addition.push(panel.mesh()?);
        }
        scene.meshes.try_reserve_exact(addition.len()).map_err(|_| invalid("could not reserve captured stage geometry"))?;
        cancel.check()?;
        for body in addition {
            scene.bounds = scene.bounds.union(&body.mesh.bounds());
            scene.meshes.push(body);
        }
        Ok(())
    }
}
impl<'de> Deserialize<'de> for Stage {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
        struct Panels;
        impl<'de> serde::de::Visitor<'de> for Panels {
            type Value = Stage;
            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str("at most 32 passive stage panels")
            }
            fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<Stage, A::Error> {
                let mut panels = Vec::new();
                while let Some(panel) = seq.next_element::<StagePanel>()? {
                    if panels.len() == MAX_STAGE_PANELS {
                        return Err(serde::de::Error::custom("at most 32 stage panels"));
                    }
                    panel.validate().map_err(serde::de::Error::custom)?;
                    panels.try_reserve_exact(1).map_err(serde::de::Error::custom)?;
                    panels.push(panel);
                }
                Stage::new(panels).map_err(serde::de::Error::custom)
            }
        }
        d.deserialize_seq(Panels)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    fn panel() -> StagePanel {
        StagePanel { id: "floor".into(), center_mm: [0., 0., -1.], half_u_mm: [20., 0., 0.], half_v_mm: [0., 20., 0.], reflectance_linear: [0.18; 3] }
    }
    #[test]
    fn analytic_clearance_covers_touching_separation_and_rotated_cards() {
        let bounds = Aabb3 { min: Vec3::new(-1., -1., 0.), max: Vec3::new(1., 1., 2.) };
        let mut p = panel();
        assert!(p.separated_from(bounds).unwrap());
        p.center_mm[2] = 0.;
        assert!(!p.separated_from(bounds).unwrap());
        p.center_mm = [40., 0., 1.];
        assert!(p.separated_from(bounds).unwrap());
        p.center_mm = [0., 0., 1.];
        p.half_u_mm = [2., 2., 0.];
        p.half_v_mm = [0., 0., 4.];
        assert!(!p.separated_from(bounds).unwrap());
        p.center_mm = [20., 0., 1.];
        assert!(p.separated_from(bounds).unwrap());
    }
    #[test]
    fn stage_is_passive_atomic_and_preserves_existing_ordinals() {
        let stage = Stage::new(vec![panel()]).unwrap();
        let mut scene = ProductScene { meshes: vec![], bounds: Aabb3::EMPTY };
        stage.append_to(&mut scene, &CancelToken::default()).unwrap();
        assert_eq!(scene.meshes.len(), 1);
        assert_eq!(scene.meshes[0].mesh.triangles.len(), 2);
        assert_eq!(scene.meshes[0].surface.unwrap().dielectric_ior(), 1.0);
        assert!(scene.meshes[0].transmission.is_none());
        // Linear 0.18 shows as sRGB 118.
        assert_eq!(scene.meshes[0].color, [118; 3]);
        let before = scene.meshes[0].mesh.clone();
        assert!(stage.append_to(&mut scene, &CancelToken::default()).is_err());
        assert_eq!(scene.meshes.len(), 1);
        assert!(Arc::ptr_eq(&before, &scene.meshes[0].mesh));
        let token = CancelToken::default();
        token.cancel();
        assert!(stage.append_to(&mut scene, &token).is_err());
    }
    #[test]
    fn staged_metadata_roundtrips_and_hostile_inputs_refuse() {
        let stage = Stage::new(vec![panel()]).unwrap();
        let wire = serde_json::to_string(&stage).unwrap();
        assert_eq!(serde_json::from_str::<Stage>(&wire).unwrap(), stage);
        let mut p = panel();
        p.reflectance_linear[0] = 1.1;
        assert!(Stage::new(vec![p]).is_err());
        assert!(Stage::new(vec![panel(), panel()]).is_err());
        assert!(serde_json::from_value::<Stage>(serde_json::json!(vec![panel(); 33])).is_err());
        let mut wire = serde_json::to_value(&stage).unwrap();
        wire[0]["emission"] = serde_json::json!(5);
        assert!(serde_json::from_value::<Stage>(wire).is_err());
    }
}