GemApi

Static entry point for the gem scripting facade. This is what LLM-generated Python scripts call (via clr.AddReference(“Artisan”); from ArtisanPlugin.Scripting import GemApi as gem). Read-only methods don’t gate on the license — they let unlicensed users at least inspect their own document. Anything that modifies the document goes through GemHandle which calls LicenseGate.RequireValid().

from ArtisanPlugin.Scripting import GemApi

See also the guide, Gems › Create, and the Python package, ra.gems.

Methods

Method
All	IGem handles for every object of this kind in the active document (empty when there is no document).
ByLayer	IGem handles on the layer with the given full path (empty when the layer does not exist).
ByMaterial
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 null 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”, …).

All

IReadOnlyList<IGem> GemApi.All()

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

Returns IReadOnlyList<IGem>.

ByLayer

IReadOnlyList<IGem> GemApi.ByLayer(string layerName)

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

Parameter	Type	Default
layerName	string	required

Returns IReadOnlyList<IGem>.

ByMaterial

IReadOnlyList<IGem> GemApi.ByMaterial(string materialName)

Parameter	Type	Default
materialName	string	required

Returns IReadOnlyList<IGem>.

Collisions

IReadOnlyList<array<IGem>> GemApi.Collisions()

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.

Returns IReadOnlyList<array<IGem>>.

Count

int GemApi.Count()

Number of objects of this kind in the active document.

Returns int.

Create

IGem GemApi.Create(string shape, string material, double caratWeight, Plane plane)

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. caratWeight 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	Default
shape	string	required
material	string	required
caratWeight	double	required
plane	Plane	required

Returns IGem.

Find

IGem GemApi.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 IGem.

Materials

IReadOnlyList<string> GemApi.Materials()

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

Returns IReadOnlyList<string>.

Selected

IReadOnlyList<IGem> GemApi.Selected()

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

Returns IReadOnlyList<IGem>.

Shapes

IReadOnlyList<string> GemApi.Shapes()

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

Returns IReadOnlyList<string>.

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.

IGem

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
CaratWeight	double	get
Id	Guid	get
LayerName	string	get
Material	string	get	compound name, e.g. “Diamond”
Plane	Plane	get	the gem’s full placement plane (origin + orientation)
Position	Point3d	get	origin of the gem’s plane
Shape	string	get	”ROUND”, “PRINCESS”, “MARQUISE”, …
SizeX	double	get	mm
SizeY	double	get	mm
SizeZ	double	get	mm

Method
IGem Copy()	duplicate in place, returns the new gem
IGem Copy(Vector3d translation)	duplicate displaced by translation, returns the new gem
void Delete()
void Flip()	turn the gem upside down (180° around its own X axis)
void Move(Vector3d translation)
void Rotate(double degrees)	spin around the gem’s own Z axis (positive = counter-clockwise)
void Scale(double factor)	uniform scale of the current size (factor > 0)
void Select(bool on)	Selection state in the viewport. Not a document mutation (no undo record, no license gate) — useful for scripts that end by highlighting their result.
void SetCaratWeight(double caratWeight)	resize by carat, keeping shape/material/plane/layer
void SetMaterial(string materialName)	Mutations — each calls LicenseGate.RequireValid() before doing anything.
void SetPlane(Plane plane)	re-place the gem: moves AND orients to the given plane
void SetShape(string shape)	change the cut (“OVAL”, “PEAR”, “EMERALD”… see GemApi.Shapes()) in place: same Id, plane, material, layer and carat weight; the settings built on the gem rebuild around the new shape. For “a 1.5 ct oval”, SetShape then SetCaratWeight.
void SetSize(double sizeX, double sizeY, double sizeZ)	resize to explicit mm dimensions