Skip to content

Input and Output Files

Jump to bottom Edit New page
Ben Heasly edited this page Jul 26, 2013 · 42 revisions

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 include Collada parent scene files, and conditions files, mappings files, executive scripts, and auxiliary files like multi-spectral reflectance and illuminant data files, and bitmap texture images. All of these 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

RenderToolbox3 utilities like MakeSceneFiles(), BatchRender(), and MakeMontage() take input files as arguments. These include Collada parent 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 MakeSceneFiles(), BatchRender(), and MakeMontage() with different kinds of input files:

% plain file name
myColladaParentScene = '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
rendererNativeFiles = MakeSceneFiles(myColladaParentScene, myConditionsFile, myMappingsFile);
radianceDataFiles = BatchRender(rendererNativeFiles);
MakeMontage(radianceDataFiles, 'myCoolMontage.png');
Indirect References

Mappings files and conditions files may in turn refer to other files, like multi-spectral data 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
%    it 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.

Current Folder 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, MakeSceneFiles() temporarily adds the current folder to the path. The result would be similar to this code:

AddWorkingPath(pwd());

This adds the current folder (but not 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 that case, you should temporarily add your scene folder to the Matlab path. You could add code like this to the top of your custom script:

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

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

Output Files

RenderToolbox3 has 3 kinds of "output" file, which it puts in 3 different places. You can specify each place separately. The three kinds of file are:

  • temp files: these are intermediate files generated during batch processing. For example, BatchRender() produces a separate scene file for each variant specified in the conditions file. Temp files can be deleted automatically by BatchRender().
  • output data these are ".mat" files that contain multi-spectral outputs from renderers. BatchRender() generates these files.
  • output images these are image files, like ".tiff" and ".png" files. MakeMontage() generates these files.
Default Locations

By default, RenderToolbox3 uses output folders that are stored as Matlab preferences. To see the current output folders, try:

prefs = getpref('RenderToolbox3')

The prefs struct will contain many fields, including 3 fields that specify where to put each type of output file.

Initially, all the output folders are chosen to be inside the user's Matlab Documents folder. For example, on OS X the folders would be like these:

prefs = 

           tempFolder: '/Users/my-user-name/Documents/MATLAB/render-toolbox/temp'
     outputDataFolder: '/Users/my-user-name/Documents/MATLAB/render-toolbox/data'
    outputImageFolder: '/Users/my-user-name/Documents/MATLAB/render-toolbox/images'
    % etc...

You can customize the default output folders using Matlab's built-in setpref() function:

% put temp files relative to the current folder
setpref('RenderToolbox3', 'tempFolder', 'my-temp-files');

% put data and image files in fixed locations
setpref('RenderToolbox3', 'outputDataFolder', '/users/my-user-name/myData');
setpref('RenderToolbox3', 'outputImageFolder', '/users/my-user-name/myImages');

It's a good idea for all these folders to be different because you might want archive, delete them, or overwrite them separately or at different times.

Hints instead of setpref()

Using setpref() as above will change the output folders for all subsequent renderings. You can use a "hints" struct to pick the output folders for just the current rendering. For example:

% choose output folders for the current rendering
hints.tempFolder = 'my-temp-files';
hints.outputDataFolder = '/users/my-user-name/myData';
hints.outputImageFolder = '/users/my-user-name/myImages';

% render with output folder hints
sceneFiles = MakeSceneFiles(myColladaScene, myConditionsFile, myMappingsFile, hints);
outputFiles = BatchRender(sceneFiles);
MakeMontage(outputFiles, 'myCoolMontage.png', [], [], hints);

The hints struct has all of the same fields as the RenderToolbox3 prefs struct above. To see all of the default hint values, try:

hints = GetDefaultHints()

When you pass a hints struct to MakeSceneFiles(), BatchRender(), or MakeMontage(), RenderToolbox3 will use the values in the hints struct instead of the default RenderToolbox3 preference values. This allows you to specify custom output folders for the current rendering, without affecting any subsequent renderings.

Output Subfolders

RenderToolbox3 can automatically append a subfolder to any of the output folders above. This is useful for grouping related outputs, such as outputs that were generated by the same executive script.

You can chose the default ouptut subfolder name using setpref():

setpref('RenderToolbox3', 'outputSubfolder', 'my-ouput-name');

You can also choose the ouput subfodler for a single recipe using a hints struct:

hints.outputSubfolder = 'my-ouput-name';

Setting the ouputSubfolder to the empty string '' causes RenderToolbox3 not to append any subfolder to the output subfolders above.

You can access full output folder names, including any outputSubfolder, using the GetOutputPath() utility:

hints.outputSubfolder = 'my-ouput-name';
disp(GetOutputPath('tempFolder', hints));
disp(GetOutputPath('outputDataFolder', hints));
disp(GetOutputPath('outputImageFolder', hints));

hints.outputSubfolder = 'another-ouput-name';
disp(GetOutputPath('tempFolder', hints));
disp(GetOutputPath('outputDataFolder', hints));
disp(GetOutputPath('outputImageFolder', hints));

This would result in

/Users/my-user-name/Documents/MATLAB/render-toolbox/temp/my-ouput-name
/Users/my-user-name/Documents/MATLAB/render-toolbox/data/my-ouput-name
/Users/my-user-name/Documents/MATLAB/render-toolbox/images/my-ouput-name
/Users/my-user-name/Documents/MATLAB/render-toolbox/temp/another-ouput-name
/Users/my-user-name/Documents/MATLAB/render-toolbox/data/another-ouput-name
/Users/my-user-name/Documents/MATLAB/render-toolbox/images/another-ouput-name

This example uses a hints struct to specify the temporary outputSubfolder. hints may also be omitted, in which case GetOutputPath() will use the value from setpref('RenderToolbox3', 'outputSubfolder').

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