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.

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 Files

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, 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">
    <parameter name="maxdepth" type="integer">5</parameter>
    <parameter name="strategy" type="string">all</parameter>
</SurfaceIntegrator>

These adjustments specify a sample generator and an integreator, with some default properties.

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" 
  "integer maxdepth" [5] 
  "string strategy" "all"
Mitsuba

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="4"/>
</sampler>

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

These adjustments specify a sample generator and an integreator, with some default properties.

Mitsuba's 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="4"/>
    </sampler>
    ...
</sensor>

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

Adjustments in the Mappings File

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 sampled spectra to a scene.

Unique Identifiers

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 is replaced or modified depends on the adjustments syntax, which is different for PBRT and Mitsuba. In the examples below, the default behavior is to totally replace materials and to only 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 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]

This 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 are 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-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.0
}

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

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 replacement material and sampled spectra:

# material DragonMaterial-material
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 PBRT 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 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>

This 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 are 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
}

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

The adjusted scene contains a material named "DragonMaterial-material", of the Mitsuba type roughplastic. 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