Python package

ra.pearl

Pearls and their cups.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.PearlApi.

Functions

Function
`all()`	`Pearl` handles for every object of this kind in the active document (empty when there is no document).
`by_layer()`	`Pearl` 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 None when the id does not belong to an object of this kind.
`selected()`	Pearls currently selected in the active doc.

ra.pearl.all()

ra.pearl.all() -> List[Pearl]

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

ra.pearl.by_layer()

ra.pearl.by_layer(layer_name: str) -> List[Pearl]

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

Parameter	Type
`layer_name`	`str`	required

ra.pearl.count()

ra.pearl.count() -> int

Number of objects of this kind in the active document.

ra.pearl.create()

ra.pearl.create(diameter=None, calotte=None, calotte_angle=None, calotte_thickness=None, wire=None, wire_diameter=None, wire_length=None, plane=None) -> Pearl

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. Omit (None) to keep the tool’s default — or the user’s saved defaults — for that parameter (diameter 6, calotte_angle 35 degrees, calotte_thickness 1, wire_diameter 1, wire_length 8). calotte / wire omitted (None) 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
`diameter`	`float`	optional — None = the tool default
`calotte`	`Optional[bool]`	optional — None = the tool default
`calotte_angle`	`float`	optional — None = the tool default
`calotte_thickness`	`float`	optional — None = the tool default
`wire`	`Optional[bool]`	optional — None = the tool default
`wire_diameter`	`float`	optional — None = the tool default
`wire_length`	`float`	optional — None = the tool default
`plane`	`Optional[PlaneLike]`	optional — None = the tool default

ra.pearl.find()

ra.pearl.find(id: IdLike) -> Pearl

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

Parameter	Type
`id`	`IdLike`	required

ra.pearl.selected()

ra.pearl.selected() -> List[Pearl]

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

Handles

Objects returned by the functions above. Assigning a settable property regenerates the object; the change is one undo step inside ra.transaction().

Pearl (handle)

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 ParametricObject directly and MotherGemId is always None. Read-only: the parametric engine has no Regenerate for pearls, so there are no in-place setters (recreate + Delete to change one).

Property	Type
`calotte_angle`	`float`	degrees
`calotte_id`	`str`	None when there is no calotte child
`calotte_thickness`	`float`	millimetres
`diameter`	`float`	pearl sphere diameter, millimetres
`has_calotte`	`bool`	a calotte child was baked with this pearl
`has_wire`	`bool`	a wire child was baked with this pearl
`layer_name`	`str`
`mother_gem_id`	`str`
`object_type`	`str`
`position`	`Point3d`
`wire_diameter`	`float`	millimetres
`wire_id`	`str`	None when there is no wire child
`wire_length`	`float`	millimetres

Method
`delete()`
`move(translation: VectorLike)`

Plus what every handle has: id, delete(), update(**kwargs), parameters(), equality and hashing by id, and raw (the underlying .NET object).