Input and Output Files

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

Recipe Working Folder

RenderToolbox3 keeps track of the your current recipe's workingFolder. This is usually inside a big folder where you want to put "RenderToolbox3 stuff", plus a subfolder for the specific recipe you're working on.

You can specify your big working folder and recipe subfolder using RenderToolbox3 hints. See GetDefaultHints().

For example, you might set the big working folder to /users/myName/projects/render-toolbox. And you might be working on a recipe named red-dragon. You would specify the hints like this:

hints.workingFolder = '/users/myName/projects/render-toolbox';
hints.recipeName = 'red-dragon';

This would cause RenderToolbox3 to look for resources and to put output files withing the recipe workingFolder

/users/myName/projects/render-toolbox/red-dragon

You don't have to specify the big hints.workingFolder every time. You can set a default working folder like so:

setpref('RenderToolbox3', 'workingFolder', '/users/myName/projects/render-toolbox');

You should do this in your locally modified version of RenderToolbox3ConfigurationTemplate.m.

Named Subfolders

RenderToolbox3 defines some named subfolders within each recipe workingFolder. These keep all of your various input and output files organized in sensible groups. These folders are:

folder name	what goes in it
resources	you should put your input files like texture images and spectrum .spd files in here
scenes	RenderToolbox3 puts renderer-native scene files in here
renderings	RenderToolbox3 puts raw renderer outputs and multispectral .mat data files in here
images	RenderToolbox3 puts computed sRGB/sensor images and montages in here
temp	RenderToolbox3 attempts to put boring intermediate files in here

The first four folders probably contain interesting data that you care about. You might want to use the Recipe API to archive the data in these folders.

The last temp folder should not contain any interesting data. It should only contain boring files that RenderToolbox3 created on the way to creating interesting things like scene files. It should be safe to delete the temp folder whenever you want to.

Finding Resource Files

Your mappings files and conditions files might refer to resource files, like spectrum .spd files and texture image files. How you name these files affects how RenderToolbox3 finds them and what values it writes into renderer-native scene files.

RenderToolbox3 prefers to write relative paths into renderer-native scene files. This makes your scenes portable as long as the scene files and the resources move together.

When RenderToolbox3 it can't find a relative path to a resource, it will write a fill absolute path instead. This will allow your scenes to render, but only on the same machine where the scene files were generated. RenderToolbox3 will warn you whenever it writes an absolute resource path into a scene file by printing a message to the command window. For example:

Using absolute resource path: `/Users/myName/Documents/Projects/RenderToolbox3/RenderData/Macbeth-ColorChecker/mccBabel-1.spd`

This gives you a chance to find the offending resource and copy it into the resources named subfolder of your recipe.

Plain File Names

When you give a plain file name like Daylight.spd, RenderToolbox3 will look for it in the current workingFolder. If it finds a match there, it will use this file. In renderer-native scene files, RenderToolbox3 will write a relative path relative to the workingFolder, like resources/Daylight.spd.

This is the best way to deal with resource files because it's easy for you and it keeps your recipes portable.

If Rendertoolbox3 can't find a match in the current workingFolder, it will look on the Matlab path. If it finds a match there it will use this file. In renderer-native scene files it will write an absolute path like /user/myName/projects/render-toolbox/red-dragon/resources/Daylight.spd.

This will work as long as you don't need to make your recipes portable.

Relative Paths

When you give a relative path like resources/Daylight.spd, RenderToolbox3 will look for it in the current workingFolder. If it finds a match there, it will use this file. In renderer-native scene files, RenderToolbox3 will the same relative path.

This is also a good way to deal with resource files.

If Rendertoolbox3 can't find a match in the current workingFolder, it will look in the current folder given by pwd(). If it finds a match there it will use this file. In renderer-native scene files it will write an absolute path like /user/myName/projects/render-toolbox/red-dragon/resources/Daylight.spd.

This will work as long as you don't need to make your recipes portable.

Absolute Paths

When you give a relative path like /user/myName/projects/render-toolbox/red-dragon/resources/Daylight.spd, RenderToolbox3 will use this file. In renderer-native scene files, RenderToolbox3 will the same absolute path.

This will work as long as you don't need to make your recipes portable.

Utilities

RenderToolbox3 provides some utilities so that you don't have to write lots of ugly path strings yourself.

function	what it does
ResolveFilePath()	searches for a given file or path and gives various info about where it was found
GetWorkingFolder()	gets the current workingFolder and named subfolders
GetWorkingRelativePath()	convert a full absolute path to a relative path (relative to the current workingFolder)
GetWorkingAbsolutePath()	convert relative path (relative to the current workingFolder) to a full absolute path

See Utilities for details.