|
Render Toolbox 3
v2.1
|
Utilities for workign with recipes. More...
Functions | |
| recipe | AppendRecipeLog (recipe, comment, executed, errorData, executiveIndex) |
| Add an entry to the recipe's execution log. | |
| recipe | ChangeToRecipeFolder (recipe) |
| cd() to the working folder for a recipe. | |
| recipe | CleanRecipe (recipe) |
| Clear out recipe derived data fileds. | |
| recipe | ConfigureForRecipe (recipe) |
| Configure RenderToolbox3 to run the given recipe. | |
| recipe | CurrentRecipe (recipe) |
| Get or set the RenderToolbox3 "current recipe". | |
| recipe | ExecuteRecipe (recipe, whichExecutives, throwException) |
| Execute the given recipe and make long entries. | |
| errorData | GetFirstRecipeError (recipe, throwException) |
| Get the first logged recipe error, if any. | |
| recipe | MakeRecipeMontage (recipe) |
| Make an sRGB montage from a recipe's radianceDataFiles. | |
| recipe | MakeRecipeRenderings (recipe) |
| Make renderings from a recipe's native scene files. | |
| recipe | MakeRecipeSceneFiles (recipe) |
| Generate native scene files for the given recipe. | |
| recipe | NewRecipe (configureScript, executive, parentSceneFile, conditionsFile, mappingsFile, hints) |
| Start a new recipe from scratch. | |
| archiveName | PackUpRecipe (recipe, archiveName, ignoreFolders) |
| Save a recipe and its file dependencies to a zip file. | |
| summary | PrintRecipeLog (recipe, verbose) |
| Print a recipe's log as formatted text. | |
| recipe | ReadRecipeConditions (recipe) |
| Parse conditions from file and save in recipe struct. | |
| recipe | ReadRecipeMappings (recipe) |
| Parse mappings from file and save in recipe struct. | |
| recipe | UnpackRecipe (archiveName, hints) |
| Load a recipe and its file dependencies from an archive file. | |
| WriteRecipeLog (recipe, fileName) | |
| Write a recipe's log as formatted text to a text file. | |
Utilities for workign with recipes.
These utilities facilitate working with recipes, including making new recipes, executing them, packing up recipe archives and unpacking them, and logging progress and errors.
| recipe AppendRecipeLog | ( | recipe | , |
| comment | , | ||
| executed | , | ||
| errorData | , | ||
| executiveIndex | |||
| ) |
Add an entry to the recipe's execution log.
| recipe | a recipe struct |
| comment | index optional comment to include with the log |
| executed | a script/function name/handle that was executed |
| errorData | a Matlab exception or other error data, if any |
| executiveIndex | index of executed in recipe.executive |
Appends the given executed, errorData, and executiveIndex to the execution log of the given recipe. Also appends the current date and time, current user name, and current computer's host name.
Users may supply an optional string comment to include with other logged data.
executed should be the name of a script or function, or a function_handle that was executed on the given recipe. This is the thing that happened that should be logged.
errorData should be a Matlab exception that was caught, or any other error data that resulted from executed. errorData should only be empty of no error occured.
If executed is one of the scripts or functions listed in recipe.executive, then executiveIndex should be the index of executed within recipe.executive. RenderToolbox3 functions will always supply executiveIndex in order to track the progress of a recipe's execution. Users may omit executiveIndex.
Returns the given recipe, with the given logging information appended.
Usage: recipe = AppendRecipeLog(recipe, comment, executed, errorData, executiveIndex)
| recipe ChangeToRecipeFolder | ( | recipe | ) |
cd() to the working folder for a recipe.
| recipe | a recipe struct |
Attempts to change directory to the working folder for the given recipe.input.hints. Creates the folder if it doesn't exist yet.
Returns the given recipe, possibly updated with a new error appended.
Usage: recipe = ChangeToRecipeFolder(recipe)
| recipe CleanRecipe | ( | recipe | ) |
Clear out recipe derived data fileds.
| recipe | a recipe struct to be cleaned |
Clear recipe derived data fields.
Returns the given recipe, cleared out and reset to a like-new state.
Usage: recipe = CleanRecipe(recipe)
| recipe ConfigureForRecipe | ( | recipe | ) |
Configure RenderToolbox3 to run the given recipe.
| recipe | a recipe struct |
Attempts to configure RenderToolbox3 for rendering the given recipe using recipe.input.configureScript.
Sets the "current recipe" so that recipe.input.configureScript may access and modify the given recipe using CurrentRecipe();
Returns the given recipe, possibly updated by recipe.input.configureScript, possibly with a new error appended.
Usage: recipe = ConfigureForRecipe(recipe)
| recipe CurrentRecipe | ( | recipe | ) |
Get or set the RenderToolbox3 "current recipe".
| recipe | a recipe struct to become current |
CurrentRecipe() controls acceses to a Matlab persistent variable that holds the RenderToolbox3 "current recipe". There can be only one current recipe at a time. The current recipe is a central point of contact allowing various scripts that make up a recipe to interact.
If recipe is provided, replaces the current recipe with the given recipe.
Returns the current recipe, which is equal to the given recipe, if it was privided.
Usage: recipe = CurrentRecipe(recipe)
| recipe ExecuteRecipe | ( | recipe | , |
| whichExecutives | , | ||
| throwException | |||
| ) |
Execute the given recipe and make long entries.
| recipe | a recipe struct to be cleaned |
| whichExecutives | indices to select specific scripts or functions |
| throwException | whether to re-throw a Matlab MException |
First calls ConfigureForRecipe(), then executes each of the scripts or functions in the given recipe.input.executive, and makes a log entry for each. If a corresponding log entry already exists, skips that script or funciton and moves on to the next.
To make sure that no executive scripts or functions are skipped, first call CleanRecipe().
By default, tries to execute all of the scripts and functions in recipe.input.executive. If whichExecutives is provided, it must be an array of indices used to select specific scripts or functions. Only these elements of recipe.input.executive will be executed.
If any executive script or recipe throws an error, logs the error and stops executing. If throwException is true (the default), and the error is a Matlab MException, rethrows the exception to produce a stack trace in the command window.
Returns the given recipe, with recipe.log filled in.
Usage: recipe = ExecuteRecipe(recipe, whichExecutives, throwException)
| errorData GetFirstRecipeError | ( | recipe | , |
| throwException | |||
| ) |
Get the first logged recipe error, if any.
| recipe | a recipe struct to be cleaned |
| throwException | whether to re-throw a Matlab MException |
Searches the given recipe.log for errors and returns the first one found, if any. If throwException is true (the default), and the first error is a Matlab MException, rethrows the exception (which gives a handy stack trace in the command window).
Returns the first error found in the given recipe.log, if any.
Usage: errorData = GetFirstRecipeError(recipe)
| recipe MakeRecipeMontage | ( | recipe | ) |
Make an sRGB montage from a recipe's radianceDataFiles.
| recipe | a recipe struct |
Uses the given recipe's radiance data files to make an sRGB montage.
Returns the given recipe, with recipe.processing.xyzMontage and recipe.processing.srgbMontage and filled in.
Usage: recipe = MakeRecipeMontage(recipe)
| recipe MakeRecipeRenderings | ( | recipe | ) |
Make renderings from a recipe's native scene files.
| recipe | a recipe struct |
Uses the given recipe's renderer native scene descriptions to produce renderings, using the given recipe.input.hints.renderer.
Returns the given recipe, with recipe.rendering.radianceDataFiles filled in.
Usage: recipe = MakeRecipeRenderings(recipe)
| recipe MakeRecipeSceneFiles | ( | recipe | ) |
Generate native scene files for the given recipe.
| recipe | a recipe struct |
Uses the given recipe's parent scene file, conditions file, and mappings file to generate renderer-native scene files for the renderer specified in recipe.input.hints.renderer.
Returns the given recipe, with recipe.rendering.scenes filled in.
Usage: recipe = MakeRecipeSceneFiles(recipe)
| recipe NewRecipe | ( | configureScript | , |
| executive | , | ||
| parentSceneFile | , | ||
| conditionsFile | , | ||
| mappingsFile | , | ||
| hints | |||
| ) |
Start a new recipe from scratch.
| configureScript | name of a system configuration script |
| executive | script/function names/handles to execute |
| parentSceneFile | name of a Collada scene file |
| conditionsFile | name of a RenderToolbox3 conditions file |
| mappingsFile | name of a RenderToolbox3 mappings file |
| hints | struct of hints as from GetDefaultHints() |
Create a brand new RenderToolbox3 recipe struct with the given fields filled in and some derived fields filed in, like conditions and mappings. All arguments are optional.
configureScript should be the name of a RenderToolbox3 system configuration script, such as a locally modified copy of RenderToolbox3ConfigurationTemplate.
executive should be a cell array of function_handles or string script names to be executed in order to carry out the recipe. All function_handles must refer to functions that expect a recipe as the first argument return the recipe as the first output. All strings must refer to m-files that use CurrentRecipe() to access and modify the current recipe.
parentSceneFile should be the name name of a Collada parent scene file, for example Dragon.dae.
conditionsFile should be the name of a RenderToolbox3 conditions file, for example DragonColorCheckerConditions.txt.
mappingsFile should be the name of a RenderToolbox3 mappings file, for example DragonColorCheckerMappings.txt.
hints should be a struct of hints as from GetDefaultHints(), or a partial struct with some fields filed in, to be merged with a full hints struct.
Returns a new recipe struct which should be ready for rendering.
Usage: recipe = NewRecipe(configureScript, executive, ... parentSceneFile, conditionsFile, mappingsFile, hints)
| archiveName PackUpRecipe | ( | recipe | , |
| archiveName | , | ||
| ignoreFolders | |||
| ) |
Save a recipe and its file dependencies to a zip file.
| recipe | a recipe struct |
| archiveName | name of the archive file to create |
| ignoreFolders | optional cell array of folder names to ignore |
Creates a new zip archive named archiveName which contains the given recipe (in a mat-file) along with its file dependencies from the current working folder. See GetWorkingFolder().
By default, packs up all files in the recipe's working folder. If ignoreFolders is provided, it must be a cell array of named subfolders not to pack up with the recipe. For example, {'temp'}. See GetWorkingFolder() for more about named subfolders.
Returns the name of the zip archive that was created, which may be the same as the given archiveName.
Usage: archiveName = PackUpRecipe(recipe, archiveName, ignoreFolders)
| summary PrintRecipeLog | ( | recipe | , |
| verbose | |||
| ) |
Print a recipe's log as formatted text.
| recipe | a recipe struct |
| verbose | true for full detail, false for simple summary |
Prints the log data for the given as nicely formatted text. if verbose is provided and true, prints lots of details and stack traces for logged exceptions. Otherwise, prints a compact summary.
Prints the log data to the Command Window and also returns the same formatted text as a string.
Usage: summary = PrintRecipeLog(recipe, verbose)
| recipe ReadRecipeConditions | ( | recipe | ) |
Parse conditions from file and save in recipe struct.
| recipe | a recipe struct |
Reads RenderToolbox3 conditions from recipe.input.conditionsFile and saves the results in recipe.rendering.conditions.
Returns the given recipe, with parsed conditions.
Usage: recipe = ReadRecipeConditions(recipe)
| recipe ReadRecipeMappings | ( | recipe | ) |
Parse mappings from file and save in recipe struct.
| recipe | a recipe struct |
Reads RenderToolbox3 mappings from recipe.input.mappingsFile and saves the results in recipe.rendering.mappings.
Returns the given recipe, with parsed mappings.
Usage: recipe = ReadRecipeMappings(recipe)
| recipe UnpackRecipe | ( | archiveName | , |
| hints | |||
| ) |
Load a recipe and its file dependencies from an archive file.
| archiveName | name of the archive file to unpack |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Creates a new recipe struct based on the given archiveName, as produced by PackUpRecipe(). Also unpacks recipe file dependencies that were saved in the archive, to the current working folder.
Returns a new recipe struct that was contained in the given archiveName.
Usage: recipe = UnpackRecipe(archiveName, hints)
| WriteRecipeLog | ( | recipe | , |
| fileName | |||
| ) |
Write a recipe's log as formatted text to a text file.
| recipe | a recipe struct |
| fileName | name of the file to write |
Writes verbose log data from the given recipe to a text file at the given fileName.
Usage: PrintRecipeLog(recipe, fileName)
1.8.2
