Command Line Rendering


The scene files generated by Massive can be rendered by invoking AIR from a terminal window or command shell.  An individual frame can be rendered by providing the name of the main rib file as an argument to air:

    air rib/frame0001.rib

AIR accepts multiple rib files on a single command line.  Multiple files are processed in order from left to right.  Additional small files with RIB commands can be used to customize a rendering without modifying the main scene file.  For example, one could use the small file quant16.rib to render an output image with 16-bit values:

    air quant16.rib scene.rib

Command Line Switches

AIR provides many command line options for customizing the renderer’s behavior without modifying the main rib file.  A list of command line options can be printed with:

    air -

A list of options with brief descriptions can be found in the AIR User Manual under Reference -> Command Line Switches.  This tutorial introduces a few of the more commonly used options.

Multithreaded Rendering

 The number of threads can be set with a -p or -threads option:

    air -p 2 rib/frame0001.rib

The Linux distribution of AIR includes a separate airmt binary with multithreading support, which should be used with multiple threads:

    airmt -p 2 rib/frame0001.rib

Image Size and Output Destination

Use -res to override the image width and height set in the rib file:

    air -res 320 240 scene.rib

The output image file generated by the rendering can be set with -file:

    air -file occlusion.tif scene.rib

The image type is determined by the file name extension.  To force output to the AIR Show framebuffer instead of to a file, use the -d switch:

    air -d scene.rib

Pixel Samples and Shading Rate

AIR has two main controls for image quality.  The pixel samples option determines the number of times the scene geometry is sampled per pixel.  E.g., a pixel samples setting of 4 will use a 4x4 grid of samples at every pixel.  Use -samples to override the pixel samples setting on the command line:

    air -samples 4 scene.rib

Increase the number of pixel samples to improve the quality of geometry sampling.

The shading rate determines the shading quality of an image.  Shading rate is defined as the area in pixels covered by a single shading sample.  A lower shading rate produces a higher quality image.  For example, a shading rate of 0.25 will produce 4 shading samples per pixel.  The -sm command line option is a multiplier for the shading rate setting in the rib file:

    air -sm 0.25 scene.rib

Bucket Size and Bucket Order

By default AIR renders an image in 32x32 pixel tiles or buckets, one row at a time top to bottom.  Using a smaller bucket size may reduce peak memory use and provide better load balancing with multiple threads.  Set the bucket size with -bs:

    air -bs 16 scene.rib

Rendering by column instead of by row can also help minimize memory use for crowd scenes.  Use -ltor to render in columns, left to right:

    air -ltor scene.rib

Surface Shader Override

The -surf switch overrides all Surface shaders declared in the rib file with the alternate shader provided.  Alternative surface shaders can be used for rendering multiple output passes from a single scene file.  E.g.,

    air -surf occlusionpass -file occlusion.tif scene.rib

A related option, -nosurf, suppresses all Surface shaders in the scene file, rendering the scene with the defaultsurface shader which provides simple shading based on the surface normal.  The nosurf option is useful for quick tests and for debugging.  For example, if your scene is rendering black, rendering with -nosurf will indicate whether the agents are missing or just lacking illumination.


Rendering statistics can be enabled with -stats:

    air -stats scene.rib

Rendering Multiple Frames

AIR 8 allows a frame sequence to be rendered with simple frame number substitution. For example:

    air -frames 8 10 scene#f.rib

would render scene8.rib, scene9.rib, and scene10.rib. The frame number pattern can also be zero-padded:

    air -frames 8 10 scene#3f.rib

would render scene008.rib, scene009.rib, and scene010.rib.


© 2001-13 SiTex Graphics, Inc.  All rights reserved.