Crate brepkit_operations

Expand description

§brepkit-operations

CAD modeling operations for B-Rep solids, and the entry point for Rust consumers of brepkit. Layer L3, depending on brepkit-math, brepkit-topology, brepkit-geometry, brepkit-algo, brepkit-blend, brepkit-heal, brepkit-check, brepkit-offset, and brepkit-sketch.

§Getting started

use brepkit_operations::boolean::{boolean, BooleanOp};
use brepkit_operations::measure::solid_volume;
use brepkit_operations::primitives::{make_box, make_cylinder};
use brepkit_topology::Topology;

let mut topo = Topology::new();

// Primitives are anchored at the origin, so this cylinder rounds off the
// block's corner. Use `transform_solid` to place it somewhere else.
let block = make_box(&mut topo, 30.0, 20.0, 10.0)?;
let cutter = make_cylinder(&mut topo, 5.0, 15.0)?;
let notched = boolean(&mut topo, BooleanOp::Cut, block, cutter)?;

// A quarter-cylinder of radius 5 and height 10 is gone from the corner.
let expected = 30.0 * 20.0 * 10.0 - 0.25 * std::f64::consts::PI * 25.0 * 10.0;
let volume = solid_volume(&topo, notched, 0.01)?;
assert!((volume - expected).abs() / expected < 1e-3);

§Conventions

Modeling operations take the Topology arena as &mut and return a typed handle into it, so results compose without copying geometry. Interrogation does not: measurement, classification, validation, distance, and query borrow the arena as & and return a value, whether a number, a report, or a collection.

Fallible work returns a Result rather than panicking. unwrap, expect, and panic! are denied by lint across the workspace.

Primitives are anchored at the origin. Place them with transform rather than expecting a position argument.

§Exact geometry, and when it degrades

Booleans run on an exact path that preserves analytic and NURBS surfaces. A cylinder cut by a plane stays a cylinder, so face counts stay flat across chained operations instead of compounding: a nine-step compound boolean settles around 72 faces where a mesh-based approach would reach several thousand.

Some configurations defeat that path and fall back to a mesh-based boolean built on co-refinement. The usual causes are coincident-face contact, coaxial analytic surfaces, razor-thin geometry, and very high face counts. The fallback returns a usable, non-degenerate solid, but the curved faces come back tessellated and the result is not guaranteed watertight.

The fallback does not announce itself in the return value, which matters most for export pipelines: a STEP file written from a fallback result carries triangles where it should carry a cylinder. Snapshot boolean::mesh_fallback_count around the chain and refuse the output when it grew.

use brepkit_operations::boolean::{boolean, mesh_fallback_count, BooleanOp};
use brepkit_operations::primitives::{make_box, make_cylinder};
use brepkit_operations::validate::validate_solid;
use brepkit_topology::Topology;

let mut topo = Topology::new();
let block = make_box(&mut topo, 30.0, 20.0, 10.0)?;
let cutter = make_cylinder(&mut topo, 5.0, 15.0)?;

let before = mesh_fallback_count();
let notched = boolean(&mut topo, BooleanOp::Cut, block, cutter)?;

// This cut takes the exact path, so the counter is unmoved and the
// rounded wall is still a real cylinder.
assert_eq!(mesh_fallback_count(), before);

// Topological checks: wire closure, manifold and boundary edges,
// Euler characteristic, degenerate faces, and duplicate faces.
assert!(validate_solid(&topo, notched)?.is_valid());

§Verifying a result

Three checks, in increasing cost, and they catch different things:

validate::validate_solid reports topological defects: an unclosed wire, a shell with a free edge, a non-manifold edge, a wrong Euler characteristic, a degenerate face. Cheap, and the right default.
measure::solid_volume against a closed-form expectation catches geometric errors that leave the topology intact, which is the failure mode a boolean is most likely to produce. Pass a tight deflection: a coarse one under-counts curved faces and will disagree with itself across values.
heal::heal_solid repairs what the first two find, merging coincident vertices, dropping degenerate edges, closing wire gaps, and fixing face orientation.

A solid that passes validate_solid is well-formed, not necessarily correct. Volume is what distinguishes the two.

§Module families

Family	Modules	Purpose
Core	`primitives`, `extrude`, `revolve`, `sweep`, `loft`, `pipe`, `helix`	Shape creation
Transform	`transform`, `copy`, `mirror`, `pattern`	Spatial operations
Boolean	`boolean`, `mesh_boolean`	Set operations
Blend	`fillet`, `chamfer`, `blend_ops`	Edge smoothing
Offset	`offset_face`, `offset_trim`, `offset_v2`, `offset_wire`	Wall thickness
Surface	`fill_face`, `thicken`, `shell_op`, `draft`, `section`, `split`	Surface/solid modification
Repair	`heal`, `defeature`, `sew`, `untrim`	Shape fixing
Analysis	`measure`, `distance`, `classify`, `validate`, `query`, `feature_recognition`	Interrogation
Tessellation	`tessellate`	Mesh generation
Infrastructure	`assembly`, `compound_ops`, `evolution`, `sketch`	Utilities

§See also

brepkit_io: reading and writing STEP and the mesh formats.
brepkit_topology: the arena every operation here takes, and the surface enums it stores.
brepjs.dev: concepts, task recipes, and the TypeScript API built on this kernel.

Modules§

assembly: Assembly management: hierarchical product structure with positioned components.
blend_ops: Thin wrappers around brepkit-blend for the operations API.
boolean: Boolean operations on solids: fuse, cut, and intersect.
chamfer: Edge chamfering (cutting edges at an angle).
classify: Point-in-solid classification via ray casting and generalized winding numbers.
compound_ops: Operations on compound entities.
copy: Deep copy of topological entities.
defeature: Defeaturing: remove small features from a solid for simulation simplification.
distance: Distance measurement between shapes.
draft: Draft angle operation for injection molding applications.
evolution: Evolution tracking for modeling operations.
extrude: Linear extrusion of faces along a direction vector.
feature_recognition: Feature recognition: detect geometric features from B-Rep topology.
fill_face: Face filling: create a smooth NURBS surface from boundary curves.
fillet: Edge filleting (rounding edges with a constant or variable radius).
heal: Topology healing: repair common defects in B-Rep models.
helix: Helical sweep: sweep a profile along a helical path to create thread-like geometry (screws, springs, coils).
loft: Loft operation: create a solid by interpolating between profile faces.
measure: Measurement operations for B-rep geometry: bounding boxes, areas, volumes, and centers of mass.
mesh_boolean: Co-refinement mesh boolean operations on triangle meshes.
mirror: Mirror operation: reflect a solid across a plane.
offset_face: Face offset: create a new face offset from an existing face by a given distance along its surface normal.
offset_trim: Offset self-intersection detection and removal.
offset_v2: V2 offset operations delegating to brepkit-offset.
offset_wire: Wire offset: produce a parallel wire at a given distance.
pattern: Pattern operations: linear and circular arrays of solids.
pipe: Pipe sweep: sweep a profile along a path with optional scaling guide.
primitives: Parametric primitive shape builders.
projection: Edge projection with hidden-line removal (HLR).
query: Shape query utilities.
revolve: Revolution of a planar profile around an axis to create solids of revolution.
section: Sectioning (slicing) solids with planes.
sew: Topology sewing: merge loose faces into connected shells.
shell_op: Shell (hollow/offset) operation for creating thin-walled solids.
sketch: 2D constraint solver for sketch-mode parametric design.
split: Split a solid into two halves along a cutting plane.
sweep: Path sweep: sweep a profile along a NURBS curve.
tessellate: Tessellation: convert B-Rep faces to triangle meshes.
thicken: Thicken a face into a solid by offsetting along its normal.
transform: Affine transforms applied to topological shapes.
untrim: NURBS face untrimming: convert a trimmed NURBS face to an untrimmed tensor-product patch.
validate: Comprehensive solid validation.

Enums§

OperationsError: Errors from modeling operations.