Scripting API

Gems on curve

from ArtisanPlugin.Scripting import GemsOnCurveApi as gemsoncurve

A row of identical stones running along a line - the eternity band, the pavé line down a shoulder, the graduated run around a bezel - is laid out by spacing gems along a curve rather than placing them one by one. The tool walks an existing curve, fits as many stones of the given size and gap as will go, and can build the shared prongs and the seat cutters at the same time, exactly as the ArtisanGemsOnCurve panel does.

The parent here is a curve, not a gem. curveId must already be a curve in the active document, and the row keeps that link for the rest of its life - which is why the facade has ForCurve(curveId) where the single-gem settings have ForGem(gemId), and why the handle exposes CurveId. On a multi-gem object like this one, MotherGemId is empty by design.

Create

row = gemsoncurve.Create(curveId, gemSize = 0, distance = 0,
                         gemShape = None, gemMaterial = None,
                         prongs = False, cutters = False,
                         orientationIds = None)                   # -> IGemsOnCurve

Parameter	Default	Meaning
`curveId`	-	The parent curve - throws if the object is not a curve
`gemSize`	`0` -> tool default `1.5`	Diameter of each stone, mm
`distance`	`0` -> tool default `0.2`	Gap between consecutive stones, mm
`gemShape`	`None` -> `ROUND`	Gem shape name, from the `GemApi` vocabulary
`gemMaterial`	`None` -> `Diamond`	Gem material name, from the `GemApi` vocabulary
`prongs`	`False`	Also build the shared prongs between the stones
`cutters`	`False`	Also bake one cutter per gem, into a separate “Cutters” group
`orientationIds`	`None`	Surfaces or breps to orient the stones onto

All dimensions are millimetres, and 0 keeps the tool default - or the user’s saved gems-by-curve defaults - for that parameter. gemShape and gemMaterial are matched case-insensitively, and hyphens or spaces are normalised to underscores, so "half moon", "HALF-MOON" and "HALF_MOON" all resolve to the same shape; an unknown name throws ArgumentException.

Everything is baked into one group carrying the row’s parameters: the stones on the secondary gems layer, the prongs (when asked for) with the metal material in the same group, and the cutters (when asked for) in their own group on the primary object layer.

Create throws ArgumentException if curveId is not a curve or a vocabulary name is unknown, and InvalidOperationException if the geometry fails or no gems fit on that curve with the size and distance you gave - a short curve with large stones is the usual cause.

Edit

The row is read-only after creation: IGemsOnCurve carries no setters. To change the spacing or the stone, create a new row and Delete() the old one.

What the handle exposes for reading:

Member	Meaning
`CurveId`	The parent curve the row was distributed along
`StoneCount`	How many stones actually fitted
`GemShape`	Shape of the repeated gem template
`GemMaterial`	Material of the repeated gem template
`GemCaratWeight`	Carat weight of a single stone in the row

Plus the shared Id, MotherGemId (empty - the parent is the curve), ObjectType, LayerName, Position, Move(vector) and Delete(). Those two mutations belong inside a Transaction so the edit lands as one undo step.

from ArtisanPlugin.Scripting import GemsOnCurveApi as gemsoncurve

row = gemsoncurve.Create(curveId, gemSize = 1.2, distance = 0.15,
                         gemShape = "ROUND", prongs = True, cutters = True)
print(row.StoneCount, row.GemCaratWeight)

Queries

All(), Find(id), Count(), Selected(), ByLayer(name), ForCurve(curveId).

ForCurve returns every row built on that curve - there can be more than one.