This repository contains example code for integrating the EMCA Plugin into Mitsuba.
Before compiling Mitsuba-EMCA, first compile and install the EMCA server library.
If you cannot install the library into the system-wide directories, you can instead install the library into a local prefix
and adjust the paths EMCAINCLUDE and EMCALIBDIR in the configuration files in the build folder.
First, make sure that the EMCA Server library is installed.
For compilation, have a look at the Mitsuba documentation.
If you're running Ubuntu, you can install the remaining required prerequisites using install_prerequesites_ubuntu.sh.
With the prerequisites installed, the code can be compiled on Linux using SCons: (append -jX for parallel compilation, e.g. -j8)
scons --cfg=build/config-linux-gcc.py
We have merged and extended the patch for Python 3 compatibility, so that recent versions of SCons should work as well. Let us know if any changes to the configuration files are necessary for other operating systems.
We have tested compilation on Ubuntu 20.04.
EMCA uses C++17 features (std::variant), which may make it a bit more tricky to compile.
You need a recent version of OpenEXR that compiles with C++17, e.g. version 2.3.0.
Older versions use deprecated dynamic exception specifications that will not compile.
For compiling the GUI, check the configuration for Qt5 in data/scons/qt5.py.
We have modified it for our systems, where all Qt packages start with a Qt5 prefix rather than just Qt.
To simplify compilation on modern systems, we have also replaced GLEW-mx with GLEW.
To run Mitsuba-EMCA, you need to use the command-line utility ./dist/mtsutil emca <scene.xml>.
Before running the EMCA utility, you need to add the dist folder to the LD_LIBRARY_PATH.
Otherwise, loading Mitsuba plugins will fail.
The simplest way to do this is using the setpath.sh script:
source setpath.sh
./dist/mtsutil emca <scene.xml>
You might additionally need to add the path to the EMCA Server library to the LD_LIBRARY_PATH, if it is not installed to the default location.
Make sure that your scene.xml is configured to use an integrator that is instrumented to collect data using the EMCA API.
Unless you add your own, only the integrator pathemca collects this information.
In the scene file, adjust <integrator type="path"/> to <integrator type="pathemca"/>.
All you need to do to add support for EMCA to your path tracer is to add some instrumentation code as explained in the following section.
As an example, there is a copy of the default path tracer src/integrators/path/path.cpp at src/integrators/path/pathemca.cpp with added instrumentation for collecting the data needed by the EMCA client.
When using EMCA, make sure that your integrator is instrumented accordingly.
Otherwise, you will not have access to any path data when using the client.
The EMCA utility automatically forces the use of a deterministic sampler, which is implemented in src/samplers/deterministic.cpp as a copy of the independent sampler.
At each pixel, this sampler is seeded based on the pixel location to produce repeatable outcomes.
The sampler defined in the scene's xml file is only used to determine the sample count.
The EMCA utility is implemented in src/utils/emca.cpp and interfaces with the EMCA server library and Mitsuba.
To support Mitsuba's native types, it provides a specailization of emca::DataApi defined in include/mitsuba/core/dataapimitsuba.h and implemented in src/libcore/dataapimitsuba.cpp.
The code is licensed under GNU GPLv3, see LICENSE for details.