Compiling OpenEB on Linux
This section describes how to compile OpenEB on Linux.
Compilation and execution were tested on platforms that meet the following requirements:
Linux: Ubuntu 20.04 or 22.04 64-bit
Architecture: amd64 (a.k.a. x64)
Graphic card with support of OpenGL 3.0 minimum
CPU with support of AVX2
Compilation on other platforms (alternate Linux distributions, different versions of Ubuntu, ARM processor architecture etc.) was not tested. For those platforms some adjustments to this guide or to the code itself may be required.
Note
OpenEB is the open source version of our code base for the modules Base, Core, Core ML, Driver, UI, and HAL (see Metavision modules organization). If you acquired the full source code of the SDK (through our SDK Pro offer), OpenEB will also be the basis of your installation, but you should follow the installation guide of SDK Pro.
If you don’t want to go through some compilation steps, you can download pre-built Ubuntu packages of Metavision modules by signing-up for Metavision SDK. Once you have downloaded this version, follow our specific installation guide.
Table of Contents
Supported Cameras
OpenEB contains the source code of Prophesee camera plugins, enabling to stream data from our event-based cameras and to read recordings of event-based data. The supported cameras are:
Upgrading OpenEB
If you are upgrading OpenEB from a previous version, you should first read carefully the Release Notes as some changes may impact your usage of our SDK (e.g. API updates) and cameras (e.g. firmware update might be necessary).
Then, you need to clean your system from previously installed Prophesee software. If after a previous compilation, you chose to
deploy the Metavision files in your system path, then go to the build
folder in the source code directory and
launch the following command to remove those files:
sudo make uninstall
In addition, remove Prophesee or Metavision folders and files in your system paths (/usr/include
, /usr/lib
, /usr/bin
, /usr/share
along with their /usr/local
equivalents) and in your environment variables (PATH
, PYTHONPATH
and LD_LIBRARY_PATH
).
Installing Dependencies
Install the following dependencies:
sudo apt update
sudo apt -y install apt-utils build-essential software-properties-common wget unzip curl git cmake
sudo apt -y install libopencv-dev libboost-all-dev libusb-1.0-0-dev
sudo apt -y install libhdf5-dev hdf5-tools libglew-dev libglfw3-dev libcanberra-gtk-module ffmpeg
Optionally, if you want to run the tests, you need to install Google Gtest and Gmock packages. For more details, see Google Test User Guide :
sudo apt -y install libgtest-dev libgmock-dev
For the Python API, you will need Python and some additional libraries. If Python is not available on your system, install it. We support Python 3.8 and 3.9 on Ubuntu 20.04 and Python 3.9 and 3.10 on Ubuntu 22.04. If you want to use other versions of Python, some source code modifications will be necessary.
Then install some extra libraries:
sudo apt -y install python3-pip python3-distutils
sudo apt -y install python3.X-dev # where X is 8, 9 or 10 depending on your Python version (3.8, 3.9 or 3.10)
python3 -m pip install pip --upgrade
python3 -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" pandas scipy h5py
python3 -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner
Note
You can use anaconda to install Python and
conda to manage your Python packages, but be sure to use a Python version that we support.
You will need to adapt the library installation steps accordingly and use conda
whenever we use pip
.
In addition, check that conda PYTHONPATH
contains /usr/lib/python3/dist-packages/
. If not, add it. For example with sys.path.append()
method of python module sys
:
import sys
print(sys.path)
# Add /usr/lib/python3/dist-packages/ to PYTHONPATH if the output of print(sys.path) does not mention it.
sys.path.append("/usr/lib/python3/dist-packages/")
In this documentation, we chose to use pip as a package manager. We recommend using it with virtualenv to avoid conflicts with other installed Python packages.
The Python bindings of the C++ API rely on the pybind11 library (version >= 2.6.0).
Note
pybind11 is required only if you want to use the Python bindings of the C++ API. You can skip compiling these bindings by passing
the argument -DCOMPILE_PYTHON3_BINDINGS=OFF
during compilation (see step 3 below). This allows you to skip
installing pybind11, but you won’t be able to use our Python interface to the C++ API.
Unfortunately, there is no pre-compiled version of pybind11 available, so you need to install it manually:
wget https://github.com/pybind/pybind11/archive/v2.6.0.zip
unzip v2.6.0.zip
cd pybind11-2.6.0
mkdir build && cd build
cmake .. -DPYBIND11_TEST=OFF
cmake --build .
sudo cmake --build . --target install
To use Machine Learning features, you need to install some additional dependencies.
First, if you have some Nvidia hardware with GPUs, you can optionally install CUDA (11.6 or 11.7) and cuDNN to leverage them with PyTorch and LibTorch. Make sure that you install a version of CUDA that is compatible with your GPUs by checking Nvidia compatibility page.
Note
At the moment, we don’t support OpenCL and AMD GPUs.
Then, you will need to install PyTorch 1.13.1. Retrieve and execute the pip command of version 1.13.1 from the previous versions install guide section.
Then install some extra Python libraries:
python3 -m pip install "numba==0.56.3" "profilehooks==1.12.0" "pytorch_lightning==1.8.6" "tqdm==4.63.0" "kornia==0.6.8"
Compilation
To compile OpenEB, follow those steps:
Retrieve the source code of OpenEB and go in the created directory
git clone https://github.com/prophesee-ai/openeb.git --branch 4.1.0 cd openebIn the following sections, absolute path to this directory is called
OPENEB_SRC_DIR
Warning
If you choose to download an archive of OpenEB from GitHub rather than cloning the repository, you need to ensure that you select a
Full.Source.Code.*
archive instead of using the automatically generatedSource.Code.*
archives. This is because the latter do not include a necessary submodule.
Create and open the build directory
mkdir build && cd build
Generate the makefiles using CMake:
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
Note
If you want to specify to cmake which version of Python to consider, you should use the option
-DPython3_EXECUTABLE=<path_to_python_to_use>
. This is useful, for example, when you have a more recent version of Python than the ones we support installed on your system. In that case, cmake would select it and compilation might fail.
Compile:
cmake --build . --config Release -- -j `nproc`
Once the compilation is done, you have two options: you can choose to work directly from the build
folder
or you can deploy the OpenEB files in the system path (/usr/local/lib
, /usr/local/include
…).
Option 1 - working from
build
folder
To use OpenEB directly from the
build
folder, you need to update some environment variables using this script (which you may add to your~/.bashrc
to make it permanent):source utils/scripts/setup_env.sh
Prophesee camera plugins are included in OpenEB,
but you still need to copy the udev rules files in the system path and reload them so that your camera is detected with this command:
sudo cp <OPENEB_SRC_DIR>/hal_psee_plugins/resources/rules/*.rules /etc/udev/rules.d sudo udevadm control --reload-rules sudo udevadm triggerOption 2 - deploying in the system path
To deploy OpenEB, launch the following command:
sudo cmake --build . --target install
Note
You can also deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice by using the
CMAKE_INSTALL_PREFIX
variable (-DCMAKE_INSTALL_PREFIX=<OPENEB_INSTALL_DIR>
) when generating the makefiles in step 3. Similarly, you can configure the directory where the Python packages will be deployed using thePYTHON3_SITE_PACKAGES
variable (-DPYTHON3_SITE_PACKAGES=<PYTHON3_PACKAGES_INSTALL_DIR>
).you also need to update
LD_LIBRARY_PATH
andHDF5_PLUGIN_PATH
(which you may add to your~/.bashrc
to make it permanent):export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin
Note
If you are using a third-party camera, you need to install the plugin provided
by the camera vendor and specify the location of the plugin using the MV_HAL_PLUGIN_PATH
environment variable.
Running tests
Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process.
Go to this page to download the files necessary to run the tests. Click the
Download
button on the top right of the page. The obtained archive weighs around 1.2 Gb.Extract and put the contents of this archive into
<OPENEB_SRC_DIR>/
. For instance, the correct path of sequence gen31_timer.raw should be <OPENEB_SRC_DIR>/datasets/openeb/gen31_timer.raw.Regenerate the makefiles with the test options on. Make sure that all your pro modules were properly configured. Don’t forget to install gtest as specified here compiling OpenEB:
cd <OPENEB_SRC_DIR>/build cmake .. -DBUILD_TESTING=ON
Compile again:
cmake --build . --config Release -- -j `nproc`
Make sure you launched the
utils/scripts/setup_env.sh
mentioned before, and run the test suite:ctest -C Release
Get started!
You are now ready to use OpenEB. The best way to start getting familiar with the event-based technology is to open an event-based camera with Metavision Viewer to begin data collection and visualization. You can choose to dive directly in the SDK by following a Tutorial or looking at a Code Sample.