Input and Output Files

RenderToolbox3 needs to know where to find input files and where to put output files. Here are the conventions for input files and the preferences you can set for output files.

Input Files

Input files should be located on the Matlab path, or in the current Matlab folder. This might be all you need to know!

Read on for some details that apply to different kinds of input file.

Function Arguments

Functions like BatchRender() and MakeMontage() take input files as arguments. These include Collada scene files, mappings files, conditions files, and multi-spectral data files. These files can use plain file names, or names that include relative or absolute file paths. It is up to Matlab to resolve these plain names and relative paths. To do this, Matlab usually looks in the current folder and on the Matlab path.

Here are sample invokations of BatchRender() and MakeMontage() with different kinds of input files:

% plain file name
myColladaScene = 'coolScene.dae';

% relative path
myMappingsFile = 'mappingsStuff/coolScene/coolMappings.txt';

% absolute path
myConditionsFile = '/users/my-user-name/conditions-lists/coolConditions.txt';

% render and make a montage
outputFiles = BatchRender(myColladaScene, myConditionsFile, myMappingsFile);
MakeMontage(outputFiles, 'myCoolMontage.png');

Indirect References

Mappings files and conditions files may in turn refer to other files, like spectrum ".spd" files and texture image files. These files can also use plain file names, or names that include relative or absolute file paths. It is up to RenderToolbox3 to resolve these plain names and relative paths. To do this, it uses Matlab's built-in which() function.

For example, a mappings file might refer to the spectrum file called D65.spd:

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

RenderToolbox3 would encounter the plain file name D65.spd on the right hand side of the mapping. It would check whether such a file exists using Matlab's built-in exist() function. If the file does exist, it would resolve the absolute path to the file using the built-in which() function. The results would be similar to this code:

% plain name of a spectrum file
mySpectrum = 'D65.spd';

% replace the plain name with the full absolute path
%    which should be 'path-to-RenderToolbox3/RenderData/D65.spd'
if exist(mySpectrum, 'file')
    mySpectrum = which(mySpectrum);
end

Throughout the current rendering, RenderToolbox3 would use the absolute path name in place of the plain file name. This would allow renderers to locate arbitrary files, even though the renderers don't know about the Matlab path.

pwd() Automatically added to the Path

The which() function does not consider the current Matlab folder to be part of the Matlab path. In order to find files that are in the current folder, BatchRender() temporarily adds the current folder to the path. The result would be similar to this code:

AddWorkingPath(pwd());

This adds the current folder and its sub-folders to the beginning of the Matlab path.

After rendering, BatchRender() attempts to restore the path to its original value. In case of severe errors, or if the user aborts rendering with control-C, BatchRender() might be unable to restore the path to its original value. In that case, restarting Matlab should restore the path.

Add Custom Folders to the Path

You might want to render a scene that is not on the Matlab path, and not in the current Matlab folder. In this case, you can easily, temporarily, add your scene folder to the Matlab path. For example, you could add code like this to the top of your custom script:

mySceneFolder = '/users/my-user-name/scenes';
AddWorkingPath(mySceneFolder);

This would add your scene folder and its sub-folders to beginning of the Matlab. As long as you do not save the Matlab path, the change will be temporary.

Output Files

may be absolute or relative, in which case they depend on pwd(). empty is pwd().

BatchRender() uses a sub-folder for each renderer.

temp files

• copy of collada file, adjustments file, geometry dumps, various scene files
• not spectra or images

data files

• multi-spectral .mat files
• others in future?

image files

• MakeMontage() images
• others in future?

hints vs get/setpref()

• GetDefaultHints()
• custom hints, default to getpref()
• hints affect only current run
• setpref() affects subsequent runs