Skip to content

Scene properties (USTR)

Every scene property has a unique string identifier, its USTR. USTRs are what you pass to the CLI set and set_string commands and to the viewer messaging API set_string / get_string messages.

How it works

A set_string call takes two parts: the node picks what you are editing (::globals, ::camera, a layer name, ...), and the USTR names the property on it. The set succeeds when the name is valid and the target actually has that property.

Note

The CLI set <ustr> <value> shorthand derives the node from the prefix, so it only reaches globals_, animation_, camera_, and render_pipeline_ properties. Use set_string to reach per-layer obj_* properties.

Value encoding

All values travel as strings and are parsed according to the property's type:

Type Format Example
bool 0 or 1 (also true / false) 1
int decimal integer 1920
float decimal number 45.0
color r,g,b in 0.0 to 1.0 0.8,0.2,0.1
enum dropdown choice as a decimal integer: the position of the chosen option in the list, counting from zero (each enum property has its options listed below) 2
string UTF-8 text My Scene
void one of the pressable buttons in the Excelsior Editor's UI; setting any value presses it 1

Availability

Label Meaning
standard Exposed in the editor UI. Safe, supported surface.
pro Standard, but tied to a PRO feature (branding, spinner, interactive export).
virtual Reads and writes the live on-screen camera directly.

Globals (::globals)

USTR Type Description
globals_resolution_preset enum standard Resolution preset: 0 Custom, 1 Instagram (square), 2 Instagram (portrait), 3 YouTube.
globals_resolution_w int standard Render width in pixels.
globals_resolution_h int standard Render height in pixels.
globals_ground_scale float standard Ground plane scale.
globals_ground_angle float standard Ground plane rotation, degrees.
globals_ibl_angle float standard Environment rotation, degrees.
globals_ibl_shadows_gamma float standard Shadow gamma correction.
globals_floor_mirror_enable bool standard Enable floor mirror reflection.
globals_floor_mirror_weight float standard Mirror reflection weight.
globals_floor_gi_see_through color standard Floor see-through color.
globals_backplate_color color standard Background color.
globals_pose_id enum standard Active pose preset. Setting it applies the pose: 0 Vertical, 1 Resting Left, 2 Resting Right, 3 Horizontal Left, 4 Horizontal Right.
globals_pose_yaw float standard Model yaw rotation, degrees.
globals_pose_pos_z float standard Model vertical offset.
globals_viewer_title string standard Viewer title string.
globals_viewer_nocontrols bool standard Hide viewer controls.
globals_viewer_nolabels bool standard Hide material group labels.
globals_viewer_autospin bool standard Viewer starts with auto-spin enabled.
globals_atlas_layout enum standard Atlas contact sheet layout: 0 2 x 2, 1 2 x 1, 2 4 x 1, 3 1 x 2, 4 1 x 4, 5 Big + 4, 6 4 + Big, 7 Big : 4, 8 4 : Big.
globals_atlas_slot_0_viewpoint_id ... globals_atlas_slot_4_viewpoint_id enum standard Viewpoint assigned to each atlas slot: 0 Looking Down, 1 Perspective, 2 Through, 3 Side View, 4 Current View.
globals_branding_frontplate_enable bool pro Enable the branding frontplate overlay.
globals_branding_frontplate_alignment enum pro Frontplate alignment (the intro and outro alignments share these options): 0 Top-Left, 1 Top-Center, 2 Top-Right, 3 Center-Left, 4 Center, 5 Center-Right, 6 Bottom-Left, 7 Bottom-Center, 8 Bottom-Right.
globals_branding_frontplate_margin float pro Frontplate margin.
globals_branding_frontplate_scale float pro Frontplate scale.
globals_branding_frontplate_color_map string pro Frontplate image, as an https:// URL.
globals_branding_intro_enable bool pro Enable the intro branding sequence.
globals_branding_intro_color color pro Intro veil color.
globals_branding_intro_color_map string pro Intro logo image, as an https:// URL.
globals_branding_intro_scale float pro Intro logo scale.
globals_branding_intro_veil_hold float pro Intro veil hold time.
globals_branding_intro_logo_hold float pro Intro logo hold time.
globals_branding_outro_* mixed pro Outro counterparts of the intro set above.

Camera (::camera)

USTR Type Description
camera_hfov float standard Horizontal field of view, degrees.
camera_dof_enable bool standard Enable depth of field.
camera_focus float standard Focus distance, millimeters.
camera_dof_max_radius float standard Maximum blur radius.
camera_center_view void standard Button: recenter the view on the model.
camera_pick_focus void standard Button: pick the focus distance interactively.
camera_theta / camera_phi float standard Orbit azimuth and elevation, degrees.
camera_dolly float standard Camera distance, in normalized scene units: 0.01 (closest) to 0.5.
camera_pan_x / camera_pan_y float standard Screen space pan, in scene-relative units.

The framing attributes above belong to the scene's camera definition: the framing a scene ships with, and the one render actions use. How they relate to the live, on-screen camera depends on where you are:

  • In the CLI, set camera_theta 70 and friends reframe the live view directly, so they are the natural way to frame a shot before a take_picture.
  • In the embedded viewer, the on-screen camera follows the user's orbiting and ignores these attributes. To read or move it from JavaScript, use the tracker_cam_* virtual properties below.

Live camera (virtual)

These names are handled specially on ::camera: they read and write the live on-screen camera, so they always reflect what is on screen.

USTR Type Description
tracker_cam_theta float virtual Orbit azimuth, degrees.
tracker_cam_phi float virtual Orbit elevation, degrees.
tracker_cam_dolly float virtual Camera distance, in normalized scene units: 0.01 (closest) to 1 (farthest).
tracker_cam_pan_x / tracker_cam_pan_y float virtual Screen space pan, in scene-relative units.
tracker_cam_hfov float virtual Live horizontal field of view, degrees.

Render pipeline (::render_pipeline)

USTR Type Description
render_pipeline_glare_enable bool standard Enable glare.
render_pipeline_glare_strength float standard Glare intensity.
render_pipeline_ssr_re_enable bool standard Enable round edges.
render_pipeline_ssr_re_radius float standard Round edges radius.
render_pipeline_sharpen_enable bool standard Enable sharpening.
render_pipeline_sharpen_strength float standard Sharpen intensity.

Animation (::animation)

USTR Type Description
animation_bitrate int standard Video bitrate.
animation_speed enum standard Animation speed: 0 Very fast (3 s), 1 Fast (6 s), 2 Normal (12 s, the default), 3 Slow (18 s), 4 Very slow (26 s).
animation_easing enum standard Easing function: 0 Constant, 1 Ease In/Out.
animation_subject enum standard What the animation drives: 0 Camera, 1 Pose (slow).
animation_rotate float standard Rotation amount, degrees (45 to 360).
animation_rotate_flip bool standard Flip rotation direction.
animation_boomerang_enable bool standard Boomerang (ping-pong) playback.
animation_motion_blur_enable bool standard Motion blur.

Objects and materials (per layer)

Object properties live on layers. Address them with the layer name or its id: set_string "Metal Band" obj_visible 0.

USTR Type Description
obj_visible bool standard Layer visibility.

The most useful material controls per family:

USTR Type Family Description
obj_mtl_absorption float gemstone Light absorption (color depth).
obj_mtl_scs_amplitude float gemstone Clarity.
obj_mtl_roughness float metal, pearl Surface roughness.
obj_mtl_coating_weight float pearl, plastic Luster (pearl) or glossiness (plastic).
obj_mtl_coating_roughness float opal, plastic Coating roughness.

Found a mistake?

We do our best to keep this reference accurate and in step with the product, but mistakes and omissions can slip through, and they are never intentional. If anything here looks wrong, incomplete, or unclear, please contact us and we will gladly fix it.