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"`	Claw type, applied to every prong: `ROUND`, `CUSTOM`, `OFFSET`, `DOUBLE` (the 2-2 presets), `CLAW` or `TRIPLE` (3-3)
`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

For reading, the handle reports ProngCount and RailCount, plus ProngHeight and ProngDiameter - 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.

Queries

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