Scripting API

Create from geometry

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 geometry already in the document - meshes, breps, extrusions or SubDs - projected straight down onto the workbench, so the height of each object above the plane becomes the relief. It is how a modelled ornament gets flattened into something a mill or a wax printer can take as a plaque.

Usage

id = relief.CreateFromGeometry(objectIds, feather = 0,
                               worldWidth = 0, worldHeight = 0, resolution = 0,
                               workbench = None, solid = True, capDistance = 0,
                               deleteBase = False)                # -> the baked mesh's id

Parameter	Default	Meaning
`objectIds`	-	Meshes, breps, extrusions or SubDs to project; at least one is required
`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

There is no height here: the projection takes its heights from the objects themselves, and feather is the only shaping parameter. Anything an object hides beneath itself - undercuts, hollows, back faces - is lost, which is what makes the result 2.5D.

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 objects are left untouched; delete them yourself if the relief is meant to replace them. 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 bounding boxes of the objects you passed.

With workbench left as None, the plane keeps world XY axes but its origin moves to the centre of the objects in X and Y and to their lowest Z - so the plane sits right under the geometry and the whole projected height is positive. Any of worldWidth / worldHeight left at 0 is then fitted: the 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 objects yield no valid bounds, the sides fall back to 50 x 50 mm. The plane’s direction is what decides the projection, so a tilted or reversed workbench is how you relieve something from an angle other than straight down the world Z.

Errors

An empty or None objectIds throws Pass at least one mesh, brep, extrusion or SubD. Every id must resolve in the active document - Object <id> was not found in this document. - and must be a mesh, a SubD, or something with a brep form: Object <id> is not a mesh, brep, extrusion or SubD. Curves, points and annotations are rejected here.

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 projected ornament with a texture or an image merged over it, or subtracted from a puffed base - or you want the user to keep refining the result in the panel afterwards, use the step-by-step route instead: SetupProject, then AddGeometry and friends, then Bake. See the project stack.

from ArtisanPlugin.Scripting import ReliefApi as relief, Transaction

with Transaction.Begin("Flatten ornament"):
    mesh_id = relief.CreateFromGeometry(ornament_ids, feather = 0.2,
                                        resolution = 1024, capDistance = 1.5)