ra.render

Render materials, staging and batch rendering.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.RenderApi.

Functions

Function
apply_design_materials()	Applies the DESIGN (viewport) materials to every visible object in the active document — the ArtisanApplyDesignMaterials command, headless.
apply_render_materials()	Applies the photorealistic RENDER materials to every visible object in the active document — the ArtisanApplyRenderMaterials command, headless.
batch_render()	Renders every .3dm file in folder (optionally recursing into sub-folders) with the current render engine — the ArtisanBatchRendering command, headless: no options dialog, no folder picker, no progress window (per-file failures come back in the result instead).
create_pair()	Duplicates the objects as the second piece of a pair — the ArtisanPair command, headless.
lie_on_ground()	Rotates the objects around the X (or Y) axis so they lie as FLAT on the ground plane as possible — the ArtisanLyingOnTheGround command, used to stage pieces for renders.

ra.render.apply_design_materials()

ra.render.apply_design_materials() -> int

Applies the DESIGN (viewport) materials to every visible object in the active document — the ArtisanApplyDesignMaterials command, headless. Global, like the command: no selection is taken. Gems, diamonds, pearls and cabochons get their gem material from the document material table; breps, extrusions, meshes and SubDs get the document’s Metal 1 material (the command deliberately ignores the Metal 02/03 layers on this side of the switch). Returns the number of objects visited.

ra.render.apply_render_materials()

ra.render.apply_render_materials() -> int

Applies the photorealistic RENDER materials to every visible object in the active document — the ArtisanApplyRenderMaterials command, headless. Global, like the command: no selection is taken. Gems and diamonds get their gem RenderMaterial from the render catalog; pearls and cabochons the pearl material; breps, extrusions, meshes and SubDs the render metal of their LAYER (“Metal 01”/“Metal 02”/ “Metal 03” map to the document’s metal positions, anything else falls back to Metal 1). Same side effects as the command: raises the document render sampling to 25 samples and, on Rhino 8+, installs the default 2Shapes environment when none (or the stock “Studio” one) is active. Returns the number of objects visited.

ra.render.batch_render()

ra.render.batch_render(folder: str, include_subfolders=None, extension=None, custom_resolution=None, width=None, height=None) -> BatchRenderResult

Renders every .3dm file in folder (optionally recursing into sub-folders) with the current render engine — the ArtisanBatchRendering command, headless: no options dialog, no folder picker, no progress window (per-file failures come back in the result instead). Each image is saved NEXT TO its .3dm with the same base name and the given extension (“.jpg” or “.png”, the dialog’s two formats; jpg is the dialog default). When custom_resolution is True every file renders at width x height pixels (dialog defaults 1920 x 1080, valid 16..20000); when False each file renders at its own saved render settings. WARNING — the ACTIVE DOCUMENT CHANGES during the run: each file is opened with _-Open, replacing whatever is open, and (same as the command) the ORIGINAL DOCUMENT IS NOT RESTORED — the last rendered file stays active when this returns. Before each open the current document’s modified flag is cleared so Rhino never prompts to save, which means unsaved changes in the open document are silently discarded. Save your work before calling this.

Parameter	Type
folder	str	required
include_subfolders	bool	optional — None = the tool default
extension	str	optional — None = the tool default
custom_resolution	bool	optional — None = the tool default
width	int	optional — None = the tool default
height	int	optional — None = the tool default

ra.render.create_pair()

ra.render.create_pair(object_ids=None, distance=None, angle=None, mirror=None) -> List[str]

Duplicates the objects as the second piece of a pair — the ArtisanPair command, headless. The copy is rotated angle degrees around the Z axis at the selection’s bounding-box center, moved distance mm along X, and optionally mirrored (for asymmetric designs like earrings). Defaults match the command (20 mm, -20 degrees, no mirror). object_ids None/empty = current selection. Returns the ids of the copies.

Parameter	Type
object_ids	Sequence[IdLike]	optional — None = the tool default
distance	float	optional — None = the tool default
angle	float	optional — None = the tool default
mirror	bool	optional — None = the tool default

ra.render.lie_on_ground()

ra.render.lie_on_ground(object_ids=None, around_x=None, keep_original=None)

Rotates the objects around the X (or Y) axis so they lie as FLAT on the ground plane as possible — the ArtisanLyingOnTheGround command, used to stage pieces for renders. Scans rotations in 0.5-degree steps minimizing the total Z height, then picks the face-down orientation of the two candidates. keep_original True leaves the original in place and flattens a copy (the command’s DeleteOriginal toggle, inverted). object_ids None/empty = current selection.

Parameter	Type
object_ids	Sequence[IdLike]	optional — None = the tool default
around_x	bool	optional — None = the tool default
keep_original	bool	optional — None = the tool default