Skip to content

Adjustments Files

Jump to bottom Edit New page
benjamin-heasly edited this page Oct 25, 2012 · 41 revisions

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.

Merging Collada Scene and Adjustments

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.

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 here:

(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:

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

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

Here is an excerpt from the default Mitsuba adjustments file, located here:

(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>

Mappings File Adjustments

The [mappings file](Mappings File Format) can specify scene adjustments in addition to those specified in the default adjustments files. These can be new scene elements, or they can replace or modify scene elements that began life in the modeling application and the Collada Scene file. RenderToolbox3 combines default and additional adjustments into one grand adjustments file, and applies it to the scene.

The examples below use the mappings file to introduce sampled spectra to a scene. They declare a plastic material which replaces the default material used by each renderer. They also declare a light, which modifies an existing light that was specified in the modeling application.

Unique Identifiers

Scene elements are replaced and modified 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".

When matching ids appear in adjustments files of mappings files, the corresponding scene elements will be replaced or modified. Whether an element is replaced or modified depends on the element's type. The default behavior in RenderToolbox3 is to replace materials, but modify lights.

PBRT

Consider a scene that contains a dragon model and a distant sun light. The dragon model uses a material named "DragonMaterial" and the light is named "Sun. Without any adjustments, the scene could be converted to a PBRT scene file that contains the following declarations:

# 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 unadjusted scene contains a material named "DragonMaterial-material", of the default type uber. It also contains a light named "Sun-light". Both scene elements use RGB colors, which is undesirable for physically-based rendering.

The following mappings specify a replacement material of the PBRT type plastic. They also specify sampled spectra to use for the material reflectance and the light.

PBRT {
    DragonMaterial-material:Material:plastic
    DragonMaterial-material:roughness.float = 0.003
    DragonMaterial-material:Kd.spectrum = mccBabel-23.spd
    DragonMaterial-material:Ks.spectrum = 300:1.0
}

Generic {
    % use daylight
    Sun-light:light:directional
    Sun-light:intensity.spectrum = D65.spd
}

Note: these adjustments are specified using [Scene Target](Mappings Syntax) syntax.

Using these adjustments, the scene could be converted to a PBRT scene file that contains the following declarations:

MakeNamedMaterial "DragonMaterial-material" 
  "string type" "plastic" 
  "spectrum Kd" "mccBabel-23.spd" 
  "spectrum Ks" [300:1.0] 
  "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 adjusted scene contains a material named "DragonMaterial-material", of the specified type plastic. Both The material and the "Sun-light" use sampled spectra specified in .spd files.

Mitsuba

Again, consider a scene that contains a dragon model and a distant sun light. The dragon model uses a material named "DragonMaterial" and the light is named "Sun. Without any adjustments, the scene could be converted to a Mitsuba scene file that contains the following declarations:

<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 unadjusted scene contains a material named "DragonMaterial-material", of the default type diffuse. It also contains a light named "Sun-light". Both scene elements use RGB colors, which is undesirable for physically-based rendering.

The following mappings specify a replacement material of the Mitsuba type roughplastic. They also specify sampled spectra to use for the material reflectance and the light.

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
}

Note: again, these adjustments are specified using [Scene Target](Mappings Syntax) syntax.

Using these adjustments, the scene could be converted to a Mitsuba scene file that contains the following declarations:

<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>

The adjusted scene contains a material named "DragonMaterial-material", of the specified type plastic. Both The material and the "Sun-light" use sampled spectra specified in .spd files.

Add a custom footer
Add a custom sidebar
Clone this wiki locally