Scripting API

Advanced basket

from ArtisanPlugin.Scripting import AdvancedBasketApi as advbasket

An advanced basket is the open cage of claws and rails that sits under a stone, but built as a free layout rather than a fixed pattern: it stores one entry per prong and per rail, each with its own position, section and dimensions, so a basket can mix claw types or hang its rails at any depth. The tool builds it as the ArtisanAdvancedBasket panel does, and this facade lays the prongs and rails out evenly, the way the panel’s presets do.

Each basket is built under a mother gem and stays its parametric child.

Create

baskets = advbasket.Create(gemIds = None, prongs = 4, prongMode = "ROUND",
                           prongDiameter = 1.5, prongHeight = 4,
                           rails = None, railWidth = 1.5,
                           profile = None)              # -> [IAdvancedBasket]

Create takes a list of gems and returns one IAdvancedBasket handle per gem, in input order - not a single handle. Each gem gets its own group and its own serialised copy of the model, so the mother gem stored in each basket is the right one.

Parameter	Default	Meaning
`gemIds`	`None`	The mother gems. `None` or empty = the gems currently selected in the document; throws if that leaves nothing
`prongs`	`4`	Prong count, laid out evenly around the gem. `0` keeps the saved layout, or falls back to the tool’s `4` preset (prongs at the diagonals) when there is none. Negative is rejected
`prongMode`	`"ROUND"`	Prong type, applied to every prong: `ROUND`, `CUSTOM`, `OFFSET`, `DOUBLE` (the 2-2 presets), `CLAW` or `TRIPLE` (3-3); `DEFAULT` and `CIRCLE` also mean `ROUND` - see Prong modes and claws
`prongDiameter`	`1.5`	Sets the top and bottom prong diameters together, mm
`prongHeight`	`4`	Prong height, mm
`rails`	`None`	`None` keeps the saved rails (a fresh basket has none); `0` = no rails, `1` = one rail 1 mm under the girdle, `2` adds a second at 3.66 mm, and further rails keep that 2.66 mm spacing. Negative is rejected
`railWidth`	`1.5`	Rail width, applied to every rail, mm
`profile`	`None`	Resolves a `CLOSED_PROFILE` asset by name for the prongs; it also switches them to `CUSTOM` mode unless `prongMode` says otherwise. `None` keeps each mode’s built-in section

Millimetres throughout, and 0/None keeps the tool default - or the user’s saved defaults for the advanced basket, when they have stored any. Prong positions are the tool’s preset fractions around the gem curve, so 4 prongs land on the diagonals and 6 sit rotated with a pair on the Y axis.

Every part of each basket is baked into its own group, put on the metal material, with the parameters and the mother gem stored in the group’s user data. Any id in the list that is not really a gem throws, and a basket that fails to compute throws with the kernel’s message.

Edit

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

Setter	What it changes
`SetProngCount(n)`	Rebuilds the prong set evenly spaced, cloning the first existing prong’s settings; must be >= 1
`SetProngDiameter(mm)`	Top and bottom diameters of every prong at once - must be > 0
`SetProngHeight(mm)`	Height of every prong - must be > 0
`SetRailCount(n)`	Rebuilds the rail set at the preset depths, cloning the first existing rail’s settings; `0` removes them, negative is rejected
`SetProngMode(mode)`	Every prong: `ROUND`, `CUSTOM`, `CLAW`, `OFFSET`, `DOUBLE` or `TRIPLE`
`SetClawCapDistance` / `SetClawCapHeight` / `SetClawTipWidth` / `SetClawTipSmoothness`	The claw tips of every prong - see Prong modes and claws

For reading, the handle reports ProngCount, RailCount and ProngMode (MIXED when the prongs differ), plus ProngHeight, ProngDiameter and the four claw values - the per-prong values of the first prong, since each entry carries its own, and 0 when there are none. It also reports GemShape, GemMaterial, GemCaratWeight and the shared Id, MotherGemId, LayerName, Position, Move() and Delete().

from ArtisanPlugin.Scripting import AdvancedBasketApi as advbasket, Transaction

with Transaction.Begin("Advanced baskets under the selection"):
    for b in advbasket.Create(prongMode = "DOUBLE", rails = 2):
        b.SetProngHeight(3.6)

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

Every prong and rail value, by path

Everything the panel’s per-prong and per-rail editors hold is reachable by path: ParametersJson shows the model, GetParameter(path) reads one value and SetParameter(path, value) writes one, as text. Paths ignore case and underscores (Prongs[0].Inclination or prongs[0].inclination), and [*] sets the value on every prong or rail. Enum fields, such as a prong’s Mode, take their number; use SetProngMode for the mode.

from ArtisanPlugin.Scripting import AdvancedBasketApi as advbasket, Transaction

b = advbasket.Selected()[0]
with Transaction.Begin("Prong bow and rail"):
    b.SetParameter("prongs[*].inclination", "12")    # every prong
    b.SetParameter("prongs[0].gem_inside", "0.2")    # just the first one
    b.SetParameter("rails[1].width", "1.2")
print(b.GetParameter("Prongs[3].Inclination"))       # 12

Over MCP, edit_object takes the same paths as keys: {"object_id": "…", "prongs[*].inclination": 12}.

Some values only matter in certain modes or on certain stones:

Value	Used by
`Angle` (the panel’s “Separation”)	`DOUBLE` and `TRIPLE` prongs
`MiddleGemInside` (the panel’s “Exterior gem inside”)	`TRIPLE` prongs
`Tangent`	Stones that aren’t round, with `CUSTOM`, `OFFSET` or `CLAW` prongs, or `DOUBLE` / `TRIPLE` with `BottomToCenter` off
`Rails[i].FilletRadius`	Rounds the corners of the rail’s path, so it shows on cuts with corners (princess, baguette, marquise tips, heart, trillion), not on a round or oval stone

Queries

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