Scripting API

Scene & effects

from ArtisanPlugin.Scripting import RealtimeRenderApi as rtr

The viewer’s look - background, lighting, and a full post-processing stack - is one big options object, and this page is the scripted way into it. Two curated calls cover the common moves; the generic SetViewerOption reaches everything else. All of them fire and forget, and none of them touches the Rhino document.

Background

rtr.SetViewerBackground("#1a1a2e", "#0b0b14")   # -> None  (top, bottom)
rtr.SetViewerBackground("white")                # -> None  (top only)

Sets the background gradient. Colors are CSS colors - hex or named. Pass one or both ends; passing neither throws “Pass at least one color.”

Lighting environment

rtr.SetViewerEnvironment("studio", 1.2)                          # preset + intensity
rtr.SetViewerEnvironment("https://cdn.example.com/loft.hdr")     # custom HDRI

Parameter	Default	Meaning
`presetOrUrl`	required	A preset name, or an HDR/EXR url
`intensity`	`0` (untouched)	Environment intensity; `1` is neutral

The presets, exactly as the viewer ships them: studio, sunset, dawn, night, warehouse, forest, apartment, city, park, lobby. Anything that is not one of those and does not look like a url (starts with http, or ends in .hdr/.exr) throws listing the valid names. intensity is only written when greater than 0.

Any option: SetViewerOption

rtr.SetViewerOption("effectComposerBloomEnabled", "true")     # -> None
rtr.SetViewerOption("effectComposerBloomIntensity", "0.6")
rtr.SetViewerOption("autoRotate", "true")

Parameter	Default	Meaning
`path`	required	The option key
`value`	required	Parsed as bool, number or string, in that order

"true"/"false" become booleans, anything numeric becomes a number, everything else stays a string ("#ffffff"). The option groups worth knowing:

Group	Keys
Bevel	`bevelEnabled`, `bevelRadius`, `bevelStrength`, `bevelEdgeAmplify`
Contact shadow	`jewelryShadowEnabled`, `…Darkness`, `…Blur`, `…Scale`, `…Falloff`, `…Color`, `…LightX/Y/Z`
Ambient occlusion	`effectComposerN8aoEnabled`, `…Radius`, `…Intensity`
Depth of field	`effectComposerDepthOfFieldEnabled`, `…FocusDistance`, `…FocalLength`, `…BokehScale`, `…Autofocus`
Bloom	`effectComposerBloomEnabled`, `…Intensity`, `…LuminanceThreshold`, `…Radius`
Vignette	`effectComposerVignetteEnabled`, `…Offset`, `…Darkness`
Color grading	`effectComposerBrightnessContrast`, `effectComposerHueSaturation`
Caustics	`causticsEnabled`, `causticsIntensity`, `causticsColor`, `causticsIor`
Studio lights	`keyLightEnabled/Intensity/Color`, `fillLight`, `rimLight`
Misc	`autoRotate`, `autoRotateSpeed`, `toneMappingExposure`, `environmentBlur`

An unknown key is not an error - the page just stores it and nothing changes. Spell carefully.

A batch of options: SetViewerOptions

rtr.SetViewerOptions("""{
  "effectComposerBloomEnabled": true,
  "effectComposerBloomIntensity": 0.6,
  "effectComposerVignetteEnabled": true,
  "jewelryShadowEnabled": true
}""")                                          # -> None

Applies several options in one round trip. The argument is a JSON object of keys to values; anything else throws “optionsJson must be a JSON object of option keys to values.”, and an empty object throws “optionsJson has no options.” Values here are real JSON types, so no string-parsing rules apply.