= PBRT Help =

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).
 * http://graphics.stanford.edu/courses/cs348b-07/pbrt/pbrt-cs348b-1.03.zip
 * /afs/ir/class/cs348b/pbrt/pbrt-cs348b-1.03.tar.gz

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)

setenv PBRT_SEARCHPATH $(PBRTSRC_ROOT)/bin

(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
endif

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 [http://www.cygwin.com 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.


==== 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.