Capture

from ArtisanPlugin.Scripting import ViewApi as view

Capture writes what a viewport is drawing to an image file, at whatever resolution you ask for rather than the on-screen size. It is the last step of a batch render: open a design, set the display mode, restore an angle, capture; repeat for every angle and every file.

Usage

path = view.Capture(path, width = 0, height = 0, viewport = None)

Parameter	Default	Meaning
path	-	Destination file. Relative paths are resolved against the process working directory
width	0 -> the viewport’s on-screen width	Output width in pixels
height	0 -> the viewport’s on-screen height	Output height in pixels
viewport	None	Viewport to capture; None means the active one

Returns the full path written, as a string - always absolute, and always with the extension the file actually got, so log or collect that value rather than the string you passed in.

Size

The custom size applies only when both width and height are greater than zero. If either is 0 - or negative - the pair is discarded and the capture falls back to the viewport’s current client rectangle, that is, its on-screen pixel size. There is no “set the width and let the height follow”: passing width = 1920, height = 0 silently gives you the on-screen size, not a 1920-wide image. Work out both numbers yourself, and note that a size with a different aspect ratio from the viewport changes what fits in frame, not just the pixel count.

Path and format

The format is always PNG - it is not inferred from the extension. What the extension controls is only the file name: the path is made absolute, and if it does not already end in .png (case-insensitively) then .png is appended, not substituted. So "front" becomes front.png, but "front.jpg" becomes front.jpg.png and still contains PNG data. Give it a .png path, or none at all.

Missing folders in the destination are created for you, so a batch loop can write straight into out/2026-08/rings/ without preparing the tree. An existing file at the path is overwritten without warning.

What it changes, and what it needs

Returns a string; it changes nothing in the document - no geometry, no settings, and the file is not marked modified - so it needs no Transaction. It does not move the camera or change the display mode either: it records the viewport exactly as it stands, which is why the calls that set up the shot must come first.

It does require a valid licence: unlike the camera moves, writing a file out of RhinoArtisan is gated like the other exports, and the gate is checked before the path is even examined.

Errors: ArgumentException with "A destination file path is required." for an empty or whitespace path; the usual viewport resolution failures - InvalidOperationException "No active document.", InvalidOperationException "No active view.", or ArgumentException "Unknown viewport 'Persp'. Viewports: Perspective, Top, Front, Right."; and InvalidOperationException with "Rhino could not capture the viewport." when Rhino returns no bitmap. Filesystem problems - an unwritable folder, a locked file - surface as the ordinary .NET IO exceptions.

from ArtisanPlugin.Scripting import ViewApi as view

view.SetDisplayMode("Rendered", viewport = "Perspective")
for angle in ("Hero", "Side", "Detail"):
    view.RestoreNamedView(angle, viewport = "Perspective")
    written = view.Capture(r"C:\out\ring-%s" % angle, 1920, 1080, viewport = "Perspective")
    print("wrote", written)   # C:\out\ring-Hero.png