-
Notifications
You must be signed in to change notification settings - Fork 2
Mappings File Format
The "mappings file" is the central point of control for RenderToolbox3. It connects the Collada scene file, the [conditions file](Conditions File Format), and the renderer [adjustments file](Adjustments Files) and allows these files to exchange values. It also allows the user to introduce new values, including values that are renderer-specific.
The mappings file contains multiple "mappings", which are lines of text, described on the [mappings](Mappings Syntax) page.
The mappings file should be a plain text file with mappings laid out in blocks. A mapping is a single line of text that modifies part of the scene. A block gathers up one or more related mappings.
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)
}
This file has 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.
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 may contain named variables enclosed in ()
parentheses. These variables should match 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
The conditions file specifies 3 values for dragonColor
, so 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)
.
See Conditions File Format for more about conditions files.
Blocks gather up related mappings. Blocks have names, which help RenderToolbox3 to interpret mappings correctly. Blocks can also have groups, which allow users to activate and deactivate specific blocks.
Block names determine how RenderToolbox3 interprets mappings and applies them to the scene. There are 6 valid block names:
-
Collada
mappings modify the Collada scene file. -
PBRT
andPBRT-path
mappings modify the the PBRT adjustments file. -
Mitsuba
andMitsuba-path
mappings modify the the Mitsuba adjustments file. -
Generic
mappings modify the adjustments file for either renderer. See Generic Scene Elements.
Blocks with any other names will go unused.
PBRT
, PBRT-path
, Mitsuba
, Mitsuba-path
, and Generic
blocks can introduce scene elements that Collada doesn't know about. This includes sampled spectra and area lights. Mappings in these blocks apply to the [adjustments file](Adjustments Files) for the current renderer.
See the [mappings](Mappings Syntax) page for more about what to put in each kind of block.
Blocks can belong to arbitrary groups. Groups allow some blocks to be activated, 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
plasticGroup
metalGroup
Blocks with no group name are always used. If the conditions file does not specify a groupName
variable, all blocks are used.