Skip to content

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

18.6 KB
Raw Blame
//! 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;