SceneVariables

Overview

SceneVariables are the global rendering settings.


Attribute Reference

Caching attributes

fast_geometry_update

Bool
default: False

No documentation available

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

maximum number of simultaneous open 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

No documentation available

layer

Layer
default: None

No documentation available

Checkpoint attributes

checkpoint_active

Bool
default: False

No documentation available

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

No documentation available

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.10000000149

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

interactive_mode

Bool
default: False

No documentation available

machine_id

Int
default: -1

No documentation available

num_machines

Int
default: -1

No documentation available

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.

progressive_shading

Bool
default: False

No documentation available

task_distribution_type

Int enum
  0 = “non-overlapped tile”
  1 = “multiplex pixel” (default)

No documentation available

threads

Int
default: 0

No documentation available

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

No documentation available

enable_dof

Bool
default: True

No documentation available

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

No documentation available

enable_subsurface_scattering

Bool
default: True

No documentation available

lights_visible_in_camera

Bool
default: False

No documentation available

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

No documentation available

debug

Bool
default: False

No documentation available

error

Bool
default: True

No documentation available

fatal_color

Rgb
default: [ 1, 0, 1 ]

No documentation available

info

Bool
default: False

No documentation available

stats_file

String
default:

No documentation available

warning

Bool
default: True

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.00999999977648

(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 loaded 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_sampler_strategy

Int enum
  0 = “multi-sample” (default)
  1 = “one-sample”
  2 = “one-lobe”

Indirect sampling and evaluation strategy: all lobes using one path segment per lobe (multi-sample), all lobes using one shared path segment (one-sample), or one lobe.

bsdf_samples

Int
default: 2

No documentation available

bssrdf_samples

Int
default: 2

No documentation available

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

No documentation available

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.999000012875

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.0375000014901

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.649999976158

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.649999976158

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.995000004768

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”

No documentation available

checkpoint_tile_order

Int enum
  0 = “top”
  1 = “bottom”
  2 = “left”
  3 = “right”
  4 = “morton” (default)
  5 = “random”
  6 = “spiral square”
  7 = “spiral rect”

No documentation available

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”

No documentation available

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 copied or renamed. 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.