Skip to content

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

5.5 KB
Raw Blame
//! Definition-local visual coordinates, independent of geometry and engineering axes.
//! This numerical foundation installs no texture sampler, shader or persistent record.

use solidcore_record::Vec3;
use solidcraft_geom::Aabb3;
use solidcraft_geom::prelude::*;

/// Admission bounds, not a GPU precision or engineering applicability guarantee.
pub const MAX_LOCAL_MM: f64 = 1e9;
pub const MIN_REPEAT_MM: f64 = 1e-3;
pub const MAX_REPEAT_MM: f64 = 1e6;
pub const MAX_REPEAT_COORDINATE: f64 = 1e6;
/// Absolute tolerance for unit-length squared, orthogonality and handedness checks.
pub const FRAME_TOLERANCE: f64 = 1e-10;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MappingError {
    Position,
    Frame,
    RepeatSize,
    Coordinates,
    Bounds,
}

impl std::fmt::Display for MappingError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Position => "visual mapping positions must be finite and within +/-1e9 mm",
            Self::Frame => "visual mapping axes must form a right-handed orthonormal frame",
            Self::RepeatSize => "visual repeat sizes must be finite and within [0.001, 1e6] mm",
            Self::Coordinates => "visual repeat coordinates exceed the +/-1e6 admission limit",
            Self::Bounds => "grain suggestion needs finite ordered local bounds with a positive extent",
        })
    }
}
impl std::error::Error for MappingError {}

/// A one-time visual suggestion; not a material-local mechanical L/R/T assignment.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum GrainAxis {
    X,
    Y,
    Z,
}

impl GrainAxis {
    /// First axis is the visual grain direction. The other two complete a right-handed frame.
    pub fn axes(self) -> [Vec3; 3] {
        match self {
            Self::X => [Vec3::X, Vec3::Y, Vec3::Z],
            Self::Y => [Vec3::Y, Vec3::Z, Vec3::X],
            Self::Z => [Vec3::Z, Vec3::X, Vec3::Y],
        }
    }
}

/// Suggest from definition-local bounds only, with exact ties resolved X, then Y, then Z.
/// The caller stores an accepted frame once; this function never observes a later rebuild.
pub fn suggest_grain_axis(local_bounds: Aabb3) -> Result<GrainAxis, MappingError> {
    if !bounded_position(local_bounds.min) || !bounded_position(local_bounds.max) || local_bounds.is_empty() {
        return Err(MappingError::Bounds);
    }
    let extent = local_bounds.max - local_bounds.min;
    if extent.x.max(extent.y).max(extent.z) <= 0.0 {
        return Err(MappingError::Bounds);
    }
    if extent.x >= extent.y && extent.x >= extent.z {
        Ok(GrainAxis::X)
    } else if extent.y >= extent.z {
        Ok(GrainAxis::Y)
    } else {
        Ok(GrainAxis::Z)
    }
}

/// Immutable admitted visual frame. Fields cannot be changed without readmission.
/// No serde implementation: eventual document/catalog readers must use `new`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct VisualMapping {
    origin_mm: Vec3,
    axes: [Vec3; 3],
    repeat_mm: Vec3,
}

impl VisualMapping {
    /// Axes are unit directions in definition-local space, in grain/across/depth order.
    /// Repeat sizes are distances along those directions, not body-bound fractions.
    /// Small floating-point frame error is admitted within `FRAME_TOLERANCE`; no skew,
    /// reflection, rescaling, orthogonalization or replacement frame is manufactured.
    pub fn new(origin_mm: Vec3, axes: [Vec3; 3], repeat_mm: Vec3) -> Result<Self, MappingError> {
        if !bounded_position(origin_mm) {
            return Err(MappingError::Position);
        }
        let [x, y, z] = axes;
        if !axes.into_iter().all(|v| v.is_finite() && (v.len2() - 1.0).abs() <= FRAME_TOLERANCE)
            || x.dot(y).abs() > FRAME_TOLERANCE
            || x.dot(z).abs() > FRAME_TOLERANCE
            || y.dot(z).abs() > FRAME_TOLERANCE
            || (x.cross(y).dot(z) - 1.0).abs() > FRAME_TOLERANCE
        {
            return Err(MappingError::Frame);
        }
        if ![repeat_mm.x, repeat_mm.y, repeat_mm.z].into_iter().all(|v| v.is_finite() && (MIN_REPEAT_MM..=MAX_REPEAT_MM).contains(&v)) {
            return Err(MappingError::RepeatSize);
        }
        Ok(Self { origin_mm, axes, repeat_mm })
    }

    pub fn origin_mm(self) -> Vec3 {
        self.origin_mm
    }
    pub fn axes(self) -> [Vec3; 3] {
        self.axes
    }
    pub fn repeat_mm(self) -> Vec3 {
        self.repeat_mm
    }

    /// Unwrapped signed repeat coordinates, calculated in f64. No clamping or UV seam.
    /// The host must first invert the selected instance placement into definition-local
    /// space. World-space bounding boxes and camera/mesh positions are not inputs here.
    /// Samplers choose wrapping/filtering; GPU consumers need their own precision budget.
    pub fn coordinates(self, local_point_mm: Vec3) -> Result<Vec3, MappingError> {
        if !bounded_position(local_point_mm) {
            return Err(MappingError::Position);
        }
        let delta = local_point_mm - self.origin_mm;
        let [x, y, z] = self.axes;
        let result = Vec3::new(delta.dot(x) / self.repeat_mm.x, delta.dot(y) / self.repeat_mm.y, delta.dot(z) / self.repeat_mm.z);
        if !result.is_finite() || [result.x, result.y, result.z].into_iter().any(|v| v.abs() > MAX_REPEAT_COORDINATE) {
            return Err(MappingError::Coordinates);
        }
        Ok(result)
    }
}

fn bounded_position(value: Vec3) -> bool {
    value.is_finite() && [value.x, value.y, value.z].into_iter().all(|v| v.abs() <= MAX_LOCAL_MM)
}

#[cfg(test)]
#[path = "mapping_tests.rs"]
mod tests;