PearlApi

Pearls and their cups.

from ArtisanPlugin.Scripting import PearlApi

See also the guide, Gemsets › Pearl, and the Python package, ra.pearl.

Methods

Method
All	IPearl handles for every object of this kind in the active document (empty when there is no document).
ByLayer	IPearl handles on the layer with the given full path (empty when the layer does not exist).
Count	Number of objects of this kind in the active document.
Create	Creates a pearl (the ArtisanPearl tool, headless) and adds it to the active document.
Find	The handle for id, or null when the id does not belong to an object of this kind.
Selected	Pearls currently selected in the active doc.

All

IReadOnlyList<IPearl> PearlApi.All()

IPearl handles for every object of this kind in the active document (empty when there is no document).

Returns IReadOnlyList<IPearl>.

ByLayer

IReadOnlyList<IPearl> PearlApi.ByLayer(string layerName)

IPearl handles on the layer with the given full path (empty when the layer does not exist).

Parameter	Type	Default
layerName	string	required

Returns IReadOnlyList<IPearl>.

Count

int PearlApi.Count()

Number of objects of this kind in the active document.

Returns int.

Create

IPearl PearlApi.Create(
    double diameter = 0,
    bool? calotte = null,
    double calotteAngle = 0,
    double calotteThickness = 0,
    bool? wire = null,
    double wireDiameter = 0,
    double wireLength = 0,
    Plane? plane = null)

Creates a pearl (the ArtisanPearl tool, headless) and adds it to the active document. A pearl is its own stone — a sphere placed on plane (omitted = world XY) — optionally baked together with two metal children, exactly like the panel’s Accept: a calotte (cup holding the pearl) and a wire (post drilled into it). The children become PearlCalotteCustomObject / PearlWireCustomObject instances linked to the pearl, on the metal layer with the metal material. All dimensional arguments are millimetres. Pass 0 (or omit) to keep the tool’s default — or the user’s saved defaults — for that parameter (diameter 6, calotteAngle 35 degrees, calotteThickness 1, wireDiameter 1, wireLength 8). calotte / wire omitted (null) keep the default (both enabled); pass false to skip that child. Throws InvalidOperationException when the geometry fails to compute (e.g. calotte thickness must be > 0.2 mm).

Parameter	Type	Default
diameter	double	0
calotte	bool?	null
calotteAngle	double	0
calotteThickness	double	0
wire	bool?	null
wireDiameter	double	0
wireLength	double	0
plane	Plane?	null

Returns IPearl.

Find

IPearl PearlApi.Find(Guid id)

The handle for id, or null when the id does not belong to an object of this kind.

Parameter	Type	Default
id	Guid	required

Returns IPearl.

Selected

IReadOnlyList<IPearl> PearlApi.Selected()

Pearls currently selected in the active doc. Empty list if nothing is selected or the selection contains no pearls.

Returns IReadOnlyList<IPearl>.

Handles and sections

What the methods above hand back. A handle’s setters regenerate the object; wrap changes in a Transaction so they land as one undo step.

IPearl

Handle — extends IParametricObject.

A pearl is its own stone (a sphere on a plane) with two optional metal children baked alongside it: a calotte (cup) and a wire (post). It is not built around a mother gem, so it extends IParametricObject directly and MotherGemId is always Guid.Empty. Read-only: the parametric engine has no Regenerate for pearls, so there are no in-place setters (recreate + Delete to change one).

Property	Type
CalotteAngle	double	get	degrees
CalotteId	Guid	get	Guid.Empty when there is no calotte child
CalotteThickness	double	get	millimetres
Diameter	double	get	pearl sphere diameter, millimetres
HasCalotte	bool	get	a calotte child was baked with this pearl
HasWire	bool	get	a wire child was baked with this pearl
Id	Guid	get	(from IParametricObject)
LayerName	string	get	(from IParametricObject)
MotherGemId	Guid	get	(from IParametricObject)
ObjectType	string	get	(from IParametricObject)
Position	Point3d	get	(from IParametricObject)
WireDiameter	double	get	millimetres
WireId	Guid	get	Guid.Empty when there is no wire child
WireLength	double	get	millimetres

Method
void Delete()	(from IParametricObject)
void Move(Vector3d translation)	(from IParametricObject)