-
Notifications
You must be signed in to change notification settings - Fork 2
Installing RenderToolbox3
RenderToolbox3 runs in Matlab. From Matlab, it calls on other libraries and applications. Installing RenderToolbox3 involves downloading the RenderToolbox3 Matlab code, installing the required applications and libraries, and configuring the Matlab path and preferences.
Depending on your platform, you might also need to compile some things. If you use OS X 10.6 or later, you might be all set.
You can get the RenderToolbox3 Matlab code from GitHub. Here is a static .zip archive of the code.
If you have the version control tool Git, you can get the code and also keep it up to date. Open a terminal and type
git clone https://github.com/RenderToolbox3/RenderToolbox3.git
Either way, remember where you put the code. This is your path-to-RenderToolbox3.
RenderToolbox3 uses the physically-based renderers PBRT and Mitsuba. These are separate open-source projects, that do not run in Matlab.
If you're using OS X 10.6 or later, you can download our Pre-Built-Renderers. Otherwise, see Building Renderers for more about how to build the renderers from source.
Note: RenderTooblox3 uses a customized version of PBRT called pbrt-v2-spectral, which depends on the GSL framework. You must install GSL before you can use pbrt-v2-spectral.
On OS X the best way to get gsl is probably to use the Homebrew package manager. Once you have Homebrew installed, you should open a terminal and type
brew install gsl
On Linux, you should install gsl using your distribution's package manager. For example, on Ubuntu, open a terminal and type
sudo apt-get install gsl-bin libgsl0-dev
You should put the renderers in locations that you will remember. These will be your path-to-PBRT and path-to-Mitsuba.
On OS X, you might want to use these locations:
-
path-to-PBRT=/usr/local/bin -
path-to-Mitsuba=/Applications
On Linux, you might want to use these locations:
-
path-to-PBRT=/usr/local/bin -
path-to-Mitsuba=/usr/local/bin
RenderToolbox3 uses a few functions from the Psychophysics Toolbox, aka Psychtoolbox. You can download Psychtoolbox with the official instructions, or from the Psychtoolbox GitHub site.
Psychtoolbox is a large project which includes several intricate mex-functions. These might not work with all platforms, and might be difficult to build. Don't worry about these. RenderToolbox3 only uses a few .m functions and .mat data files from Psychtoolbox. These are located in the Psychtoolbox subfolders:
PsychCal/PsychColorimetric/PsychColorimetricData/PsychOneliners
Remember where you put Psychtoolbox. This will be your path-to-Psychtoolbox.
RenderTooblox3 contains an example scene called SimpleSphere, which uses the SphereRendererToolbox to validate the output of other renderers. You can find installation instructions at the SphereRendererToolbox wiki.
Once you have the RenderToolbox3 Matlab code and all the required applications and libraries, you must configure Matlab to use them.
RenderToolbox3 needs to find Matlab functions and data files, so add the following to your Matlab path, with subfolders:
path-to-RenderToolbox3path-to-Psychtoolbox
From the Matlab desktop, try File -> Set Path... -> Add with Subfolders...
You will probably end up with a lot of extra .svn and .git folders in your Matlab path. These are great for version control, but useless to Matlab. You can remove them with RenderToolbox3 CleanMatlabPath() utility. In Matlab, type:
CleanMatlabPath();
Then save your path.
Some scenes will require large amounts of Java heap memory, when they are converted from Collada to PBRT scene format.
For Matlab on Linux, increasing the heap size is easy, using the Matlab desktop preferences dialogs. From the Matlab desktop, go to:
- File
- Preferences
- General
- Java Heap Memory
- type in "1024"
- click OK
On OS X, the preferences dialogs may constrain the heap size you're allowed to choose. You can still increase the heap space using a java.opts file. Mathworks provides these instructions for making a java.opts file.
For example, on one particular Mac, running OS X 10.6.8, with Matlab version 2011a, and Java version 1.6, the java.opts file was located at /Applications/MATLAB_R2011a.app/bin/maci64/java.opts. It looked like this:
# In Java 1.5.0_13 and later on Mac OS X 10.5 (Leopard), the default
# rendering pipeline is provided by Sun. Previous versions used the Quartz
# pipeline. This change has significantly slowed down rendering for many
# interface components.
#
# Setting the following system property to true forces Java to use the
# Quartz rendering pipeline to improve rendering performance.
-Dapple.awt.graphics.UseQuartz=true
# Increase the Java heap size to accommodate large XML DOM documents
-Xmx1024m
This resulted in a heap size of 1024MB for Java in Matlab.
You can check your Java heap settings in Matlab by looking at the following values:
java.lang.Runtime.getRuntime.maxMemory
java.lang.Runtime.getRuntime.totalMemory
java.lang.Runtime.getRuntime.freeMemory
If java.lang.Runtime.getRuntime.maxMemory is close to one billion (1e9) then your heap should be big enough.
You must configure RenderToolbox3 with several "preference" values, such as where it can find the renderers and where it's allowed to write output files. RenderToolbox3 uses Matlab's getpref()/setpref() mechanism to store these values.
RenderToolbox3 contains a script that can help you set these values. It's located at
(path-to-RenderToolbox3)/Utilities/RenderToolbox3ConfigurationTemplate.m
You should copy this script to a folder that's separate from RenderToolbox3 and rename it however you want. You might call it MyRenderToolbox3ConfigurationScript.m. Then edit your copy of the script with values that are specific to your computer. These will include your path-to-PBRT and path-to-Mitsuba.
If you compiled PBRT using your own custom spectrum sampling, you should also edit the "S" value near the bottom of the script. See Spectrum Bands for more about spectral sampling and "S" values.
When you're done customizing this script, you should run it in matlab:
MyRenderToolbox3ConfigurationScript;
This will establish RenderToolbox3 preference values. You can see all the values using getpref():
renderToolbox3Prefs = getpref('RenderToolbox3')
pbrtPrefs = getpref('PBRT')
mitsubaPrefs = getpref('Mitsuba')
RenderToolbox3 uses a custom mex-function for reading images in the OpenEXR format. This allows RenderToolbox3 to read multi-spectral output images from Mitsuba.
You must build this function when you install RenderToolbox3. This requires you to install the OpenEXR library, which is free and open source.
On OS X the best way to get OpenEXR is probably to use the Homebrew package manager. Once you have Homebrew installed, you should open a terminal and type
brew install openexr
On Linux, you should install OpenEXR using your distribution's package manager. For example, on Ubuntu, open a terminal and type
sudo apt-get install libilmbase-dev libopenexr-dev
RenderToolbox3 includes a Matlab script called MakeReadMultichannelEXR, to help with building the mex-function from source. It's located at:
(path-to-RenderToolbox3)/Utilities/ReadMultispectralEXR/MakeReadMultichannelEXR.m
In Matlab, type:
cd (path-to-RenderToolbox3)/Utilities/ReadMultispectralEXR
MakeReadMultichannelEXR();
This should result in a new ReadMultichannelEXR() mex-function. It should also open a figure and display channel data from a test image, to verify that the function is working.
Note: You might need to edit the MakeReadMultichannelEXR script with so that it points to the OpenEXR installation location for your platform. Most users should be fine with the defaults (/usr/local/include/OpenEXR and /usr/local/lib).
Note: Several users have reported problems running MakeReadMultichannelEXR on recent versions of OS X (10.9 and later). OS X has been making frequent changes to its C build tools, which seems to break the configuration of the Matlab build tools. We have had some luck working around this.
- On OS X 10.9 and later it seems to help if you install OpenEXR using the Homebrew package manager. Here are some notes about how. We also have an outstanding Issue about OS X 10.9.
- On OS X 10.10 and later, you may have to manually modify the configuration of the Matlab build tools. Please see our discussion in this Issue about OS X 10.10+.
RenderToolbox3 contains a function that checks basic configuration and rendering functionality. It's located at
(path-to-RenderToolbox3)/Utilities/RenderToolbox3InstallationTest.m
If your path is configured correctly, you can run this function in Matlab:
renderResults = RenderToolbox3InstallationTest()
The function will check some preferences for sanity and try to render a few example scenes. Rendering might take a few minutes. If all goes well, you should see figures appear that contain rendered images.
The function will print messages related to sanity checks and rendering. It will also return a renderResults struct with data about rendering results.
If you need to fix errors, you can run your configuration script and this installation test as a pair:
% make changes to your configuration script
MyRenderToolbox3ConfigurationScript;
% try again
renderResults = RenderToolbox3InstallationTest()
You might wish to verify that your renderings are coming out correctly.
To help with this validation, the RenderToolbox3 team shares an archive of Reference Renderings.
You can generate example renderings locally, and compare them to the reference renderings. The CompareAllExampleScenes() function will match up pairs of multi-spectral data files: one file generated locally and one data file from the reference repository. For each pair, it can compute some comparison statistics and show a comparison visualization.
Beware: these commands may take hours to complete:
% store lots of renderings in your output data folder
renderResults = TestAllExampleScenes();
% summarize renderings in the output data folder vs reference renderings
visualize = 1;
matchInfo = CompareAllExampleScenes([], referenceRoot, '', visualize);
% look in detail at renderings from the coordinates test scene
visualize = 2;
CompareAllExampleScenes([], referenceRoot, 'CoordinatesTest', visualize);
The function will produce a summary figure with image comparison statistics. When visualize = 2, it will also show a detailed comparison figure for each pair of multi-spectral data files.
The function will also return a matchInfo struct with data about each matched pair of data files.