Batch Mode

Batch mode allows you to render sequences of frames from a Katana scene all at once. It is started through a command line, where you specify the file path, frame range and any other necessary options.

Note:  You will only be able to access terminal modes, including Batch Mode, if you have a Katana render license (katana_r). If you're a student, you can access one for free.

Batch mode is useful if you have a large number of frames to render as it will render out each individual file in the background. You can continue working on a Katana scene file whilst it is being batch rendered as the command uses the last saved version.

Before starting a batch render, ensure the render settings and the render flag are all set up correctly in Katana. To set the render flag, select the node you wish you render from and press V on the keyboard. The render flag can be determined through the command line, however setting it up beforehand simplifies the string needed to run Batch mode and minimizes any room for error.

Note:  When you specify the Image Filename for the output render, ensure you use one or more hashes as they will be replaced by the frame number in your rendered file name. For example: fileName_<aov>_###.<ext>

Start a Batch Render

Windows

  1. Open the Command Prompt.
  2. Navigate to the directory where you have Katana installed using the cd command, for example:

    cd C:\Program Files\Katana3.2v1\bin

  3. Enter the following command to start a batch render:

    katanaBin.exe --batch --katana-file=C:\yourDirectory\yourScene.katana -t 1-1000

    Where:

  4. Press Enter to start the render.

You can add more arguments to the command. For example, use --render-node to specify the node you would like to render from if you haven't set your render flag in the Katana scene or if you would like to change it:

katanaBin.exe --batch --katana-file=C:\yourDirectory\yourScene.katana --render-node=renderHere -t 1-1000

Linux

  1. Open a Terminal.
  2. Navigate to the directory where you have Katana installed using the cd command, for example:

    cd /opt/foundry/katana

  3. Enter the following command to start a batch render:

    ./katana --batch --katana-file=/yourDirectory/yourScene.katana -t 1-1000

    Where:

  4. Press Enter to start the render.

You can add more arguments to the command. For example, use --render-node to specify the node you would like to render from if you haven't set your render flag in the Katana scene or if you would like to change it:

./katana --batch --katana-file=/yourDirectory/yourScene.katana --render-node=renderHere -t 1-1000

Here is a full list of command line options for Batch Mode:

Option

Usage

--katana-file

Specifies the Katana recipe to load.

Syntax:

--katana-file=<filename>

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty

--asset

Specifies the asset ID to resolve.

Syntax:

--asset=<asset ID>

Example:

./katana --asset=mock:///show/shot/name/version

-t or --t

Specifies the frame range to render.

Syntax:

-t <frame range>

OR

--t=<frame range>

Where <frame range> can take the form of a range (such as 1-5) or a comma separated list (such as 1,2,3,4,5). These can be combined, for instance: 1-3,5, which would render frames 1, 2, 3, and 5.

Example:

./katana --batch --katana-file=/tmp/test.katana

--t=1-5,8 --render-node=beauty
--var

Sets the value of an existing Graph State Variable. This command-line option can be specified multiple times to override the values of multiple Graph State Variables.

Syntax:

--var <GSV name>=<GSV value>

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1 --var Shot=Sh1 --var timeOfDay=night --var variant=B --render-node=beauty

--threads2d

Specifies the number of additional processors within the application. An additional processor is also used for Katana's main thread.

This means that Katana uses 3 processors when --threads2d=2.

Syntax:

--threads2d=<num threads>

Example:

./katana --batch --katana-file=/tmp/test.katana

--t=1-1000 --threads2d=2 --render-node=beauty

--threads3d

Specifies the number of simultaneous threads the renderer uses.

Syntax:

--threads3d=<num threads>

Example:

./katana --batch --katana-file=/tmp/test.katana

--t=1-1000 --threads3d=8 --render-node=beauty

--render-node

Specifies the Render node from which to render the recipe.

Syntax:

--render-node=<node name>

Example:

./katana --batch --katana-file=/tmp/test.katana

--t=1-1000 --render-node=beauty

--render-internal-dependencies

Allows any render nodes that don't produce asset outputs to be rendered within a single katana --batch process. Asset outputs are determined by asking the current asset plug-in if the output location is an assetId, using isAssetId(). The default file asset plug-in that ships with Katana classes everything as an asset. So at present it is not possible to render any dependencies within one katana --batch command without customizing the asset plug-in.

--crop-rect

Specifies which part of an image to crop. The same cropping area is used for all renders.

Syntax:

--crop-rect="(<left>,<bottom>,<width>,<height>)"

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty --crop-rect="(0,0,256,256)"

--setDisplayWindowToCropRect

Sets the display image to the same size as the crop rectangle set by --crop-rect.

--tile-render

Used to render one tile of an image divided horizontally and vertically into tiles. For instance, using
--tile-render=1,1,3,3 splits the image into 9 smaller images (or tiles) in a 3x3 square and then renders the middle tile as the index for tile renders starts at the bottom-left corner with 0,0. In the case of 3x3 tiles, the indices are:

0,2 1,2 2,2

0,1 1,1 2,1

0,0 1,0 2,0

The results are saved in the same location as specified by the RenderOutputDefine node but with a tile suffix. For instance: tile_1_1.beauty.001.exr

Syntax:

--tile-render=<left_tile_index>, <bottom_tile_index>, <total_tiles_width>, <total_tiles_height>

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty --tile-render=0,0,2,2

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty --tile-render=0,1,2,2

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty --tile-render=1,0,2,2

./katana --batch --katana-file=/tmp/test.katana --t=1-1000

--render-node=beauty --tile-render=1,1,2,2

--tile-stitch

Used to assemble tiles rendered with the --tile-render flag into a complete image.

When stitching, you must still pass the --tile-render argument, with the number of x and y tiles, so that the stitch knows how many tiles to expect, and their configuration.

Syntax:

--tile-render=<left_tile_index>, <bottom_tile_index>, <total_tiles_width>, <total_tiles_height> --tile-stitch

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --tile-render=0,0,2,2 --tile-stitch

--tile-cleanup

Used to clean up transient tile images. Can be used in conjunction with --tile-stitch to assemble a complete image, and remove transient tiles in a single operation.

When using --tile-cleanup you must still pass the --tile-render argument with the number of x and y tiles, so that cleanup knows how many tiles to remove.

Syntax:

--tile-render=0,0,<total_tiles_width>,<total_tiles_height> --tile-cleanup

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --tile-render=0,0,2,2 --tile-stitch --tile-cleanup

--prerender-publish

In Batch mode, it executes the Pre-Render Publish Asset action on the outputs but doesn't render images.

The value specifies the filename for dumping render pass information.

Note:  This can be used together with --versionup.

Syntax:

--prerender-publish=<pass info>

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --prerender-publish=/tmp/pass_info.xml

--make-lookfilebake-scripts

Used to write out a number of Python files that can be executed in Batch mode to write look files.

Syntax:

--make-lookfilebake-scripts=<script directory>

Example:

./katana --batch --katana-file=/tmp/bake.katana --t=1

--make-lookfilebake-scripts=/tmp/bake_scripts

./katana --script /tmp/bake_scripts/preprocess.py

./katana --script /tmp/bake_scripts/lf_bake_default.py

./katana --script /tmp/bake_scripts/postprocess.py

--postrender-publish

In Batch mode, it executes the Post-Render Publish Asset action on the outputs but doesn't render images.

The value specifies the filename for dumping render pass information.

Note:  This can be used together with --versionup.

Syntax:

--postrender-publish=<pass info>

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --postrender-publish=/tmp/pass_info.xml

--versionup

Used to specify that you want to version up assets when publishing to the asset management system.

Syntax:

--versionup

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --versionup
--reuse-render-process

Iterates over the sequence of frames to render, and exports Op Tree files for all frames, then starts the renderer (/renderboot process) only once on a sequence of exported Op Tree files.

Syntax:

--reuse-render-process

Example:

./katana --batch --katana-file=/tmp/test.katana --t=1-1000 --render-node=beauty --reuse-render-process

Note:  Setting threads3d or threads2d through Batch mode takes precedence over the interactiveRenderThreads3D, and interactiveRenderThreads2D settings in Katana's Edit > Preferences > application menu.

Article:  How to render an image in multiple tiles in Batch Mode.