GemSizeApi

Gems by millimetre size instead of carats. GemApi.Create sizes a stone from its carat weight; this facade takes the dimensions directly (the way the Gem Creator panel does) and reuses the exact same insertion pipeline, so the result is indistinguishable from a hand-placed gem.

from ArtisanPlugin.Scripting import GemSizeApi

See also the Python package, ra.gem_size.

Methods

Method
Create	Creates a gem from its dimensions in mm and adds it to the active document, returning the same IGem handle GemApi.Create returns.
SameSize	The actual ArtisanGemBySize command: given some reference gems, finds every gem in the document with the same width (SizeX, 0.001 mm tolerance) — e.g.

Create

IGem GemSizeApi.Create(
    string shape,
    string material,
    double sizeX,
    double sizeY = 0,
    double sizeZ = 0,
    Plane? plane = null)

Creates a gem from its dimensions in mm and adds it to the active document, returning the same IGem handle GemApi.Create returns. shape / material accept the GemApi vocabularies (GemApi.Shapes() / GemApi.Materials()). sizeX is the width (diameter for ROUND); sizeY (length) and sizeZ (depth) 0 = the shape’s standard proportions. plane is where the gem sits (default: world XY at the origin); the carat weight is derived from the mesh volume.

Parameter	Type	Default
shape	string	required
material	string	required
sizeX	double	required
sizeY	double	0
sizeZ	double	0
plane	Plane?	null

Returns IGem.

SameSize

IReadOnlyList<Guid> GemSizeApi.SameSize(IEnumerable<Guid> gemIds = null)

The actual ArtisanGemBySize command: given some reference gems, finds every gem in the document with the same width (SizeX, 0.001 mm tolerance) — e.g. “all the 1.5 mm stones”. gemIds empty/null uses the selected gems. Read-only, no license: returns the matching ids (reference gems included); pair with select_objects / GemApi.Find.

Parameter	Type	Default
gemIds	IEnumerable<Guid>	null

Returns IReadOnlyList<Guid>.

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.

Also used here: IGem.