SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Surface records ([`brep::Surface`]) in the evaluator's form ([`EvalSurface`]), which the
//! planner and the CPU and GPU evaluators share, and the map from the record's (u, v) to the
//! evaluator's, so a face's boundary takes its parameters from its edges' exact pcurves.
//! Planes, splines and revolutions keep their own parameters ([`SurfaceEval`] holds them in
//! that form already). A cylinder, cone, sphere or torus is the revolution it is, exactly: its
//! generator (a line, or a circle as an exact rational arc) turned about its axis by the
//! record's angle u; the generator's parameter is −v on a line and, on an arc, the rational
//! parameter of the record's angle v (closed form, [`Arc::param`]).
use solidcore_record::Vec3;
use solidcore_record::brep::{self, Frame};
use solidcraft_geom::brep::eval::SurfaceEval;
use solidcraft_geom::prelude::*;
use solidcraft_geom::tess::{EvalCurve, EvalSurface};
use crate::{KernelError, Result};
fn v3(p: [f64; 3]) -> Vec3 {
Vec3::new(p[0], p[1], p[2])
}
/// No transform: the revolution as it is.
const IDENTITY: [[f64; 4]; 3] = [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0]];
/// How a face's record parameters become its evaluator's.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) enum Params {
/// The same parameters (planes, splines, revolutions).
Same,
/// A cylinder or cone: (angle, height) to (−height, angle).
Height,
/// A sphere or torus: (angle, meridian angle) to (the reversed arc's parameter, angle).
Meridian(Arc),
}
impl Params {
/// The evaluator's parameters of the record's `uv`.
pub(crate) fn to_eval(self, uv: [f64; 2]) -> [f64; 2] {
let [u, v] = uv;
match self {
Params::Same => uv,
Params::Height => [-v, u],
Params::Meridian(a) => [1.0 - a.param(v), u],
}
}
}
/// The spans of a circular arc made by [`arc`]: from angle `start`, `count` spans of `step`
/// each, over the parameter [0, 1]; `periodic` for a whole turn.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct Arc {
start: f64,
step: f64,
count: usize,
periodic: bool,
}
impl Arc {
/// The arc's parameter at `angle`. On a rational quadratic span of half angle α with middle
/// weight cos α, tan(θ / 2) runs linearly from −tan(α / 2) to tan(α / 2) with the span's
/// own parameter (θ from the span's middle). A whole turn continues by whole parameters.
pub(crate) fn param(&self, angle: f64) -> f64 {
let total = self.step * self.count as f64;
let turns = if self.periodic { ((angle - self.start) / total).floor() } else { 0.0 };
let a = angle - turns * total;
let i = (((a - self.start) / self.step).floor().max(0.0) as usize).min(self.count.saturating_sub(1));
let half = 0.5 * self.step;
let local = a - (self.start + (i as f64 + 0.5) * self.step);
let s = 0.5 * ((0.5 * local).tan() / (0.5 * half).tan() + 1.0);
(i as f64 + s) / self.count as f64 + turns
}
}
/// `surface` in the evaluator's form, and how the record's parameters map onto it. `domain` is
/// the face's parameter box in the record's parameters, `[[u0, u1], [v0, v1]]`: a cylinder's
/// or cone's generator spans the face's heights.
pub(crate) fn eval_surface(surface: &brep::Surface, domain: [[f64; 2]; 2]) -> Result<(EvalSurface, Params)> {
use std::f64::consts::{FRAC_PI_2, TAU};
let invalid = |what: &str| KernelError::Invalid(format!("tessellation: {what}"));
let axes = |f: &Frame| {
let (o, x, y) = (v3(f.origin), v3(f.x_axis), v3(f.y_axis));
(o, x, x.cross(y))
};
let revolved = |profile: EvalCurve, origin: Vec3, axis: Vec3| -> Result<EvalSurface> {
let axis = axis.normalized().ok_or_else(|| invalid("an analytic surface's frame"))?;
Ok(EvalSurface::Revolved { profile, origin, axis, transform: IDENTITY, swap: false })
};
// The generator of a cylinder or cone over the face's heights, run from the top down so the
// revolution's (generator, angle) normal is the record's natural normal (outward).
let generator = |at: &dyn Fn(f64) -> Vec3| -> Result<EvalCurve> {
let [h0, h1] = domain[1];
if !(h0.is_finite() && h1.is_finite() && h1 > h0) {
return Err(invalid("a cylinder or cone face with no height"));
}
let (a, b) = (at(h1), at(h0));
// Parameter −v: the generator at t is the surface at height −t.
Ok(EvalCurve { degree: 1, knots: vec![-h1, -h1, -h0, -h0], ctrl: vec![[a.x, a.y, a.z, 1.0], [b.x, b.y, b.z, 1.0]] })
};
// A meridian from the record's least angle to its greatest, reversed (so the normal is the
// record's natural one, outward), its angle measured from `x` toward `y` in the plane of `x`
// and the axis `z`.
let meridian = |centre: Vec3, [x, y]: [Vec3; 2], z: Vec3, r: f64, angle: [f64; 2], o: Vec3| -> Result<(EvalSurface, Params)> {
let (curve, spans) = arc(centre, x, y, r, angle);
Ok((revolved(curve.reversed(), o, z)?, Params::Meridian(spans)))
};
match surface {
brep::Surface::Cylinder { frame, radius } => {
let (o, x, z) = axes(frame);
Ok((revolved(generator(&|h| o + x * *radius + z * h)?, o, z)?, Params::Height))
}
brep::Surface::Cone { frame, radius_at_origin, half_angle } => {
let (o, x, z) = axes(frame);
let slope = half_angle.tan();
Ok((revolved(generator(&|h| o + x * (radius_at_origin + h * slope) + z * h)?, o, z)?, Params::Height))
}
brep::Surface::Sphere { frame, radius } => {
let (o, x, z) = axes(frame);
meridian(o, [x, z], z, *radius, [-FRAC_PI_2, FRAC_PI_2], o)
}
brep::Surface::Torus { frame, major_radius, minor_radius, tube_start } => {
let (o, x, z) = axes(frame);
// The tube angle counts from its start.
let (s, c) = tube_start.sin_cos();
meridian(o + x * *major_radius, [x * c + z * s, z * c - x * s], z, *minor_radius, [0.0, TAU], o)
}
_ => match SurfaceEval::new(surface) {
Ok(SurfaceEval::Eval(e, _)) => Ok((e, Params::Same)),
Ok(_) => Err(invalid("an analytic surface out of place")),
Err(e) => Err(KernelError::Failed(format!("not supported yet: tessellation: {e}"))),
},
}
}
/// The circle `centre + r (cos t x + sin t y)` for t in `angle`, as an exact rational quadratic
/// spline over [0, 1], one span per quarter turn or less, and its spans.
fn arc(centre: Vec3, x: Vec3, y: Vec3, r: f64, angle: [f64; 2]) -> (EvalCurve, Arc) {
let span = angle[1] - angle[0];
let count = (span / std::f64::consts::FRAC_PI_2).ceil().clamp(1.0, 4.0) as usize;
let step = span / count as f64;
let weight = (step / 2.0).cos();
// A point at angle `t`, its radius divided by `scale` (the middle control point of a span
// lies 1 / cos(step / 2) out), as homogeneous coordinates of weight `w`.
let at = |t: f64, scale: f64, w: f64| {
let p = centre + x * (r * t.cos() / scale) + y * (r * t.sin() / scale);
[p.x * w, p.y * w, p.z * w, w]
};
let mut ctrl = vec![at(angle[0], 1.0, 1.0)];
let mut knots = vec![0.0; 3];
for i in 0..count {
let start = angle[0] + i as f64 * step;
ctrl.push(at(start + step / 2.0, weight, weight));
ctrl.push(at(start + step, 1.0, 1.0));
knots.extend(std::iter::repeat_n((i + 1) as f64 / count as f64, if i + 1 == count { 3 } else { 2 }));
}
let periodic = (span - std::f64::consts::TAU).abs() < 1e-12;
(EvalCurve { degree: 2, knots, ctrl }, Arc { start: angle[0], step, count, periodic })
}
/// A curve on [0, 1] run the other way: t becomes 1 − t.
trait Reversed {
fn reversed(self) -> Self;
}
impl Reversed for EvalCurve {
fn reversed(mut self) -> Self {
self.ctrl.reverse();
self.knots = self.knots.iter().rev().map(|k| 1.0 - k).collect();
self
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Every face of `b` evaluates, through [`eval_surface`] and its [`Params`], as the record's
/// own evaluator ([`SurfaceEval`]) evaluates it, over the face's parameter box: the same
/// point and the same natural normal. Counts of planes, analytic surfaces and others.
fn assert_matches_the_record(b: &brep::Brep) -> [usize; 3] {
let mut kinds = [0; 3];
for face in &b.faces {
let kind = match face.surface {
brep::Surface::Plane { .. } | brep::Surface::PlaneThrough { .. } => 0,
brep::Surface::Cylinder { .. } | brep::Surface::Cone { .. } | brep::Surface::Sphere { .. } | brep::Surface::Torus { .. } => 1,
_ => 2,
};
let (eval, map) = match eval_surface(face.parameters(), face.domain) {
Ok(e) => e,
Err(e) => panic!("not evaluable: {e} ({:?})", face.surface),
};
let Ok(reference) = SurfaceEval::new(face.parameters()) else { panic!("the record's evaluator: {:?}", face.surface) };
let [[u0, u1], [v0, v1]] = face.domain;
for i in 0..=6 {
for j in 0..=6 {
let uv = [u0 + (u1 - u0) * i as f64 / 6.0, v0 + (v1 - v0) * j as f64 / 6.0];
let q = map.to_eval(uv);
let (p, n) = eval.eval(q[0], q[1]);
let Some((want, su, sv)) = reference.derivs(uv[0], uv[1]) else { panic!("reference at {uv:?}") };
assert!(p.dist(want) < 1e-9 * (1.0 + want.len()), "point at {uv:?}: {p:?} vs {want:?}");
if let Some(wn) = su.cross(sv).normalized().filter(|_| su.cross(sv).len() > 1e-9 * (su.len() * sv.len()).max(1e-12)) {
assert!(n.dist(wn) < 1e-6, "normal at {uv:?}: {n:?} vs {wn:?} ({:?})", face.surface);
}
kinds[kind] += 1;
}
}
}
kinds
}
fn record(b: crate::Result<crate::Body>) -> brep::Brep {
match b.and_then(|b| crate::brep_record(&b)) {
Ok(r) => r,
Err(e) => panic!("{e}"),
}
}
#[test]
fn primitives_evaluate_like_the_record() {
let bodies = [
crate::box_solid(Vec3::new(-1.0, -2.0, 0.0), Vec3::new(3.0, 4.0, 5.0)),
crate::cylinder(Vec3::new(1.0, 2.0, 3.0), Vec3::new(0.0, 1.0, 1.0), 2.5, 7.0),
crate::sphere(Vec3::new(0.0, 0.0, 1.0), 4.0),
crate::torus(Vec3::ZERO, 6.0, 1.5),
];
let mut kinds = [0; 3];
for b in bodies {
for (k, n) in kinds.iter_mut().zip(assert_matches_the_record(&record(b))) {
*k += n;
}
}
// Planes and the analytic surfaces (cylinder, sphere, torus) all covered.
assert!(kinds[0] > 0 && kinds[1] > 0, "{kinds:?}");
}
#[test]
fn transformed_and_mirrored_bodies_evaluate_like_the_record() {
let Ok(cyl) = crate::cylinder(Vec3::ZERO, Vec3::Z, 2.0, 5.0) else { panic!("cylinder") };
// Column-major: x → 3 − x, z → z + 1.
let mirror = [[-1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [3.0, 0.0, 1.0, 1.0]];
assert!(assert_matches_the_record(&record(crate::transform_matrix(&cyl, mirror))).iter().sum::<usize>() > 0);
}
}