Booleans

from ArtisanPlugin.Scripting import BooleanApi as boolean

The four solid operations, headless — and the reason they have their own facade rather than deferring to rs.Boolean*: an Artisan boolean stays editable. Rhino’s booleans consume their inputs and hand back a finished brep. Artisan’s bake the result into a named group carrying the operation and its parameters, hide the originals instead of deleting them, and leave the whole thing dismantlable and recomputable afterwards through ArtisanEdit and ArtisanBooleanUpdate. Same engine as the ArtisanBooleanUnion / Difference / Intersection / Split commands.

• UnionFuse two or more solids into one.
• DifferenceSubtract the cutters from the targets.
• IntersectionKeep only the volume the two sets share.
• SplitCut the targets into parts along the cutters.

cutters = cutter.Create([g.Id])                    # the gem seats
boolean.Difference([shankId], cutters)             # ...carved out of the shank

Union

ids = boolean.Union(objectIds)          # -> the result group's member ids

Parameter	Default	Meaning
objectIds	—	Two or more solids to fuse. Fewer than two raises “Union needs at least two solids.”

Union is the one operation with a single set — there are no cutters, every solid is a peer.

Difference

ids = boolean.Difference(targetIds, cutterIds)     # -> the result group's member ids

Parameter	Default	Meaning
targetIds	—	The solids to keep
cutterIds	—	The solids to subtract from them

The workhorse: this is the final “make it solid” step of most pieces — subtracting the gem cutters from a shank before printing.

Intersection

ids = boolean.Intersection(targetIds, cutterIds)   # -> the result group's member ids

Keeps only the volume common to both sets.

Split

ids = boolean.Split(targetIds, cutterIds)          # -> the result group's member ids

Cuts the targets along the cutters and keeps every resulting piece, rather than discarding one side.

What comes back

All four return the ids of the members of the result group — the result breps, which inherit the layer, colour and material of the first target you passed. Order the targets deliberately if that matters.

What lands in the document is not a bare brep but an Artisan boolean:

The group	Named Boolean <guid>, carrying RaObjectUserData with the operation, the target and cutter ids, and the tolerance used
The originals	Hidden, not deleted — both targets and cutters. Unhide them and you have your inputs back
The tolerance	The document’s ModelAbsoluteTolerance, recorded in the parameters

That stored state is what lets ArtisanEdit and ArtisanBooleanUpdate take a scripted boolean apart later, exactly as if you had run the command by hand.

Failures

Booleans are licensed mutations and need an active document. They validate before touching anything, and a failed computation leaves the document untouched:

Situation	Error
An id is not in the document	”Object … not found in the document.”
An empty or null id list	”At least one object id is required.”
Fewer than two solids for a union	”Union needs at least two solids.”
The same object in both sets	”An object cannot be in both sets of a boolean operation.”
The solids do not intersect, or are not closed	”Boolean computation failed. Check that the solids are closed and actually intersect.”

Each call opens its own undo record, so a boolean is already a single undo step on its own; wrapping several in a Transaction groups the whole run into one.