Batch Renderer

Render a family of related scenes based on a Collada parent scene. More...

Functions
outFiles	BatchRender (scenes, hints)
	Render multiple scenes at once.
radiometricScaleFactor	ComputeRadiometricScaleFactor (renderer)
	Calculate scale factors to bring renderer outputs into radiance units.
hints	GetDefaultHints (hints)
	Get default hints that affect the RenderToolbox3 utilities.
SRGBMontage XYZMontage	MakeMontage (inFiles, outFile, toneMapFactor, isScale, hints)
	Condense several multi-spectral renderings into one sRGB montage.
scenes	MakeSceneFiles (colladaFile, conditionsFile, mappingsFile, hints)
	Make a family of renderer-native scenes based on a Collada parent scene.
conditionsFile	WriteConditionsFile (conditionsFile, names, values)
	Write conditions data to a text file.
mappingsFile	WriteDefaultMappingsFile (colladaFile, mappingsFile, includeFile, reflectances, lightSpectra, excludePattern)
	Write a default mappings file for the given Collada parent scene file.

Detailed Description

Render a family of related scenes based on a Collada parent scene.

These functions make up the RenderToolox3 batch renderer, which takes a Collada parent scene file, applies manipulations specified in a conditions file and a mappings file, and produces a family of renderer-native scene files and renderings.

Function Documentation

outFiles BatchRender	(	scenes	,
		hints
	)

Render multiple scenes at once.

Parameters

scenes	cell array of renderer-native scene descriptions or files
hints	struct of RenderToolbox3 options, see GetDefaultHints()

Renders multiple renderer-native scene files in one batch. scenes should be a cell array of renderer-native scene descriptions or scene files, such as those produced by MakeSceneFiles(). All renderer-native files should be intended for the same renderer, which should be specified in hints.renderer.

hints may be a struct with options that affect the rendering process, as returned from GetDefaultHints(). If hints is omitted, default options are used. For example:

• hints.renderer specifies which renderer to use
• hints.isParallel specifies whether to render in a "parfor" loop
• hints.outputDataFolder specefies where to store multi-spectral radiance data files.
• hints.outputImageFolder specifies where to store RGB image files.
• hints.isDryRun specefies whether or not to skip actual rendering.

Renders each renderer-native scene n scenes, and writes a new mat-file for each one. Each mat-file will contain several variables including:

• multispectralImage - matrix of multi-spectral radiance data with size [height width n]
• S - spectral band description for the rendering with elements [start delta n]

height and width are pixel image dimensions and n is the number of spectral bands in the image. See the RenderToolbox3 wikiw for more about Spectrum Bands.

The each mat-file will also contain variables with metadata about how the scene was made and rendererd:

• scene - the renderer-native scene description (e.g. file name, Collada author info)
• hints - the given hints struct, or default hints struct
• versionInfo - struct of version information about RenderToolbox3, its dependencies, and the current renderer
• commandResult - text output from the the current renderer
• radiometricScaleFactor - scale factor that was used to bring renderer ouput into physical radiance units

This function uses RenderToolbox3 renderer API functions "Render", "DataToRadiance", and "VersionInfo". These functions, for the renderer specified in hints.renderer, must be on the Matlab path.

Returns a cell array of output mat-file names, with the same dimensions as the given scenes.

Usage: outFiles = BatchRender(scenes, hints)

radiometricScaleFactor ComputeRadiometricScaleFactor

(

renderer

)

Calculate scale factors to bring renderer outputs into radiance units.

Parameters

renderer

the name of the renderer to use

Calculates a radiometric unit scale factor for the given and stores the scale factor using Matlab's setpref(). Radiometric unit scale factors are used by RenderToolbox3 DataToRadiance functions to bring "raw" renderer output into physical rasiance units. Computation is based on the ExampleScenes/RadiaceTest recipe which has known radiometric properties.

See the RenderToolbox3 wiki for details about <a href="https://github.com/DavidBrainard/RenderToolbox3/wiki/RadianceTest'>Radiometric Unit calculation.

Stores the calculated scale factors for each renderer, using the built-in setpref() function. To see the results for a renderer such as "SampleRenderer", try

scaleFactor = getpref('SampleRenderer', 'radiometricScale');

Returns the computed radiometric unit scale factor for the given renderer.

Usage: radiometricScaleFactor = ComputeRadiometricScaleFactor(renderer)

hints GetDefaultHints

(

hints

)

Get default hints that affect the RenderToolbox3 utilities.

Parameters

hints

struct of RenderToolbox3 options, see GetDefaultHints()

Creates a struct of options that affect the behavior of RenderToolbox3 utilities, or fills in missing parts of a the given hints struct. RenderToolbox3 options include things like renderer name, output image size, and whether to use Matlab's Distributed Computing "parfor" loops.

If provided, hints should be a struct of renderer options with option names as fields. Any missing options will be filled in with default values. If hints is missing or not a struct, creates a new struct with all default values.

Default hint values can be set with Matlab's setpref() function. For example:

% default renderer to use
setpref('RenderToolbox3', 'renderer', 'Mitsuba');
% or
setpref('RenderToolbox3', 'renderer', 'PBRT');

% default ouput image dimensions
setpref('RenderToolbox3', 'imageHeight', 480);
setpref('RenderToolbox3', 'imageWidth', 640);

% review all the hints
hints = GetDefaultHints()

Returns a new or modified struct of batch renderer hints.

Usage: hints = GetDefaultHints(hints) Usage examples:

hints.whichConditions = [1 3 5];
hints = GetDefaultHints(hints);
BatchRender(..., hints);
MakeMontage(..., hints);

SRGBMontage XYZMontage MakeMontage	(	inFiles	,
		outFile	,
		toneMapFactor	,
		isScale	,
		hints
	)

Condense several multi-spectral renderings into one sRGB montage.

Parameters

inFiles	cell array of input mat-file names
outFile	output montage file name (optional)
toneMapFactor	how to truncate montage luminance (optional)
isScale	whether or not to scale montage luminance (optional)
hints	struct of RenderToolbox3 options, see GetDefaultHints()

Condenses several multi-spectral renderings stored in mat-files into a single sRGB montage. Tiles the input images so that the montage has roughly the same aspect ratio as the input images.

Attempts to conserve system memory by loading only one multi-spectral image at a time.

inFiles must be a cell array of mat-file names, each of which must contain multi-spectral renderer output. BatchRender() returns such a cell array.

outFile determines the file name of the new montage. The file extension determines the file format:

• If the extension is '.mat', the montage XYZ and sRGB matrices will be saved to a .mat data file.
• If the extension matches a standard image format, like '.tiff' or '.png' (default), the sRGB image will be saved in that format, using Matlab's built-in imwrite().

If toneMapFactor is provided and greater than 0, montage luminances will be truncated above this factor times the mean luminance of the entire montage.

If isScale is provided and true, montage luminances will be scaled so that the maximum input luminance of the entire montage matches the maximum possible RGB output luminance.

hints may be a struct with options that affect the montage, such as the output folder, as returned from GetDefaultHints(). If hints is omitted, default options are used.

Returns a matrix containing the tone mapped, scaled, sRGB montage with size [height width 3]. Also returns a matrix containing XYZ image data with the same size.

Usage: [SRGBMontage, XYZMontage] = MakeMontage(inFiles, outFile, toneMapFactor, isScale, hints)

scenes MakeSceneFiles	(	colladaFile	,
		conditionsFile	,
		mappingsFile	,
		hints
	)

Make a family of renderer-native scenes based on a Collada parent scene.

Parameters

colladaFile	file name or path of a Collada parent scene file
conditionsFile	file name or path of a conditions file
mappingsFile	file name or path of a mappings file
hints	struct of RenderToolbox3 options, see GetDefaultHints()

Creates a family of renderer-native scenes, based on the given colladaFile, conditionsFile, and mappingsFile. hints.renderer specifies which renderer to target.

colladaFile should be a Collada XML parent scene file. colladaFile may be left empty, if the conditionsFile contains a 'colladaFile' variable.

conditionsFile must be a RenderToolbox3 Conditions File. conditionsFile may be omitted or left empty, if only one renderer-native scene file is to be produced.

mappingsFile must be a RenderToolbox3 Mappings File. mappingsFile may be omitted or left empty if only one renderer-native scene file is to be produced, or if conditionsFile contains a 'mappingsFile' variable.

hints may be a struct with options that affect the process generating of renderer-native scene files. If hints is omitted, values are taken from GetDefaultHints().

• hints.renderer specifies which renderer to target
• hints.tempFolder is the default location for new renderer-native scene files
• hints.filmType is a renderer-specific film type to specify for the scene
• hints.imageHeight and hints.imageWidth specify the image pixel dimensions to specify for the scene
• hints.whichConditions is an array of condition numbers used to select rows from the conditionsFile.
• hints.isReuseSceneFiles specefies whether or not renderer ImportCollada functions should attempt to to skip actual scene file creation, and use existing files instead.

This function uses RenderToolbox3 renderer API functions "ApplyMappings" and "ImportCollada". These functions, for the renderer specified in hints.renderer, must be on the Matlab path.

Returns a cell array of new renderer-native scene descriptions. Each scene description. By default, each scene file will have the same base name as the given colladaFile, plus a numeric suffix. If conditionsFile contains an 'imageName' variable, each scene file be named with the value of 'imageName'.

Usage: scenes = MakeSceneFiles(colladaFile, conditionsFile, mappingsFile, hints)

conditionsFile WriteConditionsFile	(	conditionsFile	,
		names	,
		values
	)

Write conditions data to a text file.

Parameters

conditionsFile	name of new text file to write.
names	1 x n cell array of string variable names
values	m x n cell array of variable values

Writes batch renderer condition variables with the given names and values to a new text file with the given conditionsFile name. See the RenderToolbox3 wiki for more about Conditions Files.

names will appear in the first line of the new file, separated by tabs. Each of the m rows of values will appear in a separate line, with elements separated by tabs. So, the values for each variable will appear in a tab-separated column.

Attempts to convert numeric values to string, as needed.

Usage: conditionsFile = WriteConditionsFile(conditionsFile, names, values)

mappingsFile WriteDefaultMappingsFile	(	colladaFile	,
		mappingsFile	,
		includeFile	,
		reflectances	,
		lightSpectra	,
		excludePattern
	)

Write a default mappings file for the given Collada parent scene file.

Parameters

colladaFile	file name or path of the Collada parent scene file
mappingsFile	file name or path for a new mappings file
includeFile	file name or path for a mappings file to include
reflectances	cell array of matte material reflectances
lightSpectra	cell array of light source spectra
excludePattern	regular expression to filter document elements

Traverses the Collada document in the given colladaFile and writes a new mappingsFile suitable for use with BatchRender(). The mappingsFile will specify default values, including:

• mappings text in includeFile or RenderData/DefaultMappings.txt
• matte material for each geometry node
• a spectrum for each light source

Each material or light source will use a spectrum from a default list, or a provided list.

By default, prepends the text of RenderData/DefaultMappings.txt to the new mappings file. If includeFile is provided it must specify another text file to prepend instead.

By default, each matte material will use one of the Color Checker reflectance spectrums found in RenderData/Macbeth-ColorChecker. If reflectances is provided, it must be a cell array of string reflectance values to use instead.

By default, each light source will use the D65 light spectrum found in RenderData/D65.spd. If lightSpectra is provided, it must be a cell array of string spectrum values to use instead.

By default, writes mappings for all materials and light sources. If excludePattern is provided, it must be a regular expression to match against element id attributes. Elements whose ids match excludePattern will be excluded from the mappingsFile.

Returns the name of the new mappingsFile.

Usage: WriteDefaultMappingsFile(colladaFile, mappingsFile, includeFile, reflectances, lightSpectra, excludePattern)