Trait MeshBoolean

pub trait MeshBoolean: Backend {
    // Required method
    fn boolean(
        &self,
        subject: &TriMesh,
        tool: &TriMesh,
        operation: BooleanOperator,
        options: &ExecutionOptions,
    ) -> GeomResult<BooleanOutcome>;

    // Provided methods
    fn scratch_requirement(&self) -> ScratchRequirement { ... }
    fn determinism(&self) -> Determinism { ... }
    fn cancellation_granularity(&self) -> CancellationGranularity { ... }
    fn solid_requirements(&self) -> SolidRequirements { ... }
    fn subtract_many(
        &self,
        subject: &TriMesh,
        tools: &[TriMesh],
        options: &ExecutionOptions,
    ) -> GeomResult<BooleanOutcome> { ... }
    fn union_many(
        &self,
        solids: &[TriMesh],
        options: &ExecutionOptions,
    ) -> GeomResult<BooleanOutcome> { ... }
}

Mesh boolean provider.

Implementing this trait is the capability declaration. Providers that do not implement mesh booleans must not implement this trait.

Required Methods

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

Apply one regularized set operation.

Operands are pre-validated by the registry. Returns a BooleanOutcome: the mesh plus what was done to produce it. An empty result mesh is a legitimate value, not an error.

Provided Methods

fn scratch_requirement(&self) -> ScratchRequirement

Scratch this provider needs beyond its inputs and result.

Callers budget against this before dispatch. Defaults to ScratchRequirement::Unbounded so an unaudited provider is treated as unbudgetable rather than silently assumed cheap.

fn determinism(&self) -> Determinism

Reproducibility this provider guarantees for its results.

Defaults to Determinism::BestEffort: the weakest level, so a provider that has not audited its own reproducibility cannot silently satisfy a stronger request. Overstating this is the dangerous direction — Plan::admit refuses a step whose guarantee is weaker than the caller asked for, and that refusal is only sound if the declared level is honest.

A provider whose output depends on thread scheduling, hash seeding, or any other run-to-run variation must not claim Determinism::Bitwise.

fn cancellation_granularity(&self) -> CancellationGranularity

How finely this provider polls a cancellation token.

Defaults to CancellationGranularity::None: a provider that has not declared otherwise is assumed not to poll. Claiming responsiveness a provider does not have is worse than admitting none.

fn solid_requirements(&self) -> SolidRequirements

Admissibility this provider requires of its operands.

Advisory only: the registry validates at the contract level before dispatch. A provider declaring a lower level does not thereby get to accept looser input, and one declaring a higher level is rejected by the conformance suite for narrowing the contract.

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

Subtract many tools in one batch so implementations can union or schedule cutters efficiently. The default is correct but deliberately simple.

The default polls cancellation between tools, which is why the default granularity for an overriding provider must be declared honestly.

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

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

The default folds left, which is correct but makes step i pay for an accumulator holding i operands – quadratic total work. A provider that can do better should override this; see BoolmeshBoolean::union_tree for a balanced reduction that measures 28.9x faster on a 512-sphere grid.

An empty slice yields an empty solid: the union of nothing is nothing, which is a legitimate answer rather than an error.

The default polls cancellation between operands, which is why the declared granularity for an overriding provider must stay honest.

Implementors