Scripting API

Create from image

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 - the engraved plaque, the puffed monogram, the textured signet face. This entry point starts from a grayscale image: pixel brightness becomes height, white highest, and the picture is either fitted to the whole workbench or clipped into a set of closed curves.

Usage

id = relief.CreateFromImage(imagePath, height = 0, invert = False, scale = 0,
                            regionCurveIds = None,
                            worldWidth = 0, worldHeight = 0, resolution = 0,
                            workbench = None, solid = True, capDistance = 0,
                            deleteBase = False)                  # -> the baked mesh's id

Parameter	Default	Meaning
`imagePath`	-	PNG, JPG, BMP or TIFF file on disk; pixel brightness maps to height
`height`	`0` (means `1.0`)	Height at pure white, mm. Negative engraves instead of raising
`invert`	`False`	`True` maps black to the highest point
`scale`	`0` (means `1.0`)	Multiplier over the fitted image size
`regionCurveIds`	`None`	Closed planar curves: the image fits their bounds and is clipped to their interior. Omitted, the image is centred on the workbench keeping its aspect ratio
`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.

Note that height = 0 and scale = 0 are defaults, not values: you cannot ask for a zero-height image this way. 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. The resolution of the fit depends on whether you passed region curves, because those are the only inputs this creator can measure.

With regionCurveIds, and 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 all the height sits above the plane. Any of worldWidth / worldHeight left at 0 is then fitted: the curve 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.

Without region curves there is nothing to measure. The plane falls back to plain world XY at the origin, and worldWidth / worldHeight left at 0 fall back to 50 x 50 mm. 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.

Errors

The image is checked first: a blank path or a file that is not on disk throws Image file not found: <path>. Region curves must resolve 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.

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

from ArtisanPlugin.Scripting import ReliefApi as relief, Transaction

with Transaction.Begin("Engraved plaque"):
    mesh_id = relief.CreateFromImage(r"C:\art\crest.png", height = 0.6,
                                     regionCurveIds = [outline_id],
                                     resolution = 1024, capDistance = 0.8)