Skip to content

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

15.8 KB
Raw Blame
//! Exact mass properties from SMLib: area, volume, centroid and inertia, integrated on the exact
//! surfaces rather than a tessellation; the exact box; how far an edge lies from a face's surface;
//! where a point lies against a body.

use crate::{Brep, Result, core};

/// The accuracy [`Brep::mass_properties`] and [`Brep::area`] use unless told otherwise: the
/// finest SMLib allows. Analytic primitives then come out within 2e-7 of their closed forms.
pub const MEASURE_ACCURACY: f64 = 1e-8;

/// Mass properties of a body at unit density (mm, mm², mm³, mm⁵). For a density ρ the
/// mass is ρ·`volume` and the inertia scales by ρ.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MassProperties {
    pub area: f64,
    pub volume: f64,
    pub centroid: [f64; 3],
    /// Ixx, Iyy, Izz about axes through the centroid parallel to the world axes:
    /// ∫(y²+z²), ∫(z²+x²), ∫(x²+y²) dV.
    pub moments: [f64; 3],
    /// Iyz, Izx, Ixy about the centroid: ∫yz, ∫zx, ∫xy dV relative to it.
    pub products: [f64; 3],
}

impl MassProperties {
    /// The inertia tensor about the centroid (row-major), whose off-diagonal terms are the
    /// negated products.
    pub fn inertia_tensor(&self) -> [[f64; 3]; 3] {
        let [ixx, iyy, izz] = self.moments;
        let [iyz, izx, ixy] = self.products;
        [[ixx, -ixy, -izx], [-ixy, iyy, -iyz], [-izx, -iyz, izz]]
    }
}

/// Where a point lies against a body ([`Brep::classify_point`]).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum PointClass {
    /// In a void region: outside the material, or in a cavity.
    Outside,
    /// In a material region.
    Inside,
    /// Within the body's tolerance of a face, an edge or a vertex.
    OnBoundary,
}

impl Brep {
    /// Where `p` (mm) lies against this body, decided exactly on its curves and surfaces (no
    /// tessellation) by SMLib's `SmBrep::Point3DClassify` at the body's own zone tolerance: on
    /// the boundary when within that tolerance of a face, an edge or a vertex (sheet faces too),
    /// else inside a material region or outside. A body with no material (a sheet, an open shell)
    /// has no inside. A non-finite coordinate is [`Error::Argument`](crate::Error::Argument).
    pub fn classify_point(&self, p: [f64; 3]) -> Result<PointClass> {
        core::classify_point(self.core(), p)
    }

    /// Mass properties at `relative_accuracy` (clamped to [1e-8, 1e-1]; [`MEASURE_ACCURACY`] is
    /// the finest): the sum over the body's material regions, so several lumps, or lumps
    /// touching along edges or at points, measure too. A body with no material (a sheet, an open
    /// shell) has volume 0 and no inertia, its faces' area and the centroid of that area.
    pub fn mass_properties(&self, relative_accuracy: f64) -> Result<MassProperties> {
        core::mass_properties(self.core(), relative_accuracy)
    }

    /// The exact axis-aligned box, least corner then greatest: the extrema of every vertex, edge
    /// and face on its exact curve or surface, not grown by tolerances or control hulls.
    pub fn bounds(&self) -> Result<([f64; 3], [f64; 3])> {
        core::bounds(self.core())
    }

    /// How far edge `edge` (its curve over its interval) lies from the surface of face `face`,
    /// over that surface's own domain and not beyond it, in mm: SMLib's own edge/face gap, the
    /// one it sizes an edge's tolerance by. Indices are in the body's edge and face order (as
    /// it was imported and is exported). An edge run past its face's patch measures how far it
    /// goes; SMLib keeps such an edge whole when making its UV trim only when its zone tolerance
    /// (half the flat arrays' `EDGE_TOLERANCE`) covers this.
    pub fn edge_face_distance(&self, edge: usize, face: usize) -> Result<f64> {
        core::edge_face_distance(self.core(), edge, face)
    }

    /// Total area of every face, each counted once, so sheets and open shells too.
    pub fn area(&self, relative_accuracy: f64) -> Result<f64> {
        core::area(self.core(), relative_accuracy)
    }
}

/// The closed forms of the primitives' measures, for the tests.
#[cfg(test)]
pub(crate) mod closed {
    use std::f64::consts::PI;

    /// Area, volume, centroid, Ixx, Iyy, Izz about it (products are 0 for all), and the exact box.
    pub(crate) struct Closed {
        pub area: f64,
        pub volume: f64,
        pub centroid: [f64; 3],
        pub moments: [f64; 3],
        pub bounds: ([f64; 3], [f64; 3]),
    }

    /// An axis-aligned box from its lower corner.
    pub(crate) fn cuboid(o: [f64; 3], size: [f64; 3]) -> Closed {
        let [a, b, c] = size;
        let v = a * b * c;
        Closed {
            area: 2.0 * (a * b + b * c + c * a),
            volume: v,
            centroid: [o[0] + a / 2.0, o[1] + b / 2.0, o[2] + c / 2.0],
            moments: [v * (b * b + c * c) / 12.0, v * (a * a + c * c) / 12.0, v * (a * a + b * b) / 12.0],
            bounds: (o, [o[0] + a, o[1] + b, o[2] + c]),
        }
    }

    /// A cylinder about +Z on its base centre.
    pub(crate) fn cylinder(o: [f64; 3], r: f64, h: f64) -> Closed {
        let v = PI * r * r * h;
        let ixx = v * (3.0 * r * r + h * h) / 12.0;
        Closed {
            area: 2.0 * PI * r * r + 2.0 * PI * r * h,
            volume: v,
            centroid: [o[0], o[1], o[2] + h / 2.0],
            moments: [ixx, ixx, v * r * r / 2.0],
            bounds: ([o[0] - r, o[1] - r, o[2]], [o[0] + r, o[1] + r, o[2] + h]),
        }
    }

    pub(crate) fn sphere(o: [f64; 3], r: f64) -> Closed {
        let v = 4.0 / 3.0 * PI * r * r * r;
        let i = 0.4 * v * r * r;
        Closed {
            area: 4.0 * PI * r * r,
            volume: v,
            centroid: o,
            moments: [i; 3],
            bounds: ([o[0] - r, o[1] - r, o[2] - r], [o[0] + r, o[1] + r, o[2] + r]),
        }
    }

    /// A frustum (a cone when `rt` is 0) about +Z on its base centre. Its volume integrals are
    /// polynomials in z of degree at most 4, so three-point Gauss-Legendre gives them exactly.
    pub(crate) fn cone(o: [f64; 3], rb: f64, rt: f64, h: f64) -> Closed {
        let (x, w) = ([-(0.6f64).sqrt(), 0.0, (0.6f64).sqrt()], [5.0 / 9.0, 8.0 / 9.0, 5.0 / 9.0]);
        let (mut v, mut mz, mut zz, mut izz) = (0.0, 0.0, 0.0, 0.0);
        for (xi, wi) in x.iter().zip(w) {
            let (z, wi) = (h / 2.0 * (1.0 + xi), wi * h / 2.0);
            let rho = rb + (rt - rb) * z / h;
            let disc = PI * rho * rho;
            v += wi * disc;
            mz += wi * disc * z;
            zz += wi * disc * z * z;
            izz += wi * disc * rho * rho / 2.0;
        }
        let zc = mz / v;
        let ixx = izz / 2.0 + zz - v * zc * zc;
        let s = ((rb - rt).powi(2) + h * h).sqrt();
        let m = rb.max(rt);
        Closed {
            area: PI * (rb * rb + rt * rt + (rb + rt) * s),
            volume: v,
            centroid: [o[0], o[1], o[2] + zc],
            moments: [ixx, ixx, izz],
            bounds: ([o[0] - m, o[1] - m, o[2]], [o[0] + m, o[1] + m, o[2] + h]),
        }
    }

    /// A ring torus about +Z (Pappus for area and volume).
    pub(crate) fn torus(o: [f64; 3], big: f64, r: f64) -> Closed {
        let v = 2.0 * PI * PI * big * r * r;
        let ixx = v * (big * big / 2.0 + 5.0 * r * r / 8.0);
        let m = big + r;
        Closed {
            area: 4.0 * PI * PI * big * r,
            volume: v,
            centroid: o,
            moments: [ixx, ixx, v * (big * big + 0.75 * r * r)],
            bounds: ([o[0] - m, o[1] - m, o[2] - r], [o[0] + m, o[1] + m, o[2] + r]),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Error;
    fn rel(a: f64, b: f64) -> f64 {
        if b == 0.0 { a.abs() } else { (a / b - 1.0).abs() }
    }

    /// tests/oracle/01-box: the analytic values its expected.json gives, plus the box's inertia.
    #[test]
    fn the_oracle_box_measures_exactly() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/oracle/01-box/expected.json");
        let expected: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(dir).unwrap()).unwrap();
        assert_eq!(expected["source"], "analytic");
        let max = &expected["bbox"]["max"];
        let size = [0, 1, 2].map(|i| max[i].as_f64().unwrap());
        let b = Brep::make_box([0.0; 3], size).unwrap();
        let m = b.mass_properties(MEASURE_ACCURACY).unwrap();
        assert!(rel(m.volume, expected["volume_mm3"].as_f64().unwrap()) < 1e-12, "{m:?}");
        assert!(rel(m.area, expected["area_mm2"].as_f64().unwrap()) < 1e-12, "{m:?}");
        assert!(rel(b.area(MEASURE_ACCURACY).unwrap(), expected["area_mm2"].as_f64().unwrap()) < 1e-12);
        for i in 0..3 {
            assert!((m.centroid[i] - expected["center_of_mass"][i].as_f64().unwrap()).abs() < 1e-9, "{m:?}");
        }
        let [a, bb, c] = size;
        let v = a * bb * c;
        let want = [v * (bb * bb + c * c) / 12.0, v * (a * a + c * c) / 12.0, v * (a * a + bb * bb) / 12.0];
        for i in 0..3 {
            assert!(rel(m.moments[i], want[i]) < 1e-12, "{m:?}");
            assert!(m.products[i].abs() < 1e-9 * want[2], "{m:?}");
        }
    }

    /// Far from the origin the inertia is still taken about the centroid, without cancellation.
    #[test]
    fn a_box_far_from_the_origin_keeps_its_inertia() {
        let b = Brep::make_box([1.0e5, -2.0e5, 3.0e4], [3.0, 50.0, 0.5]).unwrap();
        let m = b.mass_properties(MEASURE_ACCURACY).unwrap();
        let v = 75.0;
        assert!(rel(m.volume, v) < 1e-12);
        assert!(rel(m.centroid[0], 1.0e5 + 1.5) < 1e-14 && rel(m.centroid[1], -2.0e5 + 25.0) < 1e-14);
        assert!(rel(m.moments[0], v * (2500.0 + 0.25) / 12.0) < 1e-9, "{m:?}");
        assert!(rel(m.moments[1], v * (9.0 + 0.25) / 12.0) < 1e-9, "{m:?}");
        assert!(rel(m.moments[2], v * (9.0 + 2500.0) / 12.0) < 1e-9, "{m:?}");
        let t = m.inertia_tensor();
        assert_eq!(t[0][1], t[1][0]);
        assert!(t[0][1].abs() < 1e-9 * m.moments[2]);
    }

    /// Reads `tests/oracle/<case>/expected.json`.
    #[allow(clippy::unwrap_used)] // test fixture
    fn oracle(case: &str) -> serde_json::Value {
        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/oracle").join(case).join("expected.json");
        let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap();
        assert_eq!(v["source"], "analytic", "{case}");
        v
    }

    use closed::Closed;

    /// A primitive with its closed forms.
    struct Expected {
        name: &'static str,
        body: Brep,
        area: f64,
        volume: f64,
        centroid: [f64; 3],
        moments: [f64; 3],
    }

    #[allow(clippy::unwrap_used)] // test fixture
    fn expected(name: &'static str, body: Result<Brep>, c: Closed) -> Expected {
        Expected { name, body: body.unwrap(), area: c.area, volume: c.volume, centroid: c.centroid, moments: c.moments }
    }

    fn cylinder(name: &'static str, o: [f64; 3], r: f64, h: f64) -> Expected {
        expected(name, Brep::make_cylinder(o, r, h), closed::cylinder(o, r, h))
    }

    fn sphere(name: &'static str, o: [f64; 3], r: f64) -> Expected {
        expected(name, Brep::make_sphere(o, r), closed::sphere(o, r))
    }

    fn cone(name: &'static str, o: [f64; 3], rb: f64, rt: f64, h: f64) -> Expected {
        expected(name, Brep::make_cone(o, rb, rt, h), closed::cone(o, rb, rt, h))
    }

    fn torus(name: &'static str, o: [f64; 3], big: f64, r: f64) -> Expected {
        expected(name, Brep::make_torus(o, big, r), closed::torus(o, big, r))
    }

    /// Every primitive against its closed form, at the origin and 2e5 mm out, to 1e-6 (tests/oracle
    /// accepts 1e-3). Cylinders as oracle 02 and 38 give them, against their expected.json too.
    #[test]
    fn primitives_match_their_closed_forms() {
        for (case, r) in [("02-cylinder", 15.0), ("38-coincident-cylinders", 10.0)] {
            let e = oracle(case);
            let m = Brep::make_cylinder([0.0; 3], r, 50.0).unwrap().mass_properties(MEASURE_ACCURACY).unwrap();
            assert!(rel(m.volume, e["volume_mm3"].as_f64().unwrap()) < 1e-6, "{case}: {m:?}");
            assert!(rel(m.area, e["area_mm2"].as_f64().unwrap()) < 1e-6, "{case}: {m:?}");
            for i in 0..3 {
                assert!((m.centroid[i] - e["center_of_mass"][i].as_f64().unwrap()).abs() < 1e-6, "{case}: {m:?}");
            }
        }
        let far = [1.0e5, -2.0e5, 3.0e4];
        let cases = [
            cylinder("cylinder r15 h50", [0.0; 3], 15.0, 50.0),
            cylinder("cylinder r0.25 h80, far", far, 0.25, 80.0),
            // The primitives of oracle 40-box-sphere-torus, whole.
            sphere("sphere r12", [0.0; 3], 12.0),
            sphere("sphere r7, far", far, 7.0),
            torus("torus R22 r4", [0.0; 3], 22.0, 4.0),
            torus("torus R30 r0.5, far", far, 30.0, 0.5),
            cone("frustum r10..4 h20", [0.0; 3], 10.0, 4.0, 20.0),
            cone("cone r10 h20", [0.0; 3], 10.0, 0.0, 20.0),
            cone("inverted frustum r3..9 h7", [0.0; 3], 3.0, 9.0, 7.0),
            cone("frustum r6..2 h9, far", far, 6.0, 2.0, 9.0),
        ];
        for e in &cases {
            let m = e.body.mass_properties(MEASURE_ACCURACY).unwrap();
            let name = e.name;
            assert!(rel(m.area, e.area) < 1e-6, "{name}: {m:?}");
            assert!(rel(e.body.area(MEASURE_ACCURACY).unwrap(), e.area) < 1e-6, "{name}");
            assert!(rel(m.volume, e.volume) < 1e-6, "{name}: {m:?}");
            // The centroid against the body's size: twice its largest radius of gyration.
            let size = 2.0 * e.moments.iter().fold(0.0f64, |a, &b| a.max(b)).sqrt() / e.volume.sqrt();
            let imax = e.moments.iter().fold(0.0f64, |a, &b| a.max(b));
            for i in 0..3 {
                assert!((m.centroid[i] - e.centroid[i]).abs() < 1e-6 * size, "{name}: {m:?}");
                assert!(rel(m.moments[i], e.moments[i]) < 1e-6, "{name}: {m:?}");
                assert!(m.products[i].abs() < 1e-6 * imax, "{name}: {m:?}");
            }
        }
    }

    /// A 10 × 20 × 30 box: inside, outside, on a face, an edge and a vertex; a cylinder of radius
    /// 5 just off its curved wall, within the tolerance (on it) and beyond (inside or outside).
    #[test]
    fn points_classify_exactly() {
        let b = Brep::make_box([0.0; 3], [10.0, 20.0, 30.0]).unwrap();
        assert_eq!(b.classify_point([5.0, 10.0, 15.0]).unwrap(), PointClass::Inside);
        assert_eq!(b.classify_point([5.0, 10.0, 30.0 + 1e-4]).unwrap(), PointClass::Outside);
        assert_eq!(b.classify_point([5.0, 10.0, 30.0 - 1e-4]).unwrap(), PointClass::Inside);
        assert_eq!(b.classify_point([5.0, 10.0, 30.0]).unwrap(), PointClass::OnBoundary);
        assert_eq!(b.classify_point([10.0, 10.0, 30.0]).unwrap(), PointClass::OnBoundary);
        assert_eq!(b.classify_point([10.0, 20.0, 30.0]).unwrap(), PointClass::OnBoundary);
        assert_eq!(b.classify_point([5.0, 10.0, f64::NAN]).unwrap_err(), Error::Argument);
        let c = Brep::make_cylinder([0.0; 3], 5.0, 10.0).unwrap();
        let at = |r: f64| [r * std::f64::consts::FRAC_1_SQRT_2, r * std::f64::consts::FRAC_1_SQRT_2, 5.0];
        assert_eq!(c.classify_point(at(5.0 + 1e-8)).unwrap(), PointClass::OnBoundary);
        assert_eq!(c.classify_point(at(5.0 - 1e-8)).unwrap(), PointClass::OnBoundary);
        assert_eq!(c.classify_point(at(5.0 + 1e-4)).unwrap(), PointClass::Outside);
        assert_eq!(c.classify_point(at(5.0 - 1e-4)).unwrap(), PointClass::Inside);
    }

    #[test]
    fn bad_accuracies_are_errors() {
        let b = Brep::make_box([0.0; 3], [1.0; 3]).unwrap();
        assert_eq!(b.mass_properties(f64::NAN).unwrap_err(), Error::Argument);
        assert_eq!(b.area(f64::INFINITY).unwrap_err(), Error::Argument);
        // Out of range is clamped, not refused.
        assert!(rel(b.mass_properties(1e-30).unwrap().volume, 1.0) < 1e-12);
        assert!(rel(b.mass_properties(10.0).unwrap().volume, 1.0) < 1e-12);
    }
}