MaterialSpherePortable Example Scene

The MaterialSpherePortable recipe is a variation on the MaterialSphere Example Scene recipe. It uses the Recipe API to separate scene file generation from rendering. That way, scene files could be generated on one machine, then rendered on a different machine.

The complete recipe is located in the RenderToolbox3 repository at:

(path-to-RenderToolbox3)/ExampleScenes/MaterialSphere/

Files

Like MaterialSphere, MaterialSpherePortable uses 4 basic files:

• MaterialSphere.dae is the Collada parent scene file, with camera, point light, sphere, and default material.
• MakeMaterialSpherePortable.m is the executive script that generates renderings and the final montage.
• MaterialSphereBumpsMappings.txt introduces custom materials and a bump map to the basic MaterialSphere scene.
• MaterialSphereConditions.txt lists 3 image names and 3 mappings groups, for the 3 renderings.

Most of these files behave the same way as they do in the original MaterialSphere scene.

MakeMaterialSpherePortable.m

MakeMaterialSpherePortable.m uses the Recipe API to bind together the Collada parent scene file, conditions file, and mappings file. In the Top Half, it generates renderer-native scene files and packs them up into a zip file archive.

In the Bottom Half, it unpacks the zip archive then continues where the top half left off. The Recipe API functions detect the pre-generated scene files and proceed to render them and produce an sRGB montage.

Here is the full text, with comments:

%% Render MaterialSphere in a portable fashion using the Recipe API

%% Top Half.

%% Choose inputs for a new recipe.
% replace this config script with your own config script
configScript = 'RenderToolbox3ConfigurationTemplate';

% choose the 3D model and parameteric variations
parentSceneFile = 'MaterialSphere.dae';
conditionsFile = 'MaterialSphereConditions.txt';
mappingsFile = 'MaterialSphereBumpsMappings.txt';

% choose the order of operations for rendering the recipe
executive = { ...
    @MakeRecipeSceneFiles, ...
    @MakeRecipeRenderings, ...
    @MakeRecipeMontage, ...
    };

%% Choose RenderToolbox3 options.
% which materials to use, [] means all
hints.whichConditions = [];

% pixel size of each rendering
hints.imageWidth = 200;
hints.imageHeight = 160;

% put output files in a subfolder named like this script
hints.recipeName = 'MakeMaterialSpherePortable';
ChangeToWorkingFolder(hints);

% choose the renderer
hints.renderer = 'PBRT';

%% Make a new recipe that contains all of the above choices.
recipe = NewRecipe(configScript, executive, parentSceneFile, ...
    conditionsFile, mappingsFile, hints);

% add a log message about creating this new recipe
recipe = AppendRecipeLog(recipe, 'Portable recipe for Material Sphere');

%% Move resource files inside the workingFolder, so they can be detected.
resourceFiles = { ...
    fullfile(RenderToolboxRoot(), 'RenderData/Macbeth-ColorChecker/mccBabel-11.spd'), ...
    fullfile(RenderToolboxRoot(), 'RenderData/Macbeth-ColorChecker/mccBabel-7.spd'), ...
    fullfile(RenderToolboxRoot(), 'RenderData/PBRTMetals/Au.eta.spd'), ...
    fullfile(RenderToolboxRoot(), 'RenderData/PBRTMetals/Au.k.spd'), ...
    fullfile(RenderToolboxRoot(), 'ExampleScenes/CubanSphere/earthbump1k-stretch-rgb.exr')};

resources = GetWorkingFolder('resources', false, hints);
for ii = 1:numel(resourceFiles)
    copyfile(resourceFiles{ii}, resources);
end

%% Generate scene files and pack up the recipe.
% generate all the scene files for the recipe
recipe = ExecuteRecipe(recipe, 1);

% pack up the recipe with resources and pre-generated scene files
%   don't pack up boring temp files
archiveName = fullfile(GetUserFolder(), 'MaterialSpherePortable.zip');
PackUpRecipe(recipe, archiveName, {'temp'});

% boldly delete the recipe working folder now that it's packed up
scenesFolder = GetWorkingFolder('', false, hints);
rmdir(scenesFolder, 's');

%% Bottom Half.

%% Un-pack and render in a new location -- could be on another computer.
% locate the packed-up recipe
% change this archiveName if you moved to another computer
archiveName = fullfile(GetUserFolder(), 'MaterialSpherePortable.zip');
archiveName = '/Users/ben/Documents/MATLAB/MaterialSpherePortable.zip';

% choose a folder to un-pack the recipe into
% this could also be on another computer
newFolder = fullfile(GetUserFolder(), 'AnotherComputer');
hints.workingFolder = newFolder;

% un-pack the recipe into the new folder
recipe = UnpackRecipe(archiveName, hints);

% change the recipe's configureScript if you moved to a new machine.
configureScript = 'RenderToolbox3ConfigurationTemplate';
recipe.input.configureScript = configureScript;

% render the recipe from pre-generated scene files
recipe = ExecuteRecipe(recipe);

All of the code in the Top Half could be rendered on one machine, for example a workstation that's convenient to work with and debug interactively. The result of the top half is a zip archive that contains all of the input files that went into the recipe, as well as pre-generated renderer-native scene files. Once the recipe and scene files have been safely they are no longer needed by the Top Half, so they are deleted.

All of the code in the Bottom Hald could be run on the same machine, or another machine like a remote high-power computing cluster. The bottom half starts with the same zip archive that the Top Half produced. It unpacks the archive and finds everything it needs inside in order to make renderings and produce an sRGB montage of three bumpy spheres.