San Miguel example

Motivation

This is an example of a complex scene (from PBRT-V2, actually), one of many, that you will be able to render using the iset3d toolbox. The examples in the wiki explain the logic for scenes like this (s_sanmiguel.m) and others. Each scene has its own details, mainly differing in how they set the rendering parameters, but the core ideas are the same.

In this section we use the small teapot-area-light data from iset3d/data/teapot-area. This is the simplest logic, based on PBRT Version 2. In the next few months we will replace even these introductory examples with the new Version 3 examples that we have implemented. We describe more about the Version 3 implementation as we get into the weeds, later in the wiki.

Initializing the compute environment

We begin by initializing ISETCAM and configuring the Docker environment. This initialization needs to be run once for any Matlab session.

%% Set up ISET and Docker
ieInit;      % isetcam initialization
if ~piDockerExists, piDockerConfig; end   % Check that docker is configured 

The PBRT scene file and data

Next, read the scene PBRT file.

The piRead() function expects that the PBRT scene and its related files are in a directory that has a main scene file (.pbrt). This file includes auxiliary files stored in local sub-directories (geometry, brdfs, textures, spds). Some simple examples are in the directory fullfile(piRootPath,'data','teapot-area'). As we move to Version 3, we formalized the names, formats and methods for modifying these files from Matlab functions.

Reading the scene

We read the PBRT scene and create a rendering recipe. A recipe is an iset3d class that includes the parameters needed to call PBRT. The returned recipe here is thisR.

thisR = piRead(pbrtSceneInput) 

The piRead function analyzes the contents of the pbrt scene file to initialize the recipe. In addition to reading the main PBRT scene file, we have methods for reading and modifying the geometry and material information. These will be described elsewhere.

Editing the scene properties

To achieve a specific rendering, you edit the rendering recipe parameters.

 thisR.set(parameter,value) 

Various scene properties can be modified in the recipe (e.g., textures, object distances, material properties, optics properties). Also, you can set the field of view, the spatial resolution of the output image, lens properties, the spectrum, position, and type, and so forth. As we understand more about PBRT, we add more functionality to the editing.

Saving the modified scene

After modifying the recipe, you write out a new version of the scene pbrt files in the working directory. The location of this directory is set as part of the recipe.

piWrite(thisR)

The piWrite function saves the modified scene PBRT file, and it also copies auxiliary files to the working directory. For example, it copies any necessary lens file, SPDs and such. (The original lens files are stored in data/lens directory).

The modified scene files that are written out in the working directory. The working directory will be mounted by the docker container, and the files in that directory are used to create the rendered image.

Rendering the ISET structure

Finally, invoke the PBRT docker container to render and return an ISETCAM/ISETBIO structure. If the optics are pinhole, an ISETCAM/ISETBIO scene is returned; if the optics include a lens or light field, an ISETCAM/ISETBIO optical image is returned.

ieObject = piRender(thisR)