Scripting API

Hidden halo

from ArtisanPlugin.Scripting import HiddenHaloApi as hidden

A hidden halo is the ring of small stones tucked under the centre stone, set into a rail that faces outward so the sparkle only shows from the side profile - invisible from above, which is the whole point of the style. The tool builds it as the ArtisanHiddenHalo panel does: a parametric rail under the girdle, the small stones spaced along it, and the channel and prongs that hold them.

Each hidden halo is built under a mother gem and stays its parametric child. Unlike the ordinary halo, the rail does not follow the gem’s outline: its shape is chosen with railShape, which is why any centre-gem shape is accepted.

Create

h = hidden.Create(gemId, stoneSize = 0.9, stoneDistance = 0.10,
                  channelWidth = 1.1, channelHeight = 1.0,
                  railShape = "CIRCLE", prongType = "NONE",
                  profile = None)                            # -> IHiddenHalo

Parameter	Default	Meaning
`gemId`	-	The mother gem it sits under; must be a gem in the active document
`stoneSize`	`0.9`	Diameter of each hidden-halo stone, mm
`stoneDistance`	`0.10`	Minimum gap between neighbouring stones, mm
`channelWidth`	`1.1`	Width of the channel carrying the stones, mm
`channelHeight`	`1.0`	Height of that channel, mm
`railShape`	`"CIRCLE"`	`CIRCLE`, `SQUARE` (opens at 5.50 x 5.50) or `OVAL` (5.50 x 8.70) - any other value is rejected
`prongType`	`"NONE"`	`NONE`, `SHARED` or `SCALLOPED` - any other value is rejected
`profile`	`None`	Resolves a `CHANNEL_PROFILE` asset by name; omitted = the tool’s `014` channel profile, falling back to the type default

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

Every centre-gem shape is accepted - the shape check is there for symmetry with the other halo tools, but the rail is parametric rather than traced from the gem, so no shape is rejected. An id that is not a gem still throws.

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

Edit

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

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

For reading, the handle reports RailShape, StoneCount, StoneSize, StoneWeight and TotalStoneWeight, plus GemShape, GemMaterial, GemCaratWeight and the shared Id, MotherGemId, LayerName, Position, Move() and Delete(). The rail shape is read-only once built - pick it at Create.

from ArtisanPlugin.Scripting import HiddenHaloApi as hidden, Transaction

h = hidden.Selected()[0]
with Transaction.Begin("Finer hidden halo"):
    h.SetStoneSize(0.8)
    h.SetStoneDistance(0.08)

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

Queries

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