MaterialSphere Example Scene

The MaterialSphere example recipe is minimal. The Collada parent scene contains a mesh approximation of a sphere, illuminated by a single point light. The recipe produces a family of 3 renderer-native scene files and renderings, each with a different different sphere material: matte, anisotropic Ward, and metal. The final montage is a row of 3 spheres.

This wiki page assumes you are already somewhat familiar with Blender. See Getting Started for some Blender basics.

The full recipe is located in the RenderToolbox3 repository at:

(path-to-RenderToolbox3)/ExampleScenes/MaterialSphere/

Here is what the final montage looks like, as rendered with PBRT and Mitsuba:

Above, PBRT rendered the MaterialSphere scene, 3 times, with the sphere material as a variable.

Above, Mitsuba rendered the MaterialSphere scene, 3 times, with the sphere material as a variable.

Files

The MaterialSphere recipe uses 4 files:

• MaterialSphere.dae is the Collada parent scene file, with camera, point light, sphere, and default material.
• MakeMaterialSphere.m is the Matlab executive script that generates renderings and the final montage.
• MaterialSphereMappings.txt introduces new materials and sampled spectra to the scene.
• MaterialSphereConditions.txt lists 3 image names and 3 mappings groups, for the 3 renderings.

Read more below, about how each file contributes to the final montage.

MaterialSphere.dae

MaterialSphere.dae is the Collada parent scene file that is the basis for the MaterialSphere renderings and montage. You can view the scene with a modeling application like Blender.

In Blender, try creating a new empty scene. You might need to delete a few objects that Blender adds by default. Then try clicking File -> import -> COLLADA (.dae), and choosing MaterialSphere.dae. You should be able to explore the scene and each scene object.

MakeMaterialSphere.m

MakeMaterialSphere.m is the executive script that binds together the Collada parent scene with a conditions file and mappings file. It invokes RenderToolbox3 utilities to produce a family of renderer-native scene files and renderings, and a final sRGB montage. It also produces several sensor images, which are alternative representations of the multi-spectral renderings, based on arbitrary color matching functions.

Here is the text of the executive script, with comments:

%% Choose example files, make sure they're on the Matlab path.
parentSceneFile = 'MaterialSphere.dae';
conditionsFile = 'MaterialSphereConditions.txt';
mappingsFile = 'MaterialSphereMappings.txt';

%% Choose batch renderer options.
% which materials to use, [] means all
hints.whichConditions = [];

% pixel size of each rendering
hints.imageWidth = 200;
hints.imageHeight = 160;

% put outputs in a subfolder named like this script
hints.recipeName = mfilename();
ChangeToWorkingFolder(hints);

%% Choose some color matching functions to make sensor images.
% choose several Pyschtoolbox matching functions
%   these are the names of Pyschtoolbox colorimetric .mat files
matchFuncs = {'T_xyz1931.mat', 'T_cones_smj', 'T_rods'};

% invent a new matching function that extracts a narrow wavelength band
bandName = 'narrow-band-matching';
nBands = 81;
bandSampling = [380 5 nBands];
bandFunction = zeros(1, nBands);
bandFunction(round(nBands/2)) = 1;

% choose the invented matching function, along with descriptive metadata
matchFuncs{4} = bandFunction;
matchSampling{4} = bandSampling;
matchNames{4} = bandName;

%% Render with Mitsuba and PBRT.

% how to convert multi-spectral images to sRGB
toneMapFactor = 100;
isScaleGamma = true;

% make a montage and sensor images with each renderer
for renderer = {'Mitsuba', 'PBRT'}
    
    % choose one renderer
    hints.renderer = renderer{1};
    
    % make 3 multi-spectral renderings, saved in .mat files
    nativeSceneFiles = MakeSceneFiles(parentSceneFile, conditionsFile, mappingsFile, hints);
    radianceDataFiles = BatchRender(nativeSceneFiles, hints);
    
    % condense multi-spectral renderings into one sRGB montage
    montageName = sprintf('MaterialSphere (%s)', hints.renderer);
    montageFile = [montageName '.png'];
    [SRGBMontage, XYZMontage] = ...
        MakeMontage(radianceDataFiles, montageFile, toneMapFactor, isScaleGamma, hints);
    
    % display the sRGB montage
    ShowXYZAndSRGB([], SRGBMontage, montageName);
    
    % make some sensor images, in addition to the sRGB montage
    sensorImages = MakeSensorImages( ...
        radianceDataFiles, matchFuncs, matchSampling, matchNames, hints);
end

MaterialSphereMappings.txt

MaterialSphereMappings.txt is the mappings file, which modifies the scene with things that Collada doesn't know about.

It swaps the handedness of the scene camera, so that Collada, PBRT, and Mitsuba cameras all agree. It sets parameters of the point light, to make sure that it behaves with realistic inverse-square attenuation. It also specifies sphere material properties in three different blocks of code.

The sphere material properties are contained in blocks of code that use group names: matteGroup, wardGroup, and metalGroup. These group names are used in the conditions file, below. The conditions file specifies a keyword variable, groupName which causes blocks of code to be switched on and off according to the current group name.

Switching on and off whole blocks of code allows a lot of flexibility. In this example, the different materials use unrelated parameters, and different numbers of parameters.

Note: sphere material spectra are specified in multi-spectral data spd-files. These can be found in the RenderToolbox3 RenderData/ subfolder.

Here is the mappings file text, with comments:

Collada {
    % swap camera handedness from Blender's Collada output
    Camera:scale|sid=scale = -1 1 1
}

% specify generic scene elements under the "matteGroup" condition
Generic matteGroup {
    % generic matte sphere material
    Material-material:material:matte

    % make it red
    Material-material:diffuseReflectance.spectrum = mccBabel-11.spd
}

% specify generic scene elements under the "wardGroup" condition
Generic wardGroup {
    % generic anisotropic ward sphere material
    Material-material:material:anisoward
    Material-material:alphaU.float = 0.2
    Material-material:alphaV.float = 0.2

    % make it green
    Material-material:diffuseReflectance.spectrum = mccBabel-7.spd
}

% specify generic scene elements under the "metalGroup" condition
Generic metalGroup {
    % generic metal sphere material
    Material-material:material:metal

    % make the surface somewhat rough
    Material-material:roughness.float = 0.4

    % make it out of gold!
    Material-material:eta.spectrum = Au.eta.spd
    Material-material:k.spectrum = Au.k.spd
}

Note: the names Camera, Point-light, and Material-material are the unique identifiers for elements of the scene. These identifiers are used in the Collada scene file and the mappings file, and are the points of contact between the two files.

See Mappings File Format, and Mappings Syntax for more about mappings and introducing new elements to the scene.

See Adjustments Files and Scene DOM Paths for more about scene element unique identifiers.

MaterialSphereConditions.txt

MaterialSphereConditions.txt is the conditions file, which lists variable names and values for each condition.

It lists 2 keword variables, which affect how the scene is rendered:

• imageName specifies the name of the .mat file where the batch renderer should save multi-spectral renderings. These names don't show up in the final montage, but may have other uses.
• groupName specifies which blocks of code in the mappings should be used for each condition.

It lists 3 rows of values. The scene will be rendered 3 times, each time using variable values from one row. The 2nd time the scene is rendered, the batch renderer would use values from the 2nd row of values:

• It would save multi-spectral renderings in a file named materialSphereWard.mat.
• The block of code in the mappings file with the name wardGroup would be active, and blocks with other names would be inactive.

Here is the full text:

imageName		groupName
materialSphereMatte	matteGroup
materialSphereWard	wardGroup
materialSphereMetal	metalGroup

See Conditions File Format for more about specifying variables and values.

See Mappings File Format for more about mappings group names.