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

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.

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

For reading, the handle reports ProngCount (always positive, the rotation sign is dropped), ProngHeight, ProngDiameterTop, ProngDiameterGirdle and ProngDiameterBottom, 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).