Help:RenderWarrior

From RandomControl Wiki

RenderWarrior

RendomControl commandline powertool.
	Current version		v1.0.00
	fryrender support		v1.6.00
	Arion support		v1.6.00
	Release date		December 6th, 2011
	Operating system		Microsoft Windows, Mac OS X and Linux
	Type		Commandline tool
	License		fryrender and/or Arion (single/multi)

RenderWarrior (also styled as rwa or RWA) is the fryrender and Arion commandline powertool.

Historically, both fryrender and Arion used to have their own commandline tool. Those were called frycmd.exe and arncmd.exe, respectively. In 2011 both commandline tools were fused into a single executable called renderwarrior.exe. RenderWarrior carries both engines inside, and provides a unified wrapper which makes things simpler for users. For example, now the same arguments have the same meaning on both engines.

RenderWarrior makes use of the same licensing system as the standalones. This means that in order to render with fryrender using RenderWarrior, a valid license of fryrender is required. The same applies to Arion. Customers owning both products are entitled to render seamlessly with both engines through RenderWarrior.

Since fryrender v1.6.00 and Arion v.1.5.00, RenderWarrior is available in 32-bit/64-bit flavors for Microsoft Windows, Apple Mac OS X and Linux.

Highlights

• Lua scripting in RenderWarrior.
• How to render with RenderWarrior.
• How to create batch files.

Contents 1 Purpose 2 Basic guidelines 3 Usage for DSI management 3.1 Multi-merge 3.2 DSI info 3.3 Tonemapping 4 Usage for Lua scripting 5 Usage for RCS rendering 5.1 Input RCS scene 5.2 DSI and/or RGB output 5.3 Output resolution 5.4 Animation rendering 5.5 Multi-channel rendering 5.6 Active frame/camera 5.7 Stop conditions 5.8 Stereoscopic rendering 5.9 QRN seed (fryrender) 5.10 Hardware configuration (fryrender) 5.11 Hardware configuration (Arion) 5.12 GI bounces (Arion) 5.13 XML progress output

Purpose

RenderWarrior can be used to:

• Automate render tasks through direct commandline arguments.
• Automate render tasks using Lua scripting.
• Manage DSI files.

Some typical practical examples of uses of RenderWarrior are:

• Render a multi-channel animation.
• Batch a list of renders with different cameras.
• Batch a list of renders of different scenes.
• Merge multiple DSI files.
• Dispatch render tasks on a network in a custom-made render farm.
• Render a turntable by animating a camera through a Lua script.
• ...

Basic guidelines

RenderWarrior is included in the setups of fryrender and Arion. In order to operate, RenderWarrior needs that either render engine (or both) are installed properly, with a valid customer license.

RenderWarrior has dependencies with the following other files:

• The fryrender and/or Arion customer license/s.
• The file rcsdk_base.lua.
• The Arion file hardware.cfg.

All these files are copied to the right location (the system's Roaming folder) by the product setup. So assuming that a fresh installation of either product is available, these dependencies should be completely transparent to the user.

How to invoke RenderWarrior on Windows

Let's assume that you installed fryrender under C:\Program Files\RandomControl\fryrender.

• Open a DOS box. In order to do that, go to Start > Run and type cmd.
• The executable renderwarrior.exe is installed under /apps in the installation folder. So the first step is to change the current directory to that path. In the DOS box, type:

 C:\>cd "C:\Program Files\RandomControl\fryrender\apps"

• Now you can invoke RenderWarrior by typing this in the DOS box:

 renderwarrior -fryrender

Note that all commands starting by -fryrender (or -fry) require a valid fryrender customer license, while all commands starting by -arion (or -arn) require a valid Arion customer license.

Usage for DSI management

RenderWarrior can be used to automate certain operations involving DSI files.

Multi-merge

 renderwarrior -fryrender -merge:<file> <file> <file> ...

This command takes any number of source DSI files and an output DSI file name. The source DSI files are merged, and the resulting DSI is written under the output file name.

For example, the following command merges three DSI files into a destination DSI:

 renderwarrior -fryrender -merge:"z:\final.dsi" "c:\output\source_a.dsi" "c:\output\source_b.dsi" "c:\output\source_c.dsi"

Note that all the source DSI files must match in resolution, compositing channels, and number of LightMixer layers.

DSI info

 renderwarrior -fryrender -dsiinfo:<file>

The following command displays some relevant info (resolution, number of passes, ...) extracted from a DSI file:

 renderwarrior -fryrender -dsiinfo:"c:\my output folder\output.dsi"

Tonemapping

 renderwarrior -fryrender -tonemap:<file> -rcs:<file> -rgb:<file>

RenderWarrior can apply the tonemapping configured in a RCS file to an existing DSI file.

For example, the following command applies the tonemapping configured in the given RCS to the source DSI file, producing a .png output:

 renderwarrior -fryrender -tonemap:"c:\my output folder\output.dsi" -rcs:"c:\my scenes\scene.rcs" -rgb:"d:\my renders\output.png"

Usage for Lua scripting

 renderwarrior -{fryrender|arion} -lua:<file>

One of the most sophisticated and powerful features in fryrender and Arion is the support for Lua scripting.

For example, the following command runs a Lua script picking the installed Arion customer license:

 renderwarrior -arion -lua:"c:\my scripts\turntable.lua"

Lua scripting reaches far beyond the scope of mere commandline arguments, so if you're interested in writing your own Lua scripts for fryrender or Arion, please visit our Wiki page about Lua scripting in RenderWarrior.

Usage for RCS rendering

The most common use of RenderWarrior is to automate the rendering of still frames or animations.

Input RCS scene

• -rcs:<file> - Sets the input scene.

The following command renders a scene with fryrender at 25 passes:

 renderwarrior -fryrender -rcs:scene.rcs -passes:25

Note that the Operating System uses space characters to separate commandline arguments. So if one of your arguments has spaces, you must enclose it between quotes. For example, RCS pathnames with spaces must be provided like this:

 renderwarrior -fryrender -rcs:"c:\my output folder\my scene.rcs" -passes:25

Note also that the arguments described below override the contents of the source RCS file. In general, if one of the arguments below is not set, the corresponding value in the RCS is used by default.

DSI and/or RGB output

• -dsi:<file> - Sets the output DSI file. This applies to fryrender only.
• -rgb:<file> - Sets the output RGB file.

The following command renders a scene with fryrender, setting the output paths explicitly:

 renderwarrior -fryrender -rcs:"c:\output\my scene.rcs" -dsi:"c:\output\render.dsi" -rgb:"c:\output\render.png"

Note that the bit depth used for the RGB output is inferred from the file extension specified:

• Use .hdr or .tif for 32-bpp floating-point raw output.
• Use .png for 16-bpp tonemapped output.
• Use any other supported image extension (such as .tga, .jpg, ...) for 8-bpp tonemapped output.

Also note that the RGB output name provided is appended a suffix with the compositing channel tag and the animation frame number.

If no DSI/RGB output paths are provided, the ones set in the RCS are used. If none are set in the RCS either, they are defaulted to the path the RCS file gets loaded from.

Note that during the rendering process auto-save files are generated next to the final outputs. Those auto-save files have no suffix, as they are always relative to the current channel/frame rendering process.

Output resolution

• -{w|width}:<int> - Sets the width of the output renders.
• -{h|height}:<int> - Sets the height of the output renders.

The following command renders a scene @ 1280x720 with fryrender:

 renderwarrior -fryrender -rcs:"scene.rcs" -w:1280 -h:720 -threads:16 -passes:25

Note that w/width and h/height are synonyms, so the following command is equivalent to the previous one:

 renderwarrior -fryrender -rcs:"scene.rcs" -width:1280 -height:720 -threads:16 -passes:25

Animation rendering

Users can render frame sequences with a single RenderWarrior command.

• -{seq|sequence}:<string> - Sets the frame sequence to be rendered.

The following command renders the first 100 frames of the animation in the scene with fryrender, using 16 CPU threads and 25 passes per frame:

 renderwarrior -fryrender -rcs:"c:\output\scene with animation.rcs" -width:640 -height:360 -threads:16 -passes:25 -sequence:"1-100"

Note that the string format expected by the seq/sequence argument is the same as in all host apps and the fry/Arion standalones. For example, the following command renders frames 1,7,20,21,22,23,24,25:

 renderwarrior -fryrender -rcs:"c:\output\scene with animation.rcs" -width:640 -height:360 -threads:16 -passes:25 -sequence:"1,7,20-25"

Image outputs are named <name>_<channel>_<frame>.<extension> (e.g., output_color_0001.png).

Note that frame IDs start at #1.

Multi-channel rendering

Users can render multiple compositing channels with a single RenderWarrior command.

-{chn|channel}:<string> - Sets the list of compositing channels to be rendered.

These are the compositing channels supported by the current versions of fryrender and Arion:

• color - Full unbiased render.
• decal - Textures with flat illumination. Arion only.
• alpha - Standard alpha channel.
• normals - Standard RGB-packed surface normals. R=X, G=Y, B=Z.
• objid - Colored Object ID channel.
• mtlid - Colored Material ID channel.
• matte - Sun matte/shadows channel. fryrender only.
• depth - Standard depth channel.
• mask - Black/White binary mask. fryrender only.
• vel - Velocity vectors. fryrender only.
• ao - Standard ambient occlusion.

Any combination of compositing channels can be rendered together. The following command renders the color, object ID and ambient occlusion channels in a 25-frame animation with Arion.

 renderwarrior -arion -rcs:scene.rcs -w:640 -h:360 -passes:75 -sequence:"1-25" -channels:"color objid ao"

Note that if no channels are specified explicitly, the color channel alone is rendered.

Image outputs are named <name>_<channel>_<frame>.<extension> (e.g., output_color_0001.png).

Active frame/camera

• -{frm|frame}:<int> - Sets the active frame. This argument is ignored if a frame sequence is provided.
• -{cam|camera}:<int> - Sets the active camera.

The following command renders the second camera of the third frame of a scene with Arion:

 renderwarrior -arion -rcs:scene.rcs -passes:25 -camera:2 -frame:3

Note that frame and camera IDs start at #1.

Stop conditions

Both engines are unbiased and hence they keep refining their calculations until the user decides to stop. In the case of the commandline there's no UI to stop the render process, so a stop condition must be provided.

• -passes:<int> - Sets the engine to render until the given number of passes is reached.
• -minutes:<int> - Sets the engine to render for a certain amount of minutes.

If both stop conditions are provided, the render will stop as soon as the first of them is met.

The following command renders a scene for one hour with fryrender:

 renderwarrior -fryrender -rcs:"scene.rcs" -w:640 -h:360 -threads:16 -minutes:60

The following command renders a scene with fryrender until 75 passes are completed:

 renderwarrior -fryrender -rcs:"scene.rcs" -w:640 -h:360 -threads:16 -passes:75

Stereoscopic rendering

Both engines support stereoscopic rendering of images/animations. In order to render stereoscopically, two parameters are necessary.

• -stereo:{l|left|r|right|both} - Sets which eye (or both) must be rendered.
• -ipd:<int> - Interpupillary distance, measured in millimeters. Explained here: Wikipedia.

If stereoscopic rendering is enabled, image outputs are named <name>_<channel>_<eye>_<frame>.<extension> (e.g., output_ao_left_0001.png).

For example, the following command renders a stereoscopic animation with Arion:

 renderwarrior -arion -rcs:"scene.rcs" -w:640 -h:360 -passes:75 -sequence:"1-25" -channels:"color objid ao" -stereo:both -ipd:65

QRN seed (fryrender)

fryrender uses a Quasi-Random Number seed to randomize each render. This is particularly important if the output DSI files are intended to be merged (network rendering). By default, fryrender always picks a random QRN seed so the user doesn't need to take care of picking a different one for each render. However, it is possible to set a seed explicitly.

• -seed:<int> - Sets the QRN seed.

The following command renders a scene with fryrender setting the QRN seed to 12345:

 renderwarrior -fryrender -rcs:scene.rcs -passes:25 -seed:12345

Hardware configuration (fryrender)

By default RenderWarrior auto-detects the maximum number of CPU threads available to the system. This number is used by default, to make sure that fryrender runs at full steam. However, the user can set a lower number if he wishes to spare some resources for other tasks.

• -threads:<int> - Sets the number of parallel CPU threads used by fryrender.

The following command renders a scene with fryrender, using 8 CPU threads:

 renderwarrior -fryrender -rcs:scene.rcs -passes:75 -threads:8

Hardware configuration (Arion)

Since Arion is a hybrid renderer the user can set different parameters for the CPU and the GPU devices.

• -cpu:<int> - Enables CPU rendering and sets the number of CPU threads.
• -gpu:<string> - Enables GPU rendering and sets which CUDA devices must be used.

The GPU string is a list of O (OFF) or X (ON) characters where the i-th character refers to the i-th CUDA device.

Let's assume a system with 4 CUDA devices:

• -gpu:XXXX enables all the 4 CUDA devices.
• -gpu:OXOO disables CUDA devices #1, #3 and #4, and enables device #2.
• -gpu:OOXX disables CUDA devices #1 and #2, and enables CUDA devices #3 and #4.
• ...

In a system with 4 CUDA-enabled GPUs, the following command enables them all but the first one, and also renders with 8 CPU threads:

 renderwarrior -arion -rcs:scene.rcs -passes:25 -cpu:8 -gpu:OXXX

Note that if no hardware arguments are set, RenderWarrior tries to load the file hardware.cfg where Arion standalone stores its own configuration. So one possibility is to set your hardware configuration in the standalone and then not set any hardware arguments from the commandline.

If no hardware arguments are set and no hardware.cfg file can be found, a hardware auto-detection procedure is run.

Although this is generally not desirable, you can disable CPU rendering by setting the number of CPU threads to 0.

The following command renders with Arion using the same hardware settings as the standalone:

 renderwarrior -arion -rcs:scene.rcs -passes:25

IMPORTANT: In order to enable more than one GPU a valid multi-GPU customer license is required.

GI bounces (Arion)

• -gi:<int> - Sets the maximum number of GI bounces.

The following command renders a scene with Arion, using 128 GI bounces:

 renderwarrior -arion -rcs:scene.rcs -passes:75 -gi:128

XML progress output

-- Documentation not finished yet.