Author: François Guillet

Version: 0.9 beta 2

Date: 11/26/2004

Render Utilities

The aim of this plugin is to provide facilities for rendering with Art of Illusion. Two main features are provided at the moment:

• The possibility to load/save renderer configurations;
• A batch mode which makes it possible to carry out several renders in a row, still images or animations, with a specific renderer configuration for each job. This batch mode also allows to set the rendering task priority.

After installing the plugin, relaunch AoI: there are now two new menu items in the Scene menu. These menu items are called "Load/Save Renderer Configuration..." and "Launch Batch...". Their use is discussed below.

1. Renderer Configuration Loading and Saving

The first thing to do is to setup the renderer configuration. If it's not already the case, selected the "Render Scene" command, enter full configuration, and select the OK button (otherwise the configuration is not taken into account). Abort the render if you wish. Select the "Load/Save Renderer Configuration..." command, and choose the target renderer. Finally, select the Save button and choose a file name. Any extension will do (or no extension will do as well). I suggest .rcf for render configuration, but it is not mandatory.

Loading a renderer configuration is done selecting the Load button. You don't need to select a target renderer because the target renderer information is saved in the configuration file. Every rendering parameter is loaded back. Cameras are the only item wich is not set when loading a configuration, since it is really specific to a scene.

A configuration can be specified at startup when launching AoI from the command line using the "renderConfig" system property. For example:

java -Xmx256m -DrendererConfig=C:\ArtOfIllusion\myConfig.rcf -jar ArtOfIllusion.jar

will always start AoI with the renderer parameters contained in myConfig.rcf as default parameters.

2. Batch Rendering

The first step is to write a batch sequence. This sequence is described in an XML file which format described below. The batch job is launched using the "Launch Batch..." command. Select the XML batch description file: a render window opens which displays information as renders are carried out.

Another way to launch a batch is to use the batchRender system property. Rendering will start right after AoI is launched, before any scene window is created. Only the rendering information and preview window is displayed. AoI will quit once the batch render is over.

For example:

java -Xmx256m-DbatchRender=C:\ArtOfIllusion\batch.xml -jar ArtOfIllusion.jar

will carry out the renders specified in batch.xml.

3. Batch File Format

The batch file is an XML file. These files are plain text files that can be edited with any text editors (e.g. Notepad for Windows users). Introductory material for XML can be found very easily. I will just describe the bare minimum needed to edit/build a batch file.

Any XML file must begin with the following preamble :
<? xml version="1.0" ?>

which states which XML version this file written for. Must be 1.0 as of now.

After that, information is stored within tags. A tag is started using the following notation:
<tagname>

Tag names are always written using lower caps. A opened tag must always be closed. There are two ways a tag can be closed. The first way is to close it after writing the tag contents, using /:
<tagname>
content...
</tagname>

or it can be closed right in the open tag notation:
<tagname />

In this case, the tag content is empty, but at least it exists, which can be enough for many purposes for which only tag attributes are relevant.

A batch file goes:

<? xml version="1.0" ?>
<rendercollection>
...
</rendercollection>

That is to say, the whole of the batch file description is contained within a rendercollection tag. Each render is then described within a render tag:

<?xml version="1.0"?>
<rendercollection>
<render>
...
</render>
</rendercollection>

There are then different tags which specify the image(s) filename, the renderer to be used, etc. The most important element to specify is the <scene>. Here is a scene description:

<?xml version="1.0"?>
<rendercollection>
<render>
<scene filename="C:\ArtOfIllusion\Untitled.aoi">
<camera value="0"/>
<time value="1.1"/>
</scene>
</render>
</rendercollection>

First there is the filename specification. The value is declared in the scene opening tag and in XML terms, it is an attribute of the scene tag. This is the only mandatory definition in a batch file : a scene and a scene filename. Everything else is "optional" (though the result might not be what you're looking for!). There are others tags declared within the scene tag. I call these tags "parameter tags", though they are just some other tags as far as XML is concerned. These parameter tags always take their values from the "value" attribute. So, for parameters, the tag name identifies the parameter, the attribute "value" allows to set a value for this parameter. For the scene tag, there are two possible (but not mandatory) parameters. These are:

• camera

  identifies the number of the camera to be used for rendering. Beware, this number starts at 0. 1 identifies the second camera in the scene, etc. If you need to know the index of a given camera, just record its order in the render drop down list for camera choice. Defaults to "0" if no camera tag is specified, or to the camera specified in the configuration file if one is specified.

• time

  specifies the time at which the scene must be rendered. Used for still images only. Defaults to "0" if no time is specified.

It is possible (and advised) to load a renderer configuration file previously saved using the plugin:
<configuration filename="C:\ArtOfIllusion\renderer.rcf" />
(full file text is now being omitted). It doesn't matter if configuration is specified before or after any other tag: it is loaded first, and then any other parameter are applied. configuration only takes one attribute : the configuration filename.

The <image> tag describes the rendered image(s):
<image filename="C:\ArtOfIllusion\untitled" >
<type value="jpg"/>
<height value="300"/>
<width value="400"/>
<quality value="90"/>
</image>

• filename

  specifies the name of the image(s) to save. Enter the root only: extension will be added at save time. Another file named filename.log will be created which contains a printout of all rendering settings.

• height

  the render height (defaults to 300 or configuration width if a configuration is specified).

• width

  the render width (defaults to 400 or configuration value).

• quality

  only applies to JPEG images. can be 1 to 100 (defaults to 90 or configuration value).

• type

  can be one of "jpg", "jpeg", "tif", "tiff", "png", "bmp", "hdr". This parameter specifies the image format. This format string is appened to the image filename before saving the image file. Quicktime format for animation is not available at the moment (animations are saved as a set of single images).

The <animation> tag describes the animation parameters:
<animation>
<start value="0" />
<end value="3.0" />
<fps value="15" />
<subimages value="1" />
</animation>

• start

  specifies the start time. (defaults to 0.0 or configuration value).

• end

  specifies the end time (defaults to 1.0 or configuration value).

• fps

  frames per second (defaults to 30 or configuration value).

• subimages

  frames/view for motion blur effect. Defaults to 1 or configuration value.

• on

  there is also an on attribute to switch off any animation when the loaded configuration has movie enabled. Usage is generally <animation on="false" /> since there is no need to specify any other parameter. There is no need to specify on="true" because specifying an animation tag automatically triggers animation render.

The <render> tag is important since it allows specification/modification of the renderer:
<renderer name="Raytracer">
<antialiasing value="2" />
<maxSurfaceError value="0.02" />
<maxRaysPerPixel value="64" />
<softShadows value="true" />
<gloss value="true" />
<reduceAccuracyForDistant value="false" />
</renderer>

The name attribute is really optional. It allows to specify the renderer to be used when no configuration file is loaded. Even then, the renderer defaults to Raytracer, so you really only need to use that attribute if you want to use the Raster renderer. All other parameters are the renderer parameters, so they change if you choose Raster or Raytracer. All values are dumped in each render log file (image_filename.log). Here is an example for Raytracer:

softShadows=true
minRayIntensity=0.01
maxRaysPerPixel=16
minRaysPerPixel=4
transparentBackground=false
globalIlluminationMode=0
causticsPhotons=10000
maxRayDepth=8
gloss=true
materialStepSize=1.0maxSurfaceError=0.02
highDynamicRange=true
caustics=false
globalIlluminationPhotons=10000
globalIlluminationPhotonsInEstimate=200
textureSmoothing=1.0
extraGIEnvSmoothing=100.0
russianRouletteSampling=false
depthOfField=false
antialiasing=2
extraGISmoothing=10.0
reduceAccuracyForDistant=true
causticsPhotonsInEstimate=100

Note the antialiasing value: 0 for no antialiasing, 1 for medium antialiasing, 2 for maximum antialising.

Caution: it is really best to save a renderer configuration and to change a limited number of parameters. It is harder to specify a coherent parameter set from scratch (though it is technically possible).

Finally, here is a full batch file sample. It renders the same scene twice. The first render is an animation that uses camera 0, the second is a still image that uses camera 1.

<?xml version="1.0"?> <rendercollection> <render> <configuration filename="/home/pims/tmp/ray.rcf" />
<scene filename="/home/pims/tmp/Untitled.aoi" />
<image filename="/home/pims/tmp/untitled" >
<type value="jpg"/>
<height value="300"/>
<width value="400"/>
</image>
<animation>
<start value="0" />
<end value="3.0" />
<fps value="15" />
</animation>
<renderer>
<antialiasing value="2" />
<maxRaysPerPixel value="64" />
<softShadows value="true" />
<gloss value="true" />
</renderer>
</render>
<render>
<configuration filename="/home/pims/tmp/ray.rcf" />
<scene filename="/home/pims/tmp/Untitled.aoi">
<camera value="1"/>
</scene>
<image filename="/home/pims/tmp/untitled2" >
<type value="jpg"/>
<height value="300"/>
<width value="400"/>
</image>
</render>
</rendercollection>

4. Batch Priority

The batch priority can be set using the <rendercollection> tag priority attribute. A value of "1" means priority is given to other system operations, a value of "10" means maximum priority is given to rendering. 5 is the default value and corresponds to a usual rendering priority. The given priority applies to every render in the render collection.

Here is for example a low priority job:
<rendercollection priority="1">
...
</rendercollection>

5. Source Package

The source package can be downloaded here. Uncompress the file in Art of Illusion source main directory and build the plugin using ant:

ant -f RenderUtils.xml