Struct BoolmeshBoolean 

pub struct BoolmeshBoolean;

Mesh boolean built on the algorithm absorbed from boolmesh (pure Rust, glam-only, MPL-2.0).

Adopted in docs/adr/0014 and absorbed into this crate’s private csg module by docs/adr/0047. This type owns conversion and contract enforcement; no csg type is part of the public API, so the kernel can be replaced without a consumer noticing.

Implementations

impl BoolmeshBoolean

pub const ID: BackendId

Stable identifier used in errors and explicit provider selection.

pub const fn new() -> Self

Construct the provider.

pub fn subtract_boxes_analytic( &self, subject: &TriMesh, tools: &[TriMesh], options: &ExecutionOptions, max_cells: usize, ) -> GeomResult<Option<BooleanOutcome>>

Subtract axis-aligned box cutters from an axis-aligned box subject using an exact closed-form construction, bypassing the general solver.

Returns Ok(None) when the operands are outside this path’s competence, so the caller falls back to MeshBoolean::subtract_many rather than receiving an approximate answer. Declining cases:

• subject or any tool is not an axis-aligned box (recognised structurally – triangle count, corner lattice, and face planes – not by bounding box, since every mesh has one of those)
• no tools, or no tool overlapping the subject
• the induced grid would exceed max_cells

Why opt-in rather than automatic

Dispatching on shape automatically would make output topology depend on input in a way the caller cannot predict: the same wall would produce different triangle counts depending on whether its openings happened to be axis-aligned. Callers that want the speed ask for it and handle the None; callers that want one predictable code path never see this.

Guarantees

The result is watertight by construction (adjacent cells address shared grid vertices by integer index) and deterministic across processes (vertex identity is an ordered map, not a randomly-seeded hash map).

The returned evidence has BooleanEvidence::analytic_path set, so a caller can tell this result apart from a general-solver result.

impl BoolmeshBoolean

pub fn boolean_fast( &self, subject: &TriMesh, tool: &TriMesh, operation: BooleanOperator, options: &ExecutionOptions, ) -> GeomResult<BooleanOutcome>

Alternative to MeshBoolean::boolean using a cheaper winding-number classification for the same result.

See csg::boolean03::kernel03::winding03_fast’s doc comment for the guarantee: not an approximation, but a bug in edge-break detection would mislabel a whole connected component instead of one vertex. Opt-in rather than the default until this has run against a wider correctness corpus than the differential tests already covering it.

SymmetricDifference is refused rather than silently composed from three slow-path calls: a caller asking for the fast path should get it or a clear refusal, not a surprise fallback.

Trait Implementations

impl Backend for BoolmeshBoolean

fn descriptor(&self) -> BackendDescriptor

Runtime descriptor and capability inventory.

impl Clone for BoolmeshBoolean

fn clone(&self) -> BoolmeshBoolean

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for BoolmeshBoolean

impl Debug for BoolmeshBoolean

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BoolmeshBoolean

fn default() -> BoolmeshBoolean

Returns the “default value” for a type.

impl MeshBoolean for BoolmeshBoolean

fn determinism(&self) -> Determinism

Honest about the general path, which is not byte-reproducible.

Upstream boolmesh dedups vertices through a randomly-seeded HashMap, so its output ordering varies between processes even single-threaded. That is the same root cause documented in Self::subtract_boxes_analytic, which avoids it with a BTreeMap. The general path therefore cannot claim Determinism::Bitwise at any thread count, and enabling parallel does not make it weaker than it already is.

Determinism::Topological is the honest ceiling: the result’s connectivity is stable, its vertex ordering is not. Callers needing byte reproducibility use Self::subtract_boxes_analytic, whose ordered vertex identity makes it reproducible across processes.

fn scratch_requirement(&self) -> ScratchRequirement

Measured, not guessed: ScratchRequirement::Affine over the input triangles of all operands and the worker threads the call runs on.

boolmesh builds a Morton collider and intersection tables sized by the combined input. It exposes no bound, so this was measured directly with a counting global allocator (src/bin/scratch_probe/) across all four operations at 24 to 1,536 input triangles, after one discarded warmup call so the first operation measured is not charged for process startup (#110). With rayon each boolean runs in a pool started inside the measured window, with the join halves forced onto other workers (#226; the module docs of scratch.rs say how). Worst peak in bytes over the four operations and ten runs with parallel, six on an idle 20-core machine and four at load average 20 to 43:

 triangles   1 worker   4 workers   16 workers   64 workers
        24      59752       65656       160136       471736
        96     108232      112152       193504       460672
       384     348792      357000       422472       680384
      1536    1354692     1362900      1411548      1702180

Three terms, each with its own evidence:

• Per triangle, 1,536 bytes. The slope is linear and flat at about 880 bytes per triangle from 384 up to 24,576 triangles (one worker, checked once at the two larger sizes), so this is 1.7x it. SymmetricDifference is the worst operation because it is composed from three passes and holds intermediates alive.
• Base, 64 KiB: fixed setup that dominates small inputs. 24 triangles peak at 59,752 bytes on one worker, 22 KiB above the per-triangle term, so the base is 2.9x that excess.
• Per worker, 16 KiB with parallel. A rayon worker’s own bookkeeping (deque, registry slot, thread-locals) is 4.8 KB at most from 1 to 512 threads, and it is charged to whichever boolean runs while the worker starts, which on a loaded machine can be any of them. Work stolen onto it adds its scratch alongside the rest. The measured excess over one worker is at most 6.7 KB per extra worker, idle or loaded, so this is 2.4x it. With parallel-batch alone the batch’s pool workers pay the same bookkeeping. Without either feature nothing runs off the calling thread and the term is zero.

The result is charged in the solve (#308)

This counts input triangles only, so it is the admission bound on the operands, not a bound on the call. Operands that cross many times have a far larger result: two perpendicular combs of 32 teeth, 1,048 triangles, cross 17,716 times, and their union peaked at 14.7 MB, 8.8x this declaration (52.9 MB, 31x, for the symmetric difference). With a memory budget the solve therefore charges the result once its size is known: after the intersection pass, boolean45 counts the result’s half-edges exactly and refuses with BudgetExceeded before allocating the result when this declaration plus 448 bytes per half-edge beyond three per input triangle does not fit. Ordinary results stay within the three and are charged nothing more; the intersection pass stops as soon as its crossings alone could not fit. A budget that admits this declaration can still be refused, so, as for batches, the check before dispatch is a necessary condition, not a sufficient one. A composed SymmetricDifference charges each step the union and intersection it holds. src/budget.rs gives the measurements.

Batches

The bound covers each boolean of MeshBoolean::subtract_many and MeshBoolean::union_many on that step’s own operands, not the batch in its input triangles: intermediates can outgrow the inputs, and with parallel-batch stolen work can put every pair of a level in flight at once (#259). With a memory budget the batch charges each step when its operands exist (its own copies and intermediates, plus this bound for every boolean that can be live) and refuses with BudgetExceeded before the first step that does not fit, so the check before dispatch is a necessary condition for a batch, not a sufficient one. Each boolean then gets the budget the batch does not hold (split evenly between the pairs of a parallel-batch level) and charges its result against it (#308). tests/scratch_bound.rs holds the peak of both batches under forced schedules to the smallest budget they admit.

The old PerElement { bytes_per_element: 4096 } was 2x the large-input slope but no bound at all for small inputs on a pool: 24 triangles on 16 workers peak at 125,688 to 160,136 bytes against its 98,304 (#226). tests/scratch_bound.rs measures the same workloads on 1 to 64 workers and fails if any peak exceeds this. A declared bound that is occasionally too low is worse than Unbounded, because it makes a budget look enforced when it is not.

The worker count is only known where the call runs, so with a memory budget every boolean re-checks this bound against the pool it is in and refuses with BudgetExceeded when that pool is wider than the budget check before dispatch assumed. The re-check runs in every build, so a budget given to the provider directly, without dispatch, is enforced too.

fn cancellation_granularity(&self) -> CancellationGranularity

boolmesh takes no cancellation handle, so nothing can interrupt a single boolean once it starts. Declared honestly: the batch override polls between groups, which is the only real poll point available.

fn subtract_many( &self, subject: &TriMesh, tools: &[TriMesh], options: &ExecutionOptions, ) -> GeomResult<BooleanOutcome>

Group mutually disjoint cutters and remove each group with one boolean, instead of one boolean per cutter.

Rests on (S \ A) \ B == S \ (A union B) and on a concatenation of disjoint solids being their union. Bounding-box grouping over-separates but never wrongly fuses, so the result is identical to the sequential default – gated by volume equality in tests/batch.rs.

fn union_many( &self, solids: &[TriMesh], options: &ExecutionOptions, ) -> GeomResult<BooleanOutcome>

Union many solids in one batch so implementations can choose a reduction order.

fn boolean( &self, subject: &TriMesh, tool: &TriMesh, operation: BooleanOperator, options: &ExecutionOptions, ) -> GeomResult<BooleanOutcome>

Apply one regularized set operation.

fn solid_requirements(&self) -> SolidRequirements

Admissibility this provider requires of its operands.