SceneVariables
Overview
SceneVariables are the global rendering settings.
Attribute Reference
Caching attributes
fast_geometry_update
Bool
default: False
If this flag is off, the tessellation related data for subdivision surface will be deleted after tessellation is done. This is to save memory for single frame rendering. Otherwise, that data will be kept in memory to support re-tessellation after geometry are updated.
texture_cache_size
Int
default: 4000
This setting specifies the maximum size of the texture cache in megabytes. This value can significantly impact rendering speed, where larger values often improve rendering speed.
texture_file_handles
Int
default: 24000
This setting specifies the maximum number of simultaneous open texture file handles.
Camera and Layer attributes
camera
Camera
default: None
This specifies the camera object used for rendering. If no camera is specified in the scene variables, MoonRay will render using the first camera object encountered.
dicing_camera
Camera
default: None
This attribute specifies a camera to use for adaptive geometry tessellation. The rendering camera is used if no camera is specified.
layer
Layer
default: None
This specifies the layer object used for rendering. If no layer is specified in the scene variables, MoonRay will rendering using the first layer object encountered.
Checkpoint attributes
checkpoint_active
Bool
default: False
This setting enables or disables checkpoint file writing.
checkpoint_bg_write
Bool
default: True
When set to true, checkpoint file writes occur in a background thread that runs concurrently with the MCRT threads. Otherwise, all MCRT threads must wait while the checkpoint file is written.
checkpoint_interval
Float
default: 15.0
This setting specifies the time interval, in minutes, between checkpoint file writes. The interval must be equal to or greater than 0.1 minutes.
checkpoint_max_bgcache
Int
default: 2
This setting specifies the maximum number of queued checkpoint images the checkpoint-writing background thread can handle. The value of checkpoint_max_bgcache must be greater than or equal to 1. If the number of queued checkpoint images exceeds this limit, MCRT threads will be temporarily suspended while background images are written to make room in the queue. A larger value can support background writing even with short checkpoint intervals, but it may require more memory. A value of 2 is recommended for most cases.
checkpoint_max_snapshot_overhead
Float
default: 0.0
This setting specifies the maximum fraction of the snapshot overhead threshold for an extra snapshot action in the event of an unexpected interruption by SIGINT. The value is expressed as a fraction. If the value is set to zero or a negative number, no extra snapshot action will be executed, and no checkpoint file will be generated if SIGINT is received.
checkpoint_mode
Int enum
0 = “time” (default)
1 = “quality”
This setting allows you to choose whether checkpoint images are written based on time elapsed or on quality reached.
checkpoint_overwrite
Bool
default: True
When set to true, the last checkpoint file will be overwritten when writing out the new checkpoint file. If set to false, the checkpoint filename will be appended with the total number of samples, which will result in the retention of all checkpoint files.
checkpoint_post_script
String
default:
This setting specifies the filename of a Lua script that will be executed after every checkpoint file is written. The script will run concurrently with the ongoing MCRT threads. For more information, refer to the documentation for MoonRay-provided Lua variables accessible within the script.
checkpoint_quality_steps
Int
default: 2
This setting specifies the number of quality steps, which refers to the internal sampling iteration count between checkpoint file writes. The value must be equal to or greater than 1. In the case of uniform sampling, this number of steps is equivalent to the pixel sampling steps for each pixel. For example, if you set quality steps to 2, a checkpoint file will be created every time each pixel's sample count exceeds 2, 4, 6, 8, 10, and so on. In the case of adaptive sampling, this number of steps is equivalent to the internal adaptive sampling iteration steps. A recommended number falls within the range of 1 to 3. For example, if you set the value to 2, a checkpoint file will be created after finishing every 2 adaptive sampling passes. A larger value will conduct more rendering passes before writing a file.
checkpoint_sample_cap
Int
default: 0
This setting causes the render to finish based on the total pixel sample count. For example, if the value is 1024, the render will end after the next checkpoint write when each pixel exceeds 1024 samples. If the value is set to 0, the sample cap feature is disabled.
checkpoint_snapshot_interval
Float
default: 0.0
This setting specifies the time interval, in minutes, allowed for a snapshot when a SIGINT is encountered. If the value is 0 or negative, the checkpoint_max_snapshot_overhead parameter is used instead.
checkpoint_start_sample
Int
default: 1
This setting specifies the samples per pixel (SPP). A checkpoint file is created when all pixels' SPP are greater than or equal to this number. A checkpoint file is created once this criterion is met.
checkpoint_time_cap
Float
default: 0.0
This setting determines when the render will finish based on the total render process time in minutes. If the value is exceeded, the render will finish after the next checkpoint write. If the value is set to 0, the time cap feature is disabled.
checkpoint_total_files
Int
default: 0
This variable specifies the total number of checkpoint files for the quality-based checkpoint mode. It serves as a substitute parameter for checkpoint_quality_steps. If the value is set to 0 (the default), the interval at which checkpoints are generated is controlled by the checkpoint_quality_steps variable. If the value is set to 1 or higher, the renderer will attempt to automatically generate a user-defined number of checkpoint files based on this value. This option takes into account the checkpoint_start_sample variable.
In some cases, the renderer may be unable to create the requested number of checkpoint_total_files due to limitations in the internal implementation or because the user has specified a value greater than 1 for the checkpoint_start_sample variable. However, in these cases, the renderer will attempt to generate the closest possible number of checkpoint files to the user-defined value.
Debug attributes
debug_console
Int
default: -1
This setting specifies the port number for the debug console. When the debug console functionalities are enabled, you can use a telnet connection to send commands and control rendering behavior for debugging purposes.
- A value of -1 disables all debug console functionality.
- A positive value specifies a specific port number.
- If you set the port number to 0, the kernel will find an available port for you and display the port number to stderr.
debug_pixel
IntVector
default: {}
This setting allows for rendering a single pixel and is typically used for debugging. The value given specifies the 2D pixel coordinate expressed from the bottom-left of the frame-viewport
debug_rays_depth_range
IntVector
default: {}
No documentation available
debug_rays_file
String
default:
No documentation available
debug_rays_primary_range
IntVector
default: {}
No documentation available
validate_geometry
Bool
default: False
Checks geometry for bad data
Deep Images attributes
deep_curvature_tolerance
Float
default: 45.0
Maximum curvature (in degrees) of the deep surface within a pixel before it is split
deep_format
Int enum
0 = “openexr2.0”
1 = “opendcx2.0” (default)
Deep image format:
openexr2.0: vanilla OpenEXR deep
opendcx2.0: DCX abuffer mask encoding
deep_id_attribute_names
StringVector
default: {}
Names of primitive attributes containing deep IDs
deep_layer_bias
Float
default: 0.1
Minimum distance between deep layers
deep_max_layers
Int
default: 1
Maximum number of depth layers to output
deep_vol_compression_res
Int
default: 10
Volume opacity compression resolution. Lower values gives higher compression.
deep_z_tolerance
Float
default: 2.0
Maximum range of the deep surface's Z values within a pixel before it is split
Driver attributes
machine_id
Int
default: -1
Used only in arras moonray context, automatically set by arras and indicates the MCRT computation ID in the current session
num_machines
Int
default: -1
Used only in arras moonray context, automatically set by arras and indicates total number of MCRT computations active in the current session
output_file
String
default: scene.exr
This specifies the output path for the beauty image (RGBA). This is independent of the AOV RenderOutputs, which can also write a beauty image.
task_distribution_type
Int enum
0 = “non-overlapped tile”
1 = “multiplex pixel” (default)
Used only in arras moonray context, defines the task distribution method to the MCRT computation. Multi-plex pixel is the default and preferred method. Non-overlapped tile is experimental and only used for debugging/development purposes
tmp_dir
String
default:
Define temporary directory name for temporary file generation. Use $TMPDIR environment variable value if this variable is empty.If $TMPDIR is also empty, use /tmp
Filtering attributes
pixel_filter
Int enum
0 = “box”
1 = “cubic b-spline” (default)
2 = “quadratic b-spline”
The type of filter used for filter importance sampling. A box filter with a width of 1 is analogous to disabling pixel filtering.
pixel_filter_width
Float
default: 3.0
The overall extents, in pixels, of the pixel filter. Larger values will result in softer images.
texture_blur
Float
default: 0.0
No documentation available
Fireflies Removal attributes
roughness_clamping_factor
Float
default: 0.0
Clamp material roughness along paths. A value of 1 clamps values to the maximum roughness encountered, while lower values temper the clamping value. 0 disables the effect. Using this technique reduces fireflies from indirect caustics but is biased.
sample_clamping_depth
Int
default: 1
Clamp sample values only after the given non-specular ray depth.
sample_clamping_value
Float
default: 10.0
Clamp sample radiance values to this maximum value (the feature is disabled if the value is 0.0). Using this technique reduces fireflies, but is biased.
Frame attributes
frame
Float
default: 0.0
No documentation available
max_frame
Float
default: 0.0
No documentation available
min_frame
Float
default: 0.0
No documentation available
Global Toggles attributes
cryptomatte_multi_presence
Bool
default: False
This setting determines whether to record presence bounces as separate cryptomatte samples.
enable_displacement
Bool
default: True
This setting enables or disables geometry displacement.
enable_dof
Bool
default: True
This setting enables camera depth-of-field (DOF)
enable_max_geometry_resolution
Bool
default: False
No documentation available
enable_motion_blur
Bool
default: True
No documentation available
enable_presence_shadows
Bool
default: False
No documentation available
enable_shadowing
Bool
default: True
This setting enables or disables shadowing through occlusion rays.
enable_subsurface_scattering
Bool
default: True
This setting enables or disables sub-surface scattering.
lights_visible_in_camera
Bool
default: False
This setting globally enables or disables lights being visible in camera. Each light has its own setting which may override this value.
max_geometry_resolution
Int
default: 2147483647
No documentation available
propagate_visibility_bounce_type
Bool
default: False
turns on/off propagation for ray visibility masks
shadow_terminator_fix
Int enum
0 = “Off” (default)
1 = “On”
2 = “On (Sine Compensation Alternative)”
3 = “On (GGX Compensation Alternative)”
4 = “On (Cosine Compensation Alternative”
Attempt to soften hard shadow terminator boundaries due to shading/geometric normal deviations. "ON uses a custom terminator softening method. Cosine Compensation" is Chiang's 2019 SIGGRAPH technique. "GGX" is Estevez's raytracing gems technique. "Sine Compensation" is a sine based modification of Chiang's method. Different scenes may work better with different techniques. The recommendation is to start with the custom compensation ON, then sine compensation technique, then GGX, then cosine.
Image Size attributes
aperture_window
IntVector
default: {}
The window of the camera aperture. Overrides image_width and image_height. Ordered as xmin, ymin, xmax, and ymax, with origin at the bottom-left.
image_height
Int
default: 1080
No documentation available
image_width
Int
default: 1920
No documentation available
region_window
IntVector
default: {}
Window that is rendered. Overrides image width / height (and overrides aperture window override). Order: xmin ymin xmax ymax, with origin at left bottom.
res
Float
default: 1.0
No documentation available
sub_viewport
IntVector
default: {}
Subviewport of region window. Coordinate (0,0) maps to left, bottom of region window
Logging attributes
athena_debug
Bool
default: False
[DreamWorks Animation internal] This setting enables sending logging results to the Athena debugging database instead of the production database.
debug
Bool
default: False
This setting determines whether debugging-level messages are logged.
fatal_color
Rgb
default: [ 1, 0, 1 ]
No documentation available
info
Bool
default: False
This setting determines whether information-level messages are logged.
stats_file
String
default:
No documentation available
Metadata attributes
exr_header_attributes
Metadata
default: None
Metadata that is passed directly to the exr header. Format: {"name", "type", "value"}
Motion and Scale attributes
motion_steps
FloatVector
default: {}
frame-relative time offsets for motion sampling
scene_scale
Float
default: 0.01
(in meters): one unit in world space = 'scene scale' meters
Path Guide attributes
path_guide_enable
Bool
default: False
Turn on path guiding to handle difficult light transport problems (e.g. caustics) at the cost of increased memory
See Also
Resume Render attributes
on_resume_script
String
default:
When using resumable rendering, the Lua script named here is executed after the render prep stage. In addition, MoonRay sets some Lua global variables the script can access. This functionality is disabled when the script name is empty or when not using resumable rendering. Please refer to the checkpoint/resume documentation for more details.
resumable_output
Bool
default: False
make aov output as resumable for resume render
resume_render
Bool
default: False
resuming render process
Sampling attributes
bsdf_samples
Int
default: 2
The square root of the number of samples taken for BSDF lobe evaluations on the primary intersection. The number of samples taken per material depends on the BSDF sampler strategy and the number of lobes that comprise the material.
bssrdf_samples
Int
default: 2
The square root of the number of samples taken to evaluate BSSRDF (subsurface scattering) contributions on the primary intersection.
disable_optimized_hair_sampling
Bool
default: False
Forces all hair materials to sample each hair BSDF lobe independently. This will enable the LPE label syntax for 'hair R', 'hair TT', 'hair TRT' and 'hair TRRT ' but will result in slower rendering
light_samples
Int
default: 2
The square root of the number of samples taken for each light on the primary intersection.
lock_frame_noise
Bool
default: False
By default, the random number generators are seeded by considering the frame number. However, if lock_frame_noise is true, the same seed values are used for each frame, which is typically undesirable.
max_depth
Int
default: 5
No documentation available
max_diffuse_depth
Int
default: 2
No documentation available
max_glossy_depth
Int
default: 2
No documentation available
max_hair_depth
Int
default: 5
No documentation available
max_mirror_depth
Int
default: 3
No documentation available
max_presence_depth
Int
default: 16
No documentation available
max_subsurface_per_path
Int
default: 1
No documentation available
pixel_samples
Int
default: 8
The square root of the number of primary samples taken for each pixel in uniform sampling mode. For example, a value of 4 will result in 4*4 = 16 uniform pixel samples.
presence_threshold
Float
default: 0.999
The presence threshold defines the point at which the accumulated presence can be considered opaque, skipping the generation of presence continuation rays.
russian_roulette_threshold
Float
default: 0.0375
The Russian roulette threshold specifies the point at which point Russian roulette is evaluated for direct light sampling and BSDF continuation. The unit is luminance of the radiance.
transparency_threshold
Float
default: 1.0
The transparency threshold defines the point at which the accumulated opacity can be considered opaque, skipping the generation of new transparency rays.
Volumes attributes
max_volume_depth
Int
default: 1
No documentation available
volume_attenuation_factor
Float
default: 0.65
Controls how volume attenuation gets exponentially scaled down when rendering multiple scattering volumes. Dialing down the value generally results in more translucent look. This variable is only effective when "max volume depth" is greater than 1
volume_contribution_factor
Float
default: 0.65
Controls how scattering contribution gets exponentially scaled down when rendering multiple scattering volumes. Dialing down the value generally results in a darker volume scattering look. This variable is only effective when "max volume depth" is greater than 1
volume_illumination_samples
Int
default: 4
Sample number along the ray when computing volume scattering radiance towards the eye. Set to 0 to turn off volume lighting completely.
volume_opacity_threshold
Float
default: 0.995
As a ray travels through volumes, it will accumulate opacity. When the value exceeds the volume opacity threshold, the renderer will stop further volume integration along this ray.
volume_overlap_mode
Int enum
0 = “sum” (default)
1 = “max”
2 = “rnd”
Selects how to handle contributions from overlapping volumes:
sum: add contributions from all volumes
max: only consider maximum volume based on extinction
rnd: randomly choose one value weighted by extinction
Warning: light linking does not work correctly in sum mode.
volume_phase_attenuation_factor
Float
default: 0.5
Controls how phase function (anisotropy) gets exponentially scaled down when rendering multiple scattering volumes. This variable is only effective when "max volume depth" is greater than 1
volume_quality
Float
default: 0.5
Controls the overall quality of volume rendering. The higher number gives better volume shape detail and more accurate scattering integration result.
volume_shadow_quality
Float
default: 1.0
Controls the quality of volume shadow (transmittance). The higher number gives more accurate volume shadow.
General attributes
batch_tile_order
Int enum
0 = “top”
1 = “bottom”
2 = “left”
3 = “right”
4 = “morton” (default)
5 = “random”
6 = “spiral square”
7 = “spiral rect”
8 = “morton shiftflip”
This setting specifies the order in which tiles (as areas of 8x8 pixels) are prioritized for batch rendering, which determines which areas of the image are rendered first. The ordering is not guaranteed: the strict sequence of tile starting and completion for any pass is nondeterministic due to thread scheduling.
checkpoint_tile_order
Int enum
0 = “top”
1 = “bottom”
2 = “left”
3 = “right”
4 = “morton” (default)
5 = “random”
6 = “spiral square”
7 = “spiral rect”
8 = “morton shiftflip”
This setting specifies the order in which tiles (as areas of 8x8 pixels) are prioritized for checkpoint rendering, which determines which areas of the image are rendered first. The ordering is not guaranteed: the strict sequence of tile starting and completion for any pass is nondeterministic due to thread scheduling.
crypto_uv_attribute_name
String
default:
Names of primitive attribute containing crypto UVs
fps
Float
default: 24.0
No documentation available
max_adaptive_samples
Int
default: 4096
When adaptive sampling is turned on, this represents the max number of samples we can throw at a pixel. It's best to err on the high side since adaptive sampling will cull out samples where they're not needed based on the target adaptive error, in which case we should rarely hit the max samples value.
min_adaptive_samples
Int
default: 16
This is the minimum number of samples taken per pixel before enabling adaptive sampling. A larger number of samples may prevent the adaptive sampler from prematurely identifying an area as converged but may incur a longer running time.
progressive_tile_order
Int enum
0 = “top”
1 = “bottom”
2 = “left”
3 = “right”
4 = “morton” (default)
5 = “random”
6 = “spiral square”
7 = “spiral rect”
8 = “morton shiftflip”
This setting specifies the order in which tiles (as areas of 8x8 pixels) are prioritized for progressive rendering, which determines which areas of the image are rendered first. The ordering is not guaranteed: the strict sequence of tile starting and completion for any pass is nondeterministic due to thread scheduling.
sampling_mode
Int enum
0 = “uniform” (default)
2 = “adaptive”
Controls which sampling scheme to use: uniform or adaptive.
target_adaptive_error
Float
default: 10.0
When adaptive sampling is turned on, this represents the desired quality of the output images. Lower values will give higher quality but take longer to render. Higher values will give lower quality but render quicker.
two_stage_output
Bool
default: True
This setting specifies whether to use a two-stage writing process for images. In two-stage writing, the image is first written to a temporary location and then moved to the final location. This approach significantly reduces the risk of output data corruption due to an unexpected render process termination.
The directory where the temporary files are stored is defined by the "tmp_dir" scene variable.