Scripting API

Render Studio turntables

from ArtisanPlugin.Scripting import RenderStudioApi as studio

The panel’s Turntable mode, headless: the camera orbits the current target on a horizontal circle, one frame is rendered per step, and the bundled ffmpeg assembles the frames into an MP4. Like stills it goes through Rhino’s real renderer, so it is the slow, photoreal route — the Realtime Render viewer has no video export at all.

Usage

path = studio.RenderTurntable(r"C:\out\ring.mp4")

path = studio.RenderTurntable(
    r"C:\out\ring.mp4",
    seconds = 8, framesPerSecond = 24,
    width = 1280, height = 720,
    samples = 300,
    raytraced = True)

Returns the full path of the video written.

Parameters

Parameter	Default	Meaning
`path`	required	Destination video. Resolved to a full path; `".mp4"` is appended when it has no extension; the containing folder is created.
`seconds`	`0`	Duration. `0` keeps the tool default, 5.
`framesPerSecond`	`0`	Frame rate, used both for the frame count and for the ffmpeg output. `0` keeps the tool default, 12.
`width`	`0`	Frame width in pixels. `0` keeps the tool default, 800.
`height`	`0`	Frame height in pixels. `0` keeps the tool default, 600.
`samples`	`0`	Cycles passes per frame — or capture passes when `raytraced` is `False`. `0` keeps the tool default, 500.
`raytraced`	`True`	`True` renders every frame with the current renderer (the panel’s Cycles mode). `False` captures the viewport in its current display mode instead: far faster, far lower quality.

No -1 sentinels: every numeric parameter treats any value at or below zero as “keep the default”, negatives included.

Frame count is seconds × framesPerSecond + 1 — the extra frame closes the loop back onto the starting position. At the defaults that is 5 × 12 + 1 = 61 frames. Since each frame is a full render, the cost grows with the product of duration and frame rate: an 8-second 24 fps turntable is 193 raytraced frames, not 61.

The orbit

The circle is built from the active view when the call starts:

Its centre is the camera target in X and Y, at the camera’s own Z height — so the camera keeps its elevation and its distance for the whole orbit.
Its radius is the distance from that centre to the camera position, and its seam is moved onto the camera position, so frame 1 is the view you are looking at. Frame the shot in the viewport first; there is no camera argument.
The camera is stepped around the circle and the views redrawn between frames. The last step lands back on the seam, so the camera finishes where it started.

If the camera sits directly above its target there is no circle to build:

InvalidOperationException: The camera is directly above its target: no orbit circle exists. Use a perspective view.

That is what a top view gives you — use a perspective view.

What is written where

Two things land on disk, both next to path:

The video, at path, assembled with libx264 at framesPerSecond and overwriting any existing file.
The frames, in a folder named FRAMES_<video name><token> beside the video — where the video name is the file name without extension with spaces replaced by underscores, and <token> is a random 8-character lowercase-alphanumeric string generated per call. So C:\out\my ring.mp4 produces something like C:\out\FRAMES_my_ring7k2p9dq4\.

Inside it the frames are JPEGs named frame-<token>-00000001.jpg, numbered from 1 and zero-padded to eight digits, sharing the same token as the folder.

The random token means runs never collide and frames are never overwritten; it also means the frames are never cleaned up. Every call leaves its full frame sequence behind, so a script that renders many turntables will accumulate them — delete the folder yourself once you have the video.

What it changes, and how long it blocks

Geometry is untouched, so no Transaction is needed. Two pieces of state do change and stay changed: the document render settings (fixed output size, image size, and the Cycles document-samples override, exactly as stills write them) and the active viewport camera, which is driven around the circle. The camera does come to rest where it began.

The call blocks until the MP4 exists. In raytraced mode that means one full render per frame with the render window opened and closed each time — expect minutes to hours, and plan for it: 61 frames at even ten seconds each is ten minutes. raytraced = False drops to a viewport capture per frame and is the mode to use for previews and for checking the framing before committing to a long run.

Failures

InvalidOperationException: No active document.
InvalidOperationException: No active view.
ArgumentException:         A destination file path is required.
InvalidOperationException: The camera is directly above its target: no orbit circle exists. Use a perspective view.
InvalidOperationException: The render was cancelled at frame 17 of 61.
InvalidOperationException: ffmpeg could not assemble the video (exit code 1). Frames kept in: C:\out\FRAMES_...

A cancelled frame aborts the whole run and names the frame it stopped on; the frames already rendered stay in their folder, and the camera is left wherever the orbit had reached.

ffmpeg itself is copied out of the RhinoArtisan installation into the user’s Render folder the first time a turntable is rendered. If it is missing from both places:

InvalidOperationException: ffmpeg.exe is not installed (missing from both the user Render folder and the installation). Reinstall RhinoArtisan.

Note that ffmpeg failing still leaves you every frame — the message tells you the folder, and the sequence can be assembled by hand.