Scripting API

Operations

from ArtisanPlugin.Scripting import ReliefApi as relief

Seven kinds of layer can be appended to the document’s relief project — the puffed curve fill of a signet crest, a flat engraved border, a scanned monogram, a knurled texture over a band, a modelled ornament flattened top-down — plus the two brushes, dabbed programmatically. Each call only records the layer; the height field is not evaluated until you bake or export.

All five share two trailing parameters:

Parameter	Default	Meaning
`combine`	`"Add"`	How this layer merges into what the operations below already built. The full vocabulary is on The project stack
`name`	`None`	The label on the panel’s card. `None` auto-names it `"Profile 3"`, `"Image 4"`… from the stack position

If the document has no relief project yet, the first Add* call creates one auto-fitted to that operation’s own inputs (world XY centred under them, +10% margin, 512 nodes, closed solid, 1 mm cap). To control the workbench yourself, call SetupProject before adding — its settings persist and every Add* builds on them. Lengths are in millimetres. Mutations belong inside a Transaction.

Add a curve profile

op_id = relief.AddProfile(curveIds, height = 0, profile = None, startingHeight = 0,
                          fixedProfileWidth = 0, feather = 0,
                          combine = "Add", name = None)

The classic puffed relief: closed curves filled with a cross-section profile.

Parameter	Default	Meaning
`curveIds`	—	Closed curves to fill; at least one
`height`	`0` → `1.0`	Peak height in millimetres. Negative engraves
`profile`	`None` → `"Round"`	Cross-section name from `ProfileNames()` — `Round`, `Smooth`, `Chamfer`, `Plateau`, or one of your saved profiles
`startingHeight`	`0`	Z offset at which the profile takes off. `0` is a real value here, not a sentinel
`fixedProfileWidth`	`0`	`0` selects inflate mode: the profile peaks at the deepest point of the curve set. `> 0` spans exactly that width in millimetres inwards from the curve edge
`feather`	`0`	Edge blend distance in millimetres; `0` is a hard edge, not a default

Returns the operation id. Throws Pass at least one closed curve. for an empty list, Object <id> is not a curve in this document., Curve <id> is not closed; relief regions need closed curves., and fixedProfileWidth cannot be negative.

Add a flat extrusion

op_id = relief.AddExtrude(curveIds, height = 0, feather = 0,
                          combine = "Add", name = None)

Closed curves raised to a constant height — a flat pad, or with a negative height a flat-bottomed engraving.

Parameter	Default	Meaning
`curveIds`	—	Closed curves to raise; at least one
`height`	`0` → `1.0`	Constant height in millimetres. Negative engraves
`feather`	`0`	Edge blend distance in millimetres; `0` is a hard edge

Returns the operation id. Same curve validation and error strings as AddProfile.

Add an image height map

op_id = relief.AddImage(imagePath, height = 0, invert = False, scale = 0,
                        clipCurveIds = None, combine = "Add",
                        name = None)

A greyscale image read as a height map: white is the highest point.

Parameter	Default	Meaning
`imagePath`	—	PNG, JPG, BMP or TIFF file; pixel brightness maps to height
`height`	`0` → `1.0`	Height at pure white, in millimetres. Negative engraves
`invert`	`False`	`True` maps black to the highest point
`scale`	`0` → `1.0`	Multiplier over the fitted image size
`clipCurveIds`	`None`	Optional closed curves: the image fits their bounds and is clipped to their interior. Omitted, the image is centred on the workbench keeping its aspect ratio

Returns the operation id. The file is checked immediately — a missing or blank path throws Image file not found: <path>. Note that the path is referenced, not copied into the document: move or rename the file later and Operations() reports MissingReferences = True and the bake fails.

Add a 3D texture

op_id = relief.AddTexture(textureName, height = 0, tilesU = 0, tilesV = 0,
                          invert = False, clipCurveIds = None,
                          combine = "Add", name = None)

A tiled pattern from the Textures3D library — knurls, hammering, basket weaves. Combined with Multiply it modulates a relief already built underneath rather than adding to it.

Parameter	Default	Meaning
`textureName`	—	A filename inside the Textures3D library, e.g. `"KNURL01.jpg"`; the available set is the one the Texture3D smart component offers
`height`	`0` → `0.5`	Height at pure white, in millimetres. Note the default differs from the other operations
`tilesU`	`0` → `4`	Repetitions across the workbench, or across the clip-curve bounds
`tilesV`	`0` → `4`	Repetitions the other way
`invert`	`False`	`True` maps black to the highest point
`clipCurveIds`	`None`	Optional closed curves to clip the texture to

Returns the operation id. Throws Pass a texture filename from the Textures3D library. for a blank name and Texture '<name>' was not found in the Textures3D library. when the library has no such file — a full path is not accepted, only the library filename.

Add projected geometry

op_id = relief.AddGeometry(objectIds, feather = 0,
                           combine = "Add", name = None)

Existing document geometry flattened into the relief: each object is projected top-down onto the workbench and its height above the plane becomes the height field.

Parameter	Default	Meaning
`objectIds`	—	Meshes, breps, extrusions or SubDs; at least one
`feather`	`0`	Edge blend distance in millimetres; `0` is a hard edge

Returns the operation id. Throws Pass at least one mesh, brep, extrusion or SubD. for an empty list, Object <id> was not found in this document., and Object <id> is not a mesh, brep, extrusion or SubD. for anything with no brep form. Like image paths, the object ids are references: delete the source objects and the operation is flagged and fails the bake.

Add a sculpt

op_id = relief.AddSculpt(points, radius = 0, height = 0,
                         combine = "Add", name = None)

The panel’s Sculpt brush, headless: one smooth dab per point, each raising the field by up to height at its centre. Dabs on the same spot accumulate, like brush passes — and the operation is the same brush layer the panel paints, so it stays editable, reorderable and even re-paintable in the panel afterwards.

Parameter	Default	Meaning
`points`	—	World points to dab; at least one valid point. They are projected onto the workbench plane
`radius`	`0` → `2.0`	Dab radius in millimetres, with a smooth falloff to the edge
`height`	`0` → `0.5`	Signed height per dab, mm. Negative carves
`combine`	`"Add"`	How the layer merges into the stack

Returns the operation id. Throws Pass at least one valid point. and radius cannot be negative.

To “stroke” along a path, sample a curve and pass the samples:

pts = [curve.PointAt(t) for t in curve.DivideByCount(60, True)]
relief.AddSculpt(pts, radius = 1.2, height = 0.3, name = "Freehand vein")

Add a smooth

op_id = relief.AddSmooth(points, radius = 0, strength = 0,
                         blurRadius = 0, name = None)

The panel’s Smooth brush, headless: the dabs paint a 0–1 mask, and at compute time everything below this operation in the stack is blurred where the mask says so. It is in-place by nature — it filters the accumulated field instead of contributing a layer — so it has no combine mode, and its position in the stack decides what gets smoothed.

Parameter	Default	Meaning
`points`	—	World points to dab; at least one valid point
`radius`	`0` → `2.0`	Dab radius in millimetres
`strength`	`0` → `1.0`	Mask strength per dab, `0`–`1`; `1` is full smoothing at the centre
`blurRadius`	`0` → `1.0`	Blur kernel radius in millimetres

Returns the operation id. Throws Pass at least one valid point., radius cannot be negative., strength must be between 0 and 1. and blurRadius cannot be negative.

The one-shot alternative

For a relief made of a single layer, the creators bake in one call on a transient project and leave the document’s saved project untouched: Create from image, Create from curves, Create from geometry.