-
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, and the renderer adjustments file. It allows these files to exchange values, and allows the user to introduce new values.
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 incorporates 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 incorporate related mappings. Blocks have names, which help RenderToolbox3 to interpret mappings correctly. Block 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 4 valid block names:
-
Collada
mappings modify the Collada scene file. -
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.
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
metalGroup
metalGroup
Blocks with no group name are always used. If the conditions file does not specify a groupName
variable, all blocks are used.
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.
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.
RenderToolbox3 uses 5 types of operator
:
-
=
assigns theright-hand value
to theleft-hand target
. -
+=
adds theright-hand value
to theleft-hand target
. -
-=
subtracts theright-hand value
from theleft-hand target
. -
*=
multiplies theright-hand value
with theleft-hand target
. -
/=
divides theleft-hand target
by theright-hand value
.
RenderToolbox3 uses 2 types of left-hand target
:
-
<Adjustments path>
A target enclosed in<>
angle braces should contain a Scene DOM path. Theright-hand value
will be applied to this part of the adjustments file for the current renderer. This type of target is only valid inPBRT
andMitsuba
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.
-
See below for more about generic mappings syntax.
RenderToolbox3 defiens a "generic mapping syntax" which is easier to use than Scene DOM paths. Generic syntax is allowed in the left-hand target
of PBRT
, Mitsuba
, and Generic
blocks.
Generic mappings can declare scene elements, or configure existing elements. A declaration must take the following form:
id:category:type
Where id
is a unique identifier of the new scene element, category
is the name of a broad class of scene elements, like "Material" or "emitter", and type
is a specific kind of scene element, like "plastic" or "directional".
Declarations should not use an operator
or right-hand value
.
A scene element configuration must take the following form:
id:property:type
Where id
is the unique identifier of an existing scene element, property
is the name of a property that the element exposes, such as "roughness" or "irradiance", and type
is a value-type that is allowed for the named property, such as "float" or "spectrum".
Configurations should be followed by an operator
and a right-hand value
.
Inside a PBRT
block, generic mappings may use category
, property
, and type
names that only PBRT knows about. For example, these generic mappings would declare and configure a new PBRT material:
myMaterial:Material:plastic
myMaterial:roughness.float = 0.2
The words Material
, plastic
, roughness
, and float
are all native to PBRT's scene file format.
Likewise, inside a Mitsuba
block, generic mappings may use category
, property
, and type
names that only Mitsuba knows about. For example, these generic mappings would declare and configure a new Mitsuba light source:
myLight:emitter:directional
myLight:irradiance.spectrum = mySpectrum.spd
The words emitter
, directional
, irradiance
, and spectrum
are all native to Mitsuba's scene file format.
Inside a Generic
block, generic mappings must use category
, property
, and type
names that are defined in RenderToolbox3'sn Generic Scene Elements. For example, these generic mappings would declare and configure a new material and light source, for use with either renderer:
% a generic anisotropic Ward material
myMaterial:material:ward
myMaterial:alphaU.float = 0.1
% a generic directional light
myLight:light:directional
myLight:intensity.spectrum = mySpectrum.spd
The words material
, ward
, alphaU
, and float
are all defined as part of the RenderToolbox3 generic Ward material.
Likewise, the words light
, directional
, intensity
, and spectrum
are all defined as part of the RenderToolbox3 generic directional light source.