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"	How the halo stones are held: NONE, SHARED or SCALLOPED - any other value is rejected
profile	None	Resolves a CHANNEL_PROFILE asset by name; omitted = the default profile
prongMode	None	The mother gem’s prongs: ROUND, CUSTOM (the prongProfile section; a profile alone implies it) or CLAW - see Prong modes and claws
centerProngType	None -> SINGLE	The mother gem’s prongs per position: SINGLE, DOUBLE or TRIPLE, as on the basket. ROUND takes all three, CLAW SINGLE or DOUBLE, CUSTOM only SINGLE. Not prongType, which is how the halo stones are held
prongOverlap	0	DOUBLE / TRIPLE: how much the centre prongs of a pair cross, mm. 0 = they touch

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, PEAR, HEART and MARQUISE 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
SetProngMode(mode)	The mother gem’s prongs: ROUND, CUSTOM or CLAW, with their claw values (SetClawGemInside, SetClawHeight, SetClawTension, SetClawOnCurve) - see Prong modes and claws
SetCenterProngType(type) / SetProngOverlap(mm)	SINGLE, DOUBLE or TRIPLE within what the mode takes, and how much the pair crosses. Becoming CUSTOM, or CLAW from a TRIPLE, sets the type back to SINGLE

For reading, the handle reports HaloStoneCount, HaloStoneSize, HaloStoneWeight and HaloTotalWeight, ProngMode, CenterProngType, ProngOverlap and the claw values, 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)
    h.SetCenterProngType("DOUBLE")

Through MCP, create_halo takes center_prong_type and prong_overlap; edit_object changes them later.

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

Queries

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