Boolean Operations

OpenCascade CSG (union / subtract / intersect) on scene masses and spaces. Accessed via snaptrude.design.boolean.

Every method commits the operation as one undoable step and returns the committed BooleanOutcome. Failures throw (the RPC call rejects) — no result wrapper crosses the boundary.

Eligibility (applies to all inputs): each input must be a Mass that is a room or a DEPARTMENT, has a brep, is unlocked (mesh and bucket), visible, and not in a parametric-copy group. The whole input set must be all-planar or all-non-planar, contain at least 2 components, share one group (or all be ungrouped), and be adjacent/overlapping.

Note: design.boolean.subtract is a CSG geometry delete — distinct from design.delete.entities (hard entity removal) and design.erase.edge (adjacency-edge topology op).

Types

BooleanOutcome

Result of a CSG boolean op. created are the result masses; deleted is every consumed input (for subtract this includes both the target and the tools).

Property	Type	Description
created	ComponentHandle[]	The result mass(es) the operation created
deleted	ComponentHandle[]	Every consumed input entity

BooleanOptions

Optional knobs shared by all boolean ops. The only one is a world-space translation applied to the output mass(es).

Property	Type	Description
offset	Vec3Handle (optional)	Translation added to the created result mass(es) (default: none)

Functions

union(components, options?)

Fuse 2 or more components into a single mass (A ∪ B ∪ …). Order-independent.

• Parameters:
  • components: ComponentHandle[] — The ≥2 entities to fuse (order-independent)
  • options: BooleanOptions (optional) — Optional output offset
• Returns: BooleanOutcome — The committed CSG delta
• Throws: If inputs are ineligible, disjoint, non-manifold when joined, span different groups, or the CSG yields no / invalid geometry.

// Fuse two overlapping masses into one
const { created, deleted } = await snaptrude.design.boolean.union([massA, massB]);
console.log("created:", created, "consumed:", deleted);

---

subtract(target, tools, options?)

Subtract tools from target (target − ⋃tools). Order-sensitive: the host seeds [target, ...tools] — index 0 is the arg brep, the rest are tool breps. deleted includes the target and every tool; created is the remainder mass(es).

• Parameters:
  • target: ComponentHandle — The entity subtracted FROM (arg brep)
  • tools: ComponentHandle[] — The ≥1 entities subtracted (tool breps)
  • options: BooleanOptions (optional) — Optional output offset
• Returns: BooleanOutcome — The committed CSG delta
• Throws: As union; a NoResult here carries the "select the target object first" hint from the engine.

// Carve a void out of a mass
const outcome = await snaptrude.design.boolean.subtract(buildingMass, [voidMass]);
// outcome.deleted contains buildingMass AND voidMass;
// outcome.created is the remainder mass(es)

---

intersect(components, options?)

Keep only the overlap of the inputs (A ∩ B). Order-independent. Hard constraint: exactly 2 components (the engine throws MoreThan2ComponentsForIntersect on more).

• Parameters:
  • components: ComponentHandle[] — Exactly 2 entities to intersect (order-independent)
  • options: BooleanOptions (optional) — Optional output offset
• Returns: BooleanOutcome — The committed CSG delta
• Throws: As union, plus MoreThan2ComponentsForIntersect when more than 2 components are passed.

const overlap = await snaptrude.design.boolean.intersect([massA, massB]);

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	all ops	A component or options.offset handle cannot be resolved	—
OPERATION_FAILED	all ops	The engine boolean operation fails — ineligible inputs, disjoint inputs, a non-manifold joined shape, inputs spanning different groups, or no/invalid result geometry	reason — the engine failure kind: ComponentsNotEligible, ComponentsNotConnected, NonManifoldComponentConnectivity, ComponentsNotInSameOrNoGroup, NoResult, or InvalidBreps. For ComponentsNotEligible (the only kind the engine attributes to specific inputs) also handles — the ineligible components, with the first one as the primary handle

Each OPERATION_FAILED carries a hint matched to its reason (e.g. for ComponentsNotConnected: move the components so they overlap before retrying).

intersect's exactly 2 rule is enforced by the argument schema, so passing any other count rejects with VALIDATION — the engine's MoreThan2ComponentsForIntersect kind is never reached through this API.