Cutters

from ArtisanPlugin.Scripting import CutterApi as cutter

A cutter is the solid that opens the seat: the cone, the bearing and the drill hole a stone needs in order to sit in metal. You do not print the cutter - you build one per gem, then subtract them all from the piece with BooleanApi.Difference (see Gems) as the final “make it solid” step.

Cutters are built for a mother gem and stay linked to it. Unlike the other settings, Create works on a list of gems - or on the current selection - and returns one handle per gem, in input order.

Create

cutters = cutter.Create(gemIds = None, sizeTop = 0, sizeBottom = 0, sizeDrill = 0,
                        heightTop = 0, heightCrown = 0, heightGirdle = 0,
                        heightPavilion = 0, heightDrill = -1,
                        gemInside = None, drillType = -1)        # -> [ICutter]

Parameter	Default	Meaning
gemIds	None	The gems to cut. None or empty uses the gems currently selected
sizeTop	0 -> 40	Width of the cutter at the top, % of gem size
sizeBottom	0 -> 40	Width at the bottom, % of gem size
sizeDrill	0 -> 40	Width of the drill body, % of gem size
heightTop	0 -> 100	Height above the table, %
heightCrown	0 -> 34	Crown section height, %
heightGirdle	0 -> 3	Girdle section height, %
heightPavilion	0 -> 71	Pavilion section height, %
heightDrill	-1 -> 200	Drill body height, %. See below
gemInside	unset	Millimetres added to the gem outline; negative shrinks it
drillType	-1 -> saved default	0 gem shape, 1 round, 2 square, 3 hexagon

0 keeps the tool default, or your saved Cutter defaults when you have some - except for heightDrill, which uses -1 as “keep the default” because 0 is meaningful there: heightDrill = 0 disables the drill body entirely. drillType follows the same pattern with -1, and any value above 3 raises.

Passing no gems and having nothing selected raises; so does any id in gemIds that is not a gem. Each cutter gets its own copy of the parameter model with its own gem baked in, all the new cutters land on the primary object layer, and they are added to a single new group so you can grab them in one go.

from ArtisanPlugin.Scripting import CutterApi as cutter, BooleanApi as boolean, Transaction

with Transaction.Begin("Cut the seats"):
    cutters = cutter.Create(gemIds, sizeDrill = 55, drillType = 1)
    boolean.Difference([shankId], [c.Id for c in cutters])

Edit

Create, Find and All return an ICutter handle. It has no parametric setters: a cutter is read-only apart from Move(vector) and Delete(), both of which belong inside a Transaction. To change a dimension, delete the cutter and create it again.

What it exposes for reading:

Member	Meaning
SizeTop / SizeBottom / SizeDrill	The three widths, % of gem size
HeightTop / HeightCrown / HeightPavilion / HeightDrill	The section heights, %
GemInside	Millimetres added to the gem outline
DrillType	0 gem shape, 1 round, 2 square, 3 hexagon
GemShape / GemMaterial / GemCaratWeight	The gem this cutter was built for
Id / MotherGemId / ObjectType / LayerName / Position	The structural surface

Note that heightGirdle can be set at creation but is not exposed on the handle for reading.

from ArtisanPlugin.Scripting import CutterApi as cutter

for c in cutter.All():
    print(c.GemShape, c.SizeTop, c.HeightDrill, c.DrillType)

Queries

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