Installation guide#

This guide covers all steps necessary to get Eradiate running on your machine.

Warning

Eradiate currently requires a development setup, even for end-users. This has a few consequences which we hope to overcome in the future:

installing and running Eradiate requires to use the Conda package and environment manager;
installation requires many dependencies not necessarily useful to end-users;
integrating Eradiate in your workflow can be a bit constraining if you have specific requirements on package versions.

Note

If you are interested in running Eradiate with Docker, see the dedicated page.

Prerequisites#

Before cloning the Git repository and compiling the code, ensure that your machine meets the requirements listed below.

Requirement	Tested version
git	2.18+
cmake	3.22+
ninja	1.10+
clang	11+

Tested configuration

Linux

Operating system: Ubuntu Linux 20.04.1.

Requirement	Tested version
git	2.25.1
cmake	3.22.2
ninja	1.10.0
clang	11.0.0-2
libc++	11
libc++abi	11
python	3.8.12 (miniconda3)

macOS

Operating system: macOS Monterey 12.0.1.

Requirement	Tested version
git	2.32.0 (Apple Git-132)
cmake	3.22.1
ninja	1.10.2
clang	Apple clang version 13.0.0 (clang-1300.0.29.30)
python	3.8.12 (miniconda3)

Linux

All prerequisites except for conda can be installed through the usual Linux package managers. For example, using the APT package manager, which is used in most Debian-based distributions, like Ubuntu:

# Install build tools, compiler and libc++
sudo apt install -y git cmake ninja-build clang-11 libc++-11-dev libc++abi-11-dev

# Install libraries for image I/O
sudo apt install -y libpng-dev zlib1g-dev libjpeg-dev

If your Linux distribution does not include APT, please consult your package manager’s repositories for the respective packages.

If your CMake copy is not recent enough, there are many ways to install an updated version, notably through pipx and Conda. Pick your favourite!

Note

We currently recommend compiling the C++ code with Clang based on upstream advice from the Mitsuba development team. We also recommend using Clang 11 — not another version — because we also encountered issues building with other versions. We hope to improve compiler support in the future.

macOS

On macOS, you will need to install XCode, CMake, and Ninja. XCode can be installed from the App Store. Make sure that your copy of the XCode is up-to-date. CMake and Ninja can be installed with the Homebrew package manager:

brew install cmake ninja

Additionally, running the Xcode command line tools once might be necessary:

xcode-select --install

Finally, Eradiate requires a fairly recent version of Python (at least 3.8) and we highly recommend using the Conda environment and package manager to set up your Python environment. Conda can be installed notably as part of the Anaconda distribution, or using its lightweight counterpart Miniconda. See installation instructions here.

Cloning the repository#

Note

Eradiate relies on the Git source code management tool. It also depends on multiple external dependencies, some of which (e.g. its radiometric kernel based on Mitsuba 3) are directly referred to using Git submodules.

To get the code, clone the repository including its submodules with the following command:

Public branch (users)

git clone --recursive --branch public https://github.com/eradiate/eradiate

Main branch (developers)

git clone --recursive https://github.com/eradiate/eradiate

This will clone the Eradiate repository, as well as all its dependencies. This recursive cloning procedure can take up to a few minutes depending on your Internet connection.

Note

If GitHub requests credentials to access submodules through HTTPS, we highly recommend to generate a personal access token with repo permissions and to use it instead of your password. You might also have to make sure that Git will remember your token.

Setting up the Conda environment#

Eradiate ships a set of pinned Conda environment specifications in the form of lock files. They quickly set up a reproducible environment. We strongly recommend using these instead of a regular environment file since they provide an execution environment identical to the one used for development.

In the following, we will use an environment named eradiate, but this name can be changed to your liking. We will first create an empty environment:

conda create --name eradiate

Warning

If an environment with the same name exists, you will be prompted for overwrite.

This produces an empty environment, which we then activate:

conda activate eradiate

We can now navigate to the repository where we cloned the source code and execute a GNU Make target which will initialise our empty environment properly:

cd eradiate
make conda-init

Notes

This target will not create a new Conda environment; it will instead install and/or update dependencies in the currently activated one.
This target will automatically select the appropriate lock file based on the platform on which you are working. It will also install Eradiate to your environment in development mode.
In addition to installing dependencies, this target will automate environment variable setup by sourcing setpath.sh upon environment activation, following the approach recommended by the Conda user guide.
Once the Conda environment is active, the Eradiate root directory can be reached from everywhere through the $ERADIATE_SOURCE_DIR environment variable.

Once your Conda environment is configured, you should reactivate it:

conda deactivate && conda activate eradiate

Compiling the radiometric kernel#

Configure CMake for compilation:

cmake --preset default

Inspect CMake’s output to check if Clang is used as the C++ compiler. Search for lines starting with

-- Check for working C compiler: ...
-- Check for working CXX compiler: ...

If you see gcc on this line, it very likely means that CMake is not using Clang.

Inspect CMake’s output to check if your Conda environment Python is used by CMake. Search for a line starting with:

Linux

-- Found Python: /home/<username>/miniconda3/envs/eradiate/...

macOS

-- Found Python: /Users/<username>/miniconda3/envs/eradiate/...

The content of this line may vary depending on how you installed Conda. If this path points to a Python binary not associated with a Conda virtual environment, do not proceed before fixing it.

Note

You will probably see a warning saying

Created a default ‘mitsuba.conf’ configuration file. You will probably want to edit this file to specify the desired configurations before starting to compile.

This is expected: do not worry about it.

When CMake is successfully configured, you can compile the code:

cmake --build build

The compilation process can last for up to around half an hour on old machines. It completes within a few minutes on modern workstations.

Verifying the installation#

In a terminal, try and invoke the eradiate command-line interface:

eradiate show

The command should print some information to the terminal. You are now ready to use Eradiate 🙂

Uninstall#

To uninstall Eradiate from your system, simply remove the Conda environment you used to set it up and delete the directory where you cloned the code. If you followed the installation instructions, here is a possible workflow:

Activate the Conda environment and delete the Eradiate source directory:
```
conda activate eradiate
rm -rf $ERADIATE_SOURCE_DIR
```

Deactivate the Conda environment and delete it:

conda deactivate
conda env remove --name eradiate

Installation guide

Contents

Installation guide#

Prerequisites#

Cloning the repository#

Setting up the Conda environment#

Compiling the radiometric kernel#

Verifying the installation#

Uninstall#