Python package

ra.relief

2.5D reliefs: creators, the operation stack, sculpt/smooth by points, bake, heightmaps.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.ReliefApi.

Functions

Function
`add_carbon()`	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.
`add_extrude()`	Adds a flat extrusion operation: closed curves raised to a constant height (None = the default 1.0; negative engraves), with an optional feathered edge in model units.
`add_geometry()`	Adds a projected-geometry operation (parameters as in CreateFromGeometry).
`add_image()`	Adds an image height-map operation (parameters as in CreateFromImage; clip_curve_ids are optional closed curves the image fits and is clipped to).
`add_profile()`	Adds a profile (puffed) operation to the document’s relief project.
`add_sculpt()`	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.
`add_smooth()`	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.
`add_texture()`	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).
`clear_project()`	Deletes the document’s saved relief project entirely (settings and all operations).
`create_from_curves()`	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.
`create_from_geometry()`	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.
`create_from_image()`	Bakes a relief mesh from a grayscale image height map (white = highest) in one call, without touching the document’s saved relief project.
`export_heightmap()`	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.
`get_project()`	The document’s saved relief project settings; Exists=False (all zeros) when the document has none.
`move_operation()`	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.
`profile_names()`	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.
`remove_operation()`	Removes one operation from the saved project.
`set_operation_combine()`	Changes how one operation merges into the stack (Add, Subtract, ZMax, ZMin, Absolute, Multiply).
`set_operation_enabled()`	Enables or disables one operation of the saved project (the panel’s eye toggle); disabled operations are skipped by Bake.
`setup_project()`	Creates the document’s relief project — or reconfigures its settings, keeping the existing operation stack.

ra.relief.add_carbon()

ra.relief.add_carbon(image_path: str, points: Sequence[PointLike], radius=None, strength=None, height=None, invert=None, base_radius=None, scale=None, offset_x=None, offset_y=None, combine=None, name=None) -> str

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. image_path 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. base_radius 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
`image_path`	`str`	required
`points`	`Sequence[PointLike]`	required
`radius`	`float`	optional — None = the tool default
`strength`	`float`	optional — None = the tool default
`height`	`float`	optional — None = the tool default
`invert`	`bool`	optional — None = the tool default
`base_radius`	`float`	optional — None = the tool default
`scale`	`float`	optional — None = the tool default
`offset_x`	`float`	optional — None = the tool default
`offset_y`	`float`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_extrude()

ra.relief.add_extrude(curve_ids: Sequence[IdLike], height=None, feather=None, combine=None, name=None) -> str

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

Parameter	Type
`curve_ids`	`Sequence[IdLike]`	required
`height`	`float`	optional — None = the tool default
`feather`	`float`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_geometry()

ra.relief.add_geometry(object_ids: Sequence[IdLike], feather=None, combine=None, name=None) -> str

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

Parameter	Type
`object_ids`	`Sequence[IdLike]`	required
`feather`	`float`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_image()

ra.relief.add_image(image_path: str, height=None, invert=None, scale=None, clip_curve_ids=None, combine=None, name=None) -> str

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

Parameter	Type
`image_path`	`str`	required
`height`	`float`	optional — None = the tool default
`invert`	`bool`	optional — None = the tool default
`scale`	`float`	optional — None = the tool default
`clip_curve_ids`	`Sequence[IdLike]`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_profile()

ra.relief.add_profile(curve_ids: Sequence[IdLike], height=None, profile=None, starting_height=None, fixed_profile_width=None, feather=None, combine=None, name=None) -> str

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 (None = 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
`curve_ids`	`Sequence[IdLike]`	required
`height`	`float`	optional — None = the tool default
`profile`	`str`	optional — None = the tool default
`starting_height`	`float`	optional — None = the tool default
`fixed_profile_width`	`float`	optional — None = the tool default
`feather`	`float`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_sculpt()

ra.relief.add_sculpt(points: Sequence[PointLike], radius=None, height=None, combine=None, name=None) -> str

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
`points`	`Sequence[PointLike]`	required
`radius`	`float`	optional — None = the tool default
`height`	`float`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_smooth()

ra.relief.add_smooth(points: Sequence[PointLike], radius=None, strength=None, blur_radius=None, name=None) -> str

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). blur_radius blur kernel radius in model units (0 = 1.0). Returns the operation’s Guid. Nothing is baked until Bake().

Parameter	Type
`points`	`Sequence[PointLike]`	required
`radius`	`float`	optional — None = the tool default
`strength`	`float`	optional — None = the tool default
`blur_radius`	`float`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.add_texture()

ra.relief.add_texture(texture_name: str, height=None, tiles_u=None, tiles_v=None, invert=None, clip_curve_ids=None, combine=None, name=None) -> str

Adds a tiled 3D-texture operation from the Textures3D library. texture_name 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 (None = the default 0.5). tilesU/V repetitions across the workbench or the clip-curve bounds (None = the default 4). clip_curve_ids optional closed curves to clip the texture to. Returns the operation’s Guid.

Parameter	Type
`texture_name`	`str`	required
`height`	`float`	optional — None = the tool default
`tiles_u`	`float`	optional — None = the tool default
`tiles_v`	`float`	optional — None = the tool default
`invert`	`bool`	optional — None = the tool default
`clip_curve_ids`	`Sequence[IdLike]`	optional — None = the tool default
`combine`	`str`	optional — None = the tool default
`name`	`str`	optional — None = the tool default

ra.relief.bake()

ra.relief.bake() -> str

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.

ra.relief.clear_project()

ra.relief.clear_project()

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

ra.relief.create_from_curves()

ra.relief.create_from_curves(curve_ids: Sequence[IdLike], height=None, profile=None, starting_height=None, fixed_profile_width=None, feather=None, world_width=None, world_height=None, resolution=None, workbench=None, solid=None, cap_distance=None, delete_base=None) -> str

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. curve_ids closed curves to fill; at least one. height peak height in model units (None = the default 1.0); negative engraves. profile cross-section name from ProfileNames() (None/"" = “Round”). starting_height Z offset where the profile takes off (default 0). fixed_profile_width 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). world_width/Height, resolution, workbench, solid, cap_distance, delete_base as in CreateFromImage. Returns the Guid of the baked mesh.

Parameter	Type
`curve_ids`	`Sequence[IdLike]`	required
`height`	`float`	optional — None = the tool default
`profile`	`str`	optional — None = the tool default
`starting_height`	`float`	optional — None = the tool default
`fixed_profile_width`	`float`	optional — None = the tool default
`feather`	`float`	optional — None = the tool default
`world_width`	`float`	optional — None = the tool default
`world_height`	`float`	optional — None = the tool default
`resolution`	`int`	optional — None = the tool default
`workbench`	`Optional[PlaneLike]`	optional — None = the tool default
`solid`	`bool`	optional — None = the tool default
`cap_distance`	`float`	optional — None = the tool default
`delete_base`	`bool`	optional — None = the tool default

ra.relief.create_from_geometry()

ra.relief.create_from_geometry(object_ids: Sequence[IdLike], feather=None, world_width=None, world_height=None, resolution=None, workbench=None, solid=None, cap_distance=None, delete_base=None) -> str

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. object_ids objects to project; at least one. feather edge blend distance in model units (0 = hard edge). world_width/Height, resolution, workbench, solid, cap_distance, delete_base as in CreateFromImage (auto-fit covers the objects). Returns the Guid of the baked mesh.

Parameter	Type
`object_ids`	`Sequence[IdLike]`	required
`feather`	`float`	optional — None = the tool default
`world_width`	`float`	optional — None = the tool default
`world_height`	`float`	optional — None = the tool default
`resolution`	`int`	optional — None = the tool default
`workbench`	`Optional[PlaneLike]`	optional — None = the tool default
`solid`	`bool`	optional — None = the tool default
`cap_distance`	`float`	optional — None = the tool default
`delete_base`	`bool`	optional — None = the tool default

ra.relief.create_from_image()

ra.relief.create_from_image(image_path: str, height=None, invert=None, scale=None, region_curve_ids=None, world_width=None, world_height=None, resolution=None, workbench=None, solid=None, cap_distance=None, delete_base=None) -> str

Bakes a relief mesh from a grayscale image height map (white = highest) in one call, without touching the document’s saved relief project. image_path PNG/JPG/BMP/TIFF file; pixel brightness maps to height. height height at pure white in model units (None = the default 1.0); negative engraves. invert True maps black to the highest point. scale multiplier over the fitted image size (None = the default 1.0). region_curve_ids closed planar curves; the image fits their bounds and is clipped to their interior. None/empty = image centered on the workbench keeping its aspect ratio. world_width/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 (None = world XY, auto-centered on the region curves). solid True (default) bakes a closed solid; False an open mesh. cap_distance solid thickness below the base plane (None = the default 1.0). delete_base True trims away grid cells no operation touched. Returns the Guid of the baked mesh.

Parameter	Type
`image_path`	`str`	required
`height`	`float`	optional — None = the tool default
`invert`	`bool`	optional — None = the tool default
`scale`	`float`	optional — None = the tool default
`region_curve_ids`	`Sequence[IdLike]`	optional — None = the tool default
`world_width`	`float`	optional — None = the tool default
`world_height`	`float`	optional — None = the tool default
`resolution`	`int`	optional — None = the tool default
`workbench`	`Optional[PlaneLike]`	optional — None = the tool default
`solid`	`bool`	optional — None = the tool default
`cap_distance`	`float`	optional — None = the tool default
`delete_base`	`bool`	optional — None = the tool default

ra.relief.export_heightmap()

ra.relief.export_heightmap(file_path: str)

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. file_path should end in .tif/.tiff.

Parameter	Type
`file_path`	`str`	required

ra.relief.get_project()

ra.relief.get_project() -> ReliefProjectInfo

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

ra.relief.move_operation()

ra.relief.move_operation(operation_id: IdLike, new_index: int)

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

Parameter	Type
`operation_id`	`IdLike`	required
`new_index`	`int`	required

ra.relief.operations()

ra.relief.operations() -> List[ReliefOperationInfo]

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

ra.relief.profile_names()

ra.relief.profile_names() -> List[str]

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.

ra.relief.remove_operation()

ra.relief.remove_operation(operation_id: IdLike)

Removes one operation from the saved project.

Parameter	Type
`operation_id`	`IdLike`	required

ra.relief.set_operation_combine()

ra.relief.set_operation_combine(operation_id: IdLike, combine: str)

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
`operation_id`	`IdLike`	required
`combine`	`str`	required

ra.relief.set_operation_enabled()

ra.relief.set_operation_enabled(operation_id: IdLike, enabled: bool)

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

Parameter	Type
`operation_id`	`IdLike`	required
`enabled`	`bool`	required

ra.relief.setup_project()

ra.relief.setup_project(world_width=None, world_height=None, resolution=None, workbench=None, solid=None, cap_distance=None, delete_base=None)

Creates the document’s relief project — or reconfigures its settings, keeping the existing operation stack. Same defaults as the panel: world_width/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 (None = world XY). solid True (default) = closed solid; False = open mesh. cap_distance solid thickness below the plane (None = the default 1.0). delete_base True trims cells no operation touched.

Parameter	Type
`world_width`	`float`	optional — None = the tool default
`world_height`	`float`	optional — None = the tool default
`resolution`	`int`	optional — None = the tool default
`workbench`	`Optional[PlaneLike]`	optional — None = the tool default
`solid`	`bool`	optional — None = the tool default
`cap_distance`	`float`	optional — None = the tool default
`delete_base`	`bool`	optional — None = the tool default