Skip to content

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

8.5 KB
Raw Blame
//! The curvature of a surface's normal section and its first two derivatives by arc length, from
//! the surface's exact partial derivatives ([`Partials`]): what a seam's G2, G3 and G4 compare.
//!
//! At a point `p` with unit normal `n`, the normal section along a unit tangent direction `w` is
//! the curve the plane through `p` spanned by `n` and `w` cuts from the surface. Written as a
//! height over that plane's `w` axis, `h(x) = (r − p) · n` with `x = (r − p) · w`, it starts flat
//! (`h(0) = h′(0) = 0`), and its signed curvature `κ = h″ / (1 + h′²)^(3/2)` has, at `p`,
//!
//! - `κ = h″` (the normal curvature in direction `w`: `n · r″`),
//! - `dκ/ds = h‴` (a curvature that changes along `w`: the G3 quantity),
//! - `d²κ/ds² = h⁗ − 3 h″³` (the G4 quantity).
//!
//! The height's Taylor coefficients come from the surface's: the section is the curve
//! `(u(x), v(x))` on which `(r − p) · w = x` and `(r − p) · t = 0` (`t = w × n`, the cutting
//! plane's normal). Expanding `r` about `p` in its partials and solving those two conditions order
//! by order gives each coefficient of `u` and `v` from the 2 × 2 system of the first partials
//! (the lower orders' terms on the right), and the height's coefficient is the normal part of the
//! same expansion. Nothing is sampled: the answer is exact up to rounding.

use crate::prelude::*;
use crate::tess::partials::{MAX_PARTIAL_ORDER, Partials, orders};
use solidcore_record::Vec3;

/// Taylor coefficients in `x` up to the fourth power (index = power).
type Series<T> = [T; MAX_PARTIAL_ORDER + 1];

/// The normal section's curvature and its first two arc-length derivatives at a point.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SectionJet {
    /// `κ = n · r″`, 1/mm: negative where the surface bends away from `n`.
    pub curvature: f64,
    /// `dκ/ds` along the direction, 1/mm².
    pub curvature_change: f64,
    /// `d²κ/ds²` along the direction, 1/mm³.
    pub curvature_change_rate: f64,
}

impl SectionJet {
    /// The three values in order: curvature, its change, the change's rate.
    pub fn values(&self) -> [f64; 3] {
        [self.curvature, self.curvature_change, self.curvature_change_rate]
    }
}

/// The normal section at the point of `d` (`d[0][0]`) with unit normal `normal`, along the unit
/// tangent `direction`. `None` where the first partials do not span the tangent plane across the
/// section (a pole, a degenerate point) or a value is not finite.
pub fn normal_section(d: &Partials, normal: Vec3, direction: Vec3) -> Option<SectionJet> {
    let cut = direction.cross(normal);
    let (ru, rv) = (d[1][0], d[0][1]);
    // [ru·w  rv·w; ru·t  rv·t] [a; b] = rhs, solved by Cramer's rule.
    let (m11, m12, m21, m22) = (ru.dot(direction), rv.dot(direction), ru.dot(cut), rv.dot(cut));
    let det = m11 * m22 - m12 * m21;
    let scale = ru.len() * rv.len();
    if !(det.abs() > 1e-12 * scale && scale.is_finite()) {
        return None;
    }
    let mut du: Series<f64> = [0.0; MAX_PARTIAL_ORDER + 1];
    let mut dv: Series<f64> = [0.0; MAX_PARTIAL_ORDER + 1];
    let mut height: Series<f64> = [0.0; MAX_PARTIAL_ORDER + 1];
    for k in 1..=MAX_PARTIAL_ORDER {
        // The terms of order two and up, which only reach x^k through the coefficients below k.
        let rest = *nonlinear(d, &du, &dv).get(k)?;
        let target = if k == 1 { 1.0 } else { 0.0 };
        let (r1, r2) = (target - rest.dot(direction), -rest.dot(cut));
        *du.get_mut(k)? = (r1 * m22 - m12 * r2) / det;
        *dv.get_mut(k)? = (m11 * r2 - r1 * m21) / det;
        *height.get_mut(k)? = rest.dot(normal);
    }
    let [_, _, h2, h3, h4] = height;
    let (curvature, change) = (2.0 * h2, 6.0 * h3);
    let rate = 24.0 * h4 - 3.0 * curvature.powi(3);
    let jet = SectionJet { curvature, curvature_change: change, curvature_change_rate: rate };
    jet.values().iter().all(|x| x.is_finite()).then_some(jet)
}

/// `Σ_{2 ≤ i+j ≤ 4} d[i][j] du^i dv^j / (i! j!)`, as a series in `x`.
fn nonlinear(d: &Partials, du: &Series<f64>, dv: &Series<f64>) -> Series<Vec3> {
    let pu = powers(du);
    let pv = powers(dv);
    let mut out: Series<Vec3> = [Vec3::ZERO; MAX_PARTIAL_ORDER + 1];
    for (i, j) in orders().filter(|(i, j)| i + j >= 2) {
        let term = times(&pu[i], &pv[j]);
        let weight = 1.0 / (factorial(i) * factorial(j));
        for (o, t) in out.iter_mut().zip(term) {
            *o += d[i][j] * (t * weight);
        }
    }
    out
}

/// `s^0 … s^4`, truncated to the fourth power of `x`.
fn powers(s: &Series<f64>) -> [Series<f64>; MAX_PARTIAL_ORDER + 1] {
    let mut out = [[0.0; MAX_PARTIAL_ORDER + 1]; MAX_PARTIAL_ORDER + 1];
    out[0][0] = 1.0;
    for k in 1..=MAX_PARTIAL_ORDER {
        out[k] = times(&out[k - 1], s);
    }
    out
}

/// The product of two series, truncated to the fourth power.
fn times(a: &Series<f64>, b: &Series<f64>) -> Series<f64> {
    let mut out = [0.0; MAX_PARTIAL_ORDER + 1];
    for (i, x) in a.iter().enumerate() {
        for (j, y) in b.iter().enumerate().take(MAX_PARTIAL_ORDER + 1 - i) {
            out[i + j] += x * y;
        }
    }
    out
}

fn factorial(n: usize) -> f64 {
    (1..=n).map(|k| k as f64).product()
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    use super::*;
    use crate::brep::eval::SurfaceEval;
    use solidcore_record::brep::{Frame, Surface};

    fn frame() -> Frame {
        Frame { origin: [1., 2., 3.], x_axis: [0., 1., 0.], y_axis: [0., 0., 1.] }
    }

    fn jet(s: &Surface, uv: [f64; 2], along: impl Fn(Vec3, Vec3) -> Vec3) -> SectionJet {
        let e = SurfaceEval::new(s).unwrap();
        let d = e.partials(uv[0], uv[1]).unwrap();
        let n = d[1][0].cross(d[0][1]).normalized().unwrap();
        let w = along(d[1][0].normalized().unwrap(), d[0][1].normalized().unwrap());
        normal_section(&d, n, w).unwrap()
    }

    fn near(a: f64, b: f64) -> bool {
        (a - b).abs() < 1e-9 * (1.0 + b.abs())
    }

    /// A sphere's normal sections are great circles: curvature 1/R (towards the centre, against
    /// the outward normal), constant, in every direction.
    #[test]
    fn a_sphere_is_a_constant_curvature_every_way() {
        let s = Surface::Sphere { frame: frame(), radius: 4.0 };
        for along in [|u: Vec3, _: Vec3| u, |_: Vec3, v: Vec3| v, |u: Vec3, v: Vec3| (u + v).normalized().unwrap_or(u)] {
            let j = jet(&s, [0.7, 0.3], along);
            assert!(near(j.curvature, -0.25) && near(j.curvature_change, 0.0) && near(j.curvature_change_rate, 0.0), "{j:?}");
        }
    }

    /// A cylinder across its axis: a circle (-1/R, constant); along it: a straight line.
    #[test]
    fn a_cylinder_is_a_circle_across_and_a_line_along() {
        let s = Surface::Cylinder { frame: frame(), radius: 5.0 };
        let across = jet(&s, [1.1, 2.0], |u, _| u);
        assert!(near(across.curvature, -0.2) && near(across.curvature_change, 0.0) && near(across.curvature_change_rate, 0.0), "{across:?}");
        let along = jet(&s, [1.1, 2.0], |_, v| v);
        assert!(along.values().iter().all(|x| x.abs() < 1e-12), "{along:?}");
    }

    /// The graph `z = x³/6 + x⁴/12`, an exact quartic Bézier in x and straight in y, has h″ = 0,
    /// h‴ = 1 and h⁗ = 2 at the origin: curvature 0, its change 1 and the change's rate 2 along x.
    #[test]
    fn a_polynomial_graph_reads_its_own_derivatives() {
        let z = |x: f64| x.powi(3) / 6.0 + x.powi(4) / 12.0;
        // Monomial coefficients a0..a4 = [0, 0, 0, 1/6, 1/12]; Bézier b_i = Σ_k C(i,k)/C(4,k) a_k.
        let a = [0.0, 0.0, 0.0, 1.0 / 6.0, 1.0 / 12.0];
        let c = |n: usize, k: usize| crate::bspline::binomial(n, k);
        let b: Vec<f64> = (0..=4).map(|i| (0..=i).map(|k| c(i, k) / c(4, k) * a[k]).sum()).collect();
        let mut points = Vec::new();
        for (i, bi) in b.iter().enumerate() {
            points.push(vec![[i as f64 / 4.0, 0.0, *bi], [i as f64 / 4.0, 1.0, *bi]]);
        }
        let s = Surface::Spline { u_knots: vec![0., 0., 0., 0., 0., 1., 1., 1., 1., 1.], v_knots: vec![0., 0., 1., 1.], points };
        let e = SurfaceEval::new(&s).unwrap();
        assert!(near(e.point([0.5, 0.5]).unwrap().z, z(0.5)));
        let d = e.partials(0.0, 0.5).unwrap();
        let j = normal_section(&d, Vec3::Z, Vec3::X).unwrap();
        assert!(near(j.curvature, 0.0) && near(j.curvature_change, 1.0) && near(j.curvature_change_rate, 2.0), "{j:?}");
    }

    #[test]
    fn a_degenerate_point_has_no_section() {
        let mut d: Partials = [[Vec3::ZERO; 5]; 5];
        d[1][0] = Vec3::X;
        assert!(normal_section(&d, Vec3::Z, Vec3::X).is_none(), "r_v is zero");
    }
}