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

Integrator and sampler are added to the scene. No way to specify these in Modeler, no good way to expect these in Collada file.

Actual default adjustments files in RenderData/.

Adjustments are renderer-specific.

PBRT

default adjustments excerpt

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

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

resulting scene file excerpt

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

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

Mitsuba

default adjustments excerpt

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

resulting scene file excerpt

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

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>