Mappings Syntax

A mapping is a line of text that associates a value with part of a 3D scene. Mappings can modify values in a Collada scene file. They can also specify scene elements that Collada doesn't know about, but renderers do know about. Combined with a [conditions file](Conditions File Format), mappings can create scene variants to be rendered.

Mappings must be specified in a [mappings file](Mappings File Format).

Basic Form

A mapping is a line of text with the general form:

left-hand target operator right-hand value

The right-hand value specifies a value, to apply to part of the 3D scene. The operator controls how the value will be applied to the scene. The left-hand target specifies the part of the 3D scene to modify.

There are a few variations on this form, using different types of target, operator, or value.

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 left-hand target by the right-hand value.

Left-Hand targets

RenderToolbox3 uses 2 types of left-hand target. The interpretation of the target depends on the [mappings file](Mappings File Format) block that contains the mapping.

• <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. right-hand value applies to the PBRT adjustments file. PBRT-native type names and parameter names are allowed.
  • Mitsuba target should use generic mappings. right-hand value applies to the Mitsuba adjustments file. Mitsuba-native type names and parameter names are allowed.
  • Generic target should use generic mappings. 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.

Generic Mappings

RenderToolbox3 defines a "generic mapping" syntax which is easier to use than Scene DOM paths. Generic mapping syntax is allowed in the left-hand target of mappings contained in PBRT, Mitsuba, and Generic blocks of the [mappings file](Mappings File Format).

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.

PBRT

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.

Mitsuba

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.

Generic

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.