SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! SMLib's modelling operations: booleans, fillet, chamfer, shell, offset faces and thicken.
//! Each returns a new body
//! and leaves its inputs unchanged.
//!
//! Edges and faces are chosen by points, never by SMLib's internal order: each point selects the
//! edge (face) nearest to it, which must lie within `tolerance` of it and be nearer than any other
//! by more than the body's modelling tolerance ([`Error::NoMatch`], [`Error::Ambiguous`]).
use serde_json::json;
use crate::trace::{self, PickKind};
use crate::{Brep, Error, Result, core};
/// How [`Brep::boolean`] combines two bodies.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BooleanOp {
Union,
/// The first body minus the second.
Subtract,
Intersect,
}
impl BooleanOp {
/// The operation's name in a trace ([`crate::trace`]).
pub fn word(self) -> &'static str {
match self {
BooleanOp::Union => "union",
BooleanOp::Subtract => "subtract",
BooleanOp::Intersect => "intersect",
}
}
}
/// What [`Brep::blend`] makes of each selected edge.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Blend {
/// A circular cross-section at a constant radius ([`Brep::fillet`]).
Round,
/// A curvature-continuous (G2) cross-section between the contact lines of the round of
/// that radius.
Curvature,
/// A circular cross-section of constant width from contact line to contact line: the size
/// is that width.
Chord,
/// An equal-distance chamfer ([`Brep::chamfer`]): the size is the setback along each face.
Chamfer,
}
impl Blend {
/// The section's name in a trace ([`crate::trace`]).
pub fn word(self) -> &'static str {
match self {
Blend::Round => "round",
Blend::Curvature => "curvature",
Blend::Chord => "chord",
Blend::Chamfer => "chamfer",
}
}
}
/// How two constant rounds of one radius turn round a sharp, straight, convex side edge square to
/// both on a plane (the rounds along a boss's base, at its upright edges): the turn of
/// [`Brep::blend_dropping`]'s rounds ([`Blend::Round`] only).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Turn {
/// The rounds run on to where they cross and meet in a mitre, the plane section of the two.
#[default]
Mitre,
/// The rounds end on their sections at the side edge, and the corner's face is that section
/// revolved about the side edge, an exact torus tangent to both rounds. A corner where this
/// is not built is [`Error::TurnRefused`].
Swept,
}
impl Turn {
/// The turn's name in a trace ([`crate::trace`]).
pub fn word(self) -> &'static str {
match self {
Turn::Mitre => "mitre",
Turn::Swept => "swept",
}
}
}
/// The second side of [`Brep::chamfer_sides`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum ChamferSecond {
/// The setback along the other face.
Distance(f64),
/// The angle (radians) the chamfer makes with the first face.
Angle(f64),
}
/// Most bodies [`Brep::union_all`] takes.
pub const MAX_UNION_BREPS: usize = 100_000;
/// Most points one selection may hold.
pub const MAX_POINTS: usize = 4096;
/// One edge round an opened corner's hole ([`Brep::blend_setback_open`]): its index in the
/// sheet's edge order, the face beside it in its face order, and whether that face, run
/// counter-clockwise about its outward normal, runs the edge from its start vertex to its end.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct HoleEdge {
pub edge: usize,
pub face: usize,
pub forward: bool,
}
/// The edges round an opened corner's hole, in order: each starts where the one before it ends.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Hole {
pub edges: Vec<HoleEdge>,
}
impl Brep {
/// `self` and `other` combined by `op`: `None` when the result is empty (disjoint bodies
/// intersected, a body subtracted by one that encloses it). Several separate solids come back
/// as one body, counted by [`Brep::solid_count`]. Tagged operands ([`Brep::tagged`]) give a
/// result whose [`Brep::history`] says where each face and edge came from.
pub fn boolean(&self, other: &Brep, op: BooleanOp) -> Result<Option<Brep>> {
let r = core::boolean::boolean(self.core(), other.core(), op).map(|r| r.map(Brep::made_core));
trace::maybe("boolean", &[self, other], &r, || json!({"op": op.word()}));
r
}
/// The union of `breps` in one call: they are unioned pairwise, level by level, so none takes
/// part in more than about log2(n) unions. The result is as [`Brep::boolean`]'s; operands
/// tagged each with its own number ([`Brep::tagged`]) give a result whose [`Brep::history`]
/// names them. At least one body and at most [`MAX_UNION_BREPS`].
pub fn union_all(breps: &[&Brep]) -> Result<Brep> {
if breps.is_empty() || breps.len() > MAX_UNION_BREPS {
return Err(Error::Argument);
}
let bodies: Vec<&core::Body> = breps.iter().map(|b| b.core()).collect();
let r = core::boolean::union_all(&bodies).map(Brep::made_core);
trace::made("union_all", breps, &r, || json!({}));
r
}
/// `self` and `other`, sheets of planar faces on one plane ([`Brep::planar_faces`]), combined
/// as regions of that plane by `op`: `None` when the result is empty. The result's edges are
/// the inputs' own curves, split where they cross.
pub fn boolean2d(&self, other: &Brep, op: BooleanOp) -> Result<Option<Brep>> {
let r = core::boolean::boolean2d(self.core(), other.core(), op).map(|r| r.map(Brep::made_core));
trace::maybe("boolean2d", &[self, other], &r, || json!({"op": op.word()}));
r
}
/// `self` with each face `tool` meets cut along the intersection, the pieces kept as faces of
/// one body: `None` when the tool meets no face. Tagged operands give the pieces' history
/// (each piece is a split of the face it was cut from).
pub fn imprint(&self, tool: &Brep) -> Result<Option<Brep>> {
let r = core::boolean::imprint(self.core(), tool.core()).map(|r| r.map(Brep::made_core));
trace::maybe("imprint", &[self, tool], &r, || json!({}));
r
}
/// The number of separate solid regions (voids not counted).
pub fn solid_count(&self) -> Result<usize> {
crate::core::solid_count(self.core())
}
/// The edges nearest to `edges` (each within `tolerance`), exactly those, rounded
/// at `radius`.
pub fn fillet(&self, edges: &[[f64; 3]], tolerance: f64, radius: f64) -> Result<Brep> {
let r = self.core_blend(Blend::Round, edges, &[radius], tolerance, &[], &[], core::blend::Corners::Filled);
trace::made("fillet", &[self], &r, || json!({"edges": trace::picks(self, PickKind::Edge, edges, tolerance), "radius": radius}));
r
}
/// The edges nearest to `edges` (each within `tolerance`), exactly those, cut by
/// an equal-distance chamfer `distance` back along each face (measured at each edge's
/// midpoint), with bevelled corners.
pub fn chamfer(&self, edges: &[[f64; 3]], tolerance: f64, distance: f64) -> Result<Brep> {
let r = self.core_blend(Blend::Chamfer, edges, &[distance], tolerance, &[], &[], core::blend::Corners::Filled);
trace::made("chamfer", &[self], &r, || json!({"edges": trace::picks(self, PickKind::Edge, edges, tolerance), "distance": distance}));
r
}
/// The edges nearest to `edges` (each within `tolerance`), exactly those, blended
/// as `kind`, edge i at `sizes[i]`.
pub fn blend(&self, kind: Blend, edges: &[[f64; 3]], sizes: &[f64], tolerance: f64) -> Result<Brep> {
if edges.len() > MAX_POINTS || edges.is_empty() || sizes.len() != edges.len() {
return Err(Error::Argument);
}
let r = self.core_blend(kind, edges, sizes, tolerance, &[], &[], core::blend::Corners::Filled);
trace::made(
"blend",
&[self],
&r,
|| json!({"kind": kind.word(), "edges": trace::picks(self, PickKind::Edge, edges, tolerance), "sizes": sizes}),
);
r
}
/// [`Brep::blend`], with whether each point picked an edge that a larger round, overflowing
/// its faces, removed whole: that edge is gone and not rounded (SMLib rounds the edges whose
/// blends overflow first, then what is left of the others). Two rounds turn at a side edge as
/// `turn` says; [`Turn::Swept`] is for [`Blend::Round`] only ([`Error::Argument`] otherwise).
pub fn blend_dropping(&self, kind: Blend, turn: Turn, edges: &[[f64; 3]], sizes: &[f64], tolerance: f64) -> Result<(Brep, Vec<bool>)> {
if edges.len() > MAX_POINTS || edges.is_empty() || sizes.len() != edges.len() {
return Err(Error::Argument);
}
let r = core::blend::blend_dropping(self.core(), kind, turn, edges, sizes, tolerance).map(|(b, d)| (Brep::made_core(b), d));
trace::call(
"blend_dropping",
&[self],
&r,
|(b, _)| vec![b.id],
|| json!({"kind": kind.word(), "turn": turn.word(), "edges": trace::picks(self, PickKind::Edge, edges, tolerance), "sizes": sizes}),
);
r
}
/// [`Brep::blend`] with corner setbacks: each of `corners` picks the vertex nearest it
/// (within `tolerance`), a corner where every edge is blended, and that corner's patch starts
/// `setbacks[j]` along each of its edges from the vertex (one distance per corner, as SMLib
/// keeps it). A corner SMLib builds no setback on (some edge there not blended, a chamfer) is
/// [`Error::Unsupported`]; a setback as long as an edge there, [`Error::NoRoom`].
pub fn blend_setback(
&self,
kind: Blend,
edges: &[[f64; 3]],
sizes: &[f64],
corners: &[[f64; 3]],
setbacks: &[f64],
tolerance: f64,
) -> Result<Brep> {
if edges.len() > MAX_POINTS
|| edges.is_empty()
|| sizes.len() != edges.len()
|| corners.is_empty()
|| corners.len() > MAX_POINTS
|| setbacks.len() != corners.len()
{
return Err(Error::Argument);
}
let r = self.core_blend(kind, edges, sizes, tolerance, corners, setbacks, core::blend::Corners::Filled);
trace::made("blend_setback", &[self], &r, || {
json!({"kind": kind.word(), "edges": trace::picks(self, PickKind::Edge, edges, tolerance), "sizes": sizes,
"corners": trace::picks(self, PickKind::Vertex, corners, tolerance), "setbacks": setbacks})
});
r
}
/// [`Brep::blend_setback`] with each set-back corner left open: SMLib's patch between the
/// corner's setback sections is removed, so the result is a sheet whose only free edges are
/// the holes', one [`Hole`] per corner in `corners`' order (a vertex picked twice gives its
/// hole twice). A corner whose patch SMLib does not build as a disc of faces of its own is
/// [`Error::Unsupported`].
pub fn blend_setback_open(
&self,
kind: Blend,
edges: &[[f64; 3]],
sizes: &[f64],
corners: &[[f64; 3]],
setbacks: &[f64],
tolerance: f64,
) -> Result<(Brep, Vec<Hole>)> {
if edges.len() > MAX_POINTS
|| edges.is_empty()
|| sizes.len() != edges.len()
|| corners.is_empty()
|| corners.len() > MAX_POINTS
|| setbacks.len() != corners.len()
{
return Err(Error::Argument);
}
let r = core::blend::blend_holes(self.core(), kind, edges, sizes, tolerance, corners, setbacks, core::blend::Corners::Open)
.map(|(b, holes)| (Brep::made_core(b), holes));
trace::call(
"blend_setback_open",
&[self],
&r,
|(b, _)| vec![b.id],
|| {
json!({"kind": kind.word(), "edges": trace::picks(self, PickKind::Edge, edges, tolerance), "sizes": sizes,
"corners": trace::picks(self, PickKind::Vertex, corners, tolerance), "setbacks": setbacks})
},
);
r
}
/// The one edge nearest to `edge` (within `tolerance`) rounded with a radius
/// that varies along it: a clamped B-spline of `degree` (1 to 3) with `knots` and control
/// `radii` over the position along the edge, 0 at its end nearest `start` and 1 at the other
/// (the edge curve's parameter scaled to 0..1).
pub fn fillet_variable(&self, edge: [f64; 3], tolerance: f64, start: [f64; 3], degree: usize, knots: &[f64], radii: &[f64]) -> Result<Brep> {
let r = core::blend::fillet_variable(self.core(), edge, tolerance, start, degree, knots, radii).map(Brep::made_core);
trace::made(
"fillet_variable",
&[self],
&r,
|| json!({"edge": trace::picks(self, PickKind::Edge, &[edge], tolerance), "start": start, "degree": degree, "knots": knots, "radii": radii}),
);
r
}
/// The edges nearest to `edges` (each within `tolerance`), exactly those, cut by
/// a chamfer `distance` back along the face whose outward normal leans most along `first`,
/// and by `second` on the other, with bevelled corners (setbacks measured at each edge's
/// midpoint).
pub fn chamfer_sides(&self, edges: &[[f64; 3]], tolerance: f64, distance: f64, second: ChamferSecond, first: [f64; 3]) -> Result<Brep> {
if edges.is_empty() || edges.len() > MAX_POINTS {
return Err(Error::Argument);
}
let r = core::blend::chamfer_sides(self.core(), edges, tolerance, distance, second, first).map(Brep::made_core);
trace::made("chamfer_sides", &[self], &r, || {
let second = match second {
ChamferSecond::Distance(d) => json!({"distance": d}),
ChamferSecond::Angle(a) => json!({"angle": a}),
};
json!({"edges": trace::picks(self, PickKind::Edge, edges, tolerance), "distance": distance, "second": second, "first": first})
});
r
}
/// Hollowed to a wall of `thickness` (negative: inside the original surface, positive:
/// outside), open at the faces nearest to `open_faces` (each within `tolerance`); none gives
/// a closed hollow body. An inward wall that leaves no room inside is [`Error::NoRoom`]; one
/// whose walls would just meet (a hole exactly twice the wall from a side) is
/// [`Error::WallsTouch`].
pub fn shell(&self, open_faces: &[[f64; 3]], tolerance: f64, thickness: f64) -> Result<Brep> {
let r = core::offset::shell(self.core(), open_faces, tolerance, thickness).map(Brep::made_core);
trace::made(
"shell",
&[self],
&r,
|| json!({"open_faces": trace::picks(self, PickKind::Face, open_faces, tolerance), "thickness": thickness}),
);
r
}
/// The solid with the faces nearest to `faces` (each within `tolerance`) moved `distance`
/// along their outward normals (negative: into the body), onto their surfaces' offsets, the
/// faces around them extended or trimmed to meet them. Faces moved in past all of the body
/// behind them are [`Error::NoRoom`].
pub fn offset_faces(&self, faces: &[[f64; 3]], tolerance: f64, distance: f64) -> Result<Brep> {
let r = core::offset::offset_faces(self.core(), faces, tolerance, distance).map(Brep::made_core);
trace::made("offset_faces", &[self], &r, || json!({"faces": trace::picks(self, PickKind::Face, faces, tolerance), "distance": distance}));
r
}
/// A sheet thickened into a solid by `thickness` along its surfaces' normals (negative:
/// against them), or by half each way when `symmetric`, with ruled walls along its open
/// edges. A closed solid is [`Error::Argument`].
pub fn thicken(&self, thickness: f64, symmetric: bool) -> Result<Brep> {
let r = core::offset::thicken(self.core(), thickness, symmetric).map(Brep::made_core);
trace::made("thicken", &[self], &r, || json!({"thickness": thickness, "symmetric": symmetric}));
r
}
/// This body with its topological edges and vertices removed (SMLib's
/// `SmBrep::RemoveTopologicalEdgesAndVertices`): faces on one surface meeting along an edge
/// become one, and two edges on one curve meeting at a vertex nothing else uses become one.
/// The edges nearest to `keep` (each within `tolerance`) stay. The shape is unchanged, and
/// SMLib's history tags follow the merge.
pub fn merge_faces(&self, keep: &[[f64; 3]], tolerance: f64) -> Result<Brep> {
if keep.len() > MAX_POINTS {
return Err(Error::Argument);
}
let r = core::merge::merge_faces(self.core(), keep, tolerance).map(Brep::made_core);
trace::made("merge_faces", &[self], &r, || json!({"keep": trace::picks(self, PickKind::Edge, keep, tolerance)}));
r
}
/// The flat faces nearest to `faces` (each within `tolerance`) tilted by `angle` radians
/// (0 < |angle| < 89.94 degrees) about the line where each meets the neutral plane through
/// `neutral_origin` with normal `neutral_normal`, a positive angle leaning them in going along
/// `pull`; the faces around them extended or trimmed to meet them. A face that isn't flat, or
/// isn't parallel to `pull`, is [`Error::Unsupported`].
pub fn draft(
&self,
faces: &[[f64; 3]],
tolerance: f64,
neutral_origin: [f64; 3],
neutral_normal: [f64; 3],
pull: [f64; 3],
angle: f64,
) -> Result<Brep> {
if faces.is_empty() || faces.len() > MAX_POINTS {
return Err(Error::Argument);
}
let r = core::offset::draft(self.core(), faces, tolerance, neutral_origin, neutral_normal, pull, angle).map(Brep::made_core);
trace::made("draft", &[self], &r, || {
json!({"faces": trace::picks(self, PickKind::Face, faces, tolerance), "neutral_origin": neutral_origin,
"neutral_normal": neutral_normal, "pull": pull, "angle": angle})
});
r
}
/// [`Brep::blend`] and its kin on solidcore (`core::blend::blend`).
#[allow(clippy::too_many_arguments)]
fn core_blend(
&self,
kind: Blend,
edges: &[[f64; 3]],
sizes: &[f64],
tolerance: f64,
corners: &[[f64; 3]],
setbacks: &[f64],
open: core::blend::Corners,
) -> Result<Brep> {
if edges.len() > MAX_POINTS || edges.is_empty() {
return Err(Error::Argument);
}
core::blend::blend(self.core(), kind, edges, sizes, tolerance, corners, setbacks, open).map(Brep::made_core)
}
}
#[cfg(test)]
#[path = "ops_tests.rs"]
mod tests;