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
centerProngs	None	True adds prongs of the centre stone’s own (the Halo’s); any other centerProng* value implies it. Off by default
centerProngMode	None -> ROUND	ROUND, CUSTOM or CLAW - see Prong modes and claws
centerProngType	None -> SINGLE	SINGLE, DOUBLE or TRIPLE; CLAW takes SINGLE or DOUBLE, CUSTOM only SINGLE
centerProngCount, centerProngDiameter, centerProngOverlap	tool	Prong positions round the stone, diameter (mm), and how much the prongs of a pair cross (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

Create, Find and All return an ICluster handle. Each setter regenerates the cluster in place (the group keeps its id):

Setter	What it changes
SetStoneSize, SetStoneDistance, SetDistanceToGem, SetStonesRotation, SetStonesZPosition	The cluster stones
SetProngCount (3, 4 or 5), SetProngDiameter (all three families), SetInternalProngDiameter, SetExternalProngDiameter, SetCentralProngDiameter, SetProngOrientation (CURVE or CENTER)	The prongs the cluster stones share
SetRailDiameter1/2, SetRailMoveInZ1/2, SetDoubleRail, SetBaseWidth, SetBaseHeight, SetBaseMoveInZ, SetFilletFactor	The rails and the base
CenterProngs	The centre stone’s own prongs: SetEnabled, SetMode, SetType, SetCount, SetDiameter, SetOverlap, SetGemInside, SetHeightOverGirdle, the claw values, SetBridgeMode (CURVED or STRAIGHT, how they run into the main gem rail)…

For reading, the handle reports ClusterStoneCount, ClusterStoneSize, ClusterStoneWeight and ClusterTotalWeight, plus GemShape, GemMaterial, GemCaratWeight for the mother gem and the shared Id, MotherGemId, ObjectType, LayerName, Position, Move() and Delete().

from ArtisanPlugin.Scripting import ClusterApi as cluster, Transaction

with Transaction.Begin("Cluster with double claws on the centre stone"):
    c = cluster.Create(gemId, stoneSize = 1.4, prongNumber = 3,
                       centerProngMode = "CLAW", centerProngType = "DOUBLE")
    c.CenterProngs.SetClawHeight(0.1)

print(c.ClusterStoneCount, c.ClusterTotalWeight)

Through MCP, create_cluster takes the same values as center_prong_*.

Queries

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