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
`secondChannel`	`None`	`True` builds a second channel under the first; `False` keeps one even when the saved defaults have two
`secondChannelWidth`, `secondChannelHeight`	first channel’s	Section of the second channel, mm
`secondChannelDistanceToGem`	first channel’s	Radial gap to the centre gem, mm
`secondChannelPositionZ`	one channel height under the first	Depth under the girdle, mm; positive lowers it
`secondChannelRotation`	first channel’s	Section rotation, degrees
`secondChannelProfile`	first channel’s	`CHANNEL_PROFILE` asset for the second channel

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.

Second channel

A second ring of stones under the first, for a double hidden halo. It carries the same stones and setting as the first, but no centre prongs of its own: the first ring’s prongs run past it, and a stone they pass through is dropped as on the first ring.

from ArtisanPlugin.Scripting import HiddenHaloApi as hidden, Transaction

with Transaction.Begin("Double hidden halo"):
    h = hidden.Create(gemId, secondChannel = True)
    h.SetSecondChannelPositionZ(5.2)

Through MCP, create_hidden_halo takes second_channel and the second_channel_* values.

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
`SetSecondChannel(on)`	Adds or removes the second channel
`SetSecondChannelWidth` / `Height` / `PositionZ` / `Rotation` / `DistanceToGem` / `BrightCut` / `InnerWidth` / `InnerHeight` / `Profile`	The second channel’s section, position and inner opening

For reading, the handle reports RailShape, SecondChannel and its values, 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).