Python package

ra.realtime_render

The web Realtime Render viewer: open, update, camera, materials, screenshots.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.RealtimeRenderApi.

Functions

Function
`capture_views()`	Captures the 8 standard orbital views (front, back, left, right, three-quarter x2, top, bottom) as PNGs into `folder` — one call, camera restored afterwards.
`edit_viewer_material()`	Live-edits a catalog material everywhere it is currently applied: color (CSS color), roughness 0-1, ior (gems, ~1.4-2.4), opacity 0-1.
`get_viewer_items()`	JSON array with the viewer’s parts and their current materials ([{uuid, material, …}]).
`record_turntable()`	One-call 360: turns auto-rotation on, records `seconds` of video to `path`, and schedules the rotation back off inside the page when the recording ends — the script needs no sleeps or timers.
`set_material_by_layer()`	Applies a viewer catalog material to every part on a layer.
`set_viewer_background()`	Sets the viewer’s background gradient.
`set_viewer_camera()`	Places the VIEWER camera at `position` looking at `target` (viewer/GLB coordinates, which match the Rhino model in mm).
`set_viewer_camera_preset()`	Moves the VIEWER camera to a named preset.
`set_viewer_environment()`	Sets the lighting environment: a preset name (studio, sunset, dawn, night, warehouse, forest, apartment, city, park, lobby) or an HDR/EXR URL.
`set_viewer_material()`	Changes one part’s material in the viewer.
`set_viewer_option()`	Sets ANY single viewer option by its dot-path key — backgrounds, bevel, jewelry shadows, AO, depth of field, bloom, vignette, caustics, studio lights, auto_rotate…
`set_viewer_options()`	Applies a batch of viewer options in one call.
`show_realtime_render()`	Opens the Realtime Render window (or activates it when already open), same as the ArtisanRealtimeRender command — which is hidden from the command list, so this is the only scriptable way in.
`start_video_recording()`	Starts recording the viewer to a video file.
`stop_video_recording()`	Stops a manual recording started with seconds = 0; the file is then written to the path given to StartVideoRecording.
`update_render()`	Re-exports the current document to the viewer (the ArtisanRenderUpdate command).
`viewer_screenshot()`	Saves a PNG of the current viewer frame to `path` and returns the full path written (“.png” appended when missing).
`viewer_zoom_extents()`	Frames the whole model in the viewer.

ra.realtime_render.capture_views()

ra.realtime_render.capture_views(folder: str, width=None, height=None) -> str

Captures the 8 standard orbital views (front, back, left, right, three-quarter x2, top, bottom) as PNGs into folder — one call, camera restored afterwards. Returns the paths written, one per line. Slow: expect a few seconds; the call waits up to 2 minutes.

Parameter	Type
`folder`	`str`	required
`width`	`int`	optional — None = the tool default
`height`	`int`	optional — None = the tool default

ra.realtime_render.edit_viewer_material()

ra.realtime_render.edit_viewer_material(material_name: str, color=None, roughness=None, ior=None, opacity=None)

Live-edits a catalog material everywhere it is currently applied: color (CSS color), roughness 0-1, ior (gems, ~1.4-2.4), opacity 0-1. Pass None/negative to leave a property untouched. The edit is ephemeral — re-applying the material from the catalog resets it.

Parameter	Type
`material_name`	`str`	required
`color`	`str`	optional — None = the tool default
`roughness`	`float`	optional — None = the tool default
`ior`	`float`	optional — None = the tool default
`opacity`	`float`	optional — None = the tool default

ra.realtime_render.get_viewer_items()

ra.realtime_render.get_viewer_items() -> str

JSON array with the viewer’s parts and their current materials ([{uuid, material, …}]). Call this FIRST to learn the part names (uuids) to pass to SetViewerMaterial.

ra.realtime_render.record_turntable()

ra.realtime_render.record_turntable(path: str, seconds=None, width=None, height=None, frame_rate=None) -> str

One-call 360: turns auto-rotation on, records seconds of video to path, and schedules the rotation back off inside the page when the recording ends — the script needs no sleeps or timers. Returns the path armed; the file appears when the recording finishes.

Parameter	Type
`path`	`str`	required
`seconds`	`float`	optional — None = the tool default
`width`	`int`	optional — None = the tool default
`height`	`int`	optional — None = the tool default
`frame_rate`	`int`	optional — None = the tool default

ra.realtime_render.set_material_by_layer()

ra.realtime_render.set_material_by_layer(layer_name: str, material_name: str) -> int

Applies a viewer catalog material to every part on a layer. layer_name matches the viewer item’s layer or name, case-insensitive and treating spaces and underscores as equal — so “METAL_01”, “metal 01” and “Metal 01” all hit the Rhino layer “Metal 01”. Returns how many parts changed; throws listing the available layers when nothing matches. Viewer-only: the Rhino document is untouched.

Parameter	Type
`layer_name`	`str`	required
`material_name`	`str`	required

ra.realtime_render.set_viewer_background()

ra.realtime_render.set_viewer_background(top_color: str, bottom_color=None)

Sets the viewer’s background gradient. Colors are CSS colors (“#1a1a2e”, “white”…). Pass None/empty to leave one end unchanged.

Parameter	Type
`top_color`	`str`	required
`bottom_color`	`str`	optional — None = the tool default

ra.realtime_render.set_viewer_camera()

ra.realtime_render.set_viewer_camera(position: PointLike, target: PointLike)

Places the VIEWER camera at position looking at target (viewer/GLB coordinates, which match the Rhino model in mm).

Parameter	Type
`position`	`PointLike`	required
`target`	`PointLike`	required

ra.realtime_render.set_viewer_camera_preset()

ra.realtime_render.set_viewer_camera_preset(preset: str)

Moves the VIEWER camera to a named preset. Valid presets: front, back, left, right, top, bottom, three-quarter, three-quarter-left, detail, dramatic-low. The preset frames the model automatically.

Parameter	Type
`preset`	`str`	required

ra.realtime_render.set_viewer_environment()

ra.realtime_render.set_viewer_environment(preset_or_url: str, intensity=None)

Sets the lighting environment: a preset name (studio, sunset, dawn, night, warehouse, forest, apartment, city, park, lobby) or an HDR/EXR URL. intensity > 0 also sets the environment intensity (1 = neutral).

Parameter	Type
`preset_or_url`	`str`	required
`intensity`	`float`	optional — None = the tool default

ra.realtime_render.set_viewer_material()

ra.realtime_render.set_viewer_material(part_uuid: str, material_name: str)

Changes one part’s material in the viewer. part_uuid comes from GetViewerItems(); material_name is a viewer catalog name (e.g. “YELLOW_GOLD”, “WHITE_GOLD”, “PLATINUM”, “DIAMOND”, “RUBY”). Viewer-only: the Rhino document is not modified.

Parameter	Type
`part_uuid`	`str`	required
`material_name`	`str`	required

ra.realtime_render.set_viewer_option()

ra.realtime_render.set_viewer_option(path: str, value: str)

Sets ANY single viewer option by its dot-path key — backgrounds, bevel, jewelry shadows, AO, depth of field, bloom, vignette, caustics, studio lights, auto_rotate… value is parsed as bool, number or string (“True”, “0.4”, “#ffffff”).

Parameter	Type
`path`	`str`	required
`value`	`str`	required

ra.realtime_render.set_viewer_options()

ra.realtime_render.set_viewer_options(options_json: str)

Applies a batch of viewer options in one call. options_json is a JSON object of option keys to values, e.g. {“effect_composer_bloom_enabled”:True,“effect_composer_bloom_intensity”:0.6}.

Parameter	Type
`options_json`	`str`	required

ra.realtime_render.show_realtime_render()

ra.realtime_render.show_realtime_render() -> bool

Opens the Realtime Render window (or activates it when already open), same as the ArtisanRealtimeRender command — which is hidden from the command list, so this is the only scriptable way in.

ra.realtime_render.start_video_recording()

ra.realtime_render.start_video_recording(path: str, seconds=None, width=None, height=None, frame_rate=None) -> str

Starts recording the viewer to a video file. seconds > 0 stops and saves automatically after that long; 0 records until StopVideoRecording(). The finished file lands at path (the window reroutes the viewer’s download there). The viewer picks the codec: mp4 (h264) when the OS supports it, webm otherwise — keep “.mp4”.

Parameter	Type
`path`	`str`	required
`seconds`	`float`	optional — None = the tool default
`width`	`int`	optional — None = the tool default
`height`	`int`	optional — None = the tool default
`frame_rate`	`int`	optional — None = the tool default

ra.realtime_render.stop_video_recording()

ra.realtime_render.stop_video_recording()

Stops a manual recording started with seconds = 0; the file is then written to the path given to StartVideoRecording. Saving is asynchronous — give it a moment before reading the file.

ra.realtime_render.update_render()

ra.realtime_render.update_render()

Re-exports the current document to the viewer (the ArtisanRenderUpdate command). The export runs in the background; this returns as soon as it is queued. Requires the Realtime Render window to be open — throws a clear error otherwise (the command only logged it, which a script would never see).

ra.realtime_render.viewer_screenshot()

ra.realtime_render.viewer_screenshot(path: str) -> str

Saves a PNG of the current viewer frame to path and returns the full path written (“.png” appended when missing).

Parameter	Type
`path`	`str`	required

ra.realtime_render.viewer_zoom_extents()

ra.realtime_render.viewer_zoom_extents()

Frames the whole model in the viewer.