Scripting API

Basket

from ArtisanPlugin.Scripting import BasketApi as basket

A basket is the open cage of prongs and rails that sits under a stone: the claws rise past the girdle, the upper rail closes the seat and the base rail ties the prongs together at the bottom - the airy alternative to a solid head. The tool builds it as the ArtisanBasket panel does, baking each basket as its own group carrying the parameters and the mother gem.

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

Create

baskets = basket.Create(gemIds = None, prongs = 4, prongDiameter = 1.5,
                        prongHeight = 4, prongHeightOverGirdle = 0.3,
                        gemInside = 0.35, upperRail = None, baseRail = None,
                        support = "NONE")                       # -> [IBasket]

Create takes a list of gems and returns one IBasket handle per gem, in input order - not a single handle. Each gem gets its own group and its own serialised copy of the model.

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` (rotated)	Prong count; `0` keeps the default. Negative counts give the rotated variant
`prongDiameter`	`1.5`	Sets the top, girdle and bottom prong diameters together, mm
`prongHeight`	`4`	Prong height, mm
`prongHeightOverGirdle`	`0.3`	How high the claw rises above the girdle, mm
`gemInside`	`0.35`	How deep the stone sits inside the basket, mm
`upperRail`	`None`	`None` keeps the default (enabled); `True`/`False` forces it
`baseRail`	`None`	`None` keeps the default (enabled); `True`/`False` forces it
`support`	`"NONE"`	Prong support: `NONE`, `SINGLE` or `DOUBLE` - any other value is rejected
`prongMode`	`None` -> `ROUND`	`ROUND`, `CUSTOM` (the `prongProfile` section; a profile alone implies it, and the section starts turned 90 degrees unless `prongRotation` says otherwise) or `CLAW` - see Prong modes and claws
`prongType`	`None` -> `SINGLE`	Prongs per position: `SINGLE`, `DOUBLE` (a pair side by side) or `TRIPLE` (the pair plus a thinner prong between them). `ROUND` takes all three, `CLAW` `SINGLE` or `DOUBLE` (the Double Claw), `CUSTOM` only `SINGLE`
`overlap`	`0`	`DOUBLE` / `TRIPLE`: how much the prongs of a pair, and the Triple’s middle, cross, mm. `0` = they touch; negative values are rejected
`vProngs`	`False`	V prongs on the sharp corners of the girdle (`ROUND` only) - see below
`vThickness`, `vArmLength`	`0`	Width of the V and how far each arm runs along the girdle, mm; `0` = in proportion to the prong diameter (0.8x and 1.2x)

Millimetres throughout, and 0 keeps the tool default - or the user’s saved defaults for the basket, when they have stored any. Prong and both rails start from the default CLOSED_PROFILE asset.

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 gem in the list that is not really a gem throws, and a basket that fails to compute throws with the kernel’s message.

Double, Triple and V prongs

prongType gives every prong position a pair (DOUBLE) or a pair plus a thinner middle prong (TRIPLE), slid along the girdle until their tops touch - overlap makes them cross by that much. Each position keeps a single support post.

vProngs = True replaces the round prong on every position that sits on a sharp corner of the girdle with a V that wraps it: the four corners of a princess, the tip of a pear or a heart, the tips of a marquise with 6 prongs (with 4 prongs they hold its sides, so there is no corner), the corners of a trillion. The V is built from the stone’s own outline; the other positions keep their prongs.

from ArtisanPlugin.Scripting import BasketApi as basket, Transaction

with Transaction.Begin("Double prongs, V on the corners"):
    b = basket.Create([princessId], prongType = "DOUBLE", overlap = 0.1, vProngs = True)[0]
    b.Prong.SetVArmLength(1.4)

Through MCP, add_basket_setting takes prong_type, overlap, v_prongs, v_thickness and v_arm_length; later, edit_object {"prong": {"type": "TRIPLE", "overlap": 0.05}}.

The factory values are sized for a 5 mm stone and scale to each gem, as the panel does; values you pass explicitly are used as given.

Rails

Both rails (UpperRail and BaseRail on the handle, both IBasketRail) have two section modes:

DEFAULT: an elliptical section sized by Width and Height.
CUSTOM: the rail’s CLOSED_PROFILE asset.

A rail profile only shapes the section in CUSTOM mode. Giving one therefore switches the rail to CUSTOM, whether you pass upperRailProfile / baseRailProfile to Create or call SetProfile on the rail. SetMode("DEFAULT") goes back to the ellipse.

from ArtisanPlugin.Scripting import AssetsApi as assets, BasketApi as basket, Transaction

railProfile = assets.List("CLOSED_PROFILE")[0].Name      # pick one from your library

with Transaction.Begin("Custom upper rail"):
    b = basket.Create([gemId], upperRailProfile = railProfile)[0]
    print(b.UpperRail.Mode)            # CUSTOM
    b.BaseRail.SetWidth(0.9)

Through MCP, pass upper_rail_profile / base_rail_profile to add_basket_setting. edit_object {"upper_rail": {"mode": "DEFAULT"}} goes back to the ellipse.

Create also takes element= to start from a saved Basket element (the factory BA001… included), and the handle’s SetElement(name) applies one to an existing basket, keeping its gem. The Python reference lists every Create argument and rail setter.

Edit

Create, Find and All return an IBasket handle. Each setter regenerates the basket in place - the group keeps its id so the handle stays valid, while its member objects are rebuilt:

Setter	What it changes
`SetProngCount(n)`	Prong count; `0` is rejected, negatives give the rotated variant
`SetProngDiameter(mm)`	Top, girdle and bottom diameters at once - must be > 0
`SetProngHeight(mm)`	Prong height - must be > 0
`SetProngMode(mode)`	`ROUND`, `CUSTOM` or `CLAW`; the claw values live in the `Prong` section - see Prong modes and claws
`Prong.SetType(type)` / `Prong.SetOverlap(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`
`Prong.SetVProngs(on)` / `Prong.SetVThickness(mm)` / `Prong.SetVArmLength(mm)`	V prongs and their size; `0` goes back to automatic. The getters report the size actually built, never 0

For reading, the handle reports ProngCount (always positive, the rotation sign is dropped), ProngHeight, ProngDiameterTop, ProngDiameterGirdle, ProngDiameterBottom and ProngMode, plus GemShape, GemMaterial, GemCaratWeight and the shared Id, MotherGemId, LayerName, Position, Move() and Delete().

from ArtisanPlugin.Scripting import BasketApi as basket, Transaction

with Transaction.Begin("Baskets under the selection"):
    for b in basket.Create(prongDiameter = 1.1, support = "SINGLE"):
        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), ByGemMaterial(name), ForGem(gemId).