-
Notifications
You must be signed in to change notification settings - Fork 2
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 additional renderer-specific adjustments in the [Mappings File](Mappings File Format).
Read on to learn about how adjustments work, behind the scenes.
Adjustments can replace or modify scene elements, based on unique identifiers. Unique identifiers start life in modeling applications like Blender, where users can assign an arbitrary names to scene objects. These are saved in the Collada scene file as XML id attributes that contain object names, plus descriptive suffixes like "-material" or "-light".
Adjustments also use id attributes. These allow adjustments and scene elements to be matched up, and the scene elements to be replaced or modified. Whether a scene element, or part of a scene element, is present in both the adjustments file and the scene file, the values in the adjustments file take precedence.
The RenderData/ sub-folder of RenderToolbox3 contains default adjustments files for PBRT and Mitsuba. These supplement the Collada scene with elements that are necessary for physically-based rendering, but are unknown in modeling applications like Blender, or Collada scene files.
Two supplementary scene elements are light transport sample generators and integrators. Both PBRT and Mitsuba use these scene elements, although they define them with different syntax.
Here is an excerpt from the default PBRT adjustments file, PBRTDefaultAdjustments.xml. The adjustments file is XML-based, and uses a custom schema expected by the RenderToolbox3 ColladaToPBRT() converter.
<Sampler id="sampler" type="lowdiscrepancy">
<parameter name="pixelsamples" type="integer">8</parameter>
</Sampler>
<SurfaceIntegrator id="integrator" type="directlighting" />
These adjustments specify a default sample generator and integrator.
The ColladaToPBRT() converter would include these scene elements along with scene elements from a Collada scene file. The result would be a PBRT scene file that contained the specified sample generator and integreator, as in this excerpt:
# Sampler
Sampler "lowdiscrepancy"
"integer pixelsamples" [8]
# Integrator
SurfaceIntegrator "directlighting"
Here is an excerpt from the default Mitsuba adjustments file, MitsubaDefaultAdjustments.xml. The adjustments file is XML-based, and uses a Mistuba schema that is very similar to Mitsuba scene files.
<sampler id="Camera-camera_sampler" type="ldsampler">
<integer name="sampleCount" value="8"/>
</sampler>
<integrator id="integrator" type="direct">
<integer name="shadingSamples" value="32"/>
</integrator>
These adjustments specify a sample generator and an integrator, with some default properties.
Mitsuba's scene converter would include these scene elements along with scene elements from a Collada scene file. The result would be a Mitsuba scene file that contained the specified sample generator and integrator, as in this excerpt:
<sensor id="Camera-camera" type="perspective">
...
<sampler id="Camera-camera_sampler" type="ldsampler">
<integer name="sampleCount" value="8"/>
</sampler>
...
</sensor>
<integrator id="integrator" type="direct">
<integer name="shadingSamples" value="32"/>
</integrator>
The [mappings file](Mappings File Format) can specify scene adjustments to be added to the adjustments file. The examples below use the mappings file to introduce a new material and sampled spectra to a scene.
Consider a Collada scene file that contains a dragon model and a distant sun light. The scene could be converted to PBRT or Mitsuba without any adjustments, but the dragon would use a boring default material type, and the material and light would use simple RGB colors.
The examples below show how adjustments can replace the default material with a renderer-specific material, and modify an existing light to use a sampled spectrum.
Without any adjustments, the dragon scene would be converted to a PBRT scene file with default material and RGB colors:
# material DragonMaterial-material
MakeNamedMaterial "DragonMaterial-material"
"string type" "uber"
"rgb Kd" [1.000000 0.593133 0.331203]
"float index" [1]
# light source Sun-light
LightSource "distant"
"rgb L" [1 1 1]
"point from" [0 0 0]
"point to" [0 0 -1]
The material has the id "DragonMaterial-material", and it has the default type uber. The light has the id "Sun-light". Both scene elements use rgb colors.
The following mappings adjust the scene with a replacement material of the PBRT type plastic. They also adjust the scene to use sampled spectra for the plastic reflectance and the light emission:
% PBRT-style plastic
PBRT {
DragonMaterial-material:Material:plastic
DragonMaterial-material:roughness.float = 0.003
DragonMaterial-material:Kd.spectrum = mccBabel-23.spd
DragonMaterial-material:Ks.spectrum = 300:1 800:1
}
% daylight spectrum
Generic {
Sun-light:light:directional
Sun-light:intensity.spectrum = D65.spd
}
These adjustments use [Scene Target](Mappings Syntax) syntax.
Using these adjustments, the PBRT scene file would contain the replacement plastic material and sampled spectra:
# material DragonMaterial-material
MakeNamedMaterial "DragonMaterial-material"
"string type" "plastic"
"spectrum Kd" "mccBabel-23.spd"
"spectrum Ks" [300:1 800:1]
"float roughness" [0.003]
# light source Sun-light
LightSource "distant"
"spectrum L" "D65.spd"
"point from" [0 0 0]
"point to" [0 0 -1]
The plastic material and the light use sampled spectra specified in .spd files.
Without any adjustments, the dragon scene would be converted to a Mitsuba scene file with default material and RGB colors:
<bsdf id="DragonMaterial-material" type="diffuse">
<rgb name="reflectance" value="1 0.593133 0.331203"/>
</bsdf>
<emitter id="Sun-light" type="directional">
<rgb name="irradiance" value="1 1 1"/>
</emitter>
The material has the id "DragonMaterial-material", and it has the default type diffuse. The light has the id "Sun-light". Both scene elements use rgb colors.
The following mappings adjust the scene with a replacement material of the Mitsuba type plastic. They also adjust the scene to use sampled spectra for the plastic reflectance and the light emission:
Mitsuba {
DragonMaterial-material:bsdf:roughplastic
DragonMaterial-material:alpha.float = 0.1
DragonMaterial-material:diffuseReflectance.spectrum = mccBabel-23.spd
}
Generic {
% use daylight
Sun-light:light:directional
Sun-light:intensity.spectrum = D65.spd
}
Again, these adjustments use [Scene Target](Mappings Syntax) syntax.
Using these adjustments, the Mitsuba scene file would contain the replacement plastic material and sampled spectra:
<bsdf id="DragonMaterial-material" type="roughplastic">
<float name="alpha" value="0.1"/>
<spectrum filename="mccBabel-23.spd" name="diffuseReflectance"/>
</bsdf>
<emitter id="Sun-light" type="directional">
<rgb name="irradiance" value="1 1 1"/>
<spectrum filename="D65.spd" name="irradiance"/>
</emitter>
Again, the plastic material and the light use sampled spectra specified in .spd files.