Mappings File Format

RenderToolbox3 uses a "mappings file" to associate variables in a conditions file with parts of the scene. The mappings file should be a plain text file with mappings laid out in blocks.

Layout

A simple mappings file might look like this:

Collada {
    % swap camera handedness from Blender's Collada output
    Camera:scale = -1 1 1
}

Generic {
    % choose the dragon's material and color
    DragonMaterial-material:material:matte
    DragonMaterial-material:diffuseReflectance.spectrum = (dragonColor)
}

There are two blocks, each begins with a name and is enclosed in {} braces. The first block is named Collada and contains one mapping. The second block is named Generic and contains two mappings. Block names determine how RenderToolbox3 interprets each mapping.

Block Names

Block names determine how RenderToolbox3 interprets mappings and applies them to the scene. There are 4 valid block names:

• Collada mappings modify the Collada scene file. This is the first step in batch processing.
• PBRT mappings modify the the PBRT scene adjustments file.
• Mitsuba mappings modify the the Mitsuba scene adjustments file.
• Generic mappings modify the scene adjustments file for either renderer. A few Generic Scene Elements are defined in RenderToolbox3.

Blocks with any other names will go unused.

PBRT, Mitsuba, and Generic blocks can introduce scene elements that Collada doesn't know about, but renderers do know about. This includes sampled spectra. Mappings in these blocks apply to on the Adjustments File for the current renderer.

Block Groups

Blocks can belong to named groups. Group names allow related blocks to be selected, and other blocks to be ignored. The group name must follow the block name:

PBRT plasticGroup {
    % specify PBRT-style plastic material stuff
}
Mitsuba plasticGroup {
    % specify Mitsuba-style plastic material stuff
}
PBRT metalGroup {
    % specify PBRT-style metal material stuff
}
Mitsuba metalGroup {
    % specify Mitsuba-style material stuff
}

Here there are 2 pairs of blocks: one pair uses the group name plasticGroup and the other uses the name metalGroup.

The 4 blocks could be switched on and off in pairs, with a conditions file that specifies a groupName variable:

groupName    foo   bar
metalGroup   0     1
metalGroup   1     1

See Conditions File Format for more about conditions files.

Blocks with no group name are always used. If the conditions file does not specify a groupName variable, all blocks are used.

Comments

Any line that begins with a % character is ignored as a comment. For example:

Collada {
    % on second thought, don't swap camera handedness
    %Camera:scale = -1 1 1
}

Mappings

A mapping applies a value to part of the scene. Mappings generally have the form:

left-hand target operator right-hand value

There are a few variations on this form.

Right-Hand Values

RenderToolbox3 uses 3 types of right-hand value:

• [Collada path] A value enclosed in [] square braces should contain a Scene DOM path. This value will be looked up in the Collada scene file.
• <Adjustments path> A value enclosed in <> angle braces should contain a Scene DOM path. This value will be looked up in the adjustments file for the current renderer.
• Unenclosed values will be treated as regular, constant strings.

See Scene DOM Paths for more about Scene DOM paths.

Operators

RenderToolbox3 uses 5 types of operator:

• = assigns the right-hand value to the left-hand target.
• += adds the right-hand value to the left-hand target.
• -= subtracts the right-hand value from the left-hand target.
• *= multiplies the right-hand value with the left-hand target.
• /= divides the right-hand value into the left-hand target.

Left-Hand targets

RenderToolbox3 uses 2 types of left-hand target:

• <Adjustments path> A target enclosed in <> angle braces should contain a Scene DOM path. The right-hand value will be applied to this part of the adjustments file for the current renderer. This type of target is only valid in PBRT and Mitsuba blocks.
• Unenclosed targets are interpreted differently, depending on the block name:
  • Collada target should be a Scene DOM path. right-hand value applies to the Collada scene file.
  • PBRT target should use generic mappings syntax. right-hand value applies to the PBRT adjustments file. PBRT-native type names and parameter names are allowed.
  • Mitsuba target should use generic mappings syntax. right-hand value applies to the Mitsuba adjustments file. Mitsuba-native type names and parameter names are allowed.
  • Generic target should use generic mappings syntax. right-hand value will be applied to the adjustments file for the current renderer. Only generic scene elements are allowed.

Generic mappings syntax

TODO Notes to self:

• Convenience upon Scene DOM paths.
• declare with id:category:type
• configure with id:property.type
• renderer-native vs generic scene elements.

Conditions File (variables)

The left-hand target and right-hand value may contain named variables enclosed in () parentheses. These variables should match the variables in the conditions file. For each condition, parenthetical text will be replaced with matching variable values.

For example, consider a mapping with parenthetical text for the variable dragonColor:

DragonMaterial-material:diffuseReflectance.spectrum = (dragonColor)

Also consider a conditions file that specifies the same dragonColor variable:

dragonColor
red.spd
gold.spd
orange.spd

Since the conditions file specifies 3 values for dragonColor, the scene would be rendered 3 times. Each time, a different value would be substituted into the mapping, in place of the parenthetical text (dragonColor).