Better organization of input and output folders.

[benjamin-heasly]

Based on feedback from David and Ana, and considering Issue 19 (https://github.com/DavidBrainard/RenderToolbox3/issues/19), it seems like RenderToolbox3 needs a redesign for how it handles input and output folders.

For a start, here are locations that users and RenderToolbox3 will care about:

Input

• the current Matlab folder
  • subfolders of same
• the folder where a scene lives
  • subfolders of same
• folders on the Matlab path
• a BatchRender() temp folder

Output

• the current Matlab folder
• output folders specified in a hints struct
• output folders specified with a global variable or get/setpref()
• a BatchRender() temp folder
• a BatchRender() data folder
• a MakeMontage() image folder
• subfolders for each renderer

And here are some usages that we want to accommodate:

• render a scene from outside the repository
• render a scene from outside the Matlab path
• render with outputs sent to a custom location
  • send temp, data, and montage outputs to different places
• return to a useful folder following an error

I currently favor the Matlab path for most search purposes, since it's easy for users to configure. If we know about all the files we need, then which() gives us the absolute paths we need. If we don't, we might need to pass the Matlab path to the shell so that renderers can find things on their own.

I found that which() does not search the Matlab current folder, so it would be useful to search there, or add it to the path.

I think much of this can be accommodated by adding a "RenderToolbox3" section to Matlab's get/setpref(). This can contain a few explicit input and output paths. GetDefaultHints(), BatchRender(), and MakeMontage() can check these. pwd() could be a last resort in all cases.

I think get/setpref() is a better solution than the global variable currently used in GetDefaultHints().

[benjamin-heasly]

It would be nice if BatchRender() did not have to cd() around. This would make it easier to handle errors.

One problem is Mitsuba's scene file converter, which always creates a "textures" folder in pwd(). I don't think there's a way to send this folder somewhere else. It's nice to let this folder end up in a temp location, instead of in the user's pwd().

BatchRender() could cd() just for scene file conversion, then cd() back before rendering. This would reduce the chances of errors that leave pwd() in the wrong place.

[benjamin-heasly]

Here is a design that should capture most of the considerations above.

The general approach is:

• input files come from pwd() and the Matlab path
• output locations are specified with get/setpref(), and may default to pwd()
• use cd() as little as possible
• use hints only for volatile things (which conditions to render, image dimensions, isDryRun, etc.)
• store default hint values with get/setpref() (not with a global variable, not hard-coded)

The distinction between hints and get/setprefs() is scope: a script can chose its own hints without affecting the next script that runs.

InitializeRenderToolbox() should define some useful locations in a "RenderToolbox3" section of get/setpref(). If any value is left empty, it may be treated as pwd(), come what may.

• tempFolder
• outputDataFolder
• outputImageFolder

InitializeRenderToolbox() should also define default hint values in the in a "RenderToolbox3" section of get/setpref():

• renderer
• filmType
• adjustmentsFile
• isDeleteTemp (instead of isDeleteIntermediates)
• imageHeight
• imageWidth
• whichConditions
• isDryRun

User scripts and functions like TestAllExampleScenes() would be free to mess with these. Most scripts would leave them alone.

GetDefaultHints() should merge a hints struct with default hint values from getpref(), preferring the values in the given hints struct.

MakeMontage() never uses cd(). It just writes to the ouputImageFolder, which might be empty and therefore equal to pwd().

BatchRender() does not define a workingPath from the given scene file. Instead it writes to the tempFolder and ouputDataFolder, which might be empty and therefore equivalent to pwd(). It never uses cd(), except in limited annoying cases like Mitsuba scene file conversion.

BatchRender() temporarily adds genpath(pwd()) to the Matlab path! It saves the original path and attempts to restore it after rendering, and following errors. It does not call savepath(), so any mistakes in restoring the path should be limited to the current Matlab session.

[benjamin-heasly]

To append to the design above:

A new AddWorkingPath() can accept a folder or file and add genpath(folder) or genpath(which(file)) to the path. It can check if the path already contains such paths. It can remove .svn and .git folders from the new paths.

This will be handy in a few places, like example Make scripts, and BatchRender().

It will make life easier when users create new scenes in custom folders.

[benjamin-heasly]

I think it's simpler and clearer for folders and hints to be treated all the same. So GetDefaultHints() can also return

• tempFolder
• outputDataFolder
• outputImageFolder

The distinction between hints and preferences will still be scope: hints let the user choose values for the current rendering, get/setpref() let the user change persistent defaults.

[benjamin-heasly]

de42ecb9a0eddd42dcb308d9f0b88cc8113496e0 has this improved design for input and output folders!