Scripting API

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,
                        fitToGem = False, clearance = None)      # -> [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, % of gem height
`heightCrown`	`0` -> `34`	Crown section height, % of gem height
`heightGirdle`	`0` -> `3`	Girdle band, above and below the girdle outline, % of gem height
`heightPavilion`	`0` -> `71`	Depth of the pavilion cone tip below the girdle, % of gem 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
`fitToGem`	`False`	`True` computes `gemInside`, `heightGirdle` and `heightPavilion` gem by gem, so the cutter encloses the real stone. See Fit to gem
`clearance`	unset -> `0.05`	With `fitToGem`: the gap between the stone and the cutter, mm

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])

Fit to gem

The panel and CutterApi build the same geometry. The size arguments scale the gem outline, and the pavilion is a straight cone from the girdle band to a single point heightPavilion % below it. On a round brilliant that cone follows the stone. On fancy cuts (cushion, oval, pear…) the real pavilion is convex, so the cone can sit inside the stone just below the girdle.

fitToGem = True solves this for every gem. It measures the gem’s real mesh and computes the three values that make the cutter enclose the girdle and pavilion with clearance mm:

gemInside grows until the girdle zone clears the outline.
heightGirdle extends the band down to the lowest point that still hugs the outline. It never goes below the value you gave.
heightPavilion deepens the cone until every pavilion vertex, and the culet, is covered.

The crown, top and drill are design choices, so they stay as given. The panel’s Fit to gem button does the same, and gives the same values.

from ArtisanPlugin.Scripting import CutterApi as cutter, Transaction

with Transaction.Begin("Cutters for the fancy cuts"):
    cutters = cutter.Create(gemIds, fitToGem = True, clearance = 0.08)

Edit

Create, Find and All return an ICutter handle. Its setters regenerate the cutter in place, keeping the same id. Unlike Create, they take literal values, so 0 is a real zero:

Member	Meaning
`SizeTop` / `SizeBottom` / `SizeDrill`	The three widths, % of gem size. Setters: `SetSizeTop`, `SetSizeBottom`, `SetSizeDrill`
`HeightTop` / `HeightCrown` / `HeightGirdle` / `HeightPavilion` / `HeightDrill`	The section heights, %. Setters: `SetHeightTop`… `SetHeightDrill` (`0` = no drill body)
`GemInside`	Millimetres added to the gem outline. Setter: `SetGemInside` (signed)
`DrillType`	`0` gem shape, `1` round, `2` square, `3` hexagon. Setter: `SetDrillType`
`FitToGem(clearance = None)`	Refits `GemInside`, `HeightGirdle` and `HeightPavilion` to this cutter’s gem, with a default clearance of 0.05 mm
`GemShape` / `GemMaterial` / `GemCaratWeight`	The gem this cutter was built for
`Id` / `MotherGemId` / `ObjectType` / `LayerName` / `Position`	The structural surface

Move(vector) and Delete() are available too. Wrap mutations in a Transaction.

from ArtisanPlugin.Scripting import CutterApi as cutter, Transaction

with Transaction.Begin("Refit the selected cutters"):
    for c in cutter.Selected():
        c.FitToGem(0.05)
        print(c.GemShape, c.GemInside, c.HeightPavilion)

Through MCP, create_cutters takes fit_to_gem and clearance, and edit_object {"fit_to_gem": true} refits an existing cutter.

Queries

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