Skip to content

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

17.4 KB
Raw Blame
//! Original ordered procedural weathering. These are authored optical layers,
//! not corrosion kinetics, engineering-property changes or displaced geometry.
//! Fixed-capacity intent remains copyable, bounded and portable with a saved shot.
use super::{ErrorCode, JobError, Result};
use crate::{ProductScene, surface::srgb8_to_linear};
use serde::{Deserialize, Serialize, de, ser::SerializeSeq};
use std::fmt;

pub const MAX_AGING_LAYERS: usize = 8;
const NAME_BYTES: usize = 256;
fn invalid(message: impl Into<String>) -> JobError {
    JobError::new(ErrorCode::InvalidRequest, message)
}

#[derive(Clone, Copy, PartialEq, Eq)]
pub struct BodyName {
    bytes: [u8; NAME_BYTES],
    length: u16,
}
impl BodyName {
    pub fn new(value: &str) -> Result<Self> {
        if value.is_empty() || value.len() > NAME_BYTES || value.chars().any(char::is_control) {
            return Err(invalid("aging target name must contain 1..256 UTF-8 bytes without controls"));
        }
        let mut result = Self { bytes: [0; NAME_BYTES], length: value.len() as u16 };
        if let Some(destination) = result.bytes.get_mut(..value.len()) {
            destination.copy_from_slice(value.as_bytes());
        }
        Ok(result)
    }
    pub fn as_str(&self) -> &str {
        std::str::from_utf8(self.bytes.get(..usize::from(self.length)).unwrap_or_default()).unwrap_or_default()
    }
}
impl fmt::Debug for BodyName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.as_str().fmt(f)
    }
}
impl Serialize for BodyName {
    fn serialize<S: serde::Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}
impl<'de> Deserialize<'de> for BodyName {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
        struct Name;
        impl<'de> de::Visitor<'de> for Name {
            type Value = BodyName;
            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str("a bounded exact captured body name")
            }
            fn visit_str<E: de::Error>(self, value: &str) -> std::result::Result<Self::Value, E> {
                BodyName::new(value).map_err(E::custom)
            }
        }
        d.deserialize_str(Name)
    }
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BodyTarget {
    pub body_index: u32,
    pub body_name: BodyName,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AgingKind {
    #[default]
    Rust,
    Patina,
    Dust,
    Grime,
    Scratches,
    PaintChips,
    Fading,
}
impl AgingKind {
    pub const ALL: [Self; 7] = [Self::Rust, Self::Patina, Self::Dust, Self::Grime, Self::Scratches, Self::PaintChips, Self::Fading];
    pub fn code(self) -> u32 {
        match self {
            Self::Rust => 1,
            Self::Patina => 2,
            Self::Dust => 3,
            Self::Grime => 4,
            Self::Scratches => 5,
            Self::PaintChips => 6,
            Self::Fading => 7,
        }
    }
    pub fn key(self) -> &'static str {
        match self {
            Self::Rust => "render.aging_rust",
            Self::Patina => "render.aging_patina",
            Self::Dust => "render.aging_dust",
            Self::Grime => "render.aging_grime",
            Self::Scratches => "render.aging_scratches",
            Self::PaintChips => "render.aging_chips",
            Self::Fading => "render.aging_fading",
        }
    }
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SurfaceClass {
    #[default]
    AnyOpaque,
    Metal,
    Dielectric,
}
impl SurfaceClass {
    pub fn code(self) -> u32 {
        match self {
            Self::AnyOpaque => 0,
            Self::Metal => 1,
            Self::Dielectric => 2,
        }
    }
}
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct AgingLayer {
    pub kind: AgingKind,
    pub enabled: bool,
    pub strength: f64,
    pub coverage: f64,
    pub scale_mm: f64,
    pub seed: u32,
    /// World-anchored field origin. Does not imply following a moving occurrence.
    pub origin_mm: [f64; 3],
    #[serde(skip_serializing_if = "Option::is_none")]
    pub target: Option<BodyTarget>,
    pub surface_class: SurfaceClass,
    pub color_srgb: [u8; 3],
    pub roughness: f64,
    pub metallic: f64,
    /// Bias to upward-facing geometric normals; not occlusion/cavity detection.
    pub upward_bias: f64,
}
impl Default for AgingLayer {
    fn default() -> Self {
        Self::preset(AgingKind::Rust)
    }
}
impl AgingLayer {
    pub fn preset(kind: AgingKind) -> Self {
        let (color, roughness, metallic, coverage, upward) = match kind {
            AgingKind::Rust => ([145, 63, 27], 0.9, 0.0, 0.45, 0.0),
            AgingKind::Patina => ([49, 132, 112], 0.76, 0.0, 0.48, 0.0),
            AgingKind::Dust => ([182, 166, 130], 0.96, 0.0, 0.65, 0.88),
            AgingKind::Grime => ([39, 31, 23], 0.7, 0.0, 0.42, 0.0),
            AgingKind::Scratches => ([181, 184, 188], 0.28, 1.0, 0.65, 0.0),
            AgingKind::PaintChips => ([118, 123, 132], 0.45, 1.0, 0.28, 0.0),
            AgingKind::Fading => ([230, 222, 206], 0.78, 0.0, 0.68, 0.3),
        };
        Self {
            kind,
            enabled: true,
            strength: 0.8,
            coverage,
            scale_mm: 18.0,
            seed: 19,
            origin_mm: [0.0; 3],
            target: None,
            surface_class: SurfaceClass::AnyOpaque,
            color_srgb: color,
            roughness,
            metallic,
            upward_bias: upward,
        }
    }
    pub fn active(self) -> bool {
        self.enabled && self.strength > 0.0 && self.coverage > 0.0
    }
    pub fn validate(self) -> Result<()> {
        if [self.strength, self.coverage, self.metallic, self.upward_bias].iter().any(|v| !v.is_finite() || !(0.0..=1.0).contains(v))
            || !self.scale_mm.is_finite()
            || !(0.01..=100_000.0).contains(&self.scale_mm)
            || !self.roughness.is_finite()
            || !(0.02..=1.0).contains(&self.roughness)
            || self.origin_mm.iter().any(|v| !v.is_finite() || v.abs() > 1e9)
            || self.seed > 65535
        {
            return Err(invalid(
                "aging needs strength/coverage/metallic/upward bias 0..1, scale 0.01..100000 mm, roughness 0.02..1, finite origin +/-1e9 mm and seed 0..65535",
            ));
        }
        if let Some(target) = self.target {
            if target.body_index as usize >= super::MAX_GPU_PATH_BODIES || target.body_name.as_str().starts_with("__render_stage__/") {
                return Err(invalid("aging cannot target an out-of-range body or a passive render stage"));
            }
            BodyName::new(target.body_name.as_str())?;
        }
        Ok(())
    }
}

#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct AgingStack {
    slots: [Option<AgingLayer>; MAX_AGING_LAYERS],
    length: u8,
}
impl AgingStack {
    pub fn is_empty(&self) -> bool {
        self.length == 0
    }
    pub fn len(&self) -> usize {
        usize::from(self.length)
    }
    pub fn active(&self) -> bool {
        self.iter().any(|layer| layer.active())
    }
    pub fn iter(&self) -> impl Iterator<Item = &AgingLayer> {
        self.slots.iter().take(self.len()).flatten()
    }
    pub fn get(&self, index: usize) -> Option<&AgingLayer> {
        self.slots.get(index).and_then(Option::as_ref)
    }
    pub fn get_mut(&mut self, index: usize) -> Option<&mut AgingLayer> {
        self.slots.get_mut(index).and_then(Option::as_mut)
    }
    pub fn push(&mut self, layer: AgingLayer) -> Result<()> {
        layer.validate()?;
        let index = self.len();
        let slot = self.slots.get_mut(index).ok_or_else(|| invalid("at most eight aging layers"))?;
        *slot = Some(layer);
        self.length += 1;
        Ok(())
    }
    pub fn remove(&mut self, index: usize) -> Result<()> {
        if index >= self.len() {
            return Err(invalid("aging layer index is not present"));
        }
        for current in index..self.len() - 1 {
            let next = self.slots.get(current + 1).copied().flatten();
            if let Some(slot) = self.slots.get_mut(current) {
                *slot = next;
            }
        }
        self.length -= 1;
        let end = self.len();
        if let Some(slot) = self.slots.get_mut(end) {
            *slot = None;
        }
        Ok(())
    }
    pub fn move_layer(&mut self, from: usize, to: usize) -> Result<()> {
        if from >= self.len() || to >= self.len() {
            return Err(invalid("aging reorder index is not present"));
        }
        self.slots.swap(from, to);
        Ok(())
    }
    pub fn validate(&self) -> Result<()> {
        for layer in self.iter() {
            layer.validate()?;
        }
        Ok(())
    }
    pub fn validate_scene(&self, scene: &ProductScene) -> Result<()> {
        self.validate()?;
        for layer in self.iter().filter(|layer| layer.active()) {
            if let Some(target) = layer.target {
                let body = scene.meshes.get(target.body_index as usize).ok_or_else(|| invalid("aging target body is missing"))?;
                if body.name != target.body_name.as_str() {
                    return Err(invalid("aging target identity changed; review and select the target again"));
                }
                if body.transmission.is_some() || body.opacity != 1.0 || body.faces.iter().any(|f| f.transmission.is_some() || f.opacity != 1.0) {
                    return Err(invalid("aging supports opaque surfaces only; explicit glass targets are refused"));
                }
            }
            for (index, body) in scene.meshes.iter().enumerate() {
                if body.name.starts_with("__render_stage__/") || layer.target.is_some_and(|t| t.body_index as usize != index) {
                    continue;
                }
                let bounds = body.mesh.bounds();
                if !bounds.is_empty() && bounds.diagonal() / layer.scale_mm > 4096.0 {
                    return Err(invalid("aging field exceeds 4096 repeats across a body; increase the physical scale explicitly"));
                }
            }
        }
        Ok(())
    }
    /// Five aligned vec4s per layer: id/target/class/seed, mask/scale,
    /// rebased periodic origin/Scratch cell carry, linear coat RGB/roughness, metallic/reserved.
    pub fn gpu_layers(&self, target: [f64; 3]) -> Result<[[f32; 20]; MAX_AGING_LAYERS]> {
        self.validate()?;
        if target.iter().any(|v| !v.is_finite() || v.abs() > 1e9) {
            return Err(invalid("invalid aging camera target"));
        }
        let mut result = [[0.0; 20]; MAX_AGING_LAYERS];
        for (out, layer) in result.iter_mut().zip(self.iter()) {
            if !layer.active() {
                continue;
            }
            out[0] = layer.kind.code() as f32;
            out[1] = layer.target.map_or(0, |t| t.body_index + 1) as f32;
            out[2] = layer.surface_class.code() as f32;
            out[3] = layer.seed as f32;
            out[4] = layer.strength as f32;
            out[5] = layer.coverage as f32;
            out[6] = layer.scale_mm.recip() as f32;
            out[7] = layer.upward_bias as f32;
            let mut scratch_carry = 0_u32;
            let mut place = 1_u32;
            for axis in 0..3 {
                let coordinate = (target[axis] - layer.origin_mm[axis]) / layer.scale_mm;
                out[8 + axis] = coordinate.rem_euclid(4096.0) as f32;
                if layer.kind == AgingKind::Scratches {
                    // Noise repeats every4096 cells, while floor(4*q/5)'s
                    // hashed band also needs the removed quotient modulo5.
                    // Three base5 digits fit exactly in the reserved f32 lane.
                    scratch_carry += ((coordinate / 4096.0).floor().rem_euclid(5.0) as u32) * place;
                    place *= 5;
                }
            }
            out[11] = scratch_carry as f32;
            for axis in 0..3 {
                out[12 + axis] = srgb8_to_linear(layer.color_srgb[axis]) as f32;
            }
            out[15] = layer.roughness as f32;
            out[16] = layer.metallic as f32;
        }
        Ok(result)
    }
}
impl Serialize for AgingStack {
    fn serialize<S: serde::Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
        let mut seq = s.serialize_seq(Some(self.len()))?;
        for layer in self.iter() {
            seq.serialize_element(layer)?;
        }
        seq.end()
    }
}
impl<'de> Deserialize<'de> for AgingStack {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
        struct Layers;
        impl<'de> de::Visitor<'de> for Layers {
            type Value = AgingStack;
            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str("at most eight ordered aging layers")
            }
            fn visit_seq<A: de::SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<AgingStack, A::Error> {
                let mut result = AgingStack::default();
                while let Some(layer) = seq.next_element()? {
                    result.push(layer).map_err(de::Error::custom)?;
                }
                Ok(result)
            }
        }
        d.deserialize_seq(Layers)
    }
}
#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn layers_are_bounded_ordered_and_exactly_portable() {
        let mut stack = AgingStack::default();
        assert!(!stack.active());
        for kind in AgingKind::ALL {
            stack.push(AgingLayer::preset(kind)).unwrap();
        }
        stack.move_layer(0, 3).unwrap();
        assert_eq!(stack.get(0).unwrap().kind, AgingKind::Grime);
        stack.remove(2).unwrap();
        assert_eq!(stack.len(), 6);
        let wire = serde_json::to_string(&stack).unwrap();
        assert_eq!(serde_json::from_str::<AgingStack>(&wire).unwrap(), stack);
        while stack.len() < 8 {
            stack.push(Default::default()).unwrap();
        }
        assert!(stack.push(Default::default()).is_err());
        let nine = format!("[{}]", ["{}"; 9].join(","));
        assert!(serde_json::from_str::<AgingStack>(&nine).is_err());
        assert!(serde_json::from_str::<AgingStack>(r#"[{"years":30}]"#).is_err());
    }
    #[test]
    fn hostile_values_and_names_are_rejected_without_changing_geometry() {
        for value in [f64::NAN, f64::INFINITY, -1.0, 1.1] {
            assert!(AgingLayer { strength: value, ..Default::default() }.validate().is_err());
        }
        assert!(AgingLayer { scale_mm: 0.0, ..Default::default() }.validate().is_err());
        for name in ["", "bad\nname"] {
            assert!(BodyName::new(name).is_err());
        }
        assert!(BodyName::new(&"a".repeat(257)).is_err());
        let name = BodyName::new("Módulo Ω").unwrap();
        assert_eq!(serde_json::from_str::<BodyName>(&serde_json::to_string(&name).unwrap()).unwrap(), name);
    }
    #[test]
    fn periodic_rebasing_and_disabled_layers_have_exact_boundaries() {
        let mut stack = AgingStack::default();
        stack.push(AgingLayer { scale_mm: 2.0, ..Default::default() }).unwrap();
        let a = stack.gpu_layers([0.0; 3]).unwrap();
        let b = stack.gpu_layers([8192.0; 3]).unwrap();
        assert_eq!(a, b);
        stack.get_mut(0).unwrap().enabled = false;
        assert_eq!(stack.gpu_layers([0.0; 3]).unwrap(), [[0.0; 20]; 8]);
        assert!(!stack.active());
    }
    #[test]
    fn scratch_rebase_carries_signed_camera_cells_on_all_axes_in_the_same_uniform_size() {
        let origin = [128.0, -64.0, 32.0];
        let fraction = [0.125, 0.25, 0.5];
        let layer = AgingLayer { kind: AgingKind::Scratches, scale_mm: 2.0, origin_mm: origin, ..Default::default() };
        let mut stack = AgingStack::default();
        stack.push(layer).unwrap();
        assert_eq!(std::mem::size_of::<[[f32; 20]; MAX_AGING_LAYERS]>(), 640);
        for k in [-122000_i32, -7, -1, 0, 1, 4, 5, 122000] {
            let cells = [k, k + 2, -k];
            let target = std::array::from_fn(|axis| origin[axis] + 2.0 * (4096.0 * f64::from(cells[axis]) + fraction[axis]));
            let packed = stack.gpu_layers(target).unwrap();
            assert_eq!(&packed[0][8..11], &[0.125, 0.25, 0.5]);
            let expected = cells[0].rem_euclid(5) + 5 * cells[1].rem_euclid(5) + 25 * cells[2].rem_euclid(5);
            assert_eq!(packed[0][11], expected as f32, "{cells:?}");
            assert!(packed[1..].iter().flatten().all(|value| value.to_bits() == 0));
            assert!(packed[0][17..].iter().all(|value| value.to_bits() == 0));
            // Non-Scratch layers keep their prior five-vec4 bytes. Only the
            // kind and the Scratch-only reserved carry differ in this pair.
            let mut ordinary = AgingStack::default();
            ordinary.push(AgingLayer { kind: AgingKind::Rust, ..layer }).unwrap();
            let mut expected = packed;
            expected[0][0] = AgingKind::Rust.code() as f32;
            expected[0][11] = 0.0;
            assert_eq!(ordinary.gpu_layers(target).unwrap().map(|row| row.map(f32::to_bits)), expected.map(|row| row.map(f32::to_bits)));
        }
        stack.get_mut(0).unwrap().enabled = false;
        assert!(stack.gpu_layers([999000000.0, -999000000.0, 0.0]).unwrap().iter().flatten().all(|value| value.to_bits() == 0));
        assert!(AgingStack::default().gpu_layers([999000000.0; 3]).unwrap().iter().flatten().all(|value| value.to_bits() == 0));
    }
}