Skip to content

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

19.2 KB
Raw Blame
//! Surface/surface intersection (`capi/include/smlib.h`, "Surface/surface intersection"): two
//! surfaces described in plain numbers, intersected by one of SMLib's SSI entry points, each
//! intersection curve exactly as SMLib holds it: schema 4 B-splines (`solidcraft_geom::brep`).
//!
//! The constructors take exactly the fields of an SSI corpus case (`tests/ssi-corpus`), angles in
//! degrees. Each surface's UV domain is SMLib's natural one ([`Surface::domain`]): (u, v) itself
//! for planes, the parameterisation of SMLib's internal NURBS form for the other analytic kinds.

use solidcore_record::brep as b;

use std::sync::OnceLock;

use crate::{Error, Result};

/// A surface with its UV domain: the description it was made from, from which solidcore makes its
/// own ([`crate::core::split`]).
pub struct Surface {
    /// solidcore's, made when it is first needed.
    core: OnceLock<Result<crate::core::split::Tool>>,
    spec: Spec,
}

/// What a [`Surface`] was made from: its constructor's arguments, checked as the C API checks them
/// ([`Spec::check`]).
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum Spec {
    Plane { origin: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], u: [f64; 2], v: [f64; 2] },
    Cylinder { origin: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], radius: f64, angle_deg: [f64; 2], height: [f64; 2] },
    Cone { apex: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], half_angle_deg: f64, height: [f64; 2] },
    Sphere { center: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], radius: f64, lon_deg: [f64; 2], lat_deg: [f64; 2] },
    Torus { center: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], major_radius: f64, minor_radius: f64, major_deg: [f64; 2], minor_deg: [f64; 2] },
    Nurbs { degree: [usize; 2], nu: usize, nv: usize, knots_u: Vec<f64>, knots_v: Vec<f64>, points: Vec<[f64; 3]>, weights: Option<Vec<f64>> },
}

impl std::fmt::Debug for Surface {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("smlib::ssi::Surface")
    }
}

/// The largest coordinate, degree and control net a surface may have (`SMLIB_SURFACE_MAX_*`).
const MAX_COORD: f64 = 1e8;
const MAX_DEGREE: usize = 25;
const MAX_POLES: usize = 1_000_000;

fn bounded(v: &[f64]) -> bool {
    v.iter().all(|x| x.is_finite() && x.abs() <= MAX_COORD)
}

/// Two non-zero axes that are not (nearly) parallel.
fn axes(x: &[f64; 3], y: &[f64; 3]) -> bool {
    let len = |a: &[f64; 3]| (a[0] * a[0] + a[1] * a[1] + a[2] * a[2]).sqrt();
    let c = [x[1] * y[2] - x[2] * y[1], x[2] * y[0] - x[0] * y[2], x[0] * y[1] - x[1] * y[0]];
    bounded(x) && bounded(y) && len(x) > 1e-12 && len(y) > 1e-12 && len(&c) > 1e-9 * len(x) * len(y)
}

/// An increasing interval inside `[lo, hi]` spanning at most `span`.
fn range(r: &[f64; 2], lo: f64, hi: f64, span: f64) -> bool {
    bounded(r) && r[0] < r[1] && r[0] >= lo && r[1] <= hi && r[1] - r[0] <= span
}

fn length(x: f64) -> bool {
    x.is_finite() && x > 1e-9 && x <= MAX_COORD
}

/// A knot vector of n + p + 1 non-decreasing values with a non-empty domain `[k[p], k[n]]`, no
/// interior knot repeated more than p times and no end knot more than p + 1.
fn knots(k: &[f64], n: usize, p: usize) -> bool {
    if k.len() != n + p + 1 || !bounded(k) || k.windows(2).any(|w| w[1] < w[0]) {
        return false;
    }
    let (Some(lo), Some(hi)) = (k.get(p).copied(), k.get(n).copied()) else { return false };
    let mut run = 1;
    for w in k.windows(2) {
        run = if w[1] == w[0] { run + 1 } else { 1 };
        if run > p + 1 || (run > p && w[1] > lo && w[1] < hi) {
            return false;
        }
    }
    lo < hi
}

impl Spec {
    /// The checks each of the C API's constructors makes of its arguments, so that a surface is
    /// refused before solidcore sees it.
    fn check(&self) -> Result<()> {
        let whole = |r: &[f64; 2]| range(r, -MAX_COORD, MAX_COORD, 2.0 * MAX_COORD);
        let turn = |r: &[f64; 2]| range(r, -360.0, 360.0, 360.0);
        let ok = match self {
            Spec::Plane { origin, xaxis, yaxis, u, v } => bounded(origin) && axes(xaxis, yaxis) && whole(u) && whole(v),
            Spec::Cylinder { origin, xaxis, yaxis, radius, angle_deg, height } => {
                bounded(origin) && axes(xaxis, yaxis) && length(*radius) && turn(angle_deg) && range(height, -MAX_COORD, MAX_COORD, MAX_COORD)
            }
            Spec::Cone { apex, xaxis, yaxis, half_angle_deg, height } => {
                bounded(apex)
                    && axes(xaxis, yaxis)
                    && (0.01..=89.0).contains(half_angle_deg)
                    && range(height, 0.0, MAX_COORD, MAX_COORD)
                    && height[1] - height[0] > 1e-9
            }
            Spec::Sphere { center, xaxis, yaxis, radius, lon_deg, lat_deg } => {
                bounded(center) && axes(xaxis, yaxis) && length(*radius) && turn(lon_deg) && range(lat_deg, -90.0, 90.0, 180.0)
            }
            Spec::Torus { center, xaxis, yaxis, major_radius, minor_radius, major_deg, minor_deg } => {
                bounded(center)
                    && axes(xaxis, yaxis)
                    && length(*major_radius)
                    && length(*minor_radius)
                    && minor_radius < major_radius
                    && turn(major_deg)
                    && turn(minor_deg)
            }
            Spec::Nurbs { degree: [p, q], nu, nv, knots_u, knots_v, points, weights } => {
                (1..=MAX_DEGREE).contains(p)
                    && (1..=MAX_DEGREE).contains(q)
                    && *nu > *p
                    && *nv > *q
                    && nu.checked_mul(*nv).is_some_and(|n| n <= MAX_POLES && points.len() == n)
                    && knots(knots_u, *nu, *p)
                    && knots(knots_v, *nv, *q)
                    && points.iter().all(|c| bounded(c))
                    && weights.as_ref().is_none_or(|w| w.len() == points.len() && w.iter().all(|x| (1e-6..=1e6).contains(x)))
            }
        };
        if ok { Ok(()) } else { Err(Error::Argument) }
    }
}

impl Surface {
    /// solidcore's surface, made the first time it is needed.
    fn core(&self) -> Result<&crate::core::split::Tool> {
        self.core.get_or_init(|| crate::stop::unstoppable(|| crate::core::ssi::surface(&self.spec))).as_ref().map_err(Clone::clone)
    }

    pub(crate) fn spec(&self) -> &Spec {
        &self.spec
    }

    /// A surface from its checked description.
    fn made(spec: Spec) -> Result<Surface> {
        spec.check()?;
        Ok(Surface { core: OnceLock::new(), spec })
    }

    /// `origin + u*x + v*y` (x, y the axes made unit), for u in `u`, v in `v`.
    pub fn plane(origin: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], u: [f64; 2], v: [f64; 2]) -> Result<Surface> {
        Surface::made(Spec::Plane { origin, xaxis, yaxis, u, v })
    }

    /// A cylinder of `radius` about the axis through `origin` along `xaxis × yaxis`, angle
    /// `angle_deg` from `xaxis` towards `yaxis`, for heights `height` measured from `origin`.
    pub fn cylinder(origin: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], radius: f64, angle_deg: [f64; 2], height: [f64; 2]) -> Result<Surface> {
        Surface::made(Spec::Cylinder { origin, xaxis, yaxis, radius, angle_deg, height })
    }

    /// A full cone with its apex at `apex` along `xaxis × yaxis`, radius `h * tan(half_angle_deg)`
    /// at distance h along the axis, for h in `height` (from 0: through the apex).
    pub fn cone(apex: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], half_angle_deg: f64, height: [f64; 2]) -> Result<Surface> {
        Surface::made(Spec::Cone { apex, xaxis, yaxis, half_angle_deg, height })
    }

    /// A sphere of `radius` at `center`, over longitudes `lon_deg` and latitudes `lat_deg`.
    pub fn sphere(center: [f64; 3], xaxis: [f64; 3], yaxis: [f64; 3], radius: f64, lon_deg: [f64; 2], lat_deg: [f64; 2]) -> Result<Surface> {
        Surface::made(Spec::Sphere { center, xaxis, yaxis, radius, lon_deg, lat_deg })
    }

    /// A ring torus at `center` about `xaxis × yaxis`, `major_deg` round the axis and `minor_deg`
    /// round the tube.
    pub fn torus(
        center: [f64; 3],
        xaxis: [f64; 3],
        yaxis: [f64; 3],
        major_radius: f64,
        minor_radius: f64,
        major_deg: [f64; 2],
        minor_deg: [f64; 2],
    ) -> Result<Surface> {
        Surface::made(Spec::Torus { center, xaxis, yaxis, major_radius, minor_radius, major_deg, minor_deg })
    }

    /// A (rational) B-spline surface: `nu × nv` control points, point (i, j) (i along u) at
    /// `points[i * nv + j]`; `weights` likewise, or `None` for all 1.
    pub fn nurbs(
        degree: [usize; 2],
        nu: usize,
        nv: usize,
        knots_u: &[f64],
        knots_v: &[f64],
        points: &[[f64; 3]],
        weights: Option<&[f64]>,
    ) -> Result<Surface> {
        Surface::made(Spec::Nurbs {
            degree,
            nu,
            nv,
            knots_u: knots_u.to_vec(),
            knots_v: knots_v.to_vec(),
            points: points.to_vec(),
            weights: weights.map(<[f64]>::to_vec),
        })
    }

    /// A schema 4 record surface over the parameter box `domain` (`[[u0, u1], [v0, v1]]`, the
    /// record's own parameters: radians for angles), with the record's parameterisation and
    /// normal. A spline is taken over its whole knot domain. A cone only as a whole turn, widening
    /// along its axis; a revolution not at all ([`Error::Unsupported`]).
    pub fn from_record(surface: &solidcore_record::brep::Surface, domain: [[f64; 2]; 2]) -> Result<Surface> {
        use solidcore_record::brep::Surface as S;
        let [u, v] = domain;
        let deg = |r: [f64; 2]| r.map(f64::to_degrees);
        let sub = |a: [f64; 3], b: [f64; 3]| [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
        let len = |a: [f64; 3]| (a[0] * a[0] + a[1] * a[1] + a[2] * a[2]).sqrt();
        let cross = |a: [f64; 3], b: [f64; 3]| [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
        // SMLib's plane runs along its axes made unit: the record's parameters scale by their lengths.
        let plane = |origin: [f64; 3], du: [f64; 3], dv: [f64; 3]| {
            let (a, b) = (len(du), len(dv));
            Surface::plane(origin, du, dv, [u[0] * a, u[1] * a], [v[0] * b, v[1] * b])
        };
        match surface {
            S::Plane { origin, u_axis, v_axis } => plane(*origin, *u_axis, *v_axis),
            S::PlaneThrough { origin, u_point, v_point } => plane(*origin, sub(*u_point, *origin), sub(*v_point, *origin)),
            S::Cylinder { frame, radius } => Surface::cylinder(frame.origin, frame.x_axis, frame.y_axis, *radius, deg(u), v),
            S::Cone { frame, radius_at_origin, half_angle } => {
                let t = half_angle.tan();
                if !(t > 0.0) || !(u[1] - u[0] >= std::f64::consts::TAU * (1.0 - 1e-12)) {
                    return Err(Error::Unsupported);
                }
                // The apex lies where the radius is 0; heights run from it along the axis.
                let at = -radius_at_origin / t;
                let z = cross(frame.x_axis, frame.y_axis);
                let apex = [0, 1, 2].map(|k| frame.origin[k] + z[k] * at);
                Surface::cone(apex, frame.x_axis, frame.y_axis, half_angle.to_degrees(), [(v[0] - at).max(0.0), v[1] - at])
            }
            S::Sphere { frame, radius } => Surface::sphere(frame.origin, frame.x_axis, frame.y_axis, *radius, deg(u), deg(v)),
            S::Torus { frame, major_radius, minor_radius, tube_start } => {
                // SMLib's tube angle counts from the outer equator.
                Surface::torus(frame.origin, frame.x_axis, frame.y_axis, *major_radius, *minor_radius, deg(u), deg(v.map(|a| a + tube_start)))
            }
            S::Spline { u_knots, v_knots, points } => {
                let (nu, nv) = (points.len(), points.first().map_or(0, Vec::len));
                let flat: Vec<[f64; 3]> = points.iter().flatten().copied().collect();
                let degree = [u_knots.len().checked_sub(nu + 1).ok_or(Error::Argument)?, v_knots.len().checked_sub(nv + 1).ok_or(Error::Argument)?];
                Surface::nurbs(degree, nu, nv, u_knots, v_knots, &flat, None)
            }
            S::RationalSpline { u_knots, v_knots, homogeneous } => {
                let (nu, nv) = (homogeneous.len(), homogeneous.first().map_or(0, Vec::len));
                let all: Vec<[f64; 4]> = homogeneous.iter().flatten().copied().collect();
                let flat: Vec<[f64; 3]> = all.iter().map(|h| [h[0] / h[3], h[1] / h[3], h[2] / h[3]]).collect();
                let weights: Vec<f64> = all.iter().map(|h| h[3]).collect();
                let degree = [u_knots.len().checked_sub(nu + 1).ok_or(Error::Argument)?, v_knots.len().checked_sub(nv + 1).ok_or(Error::Argument)?];
                Surface::nurbs(degree, nu, nv, u_knots, v_knots, &flat, Some(&weights))
            }
            // A ball patch's label has no (u, v): its face's NURBS form is the surface.
            S::PlacedRevolution { .. } | S::BallPatch { .. } => Err(Error::Unsupported),
        }
    }

    /// The UV domain the intersection runs within, as `[u0, u1, v0, v1]`.
    pub fn domain(&self) -> Result<[f64; 4]> {
        self.core().map(crate::core::ssi::domain)
    }

    /// The surface's point at (u, v).
    pub fn evaluate(&self, u: f64, v: f64) -> Result<[f64; 3]> {
        crate::core::ssi::evaluate(self.core()?, u, v)
    }
}

/// Which of SMLib's intersectors runs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Method {
    /// `SmSurface::GlobalSurfaceIntersect`: analytic special cases, else [`Method::Advanced`].
    Global,
    /// `SmAdvSurfaceIntersector`, the general NURBS path.
    Advanced,
}

/// A curve's type, SMLib's `SmTsectCurveType`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CurveType {
    /// The method reported no type.
    None,
    Unknown,
    /// Degenerate: one point where the surfaces touch.
    Touching,
    /// Transversal.
    Crossing,
    /// The surfaces are tangent along it.
    Tangent,
    /// Where the surfaces butt up against each other.
    Coincident,
    /// A small angle of intersection.
    NearTangent,
    /// Bounds a region where the surfaces coincide.
    RegionBoundary,
}

/// One intersection curve as SMLib returned it: its 3D curve and, where the method returned
/// them, its curves in each surface's UV, each the (rational) B-spline SMLib holds (its lines,
/// circles and ellipses are B-splines too; an intersection curve one SMLib fitted within the
/// approximation tolerance).
#[derive(Clone, Debug)]
pub struct SsiCurve {
    pub curve_type: CurveType,
    /// SMLib's deviation estimate (NaN: none).
    pub deviation: f64,
    /// The 3D curve's natural parameter interval.
    pub interval: [f64; 2],
    pub curve: b::Curve,
    /// On surface a, in a's UV.
    pub uv_a: Option<b::Curve2>,
    /// On surface b, in b's UV.
    pub uv_b: Option<b::Curve2>,
}

/// An isolated point: where a [`CurveType::Touching`] curve starts.
#[derive(Clone, Copy, Debug)]
pub struct SsiPoint {
    pub xyz: [f64; 3],
    pub uv_a: [f64; 2],
    pub uv_b: [f64; 2],
}

/// What an intersection found.
#[derive(Clone, Debug, Default)]
pub struct SsiResult {
    pub curves: Vec<SsiCurve>,
    pub points: Vec<SsiPoint>,
}

/// A (rational) B-spline's coordinates, weights and knots, as the capi hands an intersection curve
/// out: `points` 3 (or 2, in UV) reals each.
pub(crate) struct Nurbs {
    pub points: Vec<f64>,
    pub weights: Vec<f64>,
    pub knots: Vec<f64>,
}

/// The 3D B-spline: polynomial where every weight is 1.
pub(crate) fn curve3(c: Nurbs) -> b::Curve {
    let points = c.points.as_chunks::<3>().0;
    if c.weights.iter().all(|w| *w == 1.0) {
        b::Curve::Spline { knots: c.knots, points: points.to_vec() }
    } else {
        b::Curve::RationalSpline {
            knots: c.knots,
            homogeneous: points.iter().zip(&c.weights).map(|(p, w)| [p[0] * w, p[1] * w, p[2] * w, *w]).collect(),
        }
    }
}

/// A UV B-spline, as [`curve3`].
pub(crate) fn curve2(c: Nurbs) -> b::Curve2 {
    let points = c.points.as_chunks::<2>().0;
    if c.weights.iter().all(|w| *w == 1.0) {
        b::Curve2::Spline { knots: c.knots, points: points.to_vec() }
    } else {
        b::Curve2::RationalSpline { knots: c.knots, homogeneous: points.iter().zip(&c.weights).map(|(p, w)| [p[0] * w, p[1] * w, *w]).collect() }
    }
}

/// Intersects `a` and `b` within their domains with `method` at approximation tolerance
/// `approx_tol` (<= 0: SMLib's default, 1/1000 of the surfaces' size). An intersector failure is
/// SMLib's status; a curve SMLib does not hold as a B-spline is [`Error::Unsupported`].
pub fn intersect(a: &Surface, b: &Surface, method: Method, approx_tol: f64) -> Result<SsiResult> {
    crate::core::ssi::intersect(a.core()?, b.core()?, method, approx_tol)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Refused here, before solidcore sees the surface.
    #[test]
    fn bad_input_is_an_argument_error() {
        let (x, y) = ([1.0, 0.0, 0.0], [0.0, 1.0, 0.0]);
        let refused = [
            Surface::plane([0.0; 3], x, x, [0.0, 1.0], [0.0, 1.0]),
            Surface::plane([0.0; 3], x, y, [1.0, 0.0], [0.0, 1.0]),
            Surface::plane([f64::NAN; 3], x, y, [0.0, 1.0], [0.0, 1.0]),
            Surface::cylinder([0.0; 3], x, y, 0.0, [0.0, 360.0], [0.0, 1.0]),
            Surface::cone([0.0; 3], x, y, f64::NAN, [0.0, 1.0]),
            Surface::sphere([0.0; 3], x, y, 1.0, [0.0, 360.0], [-91.0, 90.0]),
            Surface::torus([0.0; 3], x, y, 1.0, 2.0, [0.0, 360.0], [0.0, 360.0]),
            Surface::nurbs([1, 1], 2, 2, &[0.0, 0.0, 1.0, 1.0], &[0.0, 0.0, 1.0, 1.0], &[[0.0; 3]; 3], None),
            Surface::nurbs([1, 1], 2, 2, &[0.0, 0.0, 1.0], &[0.0, 0.0, 1.0, 1.0], &[[0.0; 3]; 4], None),
            Surface::nurbs([1, 1], 2, 2, &[0.0, 0.0, 1.0, 1.0], &[0.0, 0.0, 1.0, 1.0], &[[0.0; 3]; 4], Some(&[0.0; 4])),
            Surface::nurbs([0, 1], 2, 2, &[0.0, 0.0, 1.0], &[0.0, 0.0, 1.0, 1.0], &[[0.0; 3]; 4], None),
        ];
        for (i, r) in refused.iter().enumerate() {
            assert_eq!(r.as_ref().err(), Some(&Error::Argument), "{i}");
        }
    }

    /// A plane's domain and points are its own parameters; a plane through a sphere's centre meets
    /// it in one great circle, by either method.
    #[test]
    fn a_plane_through_a_spheres_centre_is_a_great_circle() {
        let (x, y, z) = ([1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]);
        let plane = Surface::plane([0.0; 3], x, y, [-2.0, 2.0], [-3.0, 3.0]).unwrap();
        assert_eq!(plane.domain().unwrap(), [-2.0, 2.0, -3.0, 3.0]);
        assert_eq!(plane.evaluate(1.0, -2.0).unwrap(), [1.0, -2.0, 0.0]);
        assert_eq!(plane.evaluate(f64::NAN, 0.0).unwrap_err(), Error::Argument);
        let sphere = Surface::sphere([0.0; 3], x, z, 1.0, [0.0, 360.0], [-90.0, 90.0]).unwrap();
        for method in [Method::Global, Method::Advanced] {
            let r = intersect(&plane, &sphere, method, 1e-6).unwrap();
            assert!(!r.curves.is_empty(), "{method:?}");
            for c in &r.curves {
                let eval = solidcraft_geom::brep::eval::CurveEval::new(&c.curve).unwrap();
                let [t0, t1] = c.interval;
                for k in 0..=100 {
                    let p = eval.point(t0 + (t1 - t0) * f64::from(k) / 100.0).unwrap();
                    assert!((p.x.hypot(p.y) - 1.0).abs() < 1e-5 && p.z.abs() < 1e-5, "{method:?}: {p:?}");
                }
            }
        }
    }
}