MoonRay command-line tool
moonray is the command-line tool for rendering scenes in RDL2 scene format with MoonRay.
For interactive rendering, see moonray_gui.
For distributed single/multi machine rendering, see arras_render.
moonray takes in one or more input files, and when the render is complete the resulting rendered image is written to disk, along with any additional images that are specified via RenderOutputs in the scene description.
Command-line options
Use the -h flag to display the full list of command-line options.
$ moonray -h
Usage: moonray [options]
Options:
-help
Print this message.
-in scene.rdl{a|b}
Input RDL scene data. May appear more than once. Processes multiple
files in order.
-deltas file.rdl{a|b}
Updates to apply to RDL scene data. May appear more than once.
First renders without deltas and outputs the image. Then applies each
delta file in order, outputting an image between each one.
-out scene.exr
Output image name and type.
-threads n
Number of threads to use (all by default).
-cpu_affinity cpuIdDef
set CPU affinity definition. "-1" disables CPU affinity control. "all" uses all CPUs
cpuIdDef example : 0,1,2 => 0 1 2
0-2,4,6-9 => 0,1,2,4,6,7,8,9
-1 => disable CPU affinity
all => use all CPUs of the host
-socket_affinity socketIdDef
set Socket affinity definition. "all" uses all Sockets
socketIdDef example : 0 => 0
0,1 or 0-1 => 0 1
all => use all Sockets of the hosts
-mem_affinity on|off
set Memory affinity control. Default is off.
-auto_affinity on|off
set Auto affinity control mode. Default is on.
This automatically sets CPU and Memory affinity based on the user-specified thread total.
-size 1920 1080
Canonical frame width and height (in pixels).
-res 1.0
Resolution divisor for frame dimensions.
-exec_mode mode
Choose a specific mode of execution. Valid options are:
scalar - run in scalar mode (default).
vector - always run vectorized regardless if volumes are found.
xpu - run in xpu mode.
auto - attempt to run vectorized but fall back to scalar if volumes are found.
-sub_viewport l b r t
-sub_vp l b r t
Clamp viewport render region.
-debug_pixel x y
Only render this one pixel for debugging. Overrides viewport.
-dso_path dso/path
Prepend to search path for RDL DSOs.
-camera camera
Camera to render from.
-layer layer
Layer to render from.
-fast_geometry_update
Turn on supporting fast geometry update for animation.
-record_rays .raydb/.mm
Save ray database or mm for later debugging.
-primary_range 0 [0]
Start and end range of primary ray(s) to debug. Only active with
-record_rays.
-depth_range 0 [0]
Start and end range of ray depths to debug. Only active with
-record_rays.
-rdla_set "var name" "expression"
Sets a global variable in the Lua interpreter before any RDLA is
executed.
-scene_var "name" "value"
Override a specific scene variable.
-attr_set "object" "attribute name" "value"
Override the value of an attribute on a specific SceneObject.
-attr_bind "object" "attribute name" "bound object name"
Override the binding on an attribute of a specific SceneObject.
-info
Enable verbose progress and statistics logging on stdout.
-debug
Enable debug level logging on stdout.
-stats filename.csv
Enable logging of statistics to a formatted file.
-athena_tags "TAG1=VALUE1 TAG2=VALUE2 ... TAGN=VALUEN"
Provided string will be sent to Athena Log Server and can be used to access stats on this render
Intended to be used for storing user specific data of interest such as RATS tests, testmaps, etc
TAG and VALUES are entirely up to the user
-resume_render
activate both of resume render and checkpoint render
-resumable_output
Make aov output as resumable for resume render
-checkpoint
Enable progress checkpoint rendering mode
Below is more information on the some of the most commonly used options and workflows.
Affinity control (CPU and Memory)
See the Affinity control page for more info.
Checkpoint Rendering
See the Checkpoint/Resume Rendering page.
Execution Mode
See the Execution Modes page for more info.
Inputs
The inputs to moonray are one or more RDLA or RDLB files (see the RDL2 scene format).
$ moonray -in scene.rdla
Multiple RDL2 input files are supported. Each input file can declare new SceneObjects along with their attributes, as well as override or set attributes on SceneObjects that were declared in previously processed files. The RDL2 files are processed in the order they are given on the command-line.
It is sometimes convenient to store large vector attributes (vertices, face indices, or other per-vertex data, for example) in RDLB binary format, while the bulk of the SceneClasses and their non-vector attributes are stored in RDLA format for easy human readability.
$ moonray -in main_scene.rdla -in extra_lights.rdla -in some_large_geom_data.rdlb
Outputs
By default, moonray writes out an image named scene.exr. This name of this file can be changed using the -out argument:
$ moonray -in scene.rdla -out my_image.exr
moonray will also potentially write out additional images containing various data if the scene contains RenderOutputs
Overriding Scene Variables
It is possible to set or override any attribute of the SceneVariables directly from the command-line, via the -scene_var command-line argument. This is useful for things like optimizing render settings on an existing scene without modifying the input RDL2 files.
-- scene.rdla
SceneVariables {
["pixel_samples"] = 12,
["max_depth"] = 10,
["image_width"] = 1920,
["image_height"] = 782,
}
$ moonray -in scene.rdla -scene_var "max_depth" "2" -scene_var "pixel_samples" "1" -scene_var "res" "2"
Overriding Attributes
You can override an attribute of any Scene Object using -attr_set on the command-line. This feature can be useful for things like running a series of wedge renders via bash script, for example.
Here’s a simple example:
-- sphere.rdla
SphereGeometry("sphere") {
["radius"] = 1,
["phi_max"] = 360,
["zmax"] = 1,
["zmin"] = -1,
}
$ moonray -in sphere.rdla -attr_set "sphere" "radius" "42"
Setting Lua Variables
It is also possible to set global Lua variables that will be available during the processing of the input RDLA files using the -rdla_set command-line argument. These variables can then be accessed in an RDLA file.
Here’s an simple example:
-- sphere.rdla
SphereGeometry("sphere") {
["radius"] = my_radius,
["phi_max"] = 360,
["zmax"] = 1,
["zmin"] = -1,
}
$ moonray -in sphere.rdla -rdla_set "my_radius" "42"