Please email cs348b-spr0607-staff@lists.stanford.edu if you are having problems building or running PBRT using your preferred environment. Before emailing, read over the following notes on common issues with getting PBRT up and running on your system.

Get pbrt

Please grab the pbrt source code (version 1.03) which is available at the following two locations (Please do not use the pbrt code provided on the textbook CD. The downloads below contain many bug fixes from the original release, and we have verified that they run on the Gates B02 myth Linux machines, on VS2003/VS2005, and on MacOS).

Unzip the pbrt archive into a local directory. I'll refer to the fully qualified path to the root pbrt directory (your_local_dir/pbrt-1.03) as PBRTSRC_ROOT.

Building pbrt on Linux (the 'myth' machines in Gates B08)

Build pbrt and the pbrt tools

  1. Build pbrt: Type "make" from the PBRTSRC_ROOT directory to build pbrt. Binaries will be placed in $(PBRTSRC_ROOT)/bin.

  2. Build pbrt tools: Type "make" from $(PBRTSRC_ROOT)/tools directory to build some utility programs that are useful for working with files that you might include in pbrt scenes. Most notably is exttotiff and tifftoexr, which convert back and forth between the EXR and TIFF image formats.

Set up paths

  1. pbrt builds each of its subcomponents into separate dynamically linked libaries. At runtime, it uses the environment variable PBRT_SEARCHPATH to find these libraries. Please set PBRT_SEARCHPATH to $(PBRTSRC_ROOT)/bin in your environment. For example, we recommend that you add the following to your .login or .cshrc.

(the following line is for tcsh/csh.  Bash users make the appropriate syntax modifications)


(where on your system you'd use the fully qualified path of the root pbrt directory as $(PBRTSRC_ROOT))

2. You'll also need to add the directory /afs/ir/class/cs348b/ext/lib to your environment's LD_LIBRARY_PATH. If you already have directories in your LD_LIBRARY_PATH, the following lines might be useful to you.

if ($?LD_LIBRARY_PATH == 0) then

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/afs/ir/class/cs348b/ext/lib

3. Lastly it is convenient to add the directories PBRTSRC_ROOT/bin and PBRTSRC_ROOT/tools to your PATH.

4. To ensure the pbrt is working properly, render a simple test scene, and then convert the EXR output to a TIF file.

pbrt /afs/ir/class/cs348b/pbrt/scenes/checkerboard.prt
exrtotiff pbrt.exr pbrt.tif

You should now be able to view the image pbrt.tif using any image viewer.

A note for installing on other Linux machines

Pbrt assumes OpenEXR libraries and headers are installed on your system. You will need to download and install OpenEXR 1.4.0 on your machine before attempting to compile pbrt. OpenEXR downloads are available at http://www.openexr.com.

The cs348b pbrt 1.03 makefiles are set up to be used on the myth machines. You use the code on your own Linux machines, you will need to set the pbrt makefiles (PBRTSRC_ROOT/Makefile and PBRTSRC_ROOT/tools/Makefile) to point to the appropriate OpenEXR lib and include directories. Specifically, you'll need to change the values of EXRINCLUDEDIR and EXRLIBDIR to match your system setup.

Building pbrt on Windows Using Visual Studio 2003/2005

  1. To build pbrt, you will need a minimal installation of cygwin (for flex and bison). Note that if you install cygwin into the default c:\cygwin directory, no modifications to the Visual Studio build are necessary. If cygwin is not installed into this directory, you will need to do change the custom build step for the files {pbrtlex.l} and {pbrtparse.y} in 'core' project. In VS, right click on these files to bring up the property page, and change the command line for the custom build step to correctly call the cygwin flex and bison executables on your system.

  2. Install the OpenEXR 1.4.0 binaries, which can be obtained at http://www.openexr.com/downloads.html. Be sure to get the correct binaries for your system (you'll want either openexr-1.4.0-vsnet2003.zip or openexr-1.4.0-vsnet2005.zip) VS2003 Users: If you unzip the VS2003 version of OpenEXR into a subdirectory parallel to PBRTSRC_ROOT (the name of the subdirectory is openexr-1.4.0-vs2003), you will not need to modify the pbrt solution. If you are using VS2005 or choose to put the OpenEXR binaries in an alternate location, you will need to modify the additional include directories and additional libraries directories values in the "core" project of the pbrt solution. Right clicking and selecting "properties" on the "core" project in the solution explorer will bring up the panel to modify these build settings.

  3. Build the entire pbrt solution from the solution file PBRTSRC_ROOT/win32/pbrt.sln. A Debug mode build will place binaries in PBRTSRC_ROOT/win32/Projects/Debug. A Release mode build will place binaries in PBRTSRC_ROOT/win32/Projects/Release.

  4. Set the PBRT_SEARCHPATH. Pbrt compiles each of its modules as dynamically linked libraries and uses PBRT_SEARCHPATH to find these libraries when running. Create a system environment variable called PBRT_SEARCHPATH and set its value to either PBRTSRC_ROOT/win32/Projects/Debug or PBRTSRC_ROOT/win32/Projects/Release, depending on whether you are working with a debug or release build. You may also find it convenient to add one of these directories to your system path.

Pbrt should now be ready to go.

Additional Notes

  • If you put your pbrt source code in a directory who's full path contains a space, Visual Studio will have some problems executing the custom build steps that execution flex and bison.
  • Some students have needed to add a space after "-o" in the custom build step command. If you have problems executing the custom build steps try the following:
    • In the Visual Studio explorer: Right click on the file core/parse files/pbrtparse.y
    • Click on "Custom Build Step"
    • Add a space after "-o" in the custom build step command line
    • Do the same for core/parse files/pbrtlex.l

Exrtotiff on Windows

Exrtotiff is a simple utility provided with pbrt to convert high dynamic range (HDR) image files (.EXR) produced by a pbrt render into tiff files (.TIF) that can be displayed by most image programs. exrtotiff src is located in the PBRTSRC_ROOT/tools directory. The pbrt archive does not include a Visual Studio project file to build exrtotiff on Windows. We will attempt to provide one shortly. For now, you can download a compiled Win32 binary at http://graphics.stanford.edu/courses/cs348b-07/pbrt/win32_exrtotiff.zip.

Building pbrt on the Mac

  1. Install OpenEXR 1.4.0 on your system, which can be obtained at http://www.openexr.com/downloads.html.

  2. You need need to modify the pbrt makefiles so that EXR libraries and header files can be found by the pbrt build process.
  3. You will need to set up the PBRT_SEARCHPATH} environment variable as discussed in the Linux build instructions.

Viewing and converting EXR Images

To view .EXR images produces by pbrt, you can either convert them to .TIF files using exrtotiff or view them directly using an imaging program that supports them.

The most common usage of exrtotiff is simply converting from an .exr file to a .tif.

exrtotiff srcfilename.exr outputfilename.tif

Other Programs that can display EXR images

  • The latest versions of Photoshop (beginning with CS) can open EXR files directly.
  • In the /bin subdirectory of your OpenEXR binaries is a program called exrdisplay that can be used to directly view and adjust the exposure of EXR files.

  • OpenEXR software provides an exr-photoshop plugin for both Windows and OS X. You may download the package from http://www.openexr.com/downloads.html. The documentation is at http://www.openexr.com/photoshop_plugin.html.