The RenderToolbox "mappings file" connects the 3D scene with constant values and conditions file variables. It allows the user to introduce new kinds of values into the scene, including sampled spectra and values that are renderer-specific.

The mappings file is JSON. Each "mapping" is a JSON object, and the whole file contains an array of these objects.

You can apply mappings to the input representation of the scene using Mexximp Mappings. You can apply mappings to renderer-native scenes as they are generated using PBRT Mappings, Mitsuba Mappings, and Generic Mappings. You can put all of these in the same mappings file.

Example: ColorChecker Dragon

Let's start with an example. Here is the complete mappings file used in the Dragon example scene:

[
	{
		"name": "LightX",
		"broadType": "meshes",
		"operation": "blessAsAreaLight",
		"properties": {
			"name": "intensity",
			"valueType": "spectrum",
			"value": "D65.spd"
		}
	},
	{
		"name": "LightY",
		"broadType": "meshes",
		"operation": "blessAsAreaLight",
		"properties": {
			"name": "intensity",
			"valueType": "spectrum",
			"value": "D65.spd"
		}
	},
	{
		"name": "ReflectorMaterial",
		"broadType": "materials",
		"specificType": "matte",
		"operation": "update",
		"properties": {
			"name": "diffuseReflectance",
			"valueType": "spectrum",
			"value": "300:1.0 800:1.0"
		}
	},
	{
		"name": "WallMaterial",
		"broadType": "materials",
		"specificType": "matte",
		"operation": "update",
		"properties": {
			"name": "diffuseReflectance",
			"valueType": "spectrum",
			"value": "300:0.75 800:0.75"
		}
	},
	{
		"name": "FloorMaterial",
		"broadType": "materials",
		"specificType": "matte",
		"operation": "update",
		"properties": {
			"name": "diffuseReflectance",
			"valueType": "spectrum",
			"value": "300:0.5 800:0.5"
		}
	},
	{
		"name": "DragonMaterial",
		"broadType": "materials",
		"specificType": "matte",
		"operation": "update",
		"properties": {
			"name": "diffuseReflectance",
			"valueType": "spectrum",
			"value": "(dragonColor)"
		}
	}
]

That's a wall of text. But there are only six JSON objects, and they all have the same structure. Here's what they do.

The First Two

The first two identify meshes in the 3D scene named LightX and LightY. These are planar meshes intended to act as area lights. The mappings instruct RenderToolbox to apply the operation blessAsAreaLight to each mesh. In addition, they instruct RenderToolbox to set the illuminant intensity for each light to a spectrum file named D65.spd.

In short: they turn two meshes into area lights with a daylight spectrum.

The Last Four

The last four identify materials in the scene named ReflectorMaterial, WallMaterial, FloorMaterial, and DragonMaterial. Each instructs RenderToolbox to update the material to have type matte -- ie Lambertian reflectance. Each also assigns a spectrum value to the diffuseReflectance property of the material.

Three of the diffuseReflectance spectra are constants, specified as explicit wavelength:reflectance pairs.

The last diffuseReflectance property is bound to a variable as (dragonColor). This refers to a dragonColor column in the Conditions File.

In short: they assign reflectance spectra to four materials.

Mapping Fields

Mapping objects are expected to have specific fields. Each helps RenderToolbox to identify an element of the 3D scene, or instructs RenderToolbox what to do with that element.

Here are the expected mapping fields and their interpretations.

Field	Default	Interpretation
name	''	name used to identify the element, for example the name you would type into Blender
broadType	''	general type used to identify the element: cameras, lights, materials, etc.
index	[]	index used to identify the element, among elements of the same broadType
specificType	''	concrete type of element to set or update: matte, anisoward, plastic, etc.
destination	'Generic'	where to apply this mapping: mexximp, Mitsuba, PBRT, or Generic
operation	'create'	what to do with this element: delete, create, update, blessAsAreaLight, or blessAsBumpMap
group	''	used to select subsets of mappings, see groupName conditions file keyword
properties	[]	array of element properties, see Property Fields

Property Fields

Each mapping object may have an array of properties that refer to specific properties of a scene element.

Here are the expected property fields and their interpretations.

Field	Default	Interpretation
name	''	name used to identify the property: diffuseReflectance, intensity, etc.
operation	'='	assign value to the property, or evaluate expression
value	[]	numeric or string value to assign to the property
valueType	''	the type of the value: integer, float, spectrum, texture, etc.

Operation as Matlab Expression

Usually it makes sense just to assign a value to a property. But sometimes it makes sense to do a little calculation to choose a property value. Indeed, the calculation might need use the old value of a property when deciding a new value.

To support this, a mapping property operation may be a Matlab expression to pass to eval(), instead of the default assignment operation '='. The value of the evaluated expression will be assigned to the property.

Before evaluating the expression, RenderToolbox will bind two variables that the expression may wish to use: oldValue will be taken from the property before any change was made. value will be taken from the mapping property object's value field.

Here's an example from the RadianceTest example scene:

  {
    "name": "Point",
    "broadType": "nodes",
    "operation": "update",
    "destination": "mexximp", 
      "properties": {
      "name": "transformation",
      "operation": "mexximpTranslate([0 0 (lightDistance)]) * oldValue"
    }
  }

This example adjusts the spatial transformation applied to a point light. The oldValue is whatever spatial transformation was applied by the 3D modeler and saved in the 3D scene file. This transformation is adjusted or "nudged" by an additional translation.

JSON or Struct Array

Mappings files are stored as JSON because it's a convenient, machine-and-human-readable way to store data.

Under the hood, RenderToolbox reads the JSON into a Matlab struct array using jsonlab. jsonlab is a great utility that you might want to use with or without RenderToolbox.

So, you can work with mappings as Matlab struct arrays instead of reading and writing JSON text. Here's an example:

% read in the JSON
mappings = rtbLoadJsonMappings(which('DragonMappings.json'));

% change something
mappings(4).properties(1).value = '300:1 800:1';

% write it out
rtbWriteJson(mappings, 'fileName', 'NewMappings.json');