Skip to main content

Rendering

The rpts.render functions make offscreen PNG images of the loaded asset. They can render the whole asset, one node in isolation, each mesh separately, or a turntable sequence. The camera is a fixed default view. Access them as rpts.render.<name>().

Renderer and quality preset

Use list_renderers() to find valid renderer_id values. Use list_quality_presets() to find valid quality_preset names. Passing None for renderer_id uses the default real-time renderer, Storm. A quality_preset only affects the offline renderer, so it has no effect when the real-time renderer is used.

Listing renderers and presets​

list_renderers()​

Returns the available renderers. The real-time renderer, Storm, is always first.

Returns: a list of dicts, for example:

[{"id": "HdStormRendererPlugin", "name": "Storm"}]

list_quality_presets()​

Returns the quality preset names that are available for the renderer that is active in the interactive viewport.

This reflects the live viewport's renderer, not necessarily the renderer_id you pass to the render functions. To use the offline renderer's presets, select it in the renderer switcher first. Or pass one of the three fixed names directly. Unrecognized names resolve to "Default".

Returns: a list of preset names, for example ["Preview", "Default", "Final"] for the offline renderer. The list is empty if the active renderer has no presets, for example the default real-time renderer.

Rendering​

render_asset(renderer_id=None, quality_preset=None, background_color=None, output_path='render.png', resolution=(1024, 1024))​

Renders the whole current asset from a fixed default camera view to a PNG file.

  • renderer_id (str): one of the ids from list_renderers(). None uses the default real-time renderer, Storm. Default: None.
  • quality_preset (str): one of the names from list_quality_presets(), for example "Preview", "Default" or "Final". None leaves the active renderer's current settings unchanged. Default: None.
  • background_color (tuple of three floats): an (r, g, b) tuple with each value from 0 to 1. The background is filled with this solid opaque color. None keeps the background transparent. Default: None.
  • output_path (str): the output PNG path. Default: 'render.png'. The Sphinx output does not describe this parameter. The name and the function description ("to a PNG file") indicate its purpose.
  • resolution (tuple of two ints): (width, height) in pixels. Default: (1024, 1024).

Returns: True on success.

render_node(node, renderer_id=None, quality_preset=None, color=None, background_color=None, focus=True, ghost_opacity=0.15, output_path='render.png', resolution=(1024, 1024))​

Renders a single node in isolation from the fixed default camera view to a PNG file.

  • node (str or Node): a scene node path or an rpd.Node.
  • renderer_id (str): not described in the Sphinx output for this function. For valid values, see list_renderers(). Default: None.
  • quality_preset (str): one of the names from list_quality_presets(). None leaves the active renderer's current settings unchanged. Default: None.
  • color (tuple of three floats): an (r, g, b) tuple with each value from 0 to 1. This replaces the node's material with a flat, unlit fill of that color for this render only. It is useful for per-part masks. The live scene is never changed. None keeps the node's real material. Default: None.
  • background_color (tuple of three floats): an (r, g, b) tuple with each value from 0 to 1. The background is filled with this solid opaque color. None keeps the background transparent. Default: None.
  • focus (bool): True fits the camera tightly on this node, as if it were the only object in the scene, and hides every other node. False keeps the whole-asset framing, so the render shows where the node sits within the full assembly. In that case, the other nodes stay visible as translucent grey ghosts. Default: True.
  • ghost_opacity (float): the opacity of the non-target nodes, from 0 to 1. This is used only when focus=False. 0 is fully invisible, and 1 is fully opaque. Default: 0.15.
  • output_path (str): the output PNG path. Default: 'render.png'. The Sphinx output does not describe this parameter. The name and the function description indicate its purpose.
  • resolution (tuple of two ints): (width, height) in pixels. Default: (1024, 1024).

Returns: True on success.

render_meshes_separately(nodes=None, output_dir='renders', renderer_id=None, quality_preset=None, color=None, background_color=None, focus=True, ghost_opacity=0.15, resolution=(1024, 1024))​

Renders each mesh node in isolation, one PNG per mesh, from the fixed default camera view. Non-mesh nodes, such as groups, are expanded to their mesh descendants.

  • nodes (str, Node, or iterable of either, or None): the nodes to render. None renders every mesh node in the scene. Default: None.
  • output_dir (str): the directory where each mesh's PNG is written. Default: 'renders'.
  • renderer_id (str): not described in the Sphinx output for this function. For valid values, see list_renderers(). Default: None.
  • quality_preset (str): one of the names from list_quality_presets(). None leaves the active renderer's current settings unchanged. Default: None.
  • color (tuple of three floats): applied to every mesh, with the same meaning as in render_node(). Default: None.
  • background_color (tuple of three floats): applied to every mesh, with the same meaning as in render_node(). Default: None.
  • focus (bool): True fits the camera tightly on each mesh in turn and hides every other node. False keeps the whole-asset framing for every mesh, and shows every other node as a translucent ghost instead of hiding it. See ghost_opacity. Default: True.
  • ghost_opacity (float): the same as in render_node(). It is used only when focus=False. Default: 0.15.
  • resolution (tuple of two ints): (width, height) in pixels. Default: (1024, 1024).

Returns: a dict that maps each node path to its output file path, for example {node_path: output_file_path}. Nodes that failed to render, or that resolved to no mesh, are omitted.

note

The return description in the Sphinx output is partly garbled. The dict form shown here is the one the description states.

render_turntable(num_steps=36, renderer_id=None, quality_preset=None, background_color=None, output_dir='turntable', file_prefix='frame', resolution=(1024, 1024))​

Renders num_steps frames spaced evenly around a full 360-degree rotation of the whole asset. Nothing is hidden or highlighted. The function uses one shared engine setup for the whole sequence, which is much cheaper than calling render_asset() num_steps times.

  • num_steps (int): the number of evenly spaced frames around the full circle. Default: 36.
  • renderer_id (str): the same as in render_asset(). Default: None.
  • quality_preset (str): the same as in render_asset(). Default: None.
  • background_color (tuple of three floats): the same as in render_asset(). Default: None.
  • output_dir (str): the directory where the frames are written. It is created if needed. Default: 'turntable'.
  • file_prefix (str): the base file name. Frames are named {file_prefix}_0000.png, {file_prefix}_0001.png, and so on. Default: 'frame'.
  • resolution (tuple of two ints): (width, height) in pixels. Default: (1024, 1024).

Returns: a list of the output file paths in order, or an empty list [] if the render failed.