Python package

ra.gems

Create, query and edit stones: shapes, materials, carats, placement, copies, collisions.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.GemApi.

Functions

Function
`all()`	`Gem` handles for every object of this kind in the active document (empty when there is no document).
`by_layer()`	`Gem` handles on the layer with the given full path (empty when the layer does not exist).
`by_material()`
`collisions()`	Returns every pair of gems whose meshes intersect (each entry is an array of the two colliding gems).
`count()`	Number of objects of this kind in the active document.
`create()`	Creates a new gem and adds it to the active document, returning a handle to it.
`find()`	The handle for `id`, or None when the id does not belong to an object of this kind.
`materials()`	Valid values for the `material` argument (“DIAMOND”, “RUBY”, …).
`selected()`	Returns the gems that are currently selected in the active doc.
`shapes()`	Valid values for the `shape` argument of Create / SetShape-style calls (“ROUND”, “PRINCESS”, “MARQUISE”, …).

ra.gems.all()

ra.gems.all() -> List[Gem]

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

ra.gems.by_layer()

ra.gems.by_layer(layer_name: str) -> List[Gem]

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

Parameter	Type
`layer_name`	`str`	required

ra.gems.by_material()

ra.gems.by_material(material_name: str) -> List[Gem]

Parameter	Type
`material_name`	`str`	required

ra.gems.collisions()

ra.gems.collisions() -> List[List[Gem]]

Returns every pair of gems whose meshes intersect (each entry is an array of the two colliding gems). Same mesh-mesh test as the ArtisanGemsCollision command, scoped to the gems GemApi manages. Read-only: safe without a Transaction and without a license.

ra.gems.count()

ra.gems.count() -> int

Number of objects of this kind in the active document.

ra.gems.create()

ra.gems.create(shape: str, material: str, carat_weight: float, plane: PlaneLike) -> Gem

Creates a new gem and adds it to the active document, returning a handle to it. shape accepts case-insensitive GemShape names (“ROUND”, “PRINCESS”, “MARQUISE”, “EMERALD”, …). material accepts compound names (“Diamond”, “Ruby”, “Sapphire”, …) — the string is normalized (dashes / spaces become underscores) before matching the GemCompound enum. carat_weight drives the gem’s size via the same proportion table QuickGems uses. plane is where the gem is placed; pass Plane.WorldXY for “at the origin”. Throws ScriptingNotLicensedException if the license is invalid.

Parameter	Type
`shape`	`str`	required
`material`	`str`	required
`carat_weight`	`float`	required
`plane`	`PlaneLike`	required

ra.gems.find()

ra.gems.find(id: IdLike) -> Gem

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

Parameter	Type
`id`	`IdLike`	required

ra.gems.materials()

ra.gems.materials() -> List[str]

Valid values for the material argument (“DIAMOND”, “RUBY”, …). Read-only, no license.

ra.gems.selected()

ra.gems.selected() -> List[Gem]

Returns the gems that are currently selected in the active doc. Empty list if nothing is selected (or selection contains no gems).

ra.gems.shapes()

ra.gems.shapes() -> List[str]

Valid values for the shape argument of Create / SetShape-style calls (“ROUND”, “PRINCESS”, “MARQUISE”, …). Read-only, no license.

Handles

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

Gem (handle)

Public scripting view of a gem placed in the current RhinoDoc. This is intentionally narrow — it does NOT expose the underlying ShapesKernel GemObject. The LLM-generated Python scripts (and any third party) can only do what this surface allows, and every mutation passes through LicenseGate.

Property	Type	Settable
`carat_weight`	`float`	yes
`layer_name`	`str`
`material`	`str`	yes	compound name, e.g. “Diamond”
`plane`	`Plane`	yes	the gem’s full placement plane (origin + orientation)
`position`	`Point3d`		origin of the gem’s plane
`shape`	`str`		”ROUND”, “PRINCESS”, “MARQUISE”, …
`size_x`	`float`		mm
`size_y`	`float`		mm
`size_z`	`float`		mm

Method
`copy(translation=None) -> Gem`	duplicate displaced by `translation`, returns the new gem
`delete()`
`flip()`	turn the gem upside down (180° around its own X axis)
`move(translation: VectorLike)`
`rotate(degrees: float)`	spin around the gem’s own Z axis (positive = counter-clockwise)
`scale(factor: float)`	uniform scale of the current size (factor > 0)
`select(on: bool)`	Selection state in the viewport.
`set_size(size_x: float, size_y: float, size_z: float)`	resize to explicit mm dimensions

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