Pearl

from ArtisanPlugin.Scripting import PearlApi as pearl

A pearl is set differently from a faceted stone: it is drilled rather than gripped, so it sits on a calotte - the little metal cup that hides the drill hole - and is threaded onto a wire post glued into the hole. That trio is the whole of a classic pearl stud earring, and the tool builds all three at once, exactly as the ArtisanPearl panel’s Accept does.

Unlike the bezel, peghead or basket, PearlApi is not wrapped around a mother gem: it is a standalone stone creator. It makes its own sphere on the plane you give it, so there is no gemId argument, no ForGem query, and MotherGemId on the handle is always empty.

Create

p = pearl.Create(diameter = 0, calotte = None, calotteAngle = 0, calotteThickness = 0,
                 wire = None, wireDiameter = 0, wireLength = 0, plane = None)   # -> IPearl

Parameter	Default	Meaning
diameter	0 -> tool default 6	Pearl sphere diameter, mm
calotte	None -> keep the tool default (enabled)	Whether to bake the metal cup
calotteAngle	0 -> tool default 35	How far the cup wraps up the pearl, degrees
calotteThickness	0 -> tool default 1	Metal thickness of the cup, mm - must exceed 0.2
wire	None -> keep the tool default (enabled)	Whether to bake the post
wireDiameter	0 -> tool default 1	Post diameter, mm
wireLength	0 -> tool default 8	Post length, mm
plane	omitted -> world XY	The plane the pearl is built on

All dimensions are millimetres, and 0 keeps the tool default for that parameter - or the user’s saved pearl defaults when they have any, since Create starts from the same model the ArtisanPearl command does.

None versus False on calotte and wire

These two are nullable booleans, and the three states are genuinely different:

Value	Effect
None (omitted)	Leave the flag as the tool - or the user’s saved defaults - has it. Out of the box that means enabled, so a bare pearl.Create() gives you a pearl with a calotte and a wire
False	Explicitly disable that part - the child is not computed and not baked
True	Explicitly enable it, even if the saved defaults had it off

So None is not “off”: omitting calotte keeps the calotte. Pass False when you want a bare pearl.

What gets baked

The pearl itself goes on the last gems layer with the pearl material. Each enabled child is then baked as its own object - a pearl-calotte object and a pearl-wire object - on the metal layer with the metal material, and linked back to the pearl so the handle can find them. A child that fails to compute is simply not added, so always check HasCalotte / HasWire rather than assuming.

Create throws InvalidOperationException when the geometry fails to compute - a calotte thickness of 0.2 mm or less is the usual cause - or when the licence is invalid.

Edit

The pearl is read-only after creation: the parametric engine has no regenerate step for pearls, so IPearl carries no setters. To change a dimension, create a new pearl and Delete() the old one.

What the handle exposes for reading:

Member	Meaning
Diameter	Pearl sphere diameter, mm
HasCalotte	A calotte child was baked with this pearl
HasWire	A wire child was baked with this pearl
CalotteId	Guid of the calotte object, empty when there is none
WireId	Guid of the wire object, empty when there is none

Plus the shared Id, MotherGemId (always empty), ObjectType, LayerName, Position, Move(vector) and Delete(). Those two mutations belong inside a Transaction so the edit lands as one undo step.

from ArtisanPlugin.Scripting import PearlApi as pearl

p = pearl.Create(diameter = 8, calotte = True, calotteThickness = 0.8, wire = False)
print(p.Diameter, p.HasCalotte, p.HasWire)     # 8.0 True False

Move() and Delete() act on the pearl object; use CalotteId and WireId if you need to reach the metal children directly.

Queries

All(), Find(id), Count(), Selected(), ByLayer(name).

There is no ForGem - a pearl has no mother gem.