Scripting API

Engraving

from ArtisanPlugin.Scripting import EngravingApi

This is the ArtisanEngraveRing tool: the dedication engraved around a ring band - a date, a name, a line of a vow - not free-form engraving on an arbitrary surface. The tool takes the ring’s inner diameter, wraps the text around that circle at the letter height and spacing you give it, and returns the lettering as engraving curves, plus solid letters when you ask for a thickness.

Create

ids = EngravingApi.Create(text, diameter = 0, angle = 0, height = 1.5,
                          spacing = 0.5, thickness = 0, font = None,
                          fontStyle = "Regular", horizontalAlign = "CENTER",
                          verticalAlign = "CENTER", plane = ...)          # -> [ids]

Parameter	Default	Meaning
`text`	required	The text to engrave - empty or whitespace throws
`diameter`	`0` -> the session’s current finger size (`17.35` when none is set)	Inner diameter of the ring the text wraps around, mm
`angle`	`0`	Rotates the text around the ring, degrees - the tool’s gumball
`height`	`0` -> tool default `1.5`	Cap height of the letters, mm
`spacing`	`0` keeps -> tool default `0.5`	Letter spacing, mm; any non-zero value is taken, including negatives
`thickness`	`0`	`0` gives flat engraving curves only; `> 0` also builds the solid text to that depth, mm
`font`	`None` -> tool default Bienchen	Name of an installed font
`fontStyle`	`None` -> `Regular`	`Regular`, `Bold` or `Italic` (case-insensitive)
`horizontalAlign`	`None` -> `CENTER`	`LEFT`, `CENTER`, `RIGHT` or `JUSTIFY`
`verticalAlign`	`None` -> `CENTER`	`TOP`, `CENTER` or `BOTTOM`
`plane`	omitted or invalid -> the active view’s construction plane, then world XY	The text orientation plane

thickness is the switch that decides what you get. At 0 the tool computes the lettering as engraving curves only - the outlines you would hand to a rotary engraver, or use as a cutter later. Above 0 it also builds the solid text as breps of that depth, which is what you want when the letters are to be raised or subtracted from the band.

Defaults resolve from your saved Engrave Ring defaults when you have any; otherwise from the tool’s TextOnCurve model, seeded with HorizontalAlign = "CENTER" - so a fresh session centres the text even though the bare model would left-align it. Everything you pass explicitly overrides that. The diameter is read from the session’s current finger size unless you give one, and the text is always spread over the full domain of the ring curve, as the panel does.

Create returns a list of Guids, one per object baked, with no handle interface on the facade. The solid text breps go on the primary metal layer and the engraving curves on the primary user layer, and all of them join a single group named Engrave Ring <guid>. That group carries the serialised parameters as user data, which is what makes the result an editable Engrave Ring smart component the panel can re-open later.

An empty text throws ArgumentException before anything is computed, as do an unknown fontStyle or alignment name. When neither curves nor solids come out - in practice an unusable text or a font name that is not installed - Create raises InvalidOperationException with “Engraving computation failed. Check the text and the font name.” and adds nothing. This is a licensed mutation and needs an active document; wrap it in a Transaction so the group and all its parts undo in one step.