ReliefApi

The ArtisanRelief system, headless: 2.5D height-field reliefs built from an ordered stack of operations (curve profiles, flat extrusions, image height maps, 3D textures, projected geometry) merged with per-pixel combine modes and meshed as an open relief or a closed solid. Two ways to use it: * One-shot creators (CreateFromImage / CreateFromCurves / CreateFromGeometry): build a single-operation relief and bake the mesh in one call. They work on a transient project and leave the document’s saved ArtisanRelief project untouched. * The project stack (SetupProject, Add*, Operations, Bake…): edits the SAME per-document project the ArtisanRelief panel uses (persisted in the .3dm), so a script can build a multi-layer relief that the user can then keep refining in the panel — and vice versa. NOTE: while the ArtisanRelief panel is open it holds its own copy of the project and saves it on close, overwriting scripted changes; close the panel before scripting the project stack. Whatever route is taken, baking produces a ReliefCustomObject: the mesh carries a copy of the project that built it, so it shows up in the outliner and can be re-edited on its own. The per-document project above is the shared scratch pad for work in progress, not the record of a baked relief. All lengths are in model units (mm in a standard Artisan document). Interactive-only features stay out of this facade: the live GPU/mesh preview conduits and the graphical profile editor. The Sculpt and Smooth brushes ARE scriptable (AddSculpt/AddSmooth dab programmatically), and brush operations painted in the panel are honored by Bake and can be toggled/removed here.

from ArtisanPlugin.Scripting import ReliefApi

See also the guide, Relief, and the Python package, ra.relief.

Methods

Method
AddCarbon	Adds a carbon copy (rubbing) operation: an image laid over the workbench (centred, aspect kept, like AddImage) that shows only where the brush has rubbed.
AddExtrude	Adds a flat extrusion operation: closed curves raised to a constant height (0 = default 1.0; negative engraves), with an optional feathered edge in model units.
AddGeometry	Adds a projected-geometry operation (parameters as in CreateFromGeometry).
AddImage	Adds an image height-map operation (parameters as in CreateFromImage; clipCurveIds are optional closed curves the image fits and is clipped to).
AddProfile	Adds a profile (puffed) operation to the document’s relief project.
AddSculpt	Adds a sculpt (brush) operation dabbed programmatically: one smooth dab per point, each raising (or carving, negative height) the field by up to height mm at its center.
AddSmooth	Adds a smooth (brush) operation dabbed programmatically: everything below it in the stack is blurred where the painted mask says so — the panel’s Smooth brush, headless.
AddTexture	Adds a tiled 3D-texture operation from the Textures3D library.
Bake	Recomputes the saved project at full resolution and bakes the output mesh into the document (the panel’s Accept, headless).
ClearProject	Deletes the document’s saved relief project entirely (settings and all operations).
CreateFromCurves	Bakes a relief mesh from closed curves filled with a height profile (the classic puffed relief) in one call, without touching the document’s saved relief project.
CreateFromGeometry	Bakes a relief mesh from document geometry (meshes, breps, extrusions, SubDs) projected top-down onto the workbench — the height of each object above the plane becomes the relief.
CreateFromImage	Bakes a relief mesh from a grayscale image height map (white = highest) in one call, without touching the document’s saved relief project.
ExportHeightmap	Recomputes the saved project at full resolution and writes it as a 16-bit grayscale TIFF height map (black = lowest point), for CNC/CAM pipelines.
GetProject	The document’s saved relief project settings; Exists=false (all zeros) when the document has none.
MoveOperation	Moves one operation to a new position in the stack (0 = first applied).
Operations	The saved project’s operation stack in apply order; empty list when the document has no project.
ProfileNames	Names accepted by the “profile” parameter of profile operations: the four built-in presets (Round, Smooth, Chamfer, Plateau) followed by the user’s saved custom profiles.
RemoveOperation	Removes one operation from the saved project.
SetOperationCombine	Changes how one operation merges into the stack (Add, Subtract, ZMax, ZMin, Absolute, Multiply).
SetOperationEnabled	Enables or disables one operation of the saved project (the panel’s eye toggle); disabled operations are skipped by Bake.
SetupProject	Creates the document’s relief project — or reconfigures its settings, keeping the existing operation stack.

AddCarbon

Guid ReliefApi.AddCarbon(
    string imagePath,
    IEnumerable<Point3d> points,
    double radius = 0,
    double strength = 0,
    double height = 0,
    bool invert = false,
    double baseRadius = 0,
    double scale = 0,
    double offsetX = 0,
    double offsetY = 0,
    string combine = null,
    string name = null)

Adds a carbon copy (rubbing) operation: an image laid over the workbench (centred, aspect kept, like AddImage) that shows only where the brush has rubbed. The strokes are dabbed programmatically, one dab per point, each adding up to strength coverage at its centre; the panel’s Carbon brush can keep rubbing (or Ctrl-erasing) afterwards. imagePath image file; brightness -> height like AddImage. points world points to rub; at least one. radius dab radius in model units (0 = 2.0). strength 0-1 coverage per dab (0 = 1.0, full). height height at pure white in mm (0 = 0.5). invert flip brightness. baseRadius mm of broad tones (lighting, vignette) removed from the image before rubbing (0 = 2.0; pass a negative value for none). scale multiplier over the fitted size (0 = 1.0). offsetX/Y shift of the image centre from the workbench centre, mm. Returns the operation’s Guid. Nothing is baked until Bake().

Parameter	Type	Default
imagePath	string	required
points	IEnumerable<Point3d>	required
radius	double	0
strength	double	0
height	double	0
invert	bool	false
baseRadius	double	0
scale	double	0
offsetX	double	0
offsetY	double	0
combine	string	null
name	string	null

Returns Guid.

AddExtrude

Guid ReliefApi.AddExtrude(
    IEnumerable<Guid> curveIds,
    double height = 0,
    double feather = 0,
    string combine = null,
    string name = null)

Adds a flat extrusion operation: closed curves raised to a constant height (0 = default 1.0; negative engraves), with an optional feathered edge in model units. Returns the operation’s Guid.

Parameter	Type	Default
curveIds	IEnumerable<Guid>	required
height	double	0
feather	double	0
combine	string	null
name	string	null

Returns Guid.

AddGeometry

Guid ReliefApi.AddGeometry(
    IEnumerable<Guid> objectIds,
    double feather = 0,
    string combine = null,
    string name = null)

Adds a projected-geometry operation (parameters as in CreateFromGeometry). Returns the operation’s Guid.

Parameter	Type	Default
objectIds	IEnumerable<Guid>	required
feather	double	0
combine	string	null
name	string	null

Returns Guid.

AddImage

Guid ReliefApi.AddImage(
    string imagePath,
    double height = 0,
    bool invert = false,
    double scale = 0,
    IEnumerable<Guid> clipCurveIds = null,
    string combine = null,
    string name = null)

Adds an image height-map operation (parameters as in CreateFromImage; clipCurveIds are optional closed curves the image fits and is clipped to). Returns the operation’s Guid.

Parameter	Type	Default
imagePath	string	required
height	double	0
invert	bool	false
scale	double	0
clipCurveIds	IEnumerable<Guid>	null
combine	string	null
name	string	null

Returns Guid.

AddProfile

Guid ReliefApi.AddProfile(
    IEnumerable<Guid> curveIds,
    double height = 0,
    string profile = null,
    double startingHeight = 0,
    double fixedProfileWidth = 0,
    double feather = 0,
    string combine = null,
    string name = null)

Adds a profile (puffed) operation to the document’s relief project. Parameters as in CreateFromCurves; combine sets how the layer merges into the stack (Add, Subtract, ZMax, ZMin, Absolute, Multiply); name labels the card in the panel (null = auto “Profile N”). If the document has no project yet, one is created auto-fitted to the curves — call SetupProject first to control the workbench. Nothing is baked until Bake(). Returns the operation’s Guid.

Parameter	Type	Default
curveIds	IEnumerable<Guid>	required
height	double	0
profile	string	null
startingHeight	double	0
fixedProfileWidth	double	0
feather	double	0
combine	string	null
name	string	null

Returns Guid.

AddSculpt

Guid ReliefApi.AddSculpt(
    IEnumerable<Point3d> points,
    double radius = 0,
    double height = 0,
    string combine = null,
    string name = null)

Adds a sculpt (brush) operation dabbed programmatically: one smooth dab per point, each raising (or carving, negative height) the field by up to height mm at its center. The same operation the panel’s Sculpt brush paints — editable, reorderable and re-dabbable in the panel afterwards. Points are projected onto the workbench plane, so sample a curve and pass the points to “stroke” along it. points world points to dab; at least one. radius dab radius in model units (0 = 2.0). height signed height per dab in model units (0 = 0.5); dabs on the same spot accumulate, like brush passes. combine how the layer merges into the stack (default Add). Returns the operation’s Guid. Nothing is baked until Bake().

Parameter	Type	Default
points	IEnumerable<Point3d>	required
radius	double	0
height	double	0
combine	string	null
name	string	null

Returns Guid.

AddSmooth

Guid ReliefApi.AddSmooth(
    IEnumerable<Point3d> points,
    double radius = 0,
    double strength = 0,
    double blurRadius = 0,
    string name = null)

Adds a smooth (brush) operation dabbed programmatically: everything below it in the stack is blurred where the painted mask says so — the panel’s Smooth brush, headless. In-place by nature: it filters the accumulated field instead of contributing a layer, so it has no combine mode. points world points to dab; at least one. radius dab radius in model units (0 = 2.0). strength 0-1 mask strength per dab (0 = 1.0, full smoothing). blurRadius blur kernel radius in model units (0 = 1.0). Returns the operation’s Guid. Nothing is baked until Bake().

Parameter	Type	Default
points	IEnumerable<Point3d>	required
radius	double	0
strength	double	0
blurRadius	double	0
name	string	null

Returns Guid.

AddTexture

Guid ReliefApi.AddTexture(
    string textureName,
    double height = 0,
    double tilesU = 0,
    double tilesV = 0,
    bool invert = false,
    IEnumerable<Guid> clipCurveIds = null,
    string combine = null,
    string name = null)

Adds a tiled 3D-texture operation from the Textures3D library. textureName filename inside the library (e.g. “KNURL01.jpg”); see the Texture3D smart component for the available set. height height at pure white in model units (0 = default 0.5). tilesU/V repetitions across the workbench or the clip-curve bounds (0 = default 4). clipCurveIds optional closed curves to clip the texture to. Returns the operation’s Guid.

Parameter	Type	Default
textureName	string	required
height	double	0
tilesU	double	0
tilesV	double	0
invert	bool	false
clipCurveIds	IEnumerable<Guid>	null
combine	string	null
name	string	null

Returns Guid.

Bake

Guid ReliefApi.Bake()

Recomputes the saved project at full resolution and bakes the output mesh into the document (the panel’s Accept, headless). The project stays in the document so it can be re-edited and re-baked. Returns the Guid of the baked mesh.

Returns Guid.

ClearProject

void ReliefApi.ClearProject()

Deletes the document’s saved relief project entirely (settings and all operations). Baked meshes are ordinary meshes and are not touched.

CreateFromCurves

Guid ReliefApi.CreateFromCurves(
    IEnumerable<Guid> curveIds,
    double height = 0,
    string profile = null,
    double startingHeight = 0,
    double fixedProfileWidth = 0,
    double feather = 0,
    double worldWidth = 0,
    double worldHeight = 0,
    int resolution = 0,
    Plane? workbench = null,
    bool solid = true,
    double capDistance = 0,
    bool deleteBase = false)

Bakes a relief mesh from closed curves filled with a height profile (the classic puffed relief) in one call, without touching the document’s saved relief project. curveIds closed curves to fill; at least one. height peak height in model units (0 = default 1.0); negative engraves. profile cross-section name from ProfileNames() (null/"" = “Round”). startingHeight Z offset where the profile takes off (default 0). fixedProfileWidth 0 = inflate: the profile peaks at the deepest point of the curve set; > 0 = the profile spans exactly this width from the curve edge, in model units. feather edge blend distance in model units (0 = hard edge). worldWidth/Height, resolution, workbench, solid, capDistance, deleteBase as in CreateFromImage. Returns the Guid of the baked mesh.

Parameter	Type	Default
curveIds	IEnumerable<Guid>	required
height	double	0
profile	string	null
startingHeight	double	0
fixedProfileWidth	double	0
feather	double	0
worldWidth	double	0
worldHeight	double	0
resolution	int	0
workbench	Plane?	null
solid	bool	true
capDistance	double	0
deleteBase	bool	false

Returns Guid.

CreateFromGeometry

Guid ReliefApi.CreateFromGeometry(
    IEnumerable<Guid> objectIds,
    double feather = 0,
    double worldWidth = 0,
    double worldHeight = 0,
    int resolution = 0,
    Plane? workbench = null,
    bool solid = true,
    double capDistance = 0,
    bool deleteBase = false)

Bakes a relief mesh from document geometry (meshes, breps, extrusions, SubDs) projected top-down onto the workbench — the height of each object above the plane becomes the relief. One call, without touching the document’s saved relief project. objectIds objects to project; at least one. feather edge blend distance in model units (0 = hard edge). worldWidth/Height, resolution, workbench, solid, capDistance, deleteBase as in CreateFromImage (auto-fit covers the objects). Returns the Guid of the baked mesh.

Parameter	Type	Default
objectIds	IEnumerable<Guid>	required
feather	double	0
worldWidth	double	0
worldHeight	double	0
resolution	int	0
workbench	Plane?	null
solid	bool	true
capDistance	double	0
deleteBase	bool	false

Returns Guid.

CreateFromImage

Guid ReliefApi.CreateFromImage(
    string imagePath,
    double height = 0,
    bool invert = false,
    double scale = 0,
    IEnumerable<Guid> regionCurveIds = null,
    double worldWidth = 0,
    double worldHeight = 0,
    int resolution = 0,
    Plane? workbench = null,
    bool solid = true,
    double capDistance = 0,
    bool deleteBase = false)

Bakes a relief mesh from a grayscale image height map (white = highest) in one call, without touching the document’s saved relief project. imagePath PNG/JPG/BMP/TIFF file; pixel brightness maps to height. height height at pure white in model units (0 = default 1.0); negative engraves. invert true maps black to the highest point. scale multiplier over the fitted image size (0 = default 1.0). regionCurveIds closed planar curves; the image fits their bounds and is clipped to their interior. null/empty = image centered on the workbench keeping its aspect ratio. worldWidth/Height workbench size in model units (0 = fit the region curves with a 10% margin, or 50 when there are none). resolution grid nodes along the larger side, 64-4096 (0 = 512). workbench plane the relief sits on, grid centered at its origin (null = world XY, auto-centered on the region curves). solid true (default) bakes a closed solid; false an open mesh. capDistance solid thickness below the base plane (0 = default 1.0). deleteBase true trims away grid cells no operation touched. Returns the Guid of the baked mesh.

Parameter	Type	Default
imagePath	string	required
height	double	0
invert	bool	false
scale	double	0
regionCurveIds	IEnumerable<Guid>	null
worldWidth	double	0
worldHeight	double	0
resolution	int	0
workbench	Plane?	null
solid	bool	true
capDistance	double	0
deleteBase	bool	false

Returns Guid.

ExportHeightmap

void ReliefApi.ExportHeightmap(string filePath)

Recomputes the saved project at full resolution and writes it as a 16-bit grayscale TIFF height map (black = lowest point), for CNC/CAM pipelines. filePath should end in .tif/.tiff.

Parameter	Type	Default
filePath	string	required

GetProject

ReliefProjectInfo ReliefApi.GetProject()

The document’s saved relief project settings; Exists=false (all zeros) when the document has none. Read-only.

Returns ReliefProjectInfo.

MoveOperation

void ReliefApi.MoveOperation(Guid operationId, int newIndex)

Moves one operation to a new position in the stack (0 = first applied).

Parameter	Type	Default
operationId	Guid	required
newIndex	int	required

Operations

IReadOnlyList<ReliefOperationInfo> ReliefApi.Operations()

The saved project’s operation stack in apply order; empty list when the document has no project. Read-only.

Returns IReadOnlyList<ReliefOperationInfo>.

ProfileNames

IReadOnlyList<string> ReliefApi.ProfileNames()

Names accepted by the “profile” parameter of profile operations: the four built-in presets (Round, Smooth, Chamfer, Plateau) followed by the user’s saved custom profiles. Read-only.

Returns IReadOnlyList<string>.

RemoveOperation

void ReliefApi.RemoveOperation(Guid operationId)

Removes one operation from the saved project.

Parameter	Type	Default
operationId	Guid	required

SetOperationCombine

void ReliefApi.SetOperationCombine(Guid operationId, string combine)

Changes how one operation merges into the stack (Add, Subtract, ZMax, ZMin, Absolute, Multiply). Order matters: combine modes apply over whatever the operations below already built.

Parameter	Type	Default
operationId	Guid	required
combine	string	required

SetOperationEnabled

void ReliefApi.SetOperationEnabled(Guid operationId, bool enabled)

Enables or disables one operation of the saved project (the panel’s eye toggle); disabled operations are skipped by Bake.

Parameter	Type	Default
operationId	Guid	required
enabled	bool	required

SetupProject

void ReliefApi.SetupProject(
    double worldWidth = 0,
    double worldHeight = 0,
    int resolution = 0,
    Plane? workbench = null,
    bool solid = true,
    double capDistance = 0,
    bool deleteBase = false)

Creates the document’s relief project — or reconfigures its settings, keeping the existing operation stack. Same defaults as the panel: worldWidth/Height workbench size in model units (0 = 50). resolution grid nodes along the larger side, 64-4096 (0 = 512). workbench plane the relief sits on (null = world XY). solid true (default) = closed solid; false = open mesh. capDistance solid thickness below the plane (0 = default 1.0). deleteBase true trims cells no operation touched.

Parameter	Type	Default
worldWidth	double	0
worldHeight	double	0
resolution	int	0
workbench	Plane?	null
solid	bool	true
capDistance	double	0
deleteBase	bool	false