This guide is meant to go through each step of the redner installation process. This guide is very verbose so if you're experienced with this kind of stuff, you'll likely not need this guide. In the making of this guide, we've installed redner onto Ubuntu 14.04, 16.04 and 18.04. All other distribution installations are untested so there might be small discrepancies on how things are done there. At the end of this guide, there's an appendix with random stray comments which may relate to your specific situation (we'll be updating its contents based off of common issues encountered during installation).

If you have trouble following this guide, please feel free to open up an issue and we'll try to respond as available.

• GCC and G++
• NVIDIA Graphics Driver and CUDA (Optional)
• NVIDIA Optix Ray Tracing Engine (Optional)
• CMake and CCMake
• OpenEXR
• Embree
• Python
• Python Dependencies

Redner is compiled using gcc-7 and g++-7. To check the version of GCC installed on your system, run

ls /usr/bin | grep gcc

Confirm that gcc-7.* and g++-7.* exist in this list. If not, install them. The availability of gcc-7 and g++-7 will be dependent on the distribution of your OS.

Ubuntu 18.04 LTS (bionic)

sudo apt-get install gcc-7 g++-7

Ubuntu 14.04 LTS (trusty) or Ubuntu 16.04 LTS (xenial)

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-7 g++-7

Once you've installed the correct version of GCC and G++, make sure that the default C and C++ compiler is set to this version by running:

gcc -v

If this command tells you that the version of GCC is not the same as the one you just installed, you need to update the $CC and $CXX environment variables to the new version binaries. In your ~/.bashrc or whatever your profile shell loading script is, add the following lines:

export CC = gcc-7
export CXX = g++-7

Remember to re-run your ~/.bashrc file and confirm that these variables and the default GCC version have been updated:

source ~/.bashrc
echo $CC $CXX
gcc -v

Redner compiled for with GPU options enabled benefits a major performance boost in most tasks. Although not strictly required, we highly encourage you compile redner with CUDA.

To check if you have a valid version of CUDA installed, run the following commands and make sure you do not get any errors:

nvidia-smi
nvcc --version

We have tested redner's compilation on CUDA-9 and CUDA-10. If you have another version of CUDA and there are issues with your build, we encourage you to install these versions instead.

Please follow the official installation page from the NVIDIA CUDA Toolkit Downloads page for proper installation. We tested the builds for Linux x86_64 Ubuntu 16.04 and 18.04 deb (network) installation options.

NOTE: If you're experiencing difficulty getting this method to work, please check Appendix B at the bottom of this guide for an alternative installation guide for this step.

If you're building redner with CUDA, you'll need to also install the NVIDIA Optix Ray Tracing Engine as it is a dependency for redner. Installing Optix is pretty easy as you just need to download the library and add it to your library path.

Downloading Optix requires an NVIDIA developer account. Register here. Once registered, download the Optix library. Our code has been tested on Optix 5.1 and Optix 6.0. Please note the minimum requirements for the NVIDIA Graphics Driver requirements before downloading the library.

Once downloaded, run the script:

sh <FILENAME>

Once the installer succeeds, you'll have a directory under which all the Optix related files will be extracted to. We need to add the lib64 directory under the Optix directory to your library path. For your convenience rename the Optix directory to optix and move it to a new directory called $HOME/lib or something alike. Then, run:

touch /etc/ld.so.conf.d/optix.conf
echo $HOME/lib/optix/lib64 > /etc/ld.so.conf.d/optix.conf
sudo ldconfig

TODO: confirm that running

echo $LD_LIBRARY_PATH

returns the library added to the variable

The redner project uses CMake to generate its build script. Unfortunately, the version redner requires (>=3.12) is newer than the version shipped with most Linux distros. So you'll likely need to uninstall the version provided by the package manager and build the newer version from source.

First, we need to remove the default CMake installed by your package manager:

sudo apt-get remove cmake cmake-curses-gui

We highly recommend using the CCMake GUI for CMake as there are a very large number of configuration variables that need to be specified to successfully build redner. The CMake Source repository has the build rule for CCMake, but it skips the installation if the ncurses library is not installed in your system. To install ncurses:

sudo apt-get install libncurses5-dev libncursesw5-dev

Once ncurses is installed, download the latest version of CMake and extract it:

wget https://github.com/Kitware/CMake/releases/download/v<VERSION>/cmake-<VERSION>.tar.gz
tar -xf cmake-<VERSION>.tar.gz

Please replace the <VERSION> text with the version number for the latest stable release which can be found here.

Once, extracted, go inside the directory, build and install it:

./configure
make -j8
sudo make install -j8

NOTE: You can actually configure CMake using CMake. So instead of running the ./configure script, you may run cmake .. Obviously, in this case you would want to first download and build cmake, then uninstall the old cmake, and finally install the freshly built version of CMake. This makes the configuration step significantly faster, but we kept the above instructions as is for better clarity.

Redner also has a dependency on OpenEXR for its image read/write operations. To install OpenEXR, run:

sudo apt-get install libopenexr-dev

For non-GPU graphics computations, redner uses Embree. Even if you expect to only run your code on the GPU, we still require that this is installed. It's very useful to have a non-GPU implementation of the project working for debugging.

Embree depends on two packages: GLFW (OpenGL Graphics Library Framework), TBB (Intel Thread Building Blocks) and ISPC (Intel SPMD Program Compiler). To install GLFW and TBB, run,

sudo apt-get install libglfw3-dev libtbb-dev

To Install ISPC, download it from: ispc.github.io and extract it. The relevant ISPC binary is located in: ./bin/ispc inside the root of the repository. To make this binary visible for CMake, open /etc/environment and prepend the location of the bin folder of the repository to the list of paths in /etc/environment. Don't forget the : delimiter between paths.

With the dependencies installed, we now need to download, build and install Embree. The official Embree repository has a guide on how to install it, but here's a tldr for completeness:

git clone https://github.com/embree/embree.git
mkdir embree/build
cd embree/build
ccmake ..
make -j8
sudo make install

Please change the CMAKE_INSTALL_PREFIX from /usr/local to /usr.

The redner has a PyTorch front-end interfact and links between the CUDA/C++ backend using Pybind11. Unfortunately, due to the mess that is python environments, we found it easiest to have a separate version of python built and installed from source alongside the default one shipped with your OS. If you do not do this step, you will likely have issues getting pybind11 headers be recognized when compiling.

If you do not have an installation of python-3.6 or newer, you should do this step regardless.

Source

In order to build python, we need the following dependencies installed:

sudo apt-get install build-essential libssl-dev zlib1g-dev libreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev libbz2-dev libexpat1-dev liblzma-dev libffi-dev

Once these are installed, download, extract, build and install python.

wget https://www.python.org/ftp/python/<VERSION>/Python-<VERSION>.tar.xz
tar -xf Python-<VERSION>.tar.xz
cd Python-<VERSION>
./configure --enable-optimizations
make -j8
sudo make altinstall

To confirm successful installation, run python-<VERSION> from your shell and you should get the appropriate python shell.

As mentioned earlier, redner has a PyTorch front-end. In order to satisfy all the required python dependencies for redner, it's best to use a python environment. In this guide, we use pip, but you should be able to get the same result with any other python environment tool. We'll release a conda version for this guide soon.

To make a new python environment, run:

python<VERSION> -m venv /path/to/new/virtual/environment
source /path/to/new/virtual/environment
pip install numpy scikit-image torch torchvision

Due to a dumb issue on how pip installs packages, we need to install pybind11 onto the python outside the virtual environment.

sudo pip3 install pybind11

Hopefully everything went well so you can install redner now. The installation is pretty straightforward.

mkdir build
cd build
ccmake ..
make -j8
make install

Make sure you've already activated your virtual environment before running make install. If you did all the steps above correctly, you the project should correctly compile and you should be able to run the tutorial and test scripts included inside the repository.

Installing on Debian 9.0 (stretch) was a bad idea. They don't have gcc-7 released and installing it from their experimental branch didn't really work for me: source

If you're having trouble following along this installation, here's an alternative version that doesn't use the package manager.

Remove any existing installations of NVIDIA drivers by running:

sudo apt-get purge nvidia*
sudo apt-get autoremove

Download the NVIDIA Graphics Driver:

wget http://us.download.nvidia.com/XFree86/Linux-x86_64/430.40/NVIDIA-Linux-x86_64-430.40.run

In order to build and install the new driver you'll need to install some dependencies

sudo apt-get install build-essential gcc-multilib dkms

Warning: The installation here ignores everything related to Ubuntu GUI. If this is a desktop, you should look at the source above to make sure your Ubuntu GUI does not break when you install this driver.

Once you installed the dependencies, run the installer and check your installation.

chmod +x NVIDIA-Linux-x86-64-410.72.run
sudo ./NVIDIA-Linux-x86-64-410.72.run --dkms -s
nvidia-smi