Adjustments Files

RenderToolbox3 uses adjustments files to supplement Collada scene files. Together, the adjustments file and the Collada scene file make a complete 3D scene, suitable for physically-based rendering.

Collada files are designed to be portable and compatible with many applications. Thus, they contain the kinds of scene elements that applications tend to agree on, like cameras, lights, polygon meshes, and RGB colors.

In contrast, adjustments files are designed to work with individual renderers. Thus, they can contain renderer-specific scene elements, like light transport sample generators and integrators, and sampled spectra.

Before rendering, RenderToolbox3 merges the Collada scene file and adjustments file to make one renderer-specific scene file. The merging involves:

• converting the Collada scene file to renderer-specific format
• supplementing the scene with new elements from the adjustments file
• replacing elements of the scene with elements from the adjustments file
• modifying elements of the scene with values from the adjustments file

Usually you won't need to write your own adjustments file. RenderTooblox3 has default adjustments files for PBRT and Mitsuba, and you can specify renderer-specific adjustments in the [Mappings File](Mappings File Format).

Read on to learn about how adjustments work, behind the scenes.

Default Adjustments

The RenderData/ sub-folder of RenderToolbox3 contains default adjustments files for PBRT and Mitsuba. These specify scene elements which are necessary for physically-based rendering, but which would be difficult or impossible to specify in a Collada scene file using a Modeling application like Blender.

Two such scene elements are light transport sample generators and integrators. Both PBRT and Mitsuba use these scene elements, although they define them with different syntax.

PBRT

Here is an excerpt from the default PBRT adjustments file, located at (path-to-RenderToolbox3)/RenderData/PBRTDefaultAdjustments.xml. Like Collada scene files, the adjustments file uses XML.

<Sampler id="sampler" type="lowdiscrepancy">
    <parameter name="pixelsamples" type="integer">8</parameter>
</Sampler>

<SurfaceIntegrator id="integrator" type="directlighting">
    <parameter name="maxdepth" type="integer">5</parameter>
    <parameter name="strategy" type="string">all</parameter>
</SurfaceIntegrator>

RenderToolbox3 incorporates the adjustments file into its ColladaToPBRT() scene file conversion function. The result would be a .pbrt scene file which contains the specified sample generator and integreator:

# Integrator
SurfaceIntegrator "directlighting" 
  "integer maxdepth" [5] 
  "string strategy" "all" 

# Sampler
Sampler "lowdiscrepancy" 
  "integer pixelsamples" [8] 

Mitsuba

Here is an excerpt from the default Mitsuba adjustments file, located at (path-to-RenderToolbox3)/RenderData/MitsubaDefaultAdjustments.xml. Like the Collada scene files and Mitsuba scene files, the adjustments file uses XML.

<sampler id="Camera-camera_sampler" type="ldsampler">
    <integer name="sampleCount" value="4"/>
</sampler>

<integrator id="integrator" type="direct">
    <integer name="shadingSamples" value="100"/>
</integrator>

Mitsuba incorporates the adjustments file into its built-in scene file converter. The result would be a Mitsuba .xml scene file which contains the specified sample generator and integreator:

<sensor id="Camera-camera" type="perspective">
    ...
    <sampler id="Camera-camera_sampler" type="ldsampler">
        <integer name="sampleCount" value="4"/>
    </sampler>
    ...
</sensor>

<integrator id="integrator" type="direct">
    <integer name="shadingSamples" value="100"/>
</integrator>

Adjustments Via Mappings

Surface reflectance replaces scene element, light spectrum modifies scene element. No way to specify these in Modeler, no good way to expect these in Collada file.

Replacement and modification are based on unique identifiers.

PBRT

scene target mappings excerpt with PBRT material and Generic light

Generic {
    % use daylight
    SunX-light:light:directional
    SunX-light:intensity.spectrum = D65.spd
}
PBRT plasticGroup {
    DragonMaterial-material:Material:plastic
    DragonMaterial-material:roughness.float = 0.003
    DragonMaterial-material:Kd.spectrum = mccBabel-23.spd
    DragonMaterial-material:Ks.spectrum = 300:1.0
}

unadjusted scene file excerpt

# material DragonMaterial-material
MakeNamedMaterial "DragonMaterial-material" 
  "string type" "uber" 
  "rgb Kd" [1.000000 0.593133 0.331203] 
  "float index" [1] 

# light source SunX-light
LightSource "distant" 
  "rgb L" [1 1 1] 
  "point from" [0 0 0] 
  "point to" [0 0 -1] 

adjusted scene file excerpt

MakeNamedMaterial "DragonMaterial-material" 
  "string type" "plastic" 
  "spectrum Kd" "/Users/ben/Documents/Projects/RenderToolbox3/RenderData/Macbeth-ColorChecker/mccBabel-23.spd" 
  "spectrum Ks" [300:1.0] 
  "float roughness" [0.003] 

# light source SunX-light
LightSource "distant" 
  "spectrum L" "/Users/ben/Documents/Projects/RenderToolbox3/RenderData/D65.spd" 
  "point from" [0 0 0] 
  "point to" [0 0 -1] 

Mitsuba

scene target mappings excerpt with Mitsuba material and Generic light

Generic {
    % use daylight
    SunX-light:light:directional
    SunX-light:intensity.spectrum = D65.spd
}
Mitsuba plasticGroup {
    DragonMaterial-material:bsdf:roughplastic
    DragonMaterial-material:alpha.float = 0.1
    DragonMaterial-material:diffuseReflectance.spectrum = mccBabel-23.spd
}

unadjusted scene file excerpt

	<bsdf id="DragonMaterial-material" type="diffuse">
		<rgb name="reflectance" value="1 0.593133 0.331203"/>
	</bsdf>

	<emitter id="SunX-light" type="directional">
		<rgb name="irradiance" value="1 1 1"/>
		<transform name="toWorld">
			<lookat origin="-10, 0, 10" target="-9, 0, 10"/>
		</transform>
	</emitter>

adjusted scene file excerpt

	<emitter id="SunX-light" type="directional">
		<rgb name="irradiance" value="1 1 1"/>
		<transform name="toWorld">
			<lookat origin="-10, 0, 10" target="-9, 0, 10"/>
		</transform>
		<spectrum filename="/Users/ben/Documents/Projects/RenderToolbox3/RenderData/D65.spd" name="irradiance"/>
	</emitter>

	<bsdf id="DragonMaterial-material" type="roughplastic">
		<float name="alpha" value="0.1"/>
		<spectrum filename="/Users/ben/Documents/Projects/RenderToolbox3/RenderData/Macbeth-ColorChecker/mccBabel-23.spd" name="diffuseReflectance"/>
	</bsdf>