Halo

from ArtisanPlugin.Scripting import HaloApi as halo

A halo is the ring of small stones that frames the centre stone, sitting in a channel that follows the outline of the gem so the piece reads larger and brighter than the centre alone. The tool builds it as the ArtisanHalo panel does: it walks the mother gem’s outline, spaces the small stones around it and raises the channel and prongs that hold them.

Each halo 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

h = halo.Create(gemId, stoneSize = 1.2, stoneDistance = 0.2,
                distanceToGem = 1.2, channelWidth = 1.5, channelHeight = 1.5,
                prongType = "NONE", profile = None)          # -> IHalo

Parameter	Default	Meaning
gemId	-	The mother gem it surrounds; must be a gem in the active document
stoneSize	1.2	Diameter of each halo stone, mm
stoneDistance	0.2	Minimum gap between neighbouring halo stones, mm
distanceToGem	1.2	Distance from the mother gem to the halo channel, mm
channelWidth	1.5	Width of the channel carrying the stones, mm
channelHeight	1.5	Height of that channel, mm
prongType	"NONE"	NONE, SHARED or SCALLOPED - any other value is rejected
profile	None	Resolves a CHANNEL_PROFILE asset by name; omitted = the default profile

Millimetres throughout, and 0 keeps the tool default - or the user’s saved defaults for the halo, when they have stored any. Passing an explicit profile skips the saved defaults entirely, because those defaults replace the whole model.

HaloApi validates the mother shape. Halos are only available for ROUND, CUSHION, EMERALD, OVAL, RADIANT, ASSCHER and PEAR gems; 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 on the metal layer, with the post-compute parameters and the mother gem in the group’s user data. A halo that fails to compute throws with the kernel’s message.

Edit

Create, Find and All return an IHalo handle. Each setter regenerates the object in place, keeping its Guid and undo intact:

Setter	What it changes
SetStoneSize(mm)	Diameter of the halo stones - must be > 0
SetStoneDistance(mm)	Minimum gap between halo stones - must be > 0

For reading, the handle reports HaloStoneCount, HaloStoneSize, HaloStoneWeight and HaloTotalWeight, plus GemShape, GemMaterial, GemCaratWeight and the shared Id, MotherGemId, LayerName, Position, Move() and Delete().

from ArtisanPlugin.Scripting import HaloApi as halo, Transaction

h = halo.Selected()[0]
with Transaction.Begin("Bigger halo stones"):
    h.SetStoneSize(1.4)

Mutations belong inside a Transaction so the whole edit lands as one undo step.

Queries

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