Scripting API

Create from curves

from ArtisanPlugin.Scripting import ReliefApi as relief

A 2.5D relief is a height field: a flat rectangular grid laid on a plane, where every node is pushed up (or down) by some amount and the result is meshed. This entry point starts from closed curves - a monogram, a leaf, a coat of arms drawn flat - and fills them with a cross-section profile so they swell out of the plane. It is the classic puffed relief, and the same operation the panel calls a profile layer.

Usage

id = relief.CreateFromCurves(curveIds, height = 0, profile = None,
                             startingHeight = 0, fixedProfileWidth = 0, feather = 0,
                             worldWidth = 0, worldHeight = 0, resolution = 0,
                             workbench = None, solid = True, capDistance = 0,
                             deleteBase = False)                  # -> the baked mesh's id

Parameter	Default	Meaning
`curveIds`	-	Closed curves to fill; at least one is required
`height`	`0` (means `1.0`)	Peak height of the profile, mm. Negative engraves instead of raising
`profile`	`None` (means `"Round"`)	Cross-section by name - `Round`, `Smooth`, `Chamfer`, `Plateau`, or any of your saved profiles; see `ProfileNames()`
`startingHeight`	`0`	Z offset where the profile takes off, mm. A real `0`, not a default
`fixedProfileWidth`	`0`	`0` inflates: the profile peaks at the deepest point inside the curve set. Any value `> 0` makes the profile span exactly that width, mm, in from the curve edge
`feather`	`0`	Edge blend distance, mm. A real `0`, meaning a hard edge
`worldWidth`	`0`	Workbench width, mm - see below
`worldHeight`	`0`	Workbench height, mm - see below
`resolution`	`0` (means `512`)	Grid nodes along the larger side, 64-4096
`workbench`	`None`	The `Plane` the relief sits on; the grid is centred on its origin
`solid`	`True`	`True` bakes a closed solid, `False` an open relief mesh
`capDistance`	`0` (means `1.0`)	Solid thickness below the base plane, mm - ignored when `solid = False`
`deleteBase`	`False`	`True` trims away grid cells no operation touched

The call returns the Guid of a plain Rhino mesh - the baked relief, added to the document on the current layer with no group, no parametric tag and nothing to re-drive it from. It is added inside an undo record named “Relief”, which collapses into the surrounding Transaction when you have one, and the views are redrawn before the id comes back. The source curves are left where they are.

height is the one to watch: 0 means the 1.0 mm default, so there is no way to ask for a flat fill. startingHeight, fixedProfileWidth and feather are the opposite - their 0 is a genuine value, and fixedProfileWidth = 0 specifically selects inflate mode rather than “use the default width”. Everything is in model units (mm in a standard Artisan document).

The workbench

The workbench is the plane and the rectangle of grid the relief is computed on, and here it is fitted to the curves you passed.

With workbench left as None, the plane keeps world XY axes but its origin moves to the centre of the curves in X and Y and to their lowest Z, so the whole profile rises above the plane - flat curves drawn on a raised construction plane still work. Any of worldWidth / worldHeight left at 0 is then fitted: the curve bounding-box corners are remapped into plane space and the side is taken as twice the largest absolute local coordinate, plus 10% margin. Each side is fitted independently, so passing only worldWidth fits the height and honours your width.

Pass an explicit workbench and it is used exactly as given - it is never re-centred - but the size fit stays symmetric about that plane’s origin, so an off-centre plane produces a much larger grid than you might expect. If the curves somehow yield no valid bounds, the sides fall back to 50 x 50 mm.

Errors

An empty or None curveIds throws Pass at least one closed curve. Every id must resolve to a curve in the active document and be closed: Object <id> is not a curve in this document. or Curve <id> is not closed; relief regions need closed curves.

A negative fixedProfileWidth throws fixedProfileWidth cannot be negative., and an unrecognised profile name throws Unknown relief profile '<name>'. Use one of: ... listing everything ProfileNames() returns. Names match case-insensitively.

Workbench settings are validated before anything is computed: Workbench size cannot be negative., Resolution must be between 64 and 4096 (0 = default 512)., capDistance cannot be negative.

Then the relief is computed at full resolution and meshed. If the kernel rejects the parameters you get Relief computation failed with the given parameters (...); if the meshing stage fails, Relief meshing failed (...); if the result is empty, The relief has nothing to build; enable at least one operation. The call also needs an active document and a valid licence.

One shot versus the project stack

This is a one-shot creator: it builds a throwaway single-operation project, bakes it and hands you the mesh. The document’s saved relief project is not read, not written and not disturbed, so the ArtisanRelief panel will show whatever it showed before.

When you need more than one layer - a puffed monogram with an image or a 3D texture merged over it, or several profile passes with different combine modes - or you want the user to keep refining the result in the panel afterwards, use the step-by-step route instead: SetupProject, then AddProfile and friends, then Bake. See the project stack.

from ArtisanPlugin.Scripting import ReliefApi as relief, Transaction

with Transaction.Begin("Puffed monogram"):
    mesh_id = relief.CreateFromCurves(letter_ids, height = 1.2, profile = "Smooth",
                                      feather = 0.15, solid = False)