SceneVariables

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

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

Specifies the maximum number of simultaneous open texture file handles.

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_active

Bool
default: False

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

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

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

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”

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:

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

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

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

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

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

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_console

Int
default: -1

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: {}

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: {}

Deprecated.

debug_rays_file

String
default:

Deprecated.

debug_rays_primary_range

IntVector
default: {}

Deprecated.

validate_geometry

Bool
default: False

Checks geometry for bad data

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

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

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

Adjusts the amount of texture filtering.

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

Float
default: 0.0

Used to provide unique samples per frame, and for selecting the frame for scenes with animated data.

max_frame

Float
default: 0.0

Used to provide unique samples per frame.

min_frame

Float
default: 0.0

Used to provide unique samples per frame.

cryptomatte_multi_presence

Bool
default: False

Determines whether to record presence bounces as separate cryptomatte samples.

enable_displacement

Bool
default: True

Enables or disables geometry displacement.

enable_dof

Bool
default: True

Enables or disables camera depth-of-field (DOF)

enable_max_geometry_resolution

Bool
default: False

Specifies whether the max_geometry_resolution limit is in effect.

enable_motion_blur

Bool
default: True

Enables or disables motion blur

enable_presence_shadows

Bool
default: False

Whether or not to respect a material's "presence" value for shadow rays. Performance may improve when disabled, but all materials are treated as fully present.

enable_shadowing

Bool
default: True

Enables or disables shadowing through occlusion rays.

enable_subsurface_scattering

Bool
default: True

Enables or disables sub-surface scattering.

lights_visible_in_camera

Bool
default: False

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

Specifies a global limit to geometry resolution. Geometry procedurals should respect this limit.

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.

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

The desired height of the output image(s), in pixels.

image_width

Int
default: 1920

The desired width of the output image(s), in pixels.

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

Final divisor for the overall image dimensions. A quick way to reduce or increase the size of the render. A value of 2 halves the size of the rendered image(s). A value of 0.5 doubles it.

sub_viewport

IntVector
default: {}

Subviewport of region window. Coordinate (0,0) maps to left, bottom of region window

athena_debug

Bool
default: False

[DreamWorks Animation internal] Enables or disables sending logging results to the Athena debugging database instead of the production database.

fatal_color

Rgb
default: [ 1, 0, 1 ]

The color to use for materials or map shaders that are unable to execute shading, usually due to incomplete initialization.

log_debug

Bool
default: False

Determines whether debugging-level messages are logged.

log_info

Bool
default: False

Determines whether information-level messages are logged.

stats_file

String
default:

The filename to write the rendering statistics to in CSV format.

exr_header_attributes

Metadata
default: None

Metadata that is passed directly to the exr header. Format: {"name", "type", "value"}

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_enable

Bool
default: False

Turn on path guiding to handle difficult light transport problems (e.g. caustics) at the cost of increased memory

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

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

The maximum ray depth (number of "bounces") for diffuse|glossy|mirror event types. This can be thought of as the global depth limit. Reducing this can improve performance at the cost of biasing the rendered image.

max_diffuse_depth

Int
default: 2

The maximum ray depth (number of "bounces") for diffuse event types. Reducing this can improve performance at the cost of biasing the rendered image. Note that this limit is also governed by the global "max depth" attribute.

max_glossy_depth

Int
default: 2

The maximum ray depth (number of "bounces") for glossy event types. Reducing this can improve performance at the cost of biasing the rendered image. Note that this limit is also governed by the global "max depth" attribute.

max_hair_depth

Int
default: 5

The maximum ray depth (number of "bounces") for hair material types. This limit may need to be increased to allow for more hair-to-hair interactions, especially for blonde/white hair or fur. Reducing this can improve performance at the cost of biasing the rendered image.

max_mirror_depth

Int
default: 3

The maximum ray depth (number of "bounces") for mirror event types. Reducing this can improve performance at the cost of biasing the rendered image. Note that this limit is also governed by the global "max depth" attribute.

max_presence_depth

Int
default: 16

The maximum ray depth (number of "bounces") for presence event types. The material's "presence" attribute is ignored after this depth has been reached and the surface is treated as fully present. Reducing this can improve performance at the cost of biasing the rendered image.

max_subsurface_per_path

Int
default: 1

The maximum ray depth (number of "bounces") to allow subsurface scattering. For ray depths beyond this limit Lambertian diffuse is used to approximate subsurface scattering.

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.

max_volume_depth

Int
default: 1

The maximum ray depth (number of "bounces") for volume event types. Volumes are ignored after this depth has been reached. Reducing this can improve performance at the cost of biasing the rendered image.

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.

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”

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”

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

(Frames per second) Affects motion blur.

light_sampling_mode

Int enum
  0 = “uniform” (default)
  1 = “adaptive”

Controls which light sampling scheme to use: uniform or adaptive

light_sampling_quality

Float
default: 0.5

When the light sampling mode is 'adaptive', this attribute controls how many lights are sampled per light sample, where 0.0 is low quality (1 light sampled per light sample) and 1.0 is high quality (all lights sampled per light sample). Any value in between will cause adaptive light sampling to kick into effect, meaning that it will choose a higher or lower number of lights depending on what that particular point needs. A number closer to 0.0 will cause it to sample a lower number of lights on average, and vice versa.

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”

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

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.