Scripting API

Cluster

from ArtisanPlugin.Scripting import ClusterApi as cluster

A cluster surrounds the centre stone with a ring of small stones held individually by prongs on a rail, rather than sunk into a channel - the older, more open cousin of the halo, where metal shows between the stones. The tool builds it as the ArtisanCluster panel does: the rail is laid out around the gem, the small stones spaced along it, and internal, external and central prongs raised to hold them.

Each cluster is built around a mother gem and stays its parametric child - the group stores the computed parameters and the mother’s id in its user data.

Create

c = cluster.Create(gemId, stoneSize = 1.6, stoneDistance = 0.2,
                   distanceToGem = 1.0, prongNumber = 4,
                   prongDiameter = 0.8, railDiameter = 1.0)   # -> ICluster

Parameter	Default	Meaning
`gemId`	-	The mother gem it surrounds; must be a gem in the active document
`stoneSize`	`1.6`	Diameter of each cluster stone, mm
`stoneDistance`	`0.2`	Minimum gap between neighbouring cluster stones, mm
`distanceToGem`	`1.0`	Distance from the mother gem to the cluster stones, mm
`prongNumber`	`4`	Prongs per stone: `3`, `4` or `5` - any other value is rejected
`prongDiameter`	`0.8`	Applied to the internal, external and central prongs alike, mm
`railDiameter`	`1.0`	Diameter of the rail the stones sit on, mm

Millimetres throughout, and 0 keeps the tool default - or the user’s saved defaults for the cluster, when they have stored any.

ClusterApi validates the mother shape. Clusters are only available for ROUND, CUSHION, EMERALD, OVAL, RADIANT and ASSCHER gems - the kernel picks the matching shape variant internally - and anything else throws, as does an id that is not a gem at all.

Everything is baked into a single group: the small stones as diamonds-without-ref on the secondary gems layer, the metal breps as parametric brep objects on the metal layer, with the post-compute parameters and the mother gem in the group’s user data. A cluster that fails to compute throws with the kernel’s message.

Edit

A cluster is read-only after creation. ICluster exposes no setters, so the geometry is fixed by the arguments passed to Create - to change a cluster, delete it and build a new one.

What the handle exposes for reading:

Member	Meaning
`ClusterStoneCount`	How many small stones the cluster ended up with
`ClusterStoneSize`	Computed diameter of those stones, mm
`ClusterStoneWeight`	Carat weight of a single cluster stone
`ClusterTotalWeight`	Carat weight of all the cluster stones together
`GemShape`, `GemMaterial`, `GemCaratWeight`	The mother gem

Plus the shared Id, MotherGemId, ObjectType, LayerName, Position, and the two mutations every parametric object has, Move() and Delete() - both of which belong inside a Transaction.

from ArtisanPlugin.Scripting import ClusterApi as cluster, Transaction

with Transaction.Begin("Cluster"):
    c = cluster.Create(gemId, stoneSize = 1.4, prongNumber = 3)

print(c.ClusterStoneCount, c.ClusterTotalWeight)

Queries

All(), Find(id), Count(), Selected(), ByLayer(name), ForGem(gemId).