From c14641f02f1c63aa52c6c5c02c1ba5b0176c39f8 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sat, 15 Jun 2024 21:29:00 -0400 Subject: [PATCH 01/15] Enabling a default setting for the cmake build configuration. This allows for build requirements and instructions to be incrementally added. --- CMakeLists.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index b3d914983..804e70596 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -15,6 +15,9 @@ if(NOT CMAKE_BUILD_TYPE) "Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel." FORCE) endif(NOT CMAKE_BUILD_TYPE) +option(COMPILE_PYTHON3_BINDINGS "Enable/Disable Python bindings. Python bindings are disabled by default." OFF) +option(BUILD_TESTING "Enable/Disable test applications." OFF) + cmake_minimum_required(VERSION 3.5) project(metavision VERSION 4.6.0) From ad7c956e16064dea142ebf5575f2737d324f47e9 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sun, 16 Jun 2024 00:34:48 -0400 Subject: [PATCH 02/15] Enabling Apple specific OpenGL support. The preprocessor directives used target two conditions explicitly: 1) Apple platforms NOT running Linux, and 2) platforms running Linux. No special considerations for Windows are made at this time. --- .../metavision/sdk/ui/utils/opengl_api.h | 6 ++++++ sdk/modules/ui/cpp/src/base_glfw_window.cpp | 4 ++-- sdk/modules/ui/cpp/src/base_window.cpp | 20 +++++++++++++++++-- 3 files changed, 26 insertions(+), 4 deletions(-) diff --git a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h index 200ea27bc..807dc81b7 100644 --- a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h +++ b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h @@ -21,9 +21,15 @@ inline int glewInit(void) { return GLEW_OK; } #else // OpenGL +#if defined(__APPLE__) && !defined(__linux__) +#include +#include +#include +#elif defined(__linux__) #include #include #endif +#endif // GLFW need to be included after OpenGL #include diff --git a/sdk/modules/ui/cpp/src/base_glfw_window.cpp b/sdk/modules/ui/cpp/src/base_glfw_window.cpp index 41ecbee02..7dd34c576 100644 --- a/sdk/modules/ui/cpp/src/base_glfw_window.cpp +++ b/sdk/modules/ui/cpp/src/base_glfw_window.cpp @@ -46,11 +46,11 @@ struct GLFWContext { throw std::runtime_error("Impossible to create a glfw window"); glfwMakeContextCurrent(window); - +#if defined(__linux__) if (glewInit() != GLEW_OK) { throw std::runtime_error("Impossible to initialize GL extensions with GLEW"); } - +#endif glfwWindowHint(GLFW_VISIBLE, GLFW_TRUE); glfwMakeContextCurrent(nullptr); diff --git a/sdk/modules/ui/cpp/src/base_window.cpp b/sdk/modules/ui/cpp/src/base_window.cpp index 1f92e230c..8f5fb1ae0 100644 --- a/sdk/modules/ui/cpp/src/base_window.cpp +++ b/sdk/modules/ui/cpp/src/base_window.cpp @@ -129,9 +129,13 @@ BaseWindow::BaseWindow(const std::string &title, int width, int height, RenderMo }; // clang-format on + #if defined(__APPLE__) && !defined(__linux__) + glGenVertexArraysAPPLE(1, &vertex_array_id_); + glBindVertexArrayAPPLE(vertex_array_id_); + #else glGenVertexArrays(1, &vertex_array_id_); glBindVertexArray(vertex_array_id_); - + #endif glGenBuffers(1, &vertex_buffer_); glBindBuffer(GL_ARRAY_BUFFER, vertex_buffer_); glBufferData(GL_ARRAY_BUFFER, sizeof(g_vertex_buffer_data), g_vertex_buffer_data, GL_STATIC_DRAW); @@ -143,7 +147,11 @@ BaseWindow::BaseWindow(const std::string &title, int width, int height, RenderMo glEnableVertexAttribArray(1); glBindBuffer(GL_ARRAY_BUFFER, 0); + #if defined(__APPLE__) && !defined(__linux__) + glBindVertexArrayAPPLE(0); + #else glBindVertexArray(0); + #endif glfwMakeContextCurrent(nullptr); @@ -157,7 +165,11 @@ BaseWindow::~BaseWindow() { if (glfw_window_) { glfwMakeContextCurrent(glfw_window_); glDeleteBuffers(1, &vertex_buffer_); - glDeleteVertexArrays(1, &vertex_array_id_); + #if defined(__APPLE__) && !defined(__linux__) + glDeleteVertexArraysAPPLE(1, &vertex_array_id_); + #else + glDeleteVertexArrays(1, &vertex_array_id_); + #endif glDeleteTextures(1, &tex_id_); glDeleteProgram(program_id_); } @@ -228,7 +240,11 @@ void BaseWindow::draw_background_texture() { glBindTexture(GL_TEXTURE_2D, tex_id_); + #if defined(__APPLE__) && !defined(__linux__) + glBindVertexArrayAPPLE(vertex_array_id_); + #else glBindVertexArray(vertex_array_id_); + #endif glDrawArrays(GL_TRIANGLES, 0, 6); From 736d1d4133d661a42acbf9a85ea3fdb248a8d59d Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sun, 16 Jun 2024 00:36:56 -0400 Subject: [PATCH 03/15] Updating SDK apps to use updated Boost and Protobuf methods. These changes allow the apps to be built with a wider range of compatibility in the SW dependency versions maintained among Apple and Linux based package managers. --- .../samples/metavision_player/src/main.cpp | 6 ++--- sdk/modules/driver/cpp/src/biases.cpp | 12 ++++----- sdk/modules/driver/cpp/src/camera.cpp | 25 ++++++++++--------- sdk/modules/driver/cpp/src/camera_live.cpp | 6 ++--- .../driver/cpp/src/camera_offline_generic.cpp | 3 ++- .../driver/cpp/src/camera_serialization.cpp | 4 +++ 6 files changed, 31 insertions(+), 25 deletions(-) diff --git a/sdk/modules/core/cpp/samples/metavision_player/src/main.cpp b/sdk/modules/core/cpp/samples/metavision_player/src/main.cpp index 2df869eaf..a5bfea655 100644 --- a/sdk/modules/core/cpp/samples/metavision_player/src/main.cpp +++ b/sdk/modules/core/cpp/samples/metavision_player/src/main.cpp @@ -97,15 +97,15 @@ bool parse_command_line(int argc, const char *argv[], Parameters &app_params) { } // Check extension of provided output files - if (boost::filesystem::extension(app_params.out_bias_file) != ".bias") { + if (boost::filesystem::path(app_params.out_bias_file).extension() != ".bias") { MV_LOG_ERROR() << "Wrong extension for provided output bias file: supported extension is '.bias'"; return false; } - if (boost::filesystem::extension(app_params.out_png_file) != ".png") { + if (boost::filesystem::path(app_params.out_png_file).extension() != ".png") { MV_LOG_ERROR() << "Wrong extension for provided output PNG file: supported extension is '.png'"; return false; } - if (boost::filesystem::extension(app_params.out_avi_file) != ".avi") { + if (boost::filesystem::path(app_params.out_avi_file).extension() != ".avi") { MV_LOG_ERROR() << "Wrong extension for provided output AVI file: supported extension is '.avi'"; return false; } diff --git a/sdk/modules/driver/cpp/src/biases.cpp b/sdk/modules/driver/cpp/src/biases.cpp index 13b1dbb90..064fa02d7 100644 --- a/sdk/modules/driver/cpp/src/biases.cpp +++ b/sdk/modules/driver/cpp/src/biases.cpp @@ -31,12 +31,12 @@ Biases::~Biases() {} void Biases::set_from_file(const std::string &biases_filename) { // Check extension - const auto extension = boost::filesystem::extension(biases_filename); - if (extension != ".bias") { + const boost::filesystem::path biases_file_path = biases_filename; + if (biases_file_path.extension() != ".bias") { throw CameraException(CameraErrorCode::WrongExtension, "For bias file '" + biases_filename + "' : expected '.bias' extension to set the bias from this file but got '." + - extension + "'"); + biases_file_path.extension().generic_string() + "'"); } // open file @@ -106,12 +106,12 @@ void Biases::set_from_file(const std::string &biases_filename) { } void Biases::save_to_file(const std::string &dest_file) const { - const auto extension = boost::filesystem::extension(dest_file); - if (extension != ".bias") { + const boost::filesystem::path biases_file_path = dest_file; + if (biases_file_path.extension() != ".bias") { throw CameraException(CameraErrorCode::WrongExtension, "For bias file '" + dest_file + "' : expected '.bias' extension to set the bias from this file but got '." + - extension + "'"); + biases_file_path.extension().generic_string() + "'"); } std::ofstream output_file(dest_file); diff --git a/sdk/modules/driver/cpp/src/camera.cpp b/sdk/modules/driver/cpp/src/camera.cpp index 2de3893d7..25c604ca2 100644 --- a/sdk/modules/driver/cpp/src/camera.cpp +++ b/sdk/modules/driver/cpp/src/camera.cpp @@ -284,18 +284,18 @@ bool Camera::Private::process_impl() { } bool Camera::Private::start_recording_impl(const std::string &file_path) { - std::string ext = boost::filesystem::extension(file_path); + boost::filesystem::path path_obj(file_path); std::shared_ptr writer; - if (ext == ".raw") { + if (path_obj.extension() == ".raw") { writer = std::make_shared(file_path); - } else if (ext == ".hdf5") { + } else if (path_obj.extension() == ".hdf5") { writer = std::make_shared(file_path); } else { throw CameraException(CameraErrorCode::WrongExtension, - "Unsupported extension for the recording destination " + file_path + "."); + "Unsupported extension for the recording destination " + path_obj.string() + "."); } writer->add_metadata_map_from_camera(*pub_ptr_); - if (ext == ".raw") { + if (path_obj.extension() == ".raw") { if (!raw_data_) { throw CameraException(UnsupportedFeatureErrors::RawRecordingUnavailable, "Cannot record to a RAW file from this type of camera."); @@ -513,24 +513,25 @@ Camera Camera::from_serial(const std::string &serial, const DeviceConfig &config } Camera Camera::from_file(const std::string &file_path, const FileConfigHints &hints) { - if (boost::filesystem::extension(file_path) != "") { - if (!boost::filesystem::exists(file_path)) { + boost::filesystem::path path_obj(file_path); + if (path_obj.has_extension()) { + if (!boost::filesystem::exists(path_obj)) { throw CameraException(CameraErrorCode::FileDoesNotExist, - "Opening file at " + file_path + ": not an existing file."); + "Opening file at " + path_obj.string() + ": not an existing file."); } - if (!boost::filesystem::is_regular_file(file_path)) { + if (!boost::filesystem::is_regular_file(path_obj)) { throw CameraException(CameraErrorCode::NotARegularFile); } } - if (boost::filesystem::extension(file_path) == ".raw") { + if (path_obj.extension() == ".raw") { return Camera(new detail::OfflineRawPrivate(file_path, hints)); - } else if (boost::filesystem::extension(file_path) == ".hdf5") { + } else if (path_obj.extension() == ".hdf5") { #if defined HAS_HDF5 return Camera(new detail::OfflineGenericPrivate(file_path, hints)); #endif - } else if (boost::filesystem::extension(file_path) == ".dat" || boost::filesystem::extension(file_path) == "") { + } else if (path_obj.extension() == ".dat" || path_obj.extension() == "") { return Camera(new detail::OfflineGenericPrivate(file_path, hints)); } diff --git a/sdk/modules/driver/cpp/src/camera_live.cpp b/sdk/modules/driver/cpp/src/camera_live.cpp index ad81a75a1..ee50d25ef 100644 --- a/sdk/modules/driver/cpp/src/camera_live.cpp +++ b/sdk/modules/driver/cpp/src/camera_live.cpp @@ -206,11 +206,11 @@ bool LivePrivate::process_impl(TimingProfilerType *profiler) { } bool LivePrivate::start_recording_impl(const std::string &file_path) { - std::string base_path = boost::filesystem::change_extension(file_path, "").string(); + boost::filesystem::path path_obj(file_path); if (biases_) { - biases_->save_to_file(base_path + ".bias"); + biases_->save_to_file(path_obj.filename().string() + ".bias"); } - return Camera::Private::start_recording_impl(file_path); + return Camera::Private::start_recording_impl(path_obj.filename().string()); } void LivePrivate::save(std::ostream &os) const { diff --git a/sdk/modules/driver/cpp/src/camera_offline_generic.cpp b/sdk/modules/driver/cpp/src/camera_offline_generic.cpp index d5e30a5cd..4715cbeab 100644 --- a/sdk/modules/driver/cpp/src/camera_offline_generic.cpp +++ b/sdk/modules/driver/cpp/src/camera_offline_generic.cpp @@ -43,7 +43,8 @@ OfflineGenericPrivate::OfflineGenericPrivate(const std::string &file_path, const Private(detail::Config()) { // clang-format off try { - if (boost::filesystem::extension(file_path) == ".hdf5") { + boost::filesystem::path path_obj(file_path); + if (path_obj.extension() == ".hdf5") { file_reader_ = std::make_unique(file_path, hints.time_shift()); } else { file_reader_ = std::make_unique(file_path); diff --git a/sdk/modules/driver/cpp/src/camera_serialization.cpp b/sdk/modules/driver/cpp/src/camera_serialization.cpp index b62e3560c..4a3e1f914 100644 --- a/sdk/modules/driver/cpp/src/camera_serialization.cpp +++ b/sdk/modules/driver/cpp/src/camera_serialization.cpp @@ -655,7 +655,11 @@ std::ostream &save_device(const Device &d, std::ostream &os) { google::protobuf::util::JsonPrintOptions options; options.add_whitespace = true; + #if (GOOGLE_PROTOBUF_VERSION >= 5027000) + options.always_print_fields_with_no_presence = true; + #else options.always_print_primitive_fields = true; + #endif options.preserve_proto_field_names = true; std::string json; From 1c9c4e4bd4279cae61db41f22efd1848621f87ca Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sun, 16 Jun 2024 00:46:43 -0400 Subject: [PATCH 04/15] Updating repo documentation. --- README.md | 479 +----------------- .../linux-build-test-and-installation.md | 188 +++++++ .../macos-build-test-and-installation.md.md | 175 +++++++ .../windows-build-test-and-installation.md.md | 260 ++++++++++ 4 files changed, 643 insertions(+), 459 deletions(-) create mode 100644 docs/build-and-installation-guides/linux-build-test-and-installation.md create mode 100644 docs/build-and-installation-guides/macos-build-test-and-installation.md.md create mode 100644 docs/build-and-installation-guides/windows-build-test-and-installation.md.md diff --git a/README.md b/README.md index aa2ff55b7..f2e54fb4e 100644 --- a/README.md +++ b/README.md @@ -7,472 +7,33 @@ their own applications or camera plugins. As a camera manufacturer, ensure your event-based software suite available by building your own plugin. As a creator, scientist, academic, join and contribute to the fast-growing event-based vision community. -OpenEB is composed of the [Open modules of Metavision SDK](https://docs.prophesee.ai/stable/modules.html#chapter-modules-and-packaging-open): -* HAL: Hardware Abstraction Layer to operate any event-based vision device. -* Base: Foundations and common definitions of event-based applications. -* Core: Generic algorithms for visualization, event stream manipulation, applicative pipeline generation. -* Core ML: Generic functions for Machine Learning, event_to_video and video_to_event pipelines. -* Driver: High-level abstraction built on the top of HAL to easily interact with event-based cameras. -* UI: Viewer and display controllers for event-based data. +OpenEB is composed of the [Metavision SDK Open Modules](https://docs.prophesee.ai/stable/modules.html#chapter-modules-and-packaging-open): +* **HAL**: Hardware Abstraction Layer to operate any event-based vision device. +* **Base**: Foundations and common definitions of event-based applications. +* **Core**: Generic algorithms for visualization, event stream manipulation, applicative pipeline generation. +* **Core ML**: Generic functions for Machine Learning, event_to_video and video_to_event pipelines. +* **Driver**: High-level abstraction built on the top of HAL to easily interact with event-based cameras. +* **UI**: Viewer and display controllers for event-based data. -OpenEB also contains the source code of [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html), -enabling to stream data from our event-based cameras and to read recordings of event-based data. -The supported cameras are: +OpenEB also contains the source code for [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html) which allow applications to handle I/O operations. Once enabled, applications can stream data from event-cameras, as well as read and playback event recordings. + +## Supported Cameras * EVK2 - HD * EVK3 - VGA/320/HD * EVK4 - HD -This document describes how to compile and install the OpenEB codebase. -For further information, refer to our [online documentation](https://docs.prophesee.ai/) where you will find -some [tutorials](https://docs.prophesee.ai/stable/tutorials/index.html) to get you started in C++ or Python, -some [samples](https://docs.prophesee.ai/stable/samples.html) to discover how to use -[our API](https://docs.prophesee.ai/stable/api.html) and a more detailed -[description of our modules and packaging](https://docs.prophesee.ai/stable/modules.html). - - -## Compiling 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](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#CPUs_with_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. - - -### Upgrading OpenEB - -If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) -as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) -and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) 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: - -```bash -sudo make uninstall -``` - -In addition, make a global check in your system paths (`/usr/lib`, `/usr/local/lib`, `/usr/include`, `/usr/local/include`) -and in your environment variables (`PATH`, `PYTHONPATH` and `LD_LIBRARY_PATH`) to remove occurrences of Prophesee or Metavision files. - -### Prerequisites - -Install the following dependencies: - -```bash -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 libprotobuf-dev protobuf-compiler -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](https://google.github.io/googletest/): - -```bash -sudo apt -y install libgtest-dev libgmock-dev -``` - -For the [Python API](https://docs.prophesee.ai/stable/api/python/index.html#chapter-api-python), 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 `pip` and some Python libraries: -```bash -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" "h5py==3.7.0" pandas scipy -python3 -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner -``` - -The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library, specifically version 2.6.0. - -*Note* that pybind11 is required only if you want to use the Python bindings of the C++ API . -You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 3 during compilation (see below). -In that case, you will not need to install 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: - -```bash -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)](https://developer.nvidia.com/cuda-downloads) -and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) 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](https://docs.nvidia.com/deeplearning/cudnn/support-matrix/index.html). - -Note that, at the moment, we don't support [OpenCL](https://www.khronos.org/opencl/) and AMD GPUs. - -Then, you need to install [PyTorch 1.13.1](https://pytorch.org). -Retrieve and execute the pip command of version 1.13.1 from -the [previous versions install guide section](). - -Then install some extra Python libraries: - -```bash -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 - - 1. Retrieve the code: `git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0`. - (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 generated ``Source.Code.*`` archives. This is because the latter do not include - a necessary submodule.) - 2. Create and open the build directory in the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections): `cd openeb; mkdir build && cd build` - 3. Generate the makefiles using CMake: `cmake .. -DBUILD_TESTING=OFF`. - If you want to specify to cmake which version of Python to consider, you should use the option ``-DPython3_EXECUTABLE=``. - 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. - 4. Compile: `cmake --build . --config Release -- -j 4` - -Once the compilation is finished, 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): - - ```bash - source utils/scripts/setup_env.sh - ``` - - * [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html) 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: - - ```bash - sudo cp /hal_psee_plugins/resources/rules/*.rules /etc/udev/rules.d - sudo udevadm control --reload-rules - sudo udevadm trigger - ``` - -* Option 2 - deploying in the system path - - * To deploy OpenEB, launch the following command: - - ```bash - sudo cmake --build . --target install - ``` - - Note that 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=`) when generating the makefiles - in step 3. Similarly, you can configure the directory where the Python packages will be deployed using the - `PYTHON3_SITE_PACKAGES` variable (`-DPYTHON3_SITE_PACKAGES=`). - - * you also need to update `LD_LIBRARY_PATH` and `HDF5_PLUGIN_PATH` - (which you may add to your `~/.bashrc` to make it permanent): - - ```bash - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 - ``` - -Note that 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. - -To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) -and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) -or you can stream data from your Prophesee-compatible event-based camera. - -### Running the test suite (Optional) - -Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. - - * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. - Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. - - * Extract and put the content of this archive to `/datasets`. - For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. - - * Regenerate the makefiles with the test options enabled: - - ```bash - cd /build - cmake .. -DBUILD_TESTING=ON - ``` - - * Compile again. `cmake --build . --config Release -- -j 4` - - * Finally, run the test suite: `ctest --verbose` - -## Compiling on Windows - -Currently, we support only Windows 10. -Compilation on other versions of Windows was not tested. -For those platforms some adjustments to this guide or to the code itself may be required. - -### Upgrading OpenEB - -If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) -as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) -and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) might be necessary). - -Then, if you have previously installed any Prophesee's software, you will need to uninstall it first. -Remove the folders where you installed Metavision artifacts (check both the `build` folder of the source code and -`C:\Program Files\Prophesee` which is the default install path of the deployment step). - -### Prerequisites - -Some steps of this procedure don't work on FAT32 and exFAT file system. -Hence, make sure that you are using a NTFS file system before going further. - -You must enable the support for long paths: - * Hit the Windows key, type gpedit.msc and press Enter - * Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem - * Double-click the "Enable Win32 long paths" option, select the "Enabled" option and click "OK" - -To compile OpenEB, you will need to install some extra tools: - - * install [git](https://git-scm.com/download/win) - * install [CMake 3.21](https://cmake.org/files/v3.21/cmake-3.21.7-windows-x86_64.msi) - * install Microsoft C++ compiler (64-bit). You can choose one of the following solutions: - * For building only, you can install MS Build Tools (free, part of Windows 10 SDK package) - * Download and run ["Build tools for Visual Studio 2022" installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) - * Select "C++ build tools", make sure Windows 10 SDK is checked, and add English Language Pack - * For development, you can also download and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) - * install [vcpkg](https://github.com/microsoft/vcpkg) that will be used for installing dependencies: - * download and extract [vcpkg version 2023.11.20](https://github.com/microsoft/vcpkg/archive/refs/tags/2023.11.20.zip) - * `cd ` - * `bootstrap-vcpkg.bat` - * install the libraries by running `vcpkg.exe install --triplet x64-windows libusb boost opencv dirent gtest glew glfw3 hdf5[cpp,threadsafe,tools,zlib]` - * Finally, download and install [ffmpeg](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z) and add the `bin` directory to your PATH. - -Note that if you are using vcpkg for various projects or multiple versions of OpenEB, you might want to optimize the -number of vcpkg install you manage. To do so, you will need the versions of the libraries we require. -Those can be found in the [vcpkg repository](https://github.com/microsoft/vcpkg/tree/2023.11.20/versions) but we list them here for convenience: - * libusb: 1.0.26 - * boost: 1.83.0 - * opencv: 4.8.0 - * dirent: 1.24.0 - * gtest: 1.14.0 - * glew: 2.2.0 - * glfw3: 3.3.8 - * hdf5: 1.14.2 - -#### Installing Python and libraries - -* Download "Windows x86-64 executable installer" for one of these Python versions: - * [Python 3.8](https://www.python.org/downloads/release/python-3810/) - * [Python 3.9](https://www.python.org/downloads/release/python-3913/) -* Add Python install and script directories in your `PATH` and make sure they are listed before - the `WindowsApps` folder which contains a Python alias launching the Microsoft Store. So, if you installed - Python 3.8 in the default path, your user `PATH` should contain those three lines in that order: - -```bash -%USERPROFILE%\AppData\Local\Programs\Python\Python38 -%USERPROFILE%\AppData\Local\Programs\Python\Python38\Scripts -%USERPROFILE%\AppData\Local\Microsoft\WindowsApps -```` - -Then install `pip` and some Python libraries: - -```bash -python -m pip install pip --upgrade -python -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" "h5py==3.7.0" pandas scipy -python -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner -``` - -#### Install pybind - -The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library. -You should install pybind using vcpkg in order to get the appropriate version: `vcpkg.exe install --triplet x64-windows pybind11` - -*Note* that pybind11 is required only if you plan to use the Python bindings of the C++ API. -You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 2 during compilation (see section "Compilation using CMake"). -In that case, you will not need to install pybind11, but you won't be able to use our Python interface to the C++ API. - -#### Prerequisites for the ML module - -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)](https://developer.nvidia.com/cuda-downloads) -and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) to leverage them with pytorch and libtorch. - -Then, you need to install [PyTorch 1.13.1](https://pytorch.org). -Retrieve and execute the pip command of version 1.13.1 from -the [previous versions install guide section](). - -Then install some extra Python libraries: - -```bash -python -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 - -First, retrieve the codebase: - -```bash -git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0 -``` - -Note that 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 generated ``Source.Code.*`` archives. This is because the latter do not include -a necessary submodule. - - -#### Compilation using CMake - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the makefiles using CMake: `cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=`. - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Compile: `cmake --build . --config Release --parallel 4` - -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 (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update some environment variables using this script: - - ```bash - utils\scripts\setup_env.bat - ``` - -* Option 2 - deploying in a directory of your choice - - * To deploy SDK Pro in the default folder (`C:\Program Files\Prophesee`), execute this command - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --target install - ``` - - * To deploy OpenEB in another folder, you should generate the solution again (step 2 above) - with the additional variable `CMAKE_INSTALL_PREFIX` having the value of your target folder (`OPENEB_INSTALL_DIR`). - - Similarly, to specify where the Python packages will be deployed (``PYTHON3_PACKAGES_INSTALL_DIR``), you should use - the `PYTHON3_SITE_PACKAGES` variable. - - Here is an example of a command customizing those two folders: - - ```bash - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DCMAKE_INSTALL_PREFIX= -DPYTHON3_SITE_PACKAGES= -DBUILD_TESTING=OFF - ``` - - After this command, you should launch the actual compilation and installation of OpenEB - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --parallel 4 - cmake --build . --config Release --target install - ``` - - * You also need to manually edit some environment variables: - - * append `\bin` to `PATH` (`C:\Program Files\Prophesee\bin` if you used default configuration) - * append `\lib\metavision\hal\plugins` to `MV_HAL_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\metavision\hal\plugins` if you used default configuration) - * append `\lib\hdf5\plugin` to `HDF5_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\hdf5\plugin` if you used default configuration) - * append `` to `PYTHONPATH` (not needed if you used default configuration) - - -#### Compilation using MS Visual Studio - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the Visual Studio files using CMake: `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=` (adapt to your Visual Studio version). - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - -Once the compilation is done, you can choose to work directly from the `build` folder -or you can deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from the `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update the environment variables as done in the script `utils\scripts\setup_env.bat` - -* Option 2 - deploying OpenEB - - * To deploy OpenEB, you need to build the `INSTALL` project. - By default, files will be deployed in `C:\Program Files\Prophesee` - - -#### Camera Plugins - -Prophesee camera plugins are included in OpenEB, but you need to install the drivers -for the cameras to be available on Windows. To do so, follow this procedure: - -1. download [wdi-simple.exe from our file server](https://kdrive.infomaniak.com/app/share/975517/4f59e852-af5e-4e00-90fc-f213aad20edd) -2. execute the following commands in a Command Prompt launched as an administrator: - -```bash -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f4 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f5 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f3 -``` - -If you own an EVK2 or an RDK2, there are a few additional steps to complete that are detailed in our online documentation -in the [Camera Plugin section of the OpenEB install guide](https://docs.prophesee.ai/stable/installation/windows_openeb.html#camera-plugins). - -If you are using a third-party camera, you need to follow the instructions provided by the camera vendor -to install the driver and the camera plugin. Make sure that you reference the location of the plugin in -the `MV_HAL_PLUGIN_PATH` environment variable. - - -#### Getting Started - -To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) -and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) -or you can stream data from your Prophesee-compatible event-based camera. - - -### Running the test suite (Optional) - -Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. - - * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. - Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. - - * Extract and put the content of this archive to `/datasets`. - For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. - - * To run the test suite you need to reconfigure your build environment using CMake and to recompile - - - * Compilation using CMake - - 1. Regenerate the build using CMake (note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one):: - - ``` - cd /build - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON - ``` - 2. Compile: `cmake --build . --config Release --parallel 4` - +## Build, Test, and Install OpenEB +Follow the links below to find the build and installation guide for your OS. - * Compilation using MS Visual Studio +- [**Linux**](./docs/build-and-installation-guides/linux-build-test-and-installation.md) +- [**MacOS**](./docs/build-and-installation-guides/macos-build-test-and-installation.md.md) +- [**Windows**](./docs/build-and-installation-guides/windows-build-test-and-installation.md.md) - 1. Generate the Visual Studio files using CMake (adapt the command to your Visual Studio version and note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one): +## Additional Resources +- [**Metavision SDK Docs**](https://docs.prophesee.ai/stable/index.html) +- [**Get started** guides for C++ and Python](https://docs.prophesee.ai/stable/get_started/index.html) +- [**Code samples** for API best practices](https://docs.prophesee.ai/stable/samples.html) +- [**Technical details** regarding modules and packaging](https://docs.prophesee.ai/stable/modules.html) - `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON` - 2. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - * Running the test suite is then simply `ctest -C Release` diff --git a/docs/build-and-installation-guides/linux-build-test-and-installation.md b/docs/build-and-installation-guides/linux-build-test-and-installation.md new file mode 100644 index 000000000..2979a5a8a --- /dev/null +++ b/docs/build-and-installation-guides/linux-build-test-and-installation.md @@ -0,0 +1,188 @@ +# OpenEB Linux Build, Test, and Installation Guide +**In this guide** +- [Tested Configurations](#tested-configurations) +- [Build OpenEB C++ Binaries from Source](#build-and-install-openeb-binaries) +- [Install Python API Requirements](#install-python-api-requirements) +- [Upgrade OpenEB](#upgrade-openeb) + +## Tested Configurations +| Component | Configuration | +|-----------|----------| +| **OS** | Ubuntu 20.04 64-bit
Ubuntu 22.04 64-bit| +| **Architecture** | x64| +| **CPU** | with AVX2 support| +| **GPU** | with OpenGL +3.0 support +| **[Python3.8](https://www.python.org/downloads/release/python-3819/)**
**[Python3.9](https://www.python.org/downloads/release/python-3919/)** | Ubuntu 20.04 64-bit | +| **[Python3.9](https://www.python.org/downloads/release/python-3919/)**
**[Python3.10](https://www.python.org/downloads/release/python-31014/)** | Ubuntu 22.04 64-bit | + +Building OpenEB with component configurations other than what is listed above may require adjustments to this guide, or to the code itself. + +## Software Requirements +1. Run the command below to make sure you have the appropriate resources to use the Python API and build OpenEB binaries on your machine. + ```bash + sudo apt -y install \ + software-properties-common \ + libboost-all-dev \ + build-essential \ + libcanberra-gtk-module \ + cmake \ + ffmpeg \ + git \ + libglew-dev \ + libglfw3-dev \ + libhdf5-dev \ + hdf5-tools \ + libopencv-dev \ + libprotobuf-dev \ + protobuf-compiler \ + libusb-1.0-0-dev \ + unzip \ + apt-utils \ + wget + ``` +1. If you'll be using the Python API, Python bindings for C++, or and of the test applications, install Python3 as well. + ```bash + sudo apt -y install \ + python3.x \ + python3.x-dev \ + python3.x-distutils \ + python3.x-venv \ + python3-pip \ + python3-setuptools + ``` + > **Note**: *For externally managed environments, activate a Python virtual environment and use it for all subsequent installation and build instructions.* + - Navigate to your development area and activate a Python virtual environment. + ```console + python3 -m venv .venv && \ + source .venv/bin/activate + ``` +1. Retrieve the latest OpenEB source, or your desired branch, and navigate into the project folder. + ```bash + git clone https://github.com/prophesee-ai/openeb.git && cd openeb + ``` +1. Once inside your OpenEB directory, create an environment variable to reference that location. + ```bash + export OPENEB_SRC_DIR=`pwd` + ``` +## Build OpenEB C++ Binaries from Source +### Initial Setup and Build Configuration +1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. +1. Create a build folder for the project files and navigate into the folder. + ```bash + mkdir build && cd build + ``` +1. Use CMake to create the build files for OpenEB. + ```bash + cmake .. + ``` + +#### Additional Build Configurations +When you build OpenEB you have the option to: +1. Enable/Disable test applications +1. Enable/Disable Python binding for C++ +1. Change the build type (`Release`, `Debug`, ect.) + +By default, test applications and Python C++ bindings are disabled. However, you can control them by using the CMake configuration options given in the table below. + +| Build Description | CMake Configuration Option | +|-------------------|----------------------------| +| **Enable Test Applications** | `-DBUILD_TESTING=ON` | +| **Enable Python Bindings** | `-DCOMPILE_PYTHON3_BINDINGS=ON` | +| **Change the build type** | `-DCMAKE_BUILD_TYPE=`| + +Once you've completed the requirements for +any of the additional build configurations, use the option flags individually, or together, to enable the features you desire. + +##### Test Applications +1. Complete steps 1→4 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Install the Google Test and `pytest` dependencies. + ```bash + sudo apt -y install \ + libgtest-dev \ + libgmock-dev \ + python3-pytest + ``` +1. Download the test files and place them in your OpenEB source directory using the command below. + ```bash + wget https://kdrive.infomaniak.com/2/app/975517/share/cddcc78a-3480-420f-bc19-17d5b0535ca4/archive/1aa2f344-7856-4f29-bd6a-21d7d78762bd/download -O /tmp/open-test-dataset.zip && \ + unzip /tmp/open-test-dataset.zip -d ${OPENEB_SRC_DIR}/datasets &&\ + rm /tmp/open-test-dataset.zip + ``` + > **NOTE**: *The total download file size is ~1.4GB.* +1. Enable the test applications using the CMake command and options below. + ```bash + cmake --fresh .. -DBUILD_TESTING=ON + ``` + +##### Python Bindings for C++ +1. Complete steps 1→3 for the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Install pybind11. + ```bash + sudo apt -y install python3-pybind11 + ``` +1. Enable the Python bindings using the CMake command and options below. + ```bash + cmake --fresh .. -DCOMPILE_PYTHON3_BINDINGS=ON + ``` + +### Build, Test, and Install OpenEB Binaries +1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. +1. Build OpenEB on your machine. + ```bash + cmake --build . -j4 + ``` +1. **[Optional]** If testing was enabled in your build, you can now run the test suite. + ```bash + ctest --verbose + ``` +1. Install OpenEB. + - Use CMake to make the system path the installation target. + ```bash + sudo cmake --build . --target install + ``` + - Set an alternative installation target. + ```bash + sudo cmake --build . --target install -DCMAKE_INSTALL_PREFIX= + ``` +1. Update the necessary environment variables. + ```bash + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 + ``` + +## Install Python API Requirements +> **Note**: *Use of the Python API requires specific versions of Python. Refer to the [Tested Configurations](#tested-configurations) table to determine the version of Python that best suites your application needs.* + +1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. +1. Install the additional library dependencies using the requirements file. + ```bash + pip3 install -r ${OPENEB_SRC_DIR}/utils/python/requirements.txt + ``` +### Python API Machine Learning Requirements +Additional hardware, third-party software, and Python packages are required for using OpenEB machine learning (ML) features. +1. Follow all steps for [installing the Python API requirements](#install-python-api-requirements). +1. Ensure that your machine has, or is capable of running an Nvidia GPU that supports: + - [CUDA +11.6](https://developer.nvidia.com/cuda-downloads) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) + +1. Install the required [CUDA](https://developer.nvidia.com/cuda-downloads) and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) components once the hardware requirements are met. +1. Install [PyTorch +1.13.1](https://pytorch.org/get-started/locally/). +1. Install the additional Python packages for ML features. + ```bash + pip3 install -r ${OPENEB_SRC_DIR}/utils/python/ml-requirements.txt + ``` + > **Note**: *If you are using an externally managed environment, install the Python packages within your virtual environment* + + +## Upgrade OpenEB +To upgrade and existing installation of OpenEB: +1. Refer to our [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) before performing any upgrades to your existing OpenEB installation. +This will help you navigate changes such as API and firmware updates that can impact applications using the Metavision SDK and event-cameras. +1. Remove the previously installed OpenEB software. + ```bash + sudo make uninstall + ``` +1. Remove any remaining OpenEB files from your system's `PATH` and other environment variable locations (`PYTHONPATH` and `LD_LIBRARY_PATH`). +1. Follow the instructions to [build](#build-openeb-c-binaries-from-source) and [install](#install-openeb) OpenEB. + diff --git a/docs/build-and-installation-guides/macos-build-test-and-installation.md.md b/docs/build-and-installation-guides/macos-build-test-and-installation.md.md new file mode 100644 index 000000000..b53c61915 --- /dev/null +++ b/docs/build-and-installation-guides/macos-build-test-and-installation.md.md @@ -0,0 +1,175 @@ +# OpenEB MacOS Build, Test, and Installation Guide +**In this guide** +- [Tested Configurations](#tested-configurations) +- [Build OpenEB C++ Binaries from Source](#build-and-install-openeb-binaries) +- [Install Python API Requirements](#install-python-api-requirements) +- [Upgrade OpenEB](#upgrade-openeb) + +## Tested Configurations +| Component | Configuration | +|-----------|----------| +| **OS** | Monterey | +| **Architecture** | x64 | +| **CPU** | with AVX2 support | +| **GPU** | with OpenGL +3.0 support +| **[Python3.8](https://www.python.org/downloads/release/python-3819/)**
**[Python3.9](https://www.python.org/downloads/release/python-3919/)** | Ubuntu 20.04 64-bit | +| **[Python3.9](https://www.python.org/downloads/release/python-3919/)**
**[Python3.10](https://www.python.org/downloads/release/python-31014/)** | Ubuntu 22.04 64-bit | + +Building OpenEB with component configurations other than what is listed above may require adjustments to this guide, or to the code itself. + +## Software Requirements +This guide uses [Homebrew](https://brew.sh/) formulae to retrieve packages. It also requires that you have a working [C++ compiler](https://developer.apple.com/xcode/cpp/). +1. Run the command below to make sure you have the appropriate resources to use the build OpenEB binaries on your machine. + ```console + brew install \ + boost \ + cmake \ + eigen \ + ffmpeg \ + git \ + glew \ + glfw \ + hdf5 \ + opencv \ + protobuf \ + libusb + ``` +1. If you'll be using the Python API, Python bindings for C++, or and of the test applications, install Python3 as well. + ```console + brew install python3 + ``` + + > **Note**: *For externally managed environments, activate a Python virtual environment and use it for subsequent installation and build instructions.* + - Navigate to your development area and activate a Python virtual environment. + ```console + python3 -m venv .venv && \ + source .venv/bin/activate + ``` +1. Retrieve the latest [OpenEB source](https://github.com/emsight/openeb), or your desired branch, and navigate into the project folder. + ```console + git clone https://github.com/emsight/openeb.git && cd openeb + ``` +1. Once inside your OpenEB directory, create an environment variable to reference that location. + ```console + export OPENEB_SRC_DIR=`pwd` + ``` +## Build OpenEB C++ Binaries from Source +### Initial Setup and Build Configuration +1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. +1. Create a build folder for the project files and navigate into the folder. + ```console + mkdir build && cd build + ``` +1. Use CMake to create the build files for OpenEB. + ```console + cmake .. + ``` + +#### Additional Build Configurations +When you build OpenEB you have the option to: +1. Enable/Disable test applications +1. Enable/Disable Python binding for C++ +1. Change the build type (`Release`, `Debug`, ect.) + +By default, test applications and Python C++ bindings are disabled. However, you can control them by using the CMake configuration options given in the table below. + +| Build Description | CMake Configuration Option | +|-------------------|----------------------------| +| **Enable Test Applications** | `-DBUILD_TESTING=ON` | +| **Enable Python Bindings** | `-DCOMPILE_PYTHON3_BINDINGS=ON` | +| **Change the build type** | `-DCMAKE_BUILD_TYPE=`| + +Once you've completed the requirements for +any of the additional build configurations, use the option flags individually, or together, to enable the features you desire. + +##### Test Applications +1. Complete steps 1→4 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Install the Google Test and `pytest` dependencies. + ```console + brew install googletest && \ + pip3 install pytest + ``` +1. Download the test files and place them in your OpenEB source directory using the command below. + ```console + wget https://kdrive.infomaniak.com/2/app/975517/share/cddcc78a-3480-420f-bc19-17d5b0535ca4/archive/1aa2f344-7856-4f29-bd6a-21d7d78762bd/download -O /tmp/open-test-dataset.zip && \ + unzip /tmp/open-test-dataset.zip -d ${OPENEB_SRC_DIR}/datasets &&\ + rm /tmp/open-test-dataset.zip + ``` + > **NOTE**: *The total download file size is ~1.4GB.* +1. Enable the test applications using the CMake command and options below. + ```console + cmake --fresh .. -DBUILD_TESTING=ON + ``` + +##### Python Bindings for C++ +1. Complete steps 1→4 for the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Install pybind11. + ```console + brew install pybind11 + ``` +1. Enable the Python bindings using the CMake command and options below. + ```console + cmake --fresh .. -DCOMPILE_PYTHON3_BINDINGS=ON + ``` + +### Build, Test, and Install OpenEB Binaries +1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. +1. Build OpenEB on your machine. + ```console + cmake --build . -j4 + ``` +1. **[Optional]** If testing was enabled in your build, you can now run the test suite. + ```console + ctest --verbose + ``` +1. Install OpenEB. + - Use CMake to make the system path the installation target. + ```console + sudo cmake --build . --target install + ``` + - Set an alternative installation target. + ```console + sudo cmake --build . --target install -DCMAKE_INSTALL_PREFIX= + ``` +1. Update the necessary environment variables. + ```console + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 + ``` + +## Install Python API Requirements +> **Note**: *Use of the Python API requires specific versions of Python. Refer to the [Tested Configurations](#tested-configurations) table to determine the version of Python that best suites your application needs.* + +1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. +1. Install the additional library dependencies using the requirements file. + ```console + pip3 install -r ${OPENEB_SRC_DIR}/utils/python/requirements.txt + ``` +### Python API Machine Learning Requirements +Additional hardware, third-party software, and Python packages are required for using OpenEB machine learning (ML) features. +1. Follow all steps for [installing the Python API requirements](#install-python-api-requirements). +1. Ensure that your machine has, or is capable of running an Nvidia GPU that supports: + - [CUDA +11.6](https://developer.nvidia.com/cuda-downloads) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) + +1. Install the required [CUDA](https://developer.nvidia.com/cuda-downloads) and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) components once the hardware requirements are met. +1. Install [PyTorch +1.13.1](https://pytorch.org/get-started/locally/). +1. Install the additional Python packages for ML features. + ```console + pip3 install -r ${OPENEB_SRC_DIR}/utils/python/ml-requirements.txt + ``` + > **Note**: *If you are using an externally managed environment, install the Python packages within your virtual environment* + + +## Upgrade OpenEB +To upgrade and existing installation of OpenEB: +1. Refer to our [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) before performing any upgrades to your existing OpenEB installation. +This will help you navigate changes such as API and firmware updates that can impact applications using the Metavision SDK and event-cameras. +1. Remove the previously installed OpenEB software. + ```console + sudo make uninstall + ``` +1. Remove any remaining OpenEB files from your system's `PATH` and other environment variable locations (`PYTHONPATH` and `LD_LIBRARY_PATH`). +1. Follow the instructions to [build](#build-openeb-c-binaries-from-source) and [install](#install-openeb) OpenEB. + diff --git a/docs/build-and-installation-guides/windows-build-test-and-installation.md.md b/docs/build-and-installation-guides/windows-build-test-and-installation.md.md new file mode 100644 index 000000000..ddd4018ae --- /dev/null +++ b/docs/build-and-installation-guides/windows-build-test-and-installation.md.md @@ -0,0 +1,260 @@ +# OpenEB Windows Build, Test, and Installation Guide + +Currently, we support only Windows 10. +Compilation on other versions of Windows was not tested. +For those platforms some adjustments to this guide or to the code itself may be required. + +### Upgrading OpenEB + +If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) +as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) +and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) might be necessary). + +Then, if you have previously installed any Prophesee's software, you will need to uninstall it first. +Remove the folders where you installed Metavision artifacts (check both the `build` folder of the source code and +`C:\Program Files\Prophesee` which is the default install path of the deployment step). + +### Prerequisites + +Some steps of this procedure don't work on FAT32 and exFAT file system. +Hence, make sure that you are using a NTFS file system before going further. + +You must enable the support for long paths: + * Hit the Windows key, type gpedit.msc and press Enter + * Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem + * Double-click the "Enable Win32 long paths" option, select the "Enabled" option and click "OK" + +To compile OpenEB, you will need to install some extra tools: + + * install [git](https://git-scm.com/download/win) + * install [CMake 3.21](https://cmake.org/files/v3.21/cmake-3.21.7-windows-x86_64.msi) + * install Microsoft C++ compiler (64-bit). You can choose one of the following solutions: + * For building only, you can install MS Build Tools (free, part of Windows 10 SDK package) + * Download and run ["Build tools for Visual Studio 2022" installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + * Select "C++ build tools", make sure Windows 10 SDK is checked, and add English Language Pack + * For development, you can also download and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) + * install [vcpkg](https://github.com/microsoft/vcpkg) that will be used for installing dependencies: + * download and extract [vcpkg version 2023.11.20](https://github.com/microsoft/vcpkg/archive/refs/tags/2023.11.20.zip) + * `cd ` + * `bootstrap-vcpkg.bat` + * install the libraries by running `vcpkg.exe install --triplet x64-windows libusb boost opencv dirent gtest glew glfw3 hdf5[cpp,threadsafe,tools,zlib]` + * Finally, download and install [ffmpeg](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z) and add the `bin` directory to your PATH. + +Note that if you are using vcpkg for various projects or multiple versions of OpenEB, you might want to optimize the +number of vcpkg install you manage. To do so, you will need the versions of the libraries we require. +Those can be found in the [vcpkg repository](https://github.com/microsoft/vcpkg/tree/2023.11.20/versions) but we list them here for convenience: + * libusb: 1.0.26 + * boost: 1.83.0 + * opencv: 4.8.0 + * dirent: 1.24.0 + * gtest: 1.14.0 + * glew: 2.2.0 + * glfw3: 3.3.8 + * hdf5: 1.14.2 + +#### Installing Python and libraries + +* Download "Windows x86-64 executable installer" for one of these Python versions: + * [Python 3.8](https://www.python.org/downloads/release/python-3810/) + * [Python 3.9](https://www.python.org/downloads/release/python-3913/) +* Add Python install and script directories in your `PATH` and make sure they are listed before + the `WindowsApps` folder which contains a Python alias launching the Microsoft Store. So, if you installed + Python 3.8 in the default path, your user `PATH` should contain those three lines in that order: + +```bash +%USERPROFILE%\AppData\Local\Programs\Python\Python38 +%USERPROFILE%\AppData\Local\Programs\Python\Python38\Scripts +%USERPROFILE%\AppData\Local\Microsoft\WindowsApps +```` + +Then install `pip` and some Python libraries: + +```bash +python -m pip install pip --upgrade +python -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" "h5py==3.7.0" pandas scipy +python -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner +``` + +#### Install pybind + +The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library. +You should install pybind using vcpkg in order to get the appropriate version: `vcpkg.exe install --triplet x64-windows pybind11` + +*Note* that pybind11 is required only if you plan to use the Python bindings of the C++ API. +You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 2 during compilation (see section "Compilation using CMake"). +In that case, you will not need to install pybind11, but you won't be able to use our Python interface to the C++ API. + +#### Prerequisites for the ML module + +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)](https://developer.nvidia.com/cuda-downloads) +and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) to leverage them with pytorch and libtorch. + +Then, you need to install [PyTorch 1.13.1](https://pytorch.org). +Retrieve and execute the pip command of version 1.13.1 from +the [previous versions install guide section](). + +Then install some extra Python libraries: + +```bash +python -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 + +First, retrieve the codebase: + +```bash +git clone https://github.com/prophesee-ai/openeb.git --branch 4.5.2 +``` + +Note that 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 generated ``Source.Code.*`` archives. This is because the latter do not include +a necessary submodule. + + +#### Compilation using CMake + +Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: + + 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` + 2. Generate the makefiles using CMake: `cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=`. + Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. + 3. Compile: `cmake --build . --config Release --parallel 4` + +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 (applications, samples, libraries etc.) in a directory of your choice. + +* Option 1 - working from `build` folder + + * To use OpenEB directly from the `build` folder, + you need to update some environment variables using this script: + + ```bash + utils\scripts\setup_env.bat + ``` + +* Option 2 - deploying in a directory of your choice + + * To deploy SDK Pro in the default folder (`C:\Program Files\Prophesee`), execute this command + (your console should be launched as an administrator): + + ```bash + cmake --build . --config Release --target install + ``` + + * To deploy OpenEB in another folder, you should generate the solution again (step 2 above) + with the additional variable `CMAKE_INSTALL_PREFIX` having the value of your target folder (`OPENEB_INSTALL_DIR`). + + Similarly, to specify where the Python packages will be deployed (``PYTHON3_PACKAGES_INSTALL_DIR``), you should use + the `PYTHON3_SITE_PACKAGES` variable. + + Here is an example of a command customizing those two folders: + + ```bash + cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DCMAKE_INSTALL_PREFIX= -DPYTHON3_SITE_PACKAGES= -DBUILD_TESTING=OFF + ``` + + After this command, you should launch the actual compilation and installation of OpenEB + (your console should be launched as an administrator): + + ```bash + cmake --build . --config Release --parallel 4 + cmake --build . --config Release --target install + ``` + + * You also need to manually edit some environment variables: + + * append `\bin` to `PATH` (`C:\Program Files\Prophesee\bin` if you used default configuration) + * append `\lib\metavision\hal\plugins` to `MV_HAL_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\metavision\hal\plugins` if you used default configuration) + * append `\lib\hdf5\plugin` to `HDF5_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\hdf5\plugin` if you used default configuration) + * append `` to `PYTHONPATH` (not needed if you used default configuration) + + +#### Compilation using MS Visual Studio + +Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: + + 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` + 2. Generate the Visual Studio files using CMake: `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=` (adapt to your Visual Studio version). + Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. + 3. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. + +Once the compilation is done, you can choose to work directly from the `build` folder +or you can deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice. + +* Option 1 - working from the `build` folder + + * To use OpenEB directly from the `build` folder, + you need to update the environment variables as done in the script `utils\scripts\setup_env.bat` + +* Option 2 - deploying OpenEB + + * To deploy OpenEB, you need to build the `INSTALL` project. + By default, files will be deployed in `C:\Program Files\Prophesee` + + +#### Camera Plugins + +Prophesee camera plugins are included in OpenEB, but you need to install the drivers +for the cameras to be available on Windows. To do so, follow this procedure: + +1. download [wdi-simple.exe from our file server](https://files.prophesee.ai/share/dists/public/drivers/FeD45ki5/wdi-simple.exe) +2. execute the following commands in a Command Prompt launched as an administrator: + +```bash +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f4 +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f5 +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f3 +``` + +If you own an EVK2 or an RDK2, there are a few additional steps to complete that are detailed in our online documentation +in the [Camera Plugin section of the OpenEB install guide](https://docs.prophesee.ai/stable/installation/windows_openeb.html#camera-plugins). + +If you are using a third-party camera, you need to follow the instructions provided by the camera vendor +to install the driver and the camera plugin. Make sure that you reference the location of the plugin in +the `MV_HAL_PLUGIN_PATH` environment variable. + + +#### Getting Started + +To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) +and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) +or you can stream data from your Prophesee-compatible event-based camera. + + +### Running the test suite (Optional) + +Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. + + * Download [the files](https://dataset.prophesee.ai/index.php/s/tiP0wl0r5aW5efL) necessary to run the tests. + Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. + + * Extract and put the content of this archive to `/datasets`. + For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. + + * To run the test suite you need to reconfigure your build environment using CMake and to recompile + + + * Compilation using CMake + + 1. Regenerate the build using CMake (note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one):: + + ``` + cd /build + cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON + ``` + 2. Compile: `cmake --build . --config Release --parallel 4` + + + * Compilation using MS Visual Studio + + 1. Generate the Visual Studio files using CMake (adapt the command to your Visual Studio version and note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one): + + `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON` + + 2. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. + + * Running the test suite is then simply `ctest -C Release` From 951b69d777bf054ee42037530546c1601f12d039 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Mon, 17 Jun 2024 11:44:57 -0400 Subject: [PATCH 05/15] Typo correction. Renaming docs build guides. --- ...nd-installation.md.md => macos-build-test-and-installation.md} | 0 ...-installation.md.md => windows-build-test-and-installation.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/build-and-installation-guides/{macos-build-test-and-installation.md.md => macos-build-test-and-installation.md} (100%) rename docs/build-and-installation-guides/{windows-build-test-and-installation.md.md => windows-build-test-and-installation.md} (100%) diff --git a/docs/build-and-installation-guides/macos-build-test-and-installation.md.md b/docs/build-and-installation-guides/macos-build-test-and-installation.md similarity index 100% rename from docs/build-and-installation-guides/macos-build-test-and-installation.md.md rename to docs/build-and-installation-guides/macos-build-test-and-installation.md diff --git a/docs/build-and-installation-guides/windows-build-test-and-installation.md.md b/docs/build-and-installation-guides/windows-build-test-and-installation.md similarity index 100% rename from docs/build-and-installation-guides/windows-build-test-and-installation.md.md rename to docs/build-and-installation-guides/windows-build-test-and-installation.md From 0d1219c64066239b43e348d1cb9e17ae147ba512 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Mon, 17 Jun 2024 12:28:29 -0400 Subject: [PATCH 06/15] Fixing broken link in README. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4b90c7b8c..97ef8594b 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ OpenEB also contains the source code for [Prophesee camera plugins](https://docs Follow the links below to find the build and installation guide for your OS. - [**Linux**](./docs/build-and-installation-guides/linux-build-test-and-installation.md) -- [**MacOS**](./docs/build-and-installation-guides/macos-build-test-and-installation.md.md) -- [**Windows**](./docs/build-and-installation-guides/windows-build-test-and-installation.md.md) +- [**MacOS**](./docs/build-and-installation-guides/macos-build-test-and-installation.md) +- [**Windows**](./docs/build-and-installation-guides/windows-build-test-and-installation.md) ## Additional Resources - [**Metavision SDK Docs**](https://docs.prophesee.ai/stable/index.html) From d97362c675231b330e59c87e91eb28d3a110327f Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Mon, 17 Jun 2024 12:33:16 -0400 Subject: [PATCH 07/15] Fixing merge. --- README.md | 443 ------------------------------------------------------ 1 file changed, 443 deletions(-) diff --git a/README.md b/README.md index 97ef8594b..d76396595 100644 --- a/README.md +++ b/README.md @@ -34,446 +34,3 @@ Follow the links below to find the build and installation guide for your OS. - [**Get started** guides for C++ and Python](https://docs.prophesee.ai/stable/get_started/index.html) - [**Code samples** for API best practices](https://docs.prophesee.ai/stable/samples.html) - [**Technical details** regarding modules and packaging](https://docs.prophesee.ai/stable/modules.html) - - - -<<<<<<< HEAD -======= -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. - - -### Upgrading OpenEB - -If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) -as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) -and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) 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: - -```bash -sudo make uninstall -``` - -In addition, make a global check in your system paths (`/usr/lib`, `/usr/local/lib`, `/usr/include`, `/usr/local/include`) -and in your environment variables (`PATH`, `PYTHONPATH` and `LD_LIBRARY_PATH`) to remove occurrences of Prophesee or Metavision files. - -### Prerequisites - -Install the following dependencies: - -```bash -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 libprotobuf-dev protobuf-compiler -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](https://google.github.io/googletest/): - -```bash -sudo apt -y install libgtest-dev libgmock-dev -``` - -For the [Python API](https://docs.prophesee.ai/stable/api/python/index.html#chapter-api-python), 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 `pip` and some Python libraries: -```bash -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" "h5py==3.7.0" pandas scipy -python3 -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner -``` - -The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library, specifically version 2.6.0. - -*Note* that pybind11 is required only if you want to use the Python bindings of the C++ API . -You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 3 during compilation (see below). -In that case, you will not need to install 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: - -```bash -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)](https://developer.nvidia.com/cuda-downloads) -and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) 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](https://docs.nvidia.com/deeplearning/cudnn/support-matrix/index.html). - -Note that, at the moment, we don't support [OpenCL](https://www.khronos.org/opencl/) and AMD GPUs. - -Then, you need to install [PyTorch 1.13.1](https://pytorch.org). -Retrieve and execute the pip command of version 1.13.1 from -the [previous versions install guide section](). - -Then install some extra Python libraries: - -```bash -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 - - 1. Retrieve the code: `git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.1`. - (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 generated ``Source.Code.*`` archives. This is because the latter do not include - a necessary submodule.) - 2. Create and open the build directory in the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections): `cd openeb; mkdir build && cd build` - 3. Generate the makefiles using CMake: `cmake .. -DBUILD_TESTING=OFF`. - If you want to specify to cmake which version of Python to consider, you should use the option ``-DPython3_EXECUTABLE=``. - 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. - 4. Compile: `cmake --build . --config Release -- -j 4` - -Once the compilation is finished, 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): - - ```bash - source utils/scripts/setup_env.sh - ``` - - * [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html) 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: - - ```bash - sudo cp /hal_psee_plugins/resources/rules/*.rules /etc/udev/rules.d - sudo udevadm control --reload-rules - sudo udevadm trigger - ``` - -* Option 2 - deploying in the system path - - * To deploy OpenEB, launch the following command: - - ```bash - sudo cmake --build . --target install - ``` - - Note that 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=`) when generating the makefiles - in step 3. Similarly, you can configure the directory where the Python packages will be deployed using the - `PYTHON3_SITE_PACKAGES` variable (`-DPYTHON3_SITE_PACKAGES=`). - - * you also need to update `LD_LIBRARY_PATH` and `HDF5_PLUGIN_PATH` - (which you may add to your `~/.bashrc` to make it permanent): - - ```bash - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 - ``` - -Note that 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. - -To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) -and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) -or you can stream data from your Prophesee-compatible event-based camera. - -### Running the test suite (Optional) - -Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. - - * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. - Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. - - * Extract and put the content of this archive to `/datasets`. - For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. - - * Regenerate the makefiles with the test options enabled: - - ```bash - cd /build - cmake .. -DBUILD_TESTING=ON - ``` - - * Compile again. `cmake --build . --config Release -- -j 4` - - * Finally, run the test suite: `ctest --verbose` - -## Compiling on Windows - -Currently, we support only Windows 10. -Compilation on other versions of Windows was not tested. -For those platforms some adjustments to this guide or to the code itself may be required. - -### Upgrading OpenEB - -If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) -as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) -and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) might be necessary). - -Then, if you have previously installed any Prophesee's software, you will need to uninstall it first. -Remove the folders where you installed Metavision artifacts (check both the `build` folder of the source code and -`C:\Program Files\Prophesee` which is the default install path of the deployment step). - -### Prerequisites - -Some steps of this procedure don't work on FAT32 and exFAT file system. -Hence, make sure that you are using a NTFS file system before going further. - -You must enable the support for long paths: - * Hit the Windows key, type gpedit.msc and press Enter - * Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem - * Double-click the "Enable Win32 long paths" option, select the "Enabled" option and click "OK" - -To compile OpenEB, you will need to install some extra tools: - - * install [git](https://git-scm.com/download/win) - * install [CMake 3.21](https://cmake.org/files/v3.21/cmake-3.21.7-windows-x86_64.msi) - * install Microsoft C++ compiler (64-bit). You can choose one of the following solutions: - * For building only, you can install MS Build Tools (free, part of Windows 10 SDK package) - * Download and run ["Build tools for Visual Studio 2022" installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) - * Select "C++ build tools", make sure Windows 10 SDK is checked, and add English Language Pack - * For development, you can also download and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) - * install [vcpkg](https://github.com/microsoft/vcpkg) that will be used for installing dependencies: - * download and extract [vcpkg version 2023.11.20](https://github.com/microsoft/vcpkg/archive/refs/tags/2023.11.20.zip) - * `cd ` - * `bootstrap-vcpkg.bat` - * install the libraries by running `vcpkg.exe install --triplet x64-windows libusb boost opencv dirent gtest glew glfw3 hdf5[cpp,threadsafe,tools,zlib]` - * Finally, download and install [ffmpeg](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z) and add the `bin` directory to your PATH. - -Note that if you are using vcpkg for various projects or multiple versions of OpenEB, you might want to optimize the -number of vcpkg install you manage. To do so, you will need the versions of the libraries we require. -Those can be found in the [vcpkg repository](https://github.com/microsoft/vcpkg/tree/2023.11.20/versions) but we list them here for convenience: - * libusb: 1.0.26 - * boost: 1.83.0 - * opencv: 4.8.0 - * dirent: 1.24.0 - * gtest: 1.14.0 - * glew: 2.2.0 - * glfw3: 3.3.8 - * hdf5: 1.14.2 - -#### Installing Python and libraries - -* Download "Windows x86-64 executable installer" for one of these Python versions: - * [Python 3.8](https://www.python.org/downloads/release/python-3810/) - * [Python 3.9](https://www.python.org/downloads/release/python-3913/) -* Add Python install and script directories in your `PATH` and make sure they are listed before - the `WindowsApps` folder which contains a Python alias launching the Microsoft Store. So, if you installed - Python 3.8 in the default path, your user `PATH` should contain those three lines in that order: - -```bash -%USERPROFILE%\AppData\Local\Programs\Python\Python38 -%USERPROFILE%\AppData\Local\Programs\Python\Python38\Scripts -%USERPROFILE%\AppData\Local\Microsoft\WindowsApps -```` - -Then install `pip` and some Python libraries: - -```bash -python -m pip install pip --upgrade -python -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" "h5py==3.7.0" pandas scipy -python -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner -``` - -#### Install pybind - -The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library. -You should install pybind using vcpkg in order to get the appropriate version: `vcpkg.exe install --triplet x64-windows pybind11` - -*Note* that pybind11 is required only if you plan to use the Python bindings of the C++ API. -You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 2 during compilation (see section "Compilation using CMake"). -In that case, you will not need to install pybind11, but you won't be able to use our Python interface to the C++ API. - -#### Prerequisites for the ML module - -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)](https://developer.nvidia.com/cuda-downloads) -and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) to leverage them with pytorch and libtorch. - -Then, you need to install [PyTorch 1.13.1](https://pytorch.org). -Retrieve and execute the pip command of version 1.13.1 from -the [previous versions install guide section](). - -Then install some extra Python libraries: - -```bash -python -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 - -First, retrieve the codebase: - -```bash -git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.1 -``` - -Note that 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 generated ``Source.Code.*`` archives. This is because the latter do not include -a necessary submodule. - - -#### Compilation using CMake - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the makefiles using CMake: `cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=`. - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Compile: `cmake --build . --config Release --parallel 4` - -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 (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update some environment variables using this script: - - ```bash - utils\scripts\setup_env.bat - ``` - -* Option 2 - deploying in a directory of your choice - - * To deploy OpenEB in the default folder (`C:\Program Files\Prophesee`), execute this command - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --target install - ``` - - * To deploy OpenEB in another folder, you should generate the solution again (step 2 above) - with the additional variable `CMAKE_INSTALL_PREFIX` having the value of your target folder (`OPENEB_INSTALL_DIR`). - - Similarly, to specify where the Python packages will be deployed (``PYTHON3_PACKAGES_INSTALL_DIR``), you should use - the `PYTHON3_SITE_PACKAGES` variable. - - Here is an example of a command customizing those two folders: - - ```bash - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DCMAKE_INSTALL_PREFIX= -DPYTHON3_SITE_PACKAGES= -DBUILD_TESTING=OFF - ``` - - After this command, you should launch the actual compilation and installation of OpenEB - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --parallel 4 - cmake --build . --config Release --target install - ``` - - * You also need to manually edit some environment variables: - - * append `\bin` to `PATH` (`C:\Program Files\Prophesee\bin` if you used default configuration) - * append `\lib\metavision\hal\plugins` to `MV_HAL_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\metavision\hal\plugins` if you used default configuration) - * append `\lib\hdf5\plugin` to `HDF5_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\hdf5\plugin` if you used default configuration) - * append `` to `PYTHONPATH` (not needed if you used default configuration) - - -#### Compilation using MS Visual Studio - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the Visual Studio files using CMake: `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=` (adapt to your Visual Studio version). - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - -Once the compilation is done, you can choose to work directly from the `build` folder -or you can deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from the `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update the environment variables as done in the script `utils\scripts\setup_env.bat` - -* Option 2 - deploying OpenEB - - * To deploy OpenEB, you need to build the `INSTALL` project. - By default, files will be deployed in `C:\Program Files\Prophesee` - - -#### Camera Plugins - -Prophesee camera plugins are included in OpenEB, but you need to install the drivers -for the cameras to be available on Windows. To do so, follow this procedure: - -1. download [wdi-simple.exe from our file server](https://kdrive.infomaniak.com/app/share/975517/4f59e852-af5e-4e00-90fc-f213aad20edd) -2. execute the following commands in a Command Prompt launched as an administrator: - -```bash -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f4 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f5 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f3 -``` - -If you own an EVK2 or an RDK2, there are a few additional steps to complete that are detailed in our online documentation -in the [Camera Plugin section of the OpenEB install guide](https://docs.prophesee.ai/stable/installation/windows_openeb.html#camera-plugins). - -If you are using a third-party camera, you need to follow the instructions provided by the camera vendor -to install the driver and the camera plugin. Make sure that you reference the location of the plugin in -the `MV_HAL_PLUGIN_PATH` environment variable. - - -#### Getting Started - -To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) -and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) -or you can stream data from your Prophesee-compatible event-based camera. - - -### Running the test suite (Optional) - -Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. - - * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. - Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. - - * Extract and put the content of this archive to `/datasets`. - For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. - - * To run the test suite you need to reconfigure your build environment using CMake and to recompile - - - * Compilation using CMake - - 1. Regenerate the build using CMake (note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one):: - - ``` - cd /build - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON - ``` - 2. Compile: `cmake --build . --config Release --parallel 4` - - - * Compilation using MS Visual Studio - - 1. Generate the Visual Studio files using CMake (adapt the command to your Visual Studio version and note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one): - - `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON` - - 2. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - - * Running the test suite is then simply `ctest -C Release` ->>>>>>> e446586a1c26152dd81122cafe3816570d4a1142 From 8c030d426edf56e1298a517b952595d92158bb11 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Mon, 17 Jun 2024 13:56:39 -0400 Subject: [PATCH 08/15] Removing references to emsight from build tutorials.. --- .../macos-build-test-and-installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-and-installation-guides/macos-build-test-and-installation.md b/docs/build-and-installation-guides/macos-build-test-and-installation.md index b53c61915..3f2c927a1 100644 --- a/docs/build-and-installation-guides/macos-build-test-and-installation.md +++ b/docs/build-and-installation-guides/macos-build-test-and-installation.md @@ -45,9 +45,9 @@ This guide uses [Homebrew](https://brew.sh/) formulae to retrieve packages. It a python3 -m venv .venv && \ source .venv/bin/activate ``` -1. Retrieve the latest [OpenEB source](https://github.com/emsight/openeb), or your desired branch, and navigate into the project folder. +1. Retrieve the latest [OpenEB source](https://github.com/prophesee-ai/openeb), or your desired branch, and navigate into the project folder. ```console - git clone https://github.com/emsight/openeb.git && cd openeb + git clone https://github.com/prophesee-ai/openeb.git && cd openeb ``` 1. Once inside your OpenEB directory, create an environment variable to reference that location. ```console From 0757f7711e343e6a90765575f0f3f16dcea310b6 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Thu, 20 Jun 2024 15:24:27 -0400 Subject: [PATCH 09/15] Fixing OpenGL logic for supporting Linux/Windows/Apple platforms. Subsequently, removing extraneous Apple and Linux preprocessor directives throughout the various metavision::sdk::ui implementation files. --- .../metavision/sdk/ui/utils/opengl_api.h | 23 +++++++++++-------- sdk/modules/ui/cpp/src/base_glfw_window.cpp | 4 ++-- sdk/modules/ui/cpp/src/base_window.cpp | 20 ++-------------- 3 files changed, 18 insertions(+), 29 deletions(-) diff --git a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h index 807dc81b7..73899965f 100644 --- a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h +++ b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h @@ -14,18 +14,14 @@ #ifdef _USE_OPENGL_ES3_ #include -// While we keep support for OpenGL, we need to provide a -// dummy implementation for Glew init function -#define GLEW_OK 0 -inline int glewInit(void) { - return GLEW_OK; -} #else // OpenGL #if defined(__APPLE__) && !defined(__linux__) -#include -#include +#define GL_SILENCE_DEPRECATION #include -#elif defined(__linux__) +#else +#if defined(WIN32) +#include +#endif #include #include #endif @@ -34,4 +30,13 @@ inline int glewInit(void) { // GLFW need to be included after OpenGL #include +// While we keep support for OpenGL, we need to provide a +// dummy implementation for Glew init function +#ifndef GLEW_OK +#define GLEW_OK 0 +inline int glewInit(void) { + return GLEW_OK; +} +#endif + #endif // METAVISION_SDK_UI_UTILS_OPENGL_API diff --git a/sdk/modules/ui/cpp/src/base_glfw_window.cpp b/sdk/modules/ui/cpp/src/base_glfw_window.cpp index 7dd34c576..41ecbee02 100644 --- a/sdk/modules/ui/cpp/src/base_glfw_window.cpp +++ b/sdk/modules/ui/cpp/src/base_glfw_window.cpp @@ -46,11 +46,11 @@ struct GLFWContext { throw std::runtime_error("Impossible to create a glfw window"); glfwMakeContextCurrent(window); -#if defined(__linux__) + if (glewInit() != GLEW_OK) { throw std::runtime_error("Impossible to initialize GL extensions with GLEW"); } -#endif + glfwWindowHint(GLFW_VISIBLE, GLFW_TRUE); glfwMakeContextCurrent(nullptr); diff --git a/sdk/modules/ui/cpp/src/base_window.cpp b/sdk/modules/ui/cpp/src/base_window.cpp index 8f5fb1ae0..1f92e230c 100644 --- a/sdk/modules/ui/cpp/src/base_window.cpp +++ b/sdk/modules/ui/cpp/src/base_window.cpp @@ -129,13 +129,9 @@ BaseWindow::BaseWindow(const std::string &title, int width, int height, RenderMo }; // clang-format on - #if defined(__APPLE__) && !defined(__linux__) - glGenVertexArraysAPPLE(1, &vertex_array_id_); - glBindVertexArrayAPPLE(vertex_array_id_); - #else glGenVertexArrays(1, &vertex_array_id_); glBindVertexArray(vertex_array_id_); - #endif + glGenBuffers(1, &vertex_buffer_); glBindBuffer(GL_ARRAY_BUFFER, vertex_buffer_); glBufferData(GL_ARRAY_BUFFER, sizeof(g_vertex_buffer_data), g_vertex_buffer_data, GL_STATIC_DRAW); @@ -147,11 +143,7 @@ BaseWindow::BaseWindow(const std::string &title, int width, int height, RenderMo glEnableVertexAttribArray(1); glBindBuffer(GL_ARRAY_BUFFER, 0); - #if defined(__APPLE__) && !defined(__linux__) - glBindVertexArrayAPPLE(0); - #else glBindVertexArray(0); - #endif glfwMakeContextCurrent(nullptr); @@ -165,11 +157,7 @@ BaseWindow::~BaseWindow() { if (glfw_window_) { glfwMakeContextCurrent(glfw_window_); glDeleteBuffers(1, &vertex_buffer_); - #if defined(__APPLE__) && !defined(__linux__) - glDeleteVertexArraysAPPLE(1, &vertex_array_id_); - #else - glDeleteVertexArrays(1, &vertex_array_id_); - #endif + glDeleteVertexArrays(1, &vertex_array_id_); glDeleteTextures(1, &tex_id_); glDeleteProgram(program_id_); } @@ -240,11 +228,7 @@ void BaseWindow::draw_background_texture() { glBindTexture(GL_TEXTURE_2D, tex_id_); - #if defined(__APPLE__) && !defined(__linux__) - glBindVertexArrayAPPLE(vertex_array_id_); - #else glBindVertexArray(vertex_array_id_); - #endif glDrawArrays(GL_TRIANGLES, 0, 6); From 05c049836bbc800afaafd45cd072675588732d70 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sat, 13 Jul 2024 19:31:30 -0400 Subject: [PATCH 10/15] Updating field name change #if to protobuf version to v26.0. The renaming of takes place in v26.0 and later. --- sdk/modules/driver/cpp/src/camera_serialization.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/modules/driver/cpp/src/camera_serialization.cpp b/sdk/modules/driver/cpp/src/camera_serialization.cpp index 4a3e1f914..e7aa3d378 100644 --- a/sdk/modules/driver/cpp/src/camera_serialization.cpp +++ b/sdk/modules/driver/cpp/src/camera_serialization.cpp @@ -655,7 +655,7 @@ std::ostream &save_device(const Device &d, std::ostream &os) { google::protobuf::util::JsonPrintOptions options; options.add_whitespace = true; - #if (GOOGLE_PROTOBUF_VERSION >= 5027000) + #if (GOOGLE_PROTOBUF_VERSION >= 5026000) options.always_print_fields_with_no_presence = true; #else options.always_print_primitive_fields = true; From ee8848a7f6948d531570d68b7e18e900c60ab6d8 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Sat, 13 Jul 2024 20:20:20 -0400 Subject: [PATCH 11/15] Minor changes to the preprocessor logic. Also note that the GL_SILENCE_DEPRECATION directive is used to supress warninngs on OSX platforms related to the deprecation of OpenGL on Apple silicon. On MacOS this began with update 10.14. --- .../ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h index 73899965f..5b6f99741 100644 --- a/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h +++ b/sdk/modules/ui/cpp/include/metavision/sdk/ui/utils/opengl_api.h @@ -14,8 +14,7 @@ #ifdef _USE_OPENGL_ES3_ #include -#else // OpenGL -#if defined(__APPLE__) && !defined(__linux__) +#elif defined(__APPLE__) && !defined(__linux__) #define GL_SILENCE_DEPRECATION #include #else @@ -25,9 +24,8 @@ #include #include #endif -#endif -// GLFW need to be included after OpenGL +// GLFW needs to be included after OpenGL #include // While we keep support for OpenGL, we need to provide a From c286d09b4224af4ed9836de293bea821cdf612ff Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Mon, 15 Jul 2024 21:59:01 -0400 Subject: [PATCH 12/15] Update CMakeLists.txt Updating option comment for BUILD_TESTING Co-authored-by: Olivier Georget <116826255+ogeorget-psee@users.noreply.github.com> --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0635777d7..4b60ef50b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,7 @@ if(NOT CMAKE_BUILD_TYPE) endif(NOT CMAKE_BUILD_TYPE) option(COMPILE_PYTHON3_BINDINGS "Enable/Disable Python bindings. Python bindings are disabled by default." OFF) -option(BUILD_TESTING "Enable/Disable test applications." OFF) +option(BUILD_TESTING "Build OpenEB's test suite" OFF) cmake_minimum_required(VERSION 3.5) From cd471843e38aeed78188b43fd926280d291d2f52 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Tue, 16 Jul 2024 21:31:36 -0400 Subject: [PATCH 13/15] Removing the default OFF behavior for COMPILE_PYTHON3_BINDINGS option. Python binding are enabled by default to satisfy API requirements. The default ON behavior is defined for all NON-Android platforms. Documentation has also been updated to reflect this behavior. --- CMakeLists.txt | 1 - .../linux-build-test-and-installation.md | 32 +++++++------------ .../macos-build-test-and-installation.md | 32 +++++++------------ 3 files changed, 23 insertions(+), 42 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4b60ef50b..a5683e585 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -15,7 +15,6 @@ if(NOT CMAKE_BUILD_TYPE) "Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel." FORCE) endif(NOT CMAKE_BUILD_TYPE) -option(COMPILE_PYTHON3_BINDINGS "Enable/Disable Python bindings. Python bindings are disabled by default." OFF) option(BUILD_TESTING "Build OpenEB's test suite" OFF) cmake_minimum_required(VERSION 3.5) diff --git a/docs/build-and-installation-guides/linux-build-test-and-installation.md b/docs/build-and-installation-guides/linux-build-test-and-installation.md index 2979a5a8a..322f7d4a7 100644 --- a/docs/build-and-installation-guides/linux-build-test-and-installation.md +++ b/docs/build-and-installation-guides/linux-build-test-and-installation.md @@ -40,7 +40,7 @@ Building OpenEB with component configurations other than what is listed above ma apt-utils \ wget ``` -1. If you'll be using the Python API, Python bindings for C++, or and of the test applications, install Python3 as well. +1. If you'll be using the Python API, Python bindings for C++, or any of the test applications, install Python3 and pybind11 as well. ```bash sudo apt -y install \ python3.x \ @@ -48,7 +48,8 @@ Building OpenEB with component configurations other than what is listed above ma python3.x-distutils \ python3.x-venv \ python3-pip \ - python3-setuptools + python3-setuptools \ + python3-pybind11 ``` > **Note**: *For externally managed environments, activate a Python virtual environment and use it for all subsequent installation and build instructions.* - Navigate to your development area and activate a Python virtual environment. @@ -82,19 +83,19 @@ When you build OpenEB you have the option to: 1. Enable/Disable Python binding for C++ 1. Change the build type (`Release`, `Debug`, ect.) -By default, test applications and Python C++ bindings are disabled. However, you can control them by using the CMake configuration options given in the table below. +The table below describes CMake options that you can use to change the default build behavior. -| Build Description | CMake Configuration Option | -|-------------------|----------------------------| -| **Enable Test Applications** | `-DBUILD_TESTING=ON` | -| **Enable Python Bindings** | `-DCOMPILE_PYTHON3_BINDINGS=ON` | -| **Change the build type** | `-DCMAKE_BUILD_TYPE=`| +| CMake Configuration Option | Description | Default State | +|----------------------------|-------------|---------------| +| `BUILD_TESTING` | Enable/Disable Test Applications | `OFF` | +| `COMPILE_PYTHON3_BINDINGS` | Enable/Disable Python Bindings | `ON` | +| `CMAKE_BUILD_TYPE`| Change the build type | `Release` | Once you've completed the requirements for -any of the additional build configurations, use the option flags individually, or together, to enable the features you desire. +any of the additional build configurations, use the option flags individually, or together, to set the state you desire. ##### Test Applications -1. Complete steps 1→4 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Complete steps 1→3 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) 1. Install the Google Test and `pytest` dependencies. ```bash sudo apt -y install \ @@ -114,17 +115,6 @@ any of the additional build configurations, use the option flags individually, o cmake --fresh .. -DBUILD_TESTING=ON ``` -##### Python Bindings for C++ -1. Complete steps 1→3 for the [initial setup and build configuration.](#initial-setup-and-build-configuration) -1. Install pybind11. - ```bash - sudo apt -y install python3-pybind11 - ``` -1. Enable the Python bindings using the CMake command and options below. - ```bash - cmake --fresh .. -DCOMPILE_PYTHON3_BINDINGS=ON - ``` - ### Build, Test, and Install OpenEB Binaries 1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. 1. Build OpenEB on your machine. diff --git a/docs/build-and-installation-guides/macos-build-test-and-installation.md b/docs/build-and-installation-guides/macos-build-test-and-installation.md index 3f2c927a1..0658438e3 100644 --- a/docs/build-and-installation-guides/macos-build-test-and-installation.md +++ b/docs/build-and-installation-guides/macos-build-test-and-installation.md @@ -34,9 +34,11 @@ This guide uses [Homebrew](https://brew.sh/) formulae to retrieve packages. It a protobuf \ libusb ``` -1. If you'll be using the Python API, Python bindings for C++, or and of the test applications, install Python3 as well. +1. If you'll be using the Python API, Python bindings for C++, or any of the test applications, install Python3 and pybind11 as well. ```console - brew install python3 + brew install \ + python3 \ + pybind11 ``` > **Note**: *For externally managed environments, activate a Python virtual environment and use it for subsequent installation and build instructions.* @@ -71,19 +73,19 @@ When you build OpenEB you have the option to: 1. Enable/Disable Python binding for C++ 1. Change the build type (`Release`, `Debug`, ect.) -By default, test applications and Python C++ bindings are disabled. However, you can control them by using the CMake configuration options given in the table below. +The table below describes CMake options that you can use to change the default build behavior. -| Build Description | CMake Configuration Option | -|-------------------|----------------------------| -| **Enable Test Applications** | `-DBUILD_TESTING=ON` | -| **Enable Python Bindings** | `-DCOMPILE_PYTHON3_BINDINGS=ON` | -| **Change the build type** | `-DCMAKE_BUILD_TYPE=`| +| CMake Configuration Option | Description | Default State | +|----------------------------|-------------|---------------| +| `BUILD_TESTING` | Enable/Disable Test Applications | `OFF` | +| `COMPILE_PYTHON3_BINDINGS` | Enable/Disable Python Bindings | `ON` | +| `CMAKE_BUILD_TYPE`| Change the build type | `Release` | Once you've completed the requirements for -any of the additional build configurations, use the option flags individually, or together, to enable the features you desire. +any of the additional build configurations, use the option flags individually, or together, to set the state you desire. ##### Test Applications -1. Complete steps 1→4 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) +1. Complete steps 1→3 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) 1. Install the Google Test and `pytest` dependencies. ```console brew install googletest && \ @@ -101,16 +103,6 @@ any of the additional build configurations, use the option flags individually, o cmake --fresh .. -DBUILD_TESTING=ON ``` -##### Python Bindings for C++ -1. Complete steps 1→4 for the [initial setup and build configuration.](#initial-setup-and-build-configuration) -1. Install pybind11. - ```console - brew install pybind11 - ``` -1. Enable the Python bindings using the CMake command and options below. - ```console - cmake --fresh .. -DCOMPILE_PYTHON3_BINDINGS=ON - ``` ### Build, Test, and Install OpenEB Binaries 1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. From 1e753c4b18dbaaf6fda8cef9eb7d2b702c6db70b Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:44:15 -0400 Subject: [PATCH 14/15] Removing docs modifications. MacOS installation is untested on Prophesee's end and documenting the process introduces added complexity for both maintainers and end-users. --- README.md | 482 +++++++++++++++++- .../linux-build-test-and-installation.md | 178 ------- .../macos-build-test-and-installation.md | 167 ------ .../windows-build-test-and-installation.md | 260 ---------- 4 files changed, 462 insertions(+), 625 deletions(-) delete mode 100644 docs/build-and-installation-guides/linux-build-test-and-installation.md delete mode 100644 docs/build-and-installation-guides/macos-build-test-and-installation.md delete mode 100644 docs/build-and-installation-guides/windows-build-test-and-installation.md diff --git a/README.md b/README.md index d76396595..c2d06c5f3 100644 --- a/README.md +++ b/README.md @@ -7,30 +7,472 @@ their own applications or camera plugins. As a camera manufacturer, ensure your event-based software suite available by building your own plugin. As a creator, scientist, academic, join and contribute to the fast-growing event-based vision community. -OpenEB is composed of the [Metavision SDK Open Modules](https://docs.prophesee.ai/stable/modules.html#chapter-modules-and-packaging-open): -* **HAL**: Hardware Abstraction Layer to operate any event-based vision device. -* **Base**: Foundations and common definitions of event-based applications. -* **Core**: Generic algorithms for visualization, event stream manipulation, applicative pipeline generation. -* **Core ML**: Generic functions for Machine Learning, event_to_video and video_to_event pipelines. -* **Driver**: High-level abstraction built on the top of HAL to easily interact with event-based cameras. -* **UI**: Viewer and display controllers for event-based data. +OpenEB is composed of the [Open modules of Metavision SDK](https://docs.prophesee.ai/stable/modules.html#chapter-modules-and-packaging-open): +* HAL: Hardware Abstraction Layer to operate any event-based vision device. +* Base: Foundations and common definitions of event-based applications. +* Core: Generic algorithms for visualization, event stream manipulation, applicative pipeline generation. +* Core ML: Generic functions for Machine Learning, event_to_video and video_to_event pipelines. +* Driver: High-level abstraction built on the top of HAL to easily interact with event-based cameras. +* UI: Viewer and display controllers for event-based data. -OpenEB also contains the source code for [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html) which allow applications to handle I/O operations. Once enabled, applications can stream data from event-cameras, as well as read and playback event recordings. - -## Supported Cameras +OpenEB also contains the source code of [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html), +enabling to stream data from our event-based cameras and to read recordings of event-based data. +The supported cameras are: * EVK2 - HD * EVK3 - VGA/320/HD * EVK4 - HD -## Build, Test, and Install OpenEB -Follow the links below to find the build and installation guide for your OS. +This document describes how to compile and install the OpenEB codebase. +For further information, refer to our [online documentation](https://docs.prophesee.ai/) where you will find +some [tutorials](https://docs.prophesee.ai/stable/tutorials/index.html) to get you started in C++ or Python, +some [samples](https://docs.prophesee.ai/stable/samples.html) to discover how to use +[our API](https://docs.prophesee.ai/stable/api.html) and a more detailed +[description of our modules and packaging](https://docs.prophesee.ai/stable/modules.html). + + +## Compiling 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](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#CPUs_with_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. + + +### Upgrading OpenEB + +If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) +as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) +and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) 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: + +```bash +sudo make uninstall +``` + +In addition, make a global check in your system paths (`/usr/lib`, `/usr/local/lib`, `/usr/include`, `/usr/local/include`) +and in your environment variables (`PATH`, `PYTHONPATH` and `LD_LIBRARY_PATH`) to remove occurrences of Prophesee or Metavision files. + +### Prerequisites + +Install the following dependencies: + +```bash +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 libprotobuf-dev protobuf-compiler +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](https://google.github.io/googletest/): + +```bash +sudo apt -y install libgtest-dev libgmock-dev +``` + +For the [Python API](https://docs.prophesee.ai/stable/api/python/index.html#chapter-api-python), 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 `pip` and some Python libraries: +```bash +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" "h5py==3.7.0" pandas scipy +python3 -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner +``` + +The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library, specifically version 2.6.0. + +*Note* that pybind11 is required only if you want to use the Python bindings of the C++ API . +You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 3 during compilation (see below). +In that case, you will not need to install 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: + +```bash +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)](https://developer.nvidia.com/cuda-downloads) +and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) 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](https://docs.nvidia.com/deeplearning/cudnn/support-matrix/index.html). + +Note that, at the moment, we don't support [OpenCL](https://www.khronos.org/opencl/) and AMD GPUs. + +Then, you need to install [PyTorch 1.13.1](https://pytorch.org). +Retrieve and execute the pip command of version 1.13.1 from +the [previous versions install guide section](). + +Then install some extra Python libraries: + +```bash +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 + + 1. Retrieve the code: `git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0`. + (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 generated ``Source.Code.*`` archives. This is because the latter do not include + a necessary submodule.) + 2. Create and open the build directory in the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections): `cd openeb; mkdir build && cd build` + 3. Generate the makefiles using CMake: `cmake .. -DBUILD_TESTING=OFF`. + If you want to specify to cmake which version of Python to consider, you should use the option ``-DPython3_EXECUTABLE=``. + 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. + 4. Compile: `cmake --build . --config Release -- -j 4` + +Once the compilation is finished, 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): + + ```bash + source utils/scripts/setup_env.sh + ``` + + * [Prophesee camera plugins](https://docs.prophesee.ai/stable/installation/camera_plugins.html) 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: + + ```bash + sudo cp /hal_psee_plugins/resources/rules/*.rules /etc/udev/rules.d + sudo udevadm control --reload-rules + sudo udevadm trigger + ``` + +* Option 2 - deploying in the system path + + * To deploy OpenEB, launch the following command: + + ```bash + sudo cmake --build . --target install + ``` + + Note that 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=`) when generating the makefiles + in step 3. Similarly, you can configure the directory where the Python packages will be deployed using the + `PYTHON3_SITE_PACKAGES` variable (`-DPYTHON3_SITE_PACKAGES=`). + + * you also need to update `LD_LIBRARY_PATH` and `HDF5_PLUGIN_PATH` + (which you may add to your `~/.bashrc` to make it permanent): + + ```bash + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 + export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 + ``` + +Note that 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. + +To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) +and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) +or you can stream data from your Prophesee-compatible event-based camera. + +### Running the test suite (Optional) + +Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. + + * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. + Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. + + * Extract and put the content of this archive to `/datasets`. + For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. + + * Regenerate the makefiles with the test options enabled: + + ```bash + cd /build + cmake .. -DBUILD_TESTING=ON + ``` + + * Compile again. `cmake --build . --config Release -- -j 4` + + * Finally, run the test suite: `ctest --verbose` + +## Compiling on Windows + +Currently, we support only Windows 10. +Compilation on other versions of Windows was not tested. +For those platforms some adjustments to this guide or to the code itself may be required. + +### Upgrading OpenEB + +If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) +as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) +and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) might be necessary). + +Then, if you have previously installed any Prophesee's software, you will need to uninstall it first. +Remove the folders where you installed Metavision artifacts (check both the `build` folder of the source code and +`C:\Program Files\Prophesee` which is the default install path of the deployment step). + +### Prerequisites + +Some steps of this procedure don't work on FAT32 and exFAT file system. +Hence, make sure that you are using a NTFS file system before going further. + +You must enable the support for long paths: + * Hit the Windows key, type gpedit.msc and press Enter + * Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem + * Double-click the "Enable Win32 long paths" option, select the "Enabled" option and click "OK" + +To compile OpenEB, you will need to install some extra tools: + + * install [git](https://git-scm.com/download/win) + * install [CMake 3.21](https://cmake.org/files/v3.21/cmake-3.21.7-windows-x86_64.msi) + * install Microsoft C++ compiler (64-bit). You can choose one of the following solutions: + * For building only, you can install MS Build Tools (free, part of Windows 10 SDK package) + * Download and run ["Build tools for Visual Studio 2022" installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + * Select "C++ build tools", make sure Windows 10 SDK is checked, and add English Language Pack + * For development, you can also download and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) + * install [vcpkg](https://github.com/microsoft/vcpkg) that will be used for installing dependencies: + * download and extract [vcpkg version 2023.11.20](https://github.com/microsoft/vcpkg/archive/refs/tags/2023.11.20.zip) + * `cd ` + * `bootstrap-vcpkg.bat` + * install the libraries by running `vcpkg.exe install --triplet x64-windows libusb boost opencv dirent gtest glew glfw3 hdf5[cpp,threadsafe,tools,zlib]` + * Finally, download and install [ffmpeg](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z) and add the `bin` directory to your PATH. + +Note that if you are using vcpkg for various projects or multiple versions of OpenEB, you might want to optimize the +number of vcpkg install you manage. To do so, you will need the versions of the libraries we require. +Those can be found in the [vcpkg repository](https://github.com/microsoft/vcpkg/tree/2023.11.20/versions) but we list them here for convenience: + * libusb: 1.0.26 + * boost: 1.83.0 + * opencv: 4.8.0 + * dirent: 1.24.0 + * gtest: 1.14.0 + * glew: 2.2.0 + * glfw3: 3.3.8 + * hdf5: 1.14.2 + +#### Installing Python and libraries + +* Download "Windows x86-64 executable installer" for one of these Python versions: + * [Python 3.8](https://www.python.org/downloads/release/python-3810/) + * [Python 3.9](https://www.python.org/downloads/release/python-3913/) +* Add Python install and script directories in your `PATH` and make sure they are listed before + the `WindowsApps` folder which contains a Python alias launching the Microsoft Store. So, if you installed + Python 3.8 in the default path, your user `PATH` should contain those three lines in that order: + +```bash +%USERPROFILE%\AppData\Local\Programs\Python\Python38 +%USERPROFILE%\AppData\Local\Programs\Python\Python38\Scripts +%USERPROFILE%\AppData\Local\Microsoft\WindowsApps +```` + +Then install `pip` and some Python libraries: + +```bash +python -m pip install pip --upgrade +python -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" "h5py==3.7.0" pandas scipy +python -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner +``` + +#### Install pybind + +The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library. +You should install pybind using vcpkg in order to get the appropriate version: `vcpkg.exe install --triplet x64-windows pybind11` + +*Note* that pybind11 is required only if you plan to use the Python bindings of the C++ API. +You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 2 during compilation (see section "Compilation using CMake"). +In that case, you will not need to install pybind11, but you won't be able to use our Python interface to the C++ API. + +#### Prerequisites for the ML module + +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)](https://developer.nvidia.com/cuda-downloads) +and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) to leverage them with pytorch and libtorch. + +Then, you need to install [PyTorch 1.13.1](https://pytorch.org). +Retrieve and execute the pip command of version 1.13.1 from +the [previous versions install guide section](). + +Then install some extra Python libraries: + +```bash +python -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 + +First, retrieve the codebase: + +```bash +git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0 +``` + +Note that 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 generated ``Source.Code.*`` archives. This is because the latter do not include +a necessary submodule. + + +#### Compilation using CMake + +Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: + + 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` + 2. Generate the makefiles using CMake: `cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=`. + Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. + 3. Compile: `cmake --build . --config Release --parallel 4` + +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 (applications, samples, libraries etc.) in a directory of your choice. + +* Option 1 - working from `build` folder + + * To use OpenEB directly from the `build` folder, + you need to update some environment variables using this script: + + ```bash + utils\scripts\setup_env.bat + ``` + +* Option 2 - deploying in a directory of your choice + + * To deploy SDK Pro in the default folder (`C:\Program Files\Prophesee`), execute this command + (your console should be launched as an administrator): + + ```bash + cmake --build . --config Release --target install + ``` + + * To deploy OpenEB in another folder, you should generate the solution again (step 2 above) + with the additional variable `CMAKE_INSTALL_PREFIX` having the value of your target folder (`OPENEB_INSTALL_DIR`). + + Similarly, to specify where the Python packages will be deployed (``PYTHON3_PACKAGES_INSTALL_DIR``), you should use + the `PYTHON3_SITE_PACKAGES` variable. + + Here is an example of a command customizing those two folders: + + ```bash + cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DCMAKE_INSTALL_PREFIX= -DPYTHON3_SITE_PACKAGES= -DBUILD_TESTING=OFF + ``` + + After this command, you should launch the actual compilation and installation of OpenEB + (your console should be launched as an administrator): + + ```bash + cmake --build . --config Release --parallel 4 + cmake --build . --config Release --target install + ``` + + * You also need to manually edit some environment variables: + + * append `\bin` to `PATH` (`C:\Program Files\Prophesee\bin` if you used default configuration) + * append `\lib\metavision\hal\plugins` to `MV_HAL_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\metavision\hal\plugins` if you used default configuration) + * append `\lib\hdf5\plugin` to `HDF5_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\hdf5\plugin` if you used default configuration) + * append `` to `PYTHONPATH` (not needed if you used default configuration) + + +#### Compilation using MS Visual Studio + +Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: + + 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` + 2. Generate the Visual Studio files using CMake: `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=` (adapt to your Visual Studio version). + Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. + 3. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. + +Once the compilation is done, you can choose to work directly from the `build` folder +or you can deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice. + +* Option 1 - working from the `build` folder + + * To use OpenEB directly from the `build` folder, + you need to update the environment variables as done in the script `utils\scripts\setup_env.bat` + +* Option 2 - deploying OpenEB + + * To deploy OpenEB, you need to build the `INSTALL` project. + By default, files will be deployed in `C:\Program Files\Prophesee` + + +#### Camera Plugins + +Prophesee camera plugins are included in OpenEB, but you need to install the drivers +for the cameras to be available on Windows. To do so, follow this procedure: + +1. download [wdi-simple.exe from our file server](https://kdrive.infomaniak.com/app/share/975517/4f59e852-af5e-4e00-90fc-f213aad20edd) +2. execute the following commands in a Command Prompt launched as an administrator: + +```bash +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f4 +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f5 +wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f3 +``` + +If you own an EVK2 or an RDK2, there are a few additional steps to complete that are detailed in our online documentation +in the [Camera Plugin section of the OpenEB install guide](https://docs.prophesee.ai/stable/installation/windows_openeb.html#camera-plugins). + +If you are using a third-party camera, you need to follow the instructions provided by the camera vendor +to install the driver and the camera plugin. Make sure that you reference the location of the plugin in +the `MV_HAL_PLUGIN_PATH` environment variable. + + +#### Getting Started + +To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) +and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) +or you can stream data from your Prophesee-compatible event-based camera. + + +### Running the test suite (Optional) + +Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. + + * Download [the files](https://kdrive.infomaniak.com/app/share/975517/cddcc78a-3480-420f-bc19-17d5b0535ca4) necessary to run the tests. + Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. + + * Extract and put the content of this archive to `/datasets`. + For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. + + * To run the test suite you need to reconfigure your build environment using CMake and to recompile + + + * Compilation using CMake + + 1. Regenerate the build using CMake (note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one):: + + ``` + cd /build + cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON + ``` + 2. Compile: `cmake --build . --config Release --parallel 4` + + + * Compilation using MS Visual Studio + + 1. Generate the Visual Studio files using CMake (adapt the command to your Visual Studio version and note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one): + + `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON` -- [**Linux**](./docs/build-and-installation-guides/linux-build-test-and-installation.md) -- [**MacOS**](./docs/build-and-installation-guides/macos-build-test-and-installation.md) -- [**Windows**](./docs/build-and-installation-guides/windows-build-test-and-installation.md) + 2. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. -## Additional Resources -- [**Metavision SDK Docs**](https://docs.prophesee.ai/stable/index.html) -- [**Get started** guides for C++ and Python](https://docs.prophesee.ai/stable/get_started/index.html) -- [**Code samples** for API best practices](https://docs.prophesee.ai/stable/samples.html) -- [**Technical details** regarding modules and packaging](https://docs.prophesee.ai/stable/modules.html) + * Running the test suite is then simply `ctest -C Release` diff --git a/docs/build-and-installation-guides/linux-build-test-and-installation.md b/docs/build-and-installation-guides/linux-build-test-and-installation.md deleted file mode 100644 index 322f7d4a7..000000000 --- a/docs/build-and-installation-guides/linux-build-test-and-installation.md +++ /dev/null @@ -1,178 +0,0 @@ -# OpenEB Linux Build, Test, and Installation Guide -**In this guide** -- [Tested Configurations](#tested-configurations) -- [Build OpenEB C++ Binaries from Source](#build-and-install-openeb-binaries) -- [Install Python API Requirements](#install-python-api-requirements) -- [Upgrade OpenEB](#upgrade-openeb) - -## Tested Configurations -| Component | Configuration | -|-----------|----------| -| **OS** | Ubuntu 20.04 64-bit
Ubuntu 22.04 64-bit| -| **Architecture** | x64| -| **CPU** | with AVX2 support| -| **GPU** | with OpenGL +3.0 support -| **[Python3.8](https://www.python.org/downloads/release/python-3819/)**
**[Python3.9](https://www.python.org/downloads/release/python-3919/)** | Ubuntu 20.04 64-bit | -| **[Python3.9](https://www.python.org/downloads/release/python-3919/)**
**[Python3.10](https://www.python.org/downloads/release/python-31014/)** | Ubuntu 22.04 64-bit | - -Building OpenEB with component configurations other than what is listed above may require adjustments to this guide, or to the code itself. - -## Software Requirements -1. Run the command below to make sure you have the appropriate resources to use the Python API and build OpenEB binaries on your machine. - ```bash - sudo apt -y install \ - software-properties-common \ - libboost-all-dev \ - build-essential \ - libcanberra-gtk-module \ - cmake \ - ffmpeg \ - git \ - libglew-dev \ - libglfw3-dev \ - libhdf5-dev \ - hdf5-tools \ - libopencv-dev \ - libprotobuf-dev \ - protobuf-compiler \ - libusb-1.0-0-dev \ - unzip \ - apt-utils \ - wget - ``` -1. If you'll be using the Python API, Python bindings for C++, or any of the test applications, install Python3 and pybind11 as well. - ```bash - sudo apt -y install \ - python3.x \ - python3.x-dev \ - python3.x-distutils \ - python3.x-venv \ - python3-pip \ - python3-setuptools \ - python3-pybind11 - ``` - > **Note**: *For externally managed environments, activate a Python virtual environment and use it for all subsequent installation and build instructions.* - - Navigate to your development area and activate a Python virtual environment. - ```console - python3 -m venv .venv && \ - source .venv/bin/activate - ``` -1. Retrieve the latest OpenEB source, or your desired branch, and navigate into the project folder. - ```bash - git clone https://github.com/prophesee-ai/openeb.git && cd openeb - ``` -1. Once inside your OpenEB directory, create an environment variable to reference that location. - ```bash - export OPENEB_SRC_DIR=`pwd` - ``` -## Build OpenEB C++ Binaries from Source -### Initial Setup and Build Configuration -1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. -1. Create a build folder for the project files and navigate into the folder. - ```bash - mkdir build && cd build - ``` -1. Use CMake to create the build files for OpenEB. - ```bash - cmake .. - ``` - -#### Additional Build Configurations -When you build OpenEB you have the option to: -1. Enable/Disable test applications -1. Enable/Disable Python binding for C++ -1. Change the build type (`Release`, `Debug`, ect.) - -The table below describes CMake options that you can use to change the default build behavior. - -| CMake Configuration Option | Description | Default State | -|----------------------------|-------------|---------------| -| `BUILD_TESTING` | Enable/Disable Test Applications | `OFF` | -| `COMPILE_PYTHON3_BINDINGS` | Enable/Disable Python Bindings | `ON` | -| `CMAKE_BUILD_TYPE`| Change the build type | `Release` | - -Once you've completed the requirements for -any of the additional build configurations, use the option flags individually, or together, to set the state you desire. - -##### Test Applications -1. Complete steps 1→3 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) -1. Install the Google Test and `pytest` dependencies. - ```bash - sudo apt -y install \ - libgtest-dev \ - libgmock-dev \ - python3-pytest - ``` -1. Download the test files and place them in your OpenEB source directory using the command below. - ```bash - wget https://kdrive.infomaniak.com/2/app/975517/share/cddcc78a-3480-420f-bc19-17d5b0535ca4/archive/1aa2f344-7856-4f29-bd6a-21d7d78762bd/download -O /tmp/open-test-dataset.zip && \ - unzip /tmp/open-test-dataset.zip -d ${OPENEB_SRC_DIR}/datasets &&\ - rm /tmp/open-test-dataset.zip - ``` - > **NOTE**: *The total download file size is ~1.4GB.* -1. Enable the test applications using the CMake command and options below. - ```bash - cmake --fresh .. -DBUILD_TESTING=ON - ``` - -### Build, Test, and Install OpenEB Binaries -1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. -1. Build OpenEB on your machine. - ```bash - cmake --build . -j4 - ``` -1. **[Optional]** If testing was enabled in your build, you can now run the test suite. - ```bash - ctest --verbose - ``` -1. Install OpenEB. - - Use CMake to make the system path the installation target. - ```bash - sudo cmake --build . --target install - ``` - - Set an alternative installation target. - ```bash - sudo cmake --build . --target install -DCMAKE_INSTALL_PREFIX= - ``` -1. Update the necessary environment variables. - ```bash - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 - ``` - -## Install Python API Requirements -> **Note**: *Use of the Python API requires specific versions of Python. Refer to the [Tested Configurations](#tested-configurations) table to determine the version of Python that best suites your application needs.* - -1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. -1. Install the additional library dependencies using the requirements file. - ```bash - pip3 install -r ${OPENEB_SRC_DIR}/utils/python/requirements.txt - ``` -### Python API Machine Learning Requirements -Additional hardware, third-party software, and Python packages are required for using OpenEB machine learning (ML) features. -1. Follow all steps for [installing the Python API requirements](#install-python-api-requirements). -1. Ensure that your machine has, or is capable of running an Nvidia GPU that supports: - - [CUDA +11.6](https://developer.nvidia.com/cuda-downloads) - - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) - -1. Install the required [CUDA](https://developer.nvidia.com/cuda-downloads) and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) components once the hardware requirements are met. -1. Install [PyTorch +1.13.1](https://pytorch.org/get-started/locally/). -1. Install the additional Python packages for ML features. - ```bash - pip3 install -r ${OPENEB_SRC_DIR}/utils/python/ml-requirements.txt - ``` - > **Note**: *If you are using an externally managed environment, install the Python packages within your virtual environment* - - -## Upgrade OpenEB -To upgrade and existing installation of OpenEB: -1. Refer to our [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) before performing any upgrades to your existing OpenEB installation. -This will help you navigate changes such as API and firmware updates that can impact applications using the Metavision SDK and event-cameras. -1. Remove the previously installed OpenEB software. - ```bash - sudo make uninstall - ``` -1. Remove any remaining OpenEB files from your system's `PATH` and other environment variable locations (`PYTHONPATH` and `LD_LIBRARY_PATH`). -1. Follow the instructions to [build](#build-openeb-c-binaries-from-source) and [install](#install-openeb) OpenEB. - diff --git a/docs/build-and-installation-guides/macos-build-test-and-installation.md b/docs/build-and-installation-guides/macos-build-test-and-installation.md deleted file mode 100644 index 0658438e3..000000000 --- a/docs/build-and-installation-guides/macos-build-test-and-installation.md +++ /dev/null @@ -1,167 +0,0 @@ -# OpenEB MacOS Build, Test, and Installation Guide -**In this guide** -- [Tested Configurations](#tested-configurations) -- [Build OpenEB C++ Binaries from Source](#build-and-install-openeb-binaries) -- [Install Python API Requirements](#install-python-api-requirements) -- [Upgrade OpenEB](#upgrade-openeb) - -## Tested Configurations -| Component | Configuration | -|-----------|----------| -| **OS** | Monterey | -| **Architecture** | x64 | -| **CPU** | with AVX2 support | -| **GPU** | with OpenGL +3.0 support -| **[Python3.8](https://www.python.org/downloads/release/python-3819/)**
**[Python3.9](https://www.python.org/downloads/release/python-3919/)** | Ubuntu 20.04 64-bit | -| **[Python3.9](https://www.python.org/downloads/release/python-3919/)**
**[Python3.10](https://www.python.org/downloads/release/python-31014/)** | Ubuntu 22.04 64-bit | - -Building OpenEB with component configurations other than what is listed above may require adjustments to this guide, or to the code itself. - -## Software Requirements -This guide uses [Homebrew](https://brew.sh/) formulae to retrieve packages. It also requires that you have a working [C++ compiler](https://developer.apple.com/xcode/cpp/). -1. Run the command below to make sure you have the appropriate resources to use the build OpenEB binaries on your machine. - ```console - brew install \ - boost \ - cmake \ - eigen \ - ffmpeg \ - git \ - glew \ - glfw \ - hdf5 \ - opencv \ - protobuf \ - libusb - ``` -1. If you'll be using the Python API, Python bindings for C++, or any of the test applications, install Python3 and pybind11 as well. - ```console - brew install \ - python3 \ - pybind11 - ``` - - > **Note**: *For externally managed environments, activate a Python virtual environment and use it for subsequent installation and build instructions.* - - Navigate to your development area and activate a Python virtual environment. - ```console - python3 -m venv .venv && \ - source .venv/bin/activate - ``` -1. Retrieve the latest [OpenEB source](https://github.com/prophesee-ai/openeb), or your desired branch, and navigate into the project folder. - ```console - git clone https://github.com/prophesee-ai/openeb.git && cd openeb - ``` -1. Once inside your OpenEB directory, create an environment variable to reference that location. - ```console - export OPENEB_SRC_DIR=`pwd` - ``` -## Build OpenEB C++ Binaries from Source -### Initial Setup and Build Configuration -1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. -1. Create a build folder for the project files and navigate into the folder. - ```console - mkdir build && cd build - ``` -1. Use CMake to create the build files for OpenEB. - ```console - cmake .. - ``` - -#### Additional Build Configurations -When you build OpenEB you have the option to: -1. Enable/Disable test applications -1. Enable/Disable Python binding for C++ -1. Change the build type (`Release`, `Debug`, ect.) - -The table below describes CMake options that you can use to change the default build behavior. - -| CMake Configuration Option | Description | Default State | -|----------------------------|-------------|---------------| -| `BUILD_TESTING` | Enable/Disable Test Applications | `OFF` | -| `COMPILE_PYTHON3_BINDINGS` | Enable/Disable Python Bindings | `ON` | -| `CMAKE_BUILD_TYPE`| Change the build type | `Release` | - -Once you've completed the requirements for -any of the additional build configurations, use the option flags individually, or together, to set the state you desire. - -##### Test Applications -1. Complete steps 1→3 of the [initial setup and build configuration.](#initial-setup-and-build-configuration) -1. Install the Google Test and `pytest` dependencies. - ```console - brew install googletest && \ - pip3 install pytest - ``` -1. Download the test files and place them in your OpenEB source directory using the command below. - ```console - wget https://kdrive.infomaniak.com/2/app/975517/share/cddcc78a-3480-420f-bc19-17d5b0535ca4/archive/1aa2f344-7856-4f29-bd6a-21d7d78762bd/download -O /tmp/open-test-dataset.zip && \ - unzip /tmp/open-test-dataset.zip -d ${OPENEB_SRC_DIR}/datasets &&\ - rm /tmp/open-test-dataset.zip - ``` - > **NOTE**: *The total download file size is ~1.4GB.* -1. Enable the test applications using the CMake command and options below. - ```console - cmake --fresh .. -DBUILD_TESTING=ON - ``` - - -### Build, Test, and Install OpenEB Binaries -1. Follow the step in the [Initial Setup and Build Configuration](#initial-setup-and-build-configuration) section to create the build files that best suite your needs. -1. Build OpenEB on your machine. - ```console - cmake --build . -j4 - ``` -1. **[Optional]** If testing was enabled in your build, you can now run the test suite. - ```console - ctest --verbose - ``` -1. Install OpenEB. - - Use CMake to make the system path the installation target. - ```console - sudo cmake --build . --target install - ``` - - Set an alternative installation target. - ```console - sudo cmake --build . --target install -DCMAKE_INSTALL_PREFIX= - ``` -1. Update the necessary environment variables. - ```console - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/lib/hdf5/plugin # On Ubuntu 20.04 - export HDF5_PLUGIN_PATH=$HDF5_PLUGIN_PATH:/usr/local/hdf5/lib/plugin # On Ubuntu 22.04 - ``` - -## Install Python API Requirements -> **Note**: *Use of the Python API requires specific versions of Python. Refer to the [Tested Configurations](#tested-configurations) table to determine the version of Python that best suites your application needs.* - -1. Follow the [Software Requirements](#software-requirements) section to setup your machine and retrieve the OpenEB source code. -1. Install the additional library dependencies using the requirements file. - ```console - pip3 install -r ${OPENEB_SRC_DIR}/utils/python/requirements.txt - ``` -### Python API Machine Learning Requirements -Additional hardware, third-party software, and Python packages are required for using OpenEB machine learning (ML) features. -1. Follow all steps for [installing the Python API requirements](#install-python-api-requirements). -1. Ensure that your machine has, or is capable of running an Nvidia GPU that supports: - - [CUDA +11.6](https://developer.nvidia.com/cuda-downloads) - - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) - -1. Install the required [CUDA](https://developer.nvidia.com/cuda-downloads) and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/latest/installation/overview.html) components once the hardware requirements are met. -1. Install [PyTorch +1.13.1](https://pytorch.org/get-started/locally/). -1. Install the additional Python packages for ML features. - ```console - pip3 install -r ${OPENEB_SRC_DIR}/utils/python/ml-requirements.txt - ``` - > **Note**: *If you are using an externally managed environment, install the Python packages within your virtual environment* - - -## Upgrade OpenEB -To upgrade and existing installation of OpenEB: -1. Refer to our [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) before performing any upgrades to your existing OpenEB installation. -This will help you navigate changes such as API and firmware updates that can impact applications using the Metavision SDK and event-cameras. -1. Remove the previously installed OpenEB software. - ```console - sudo make uninstall - ``` -1. Remove any remaining OpenEB files from your system's `PATH` and other environment variable locations (`PYTHONPATH` and `LD_LIBRARY_PATH`). -1. Follow the instructions to [build](#build-openeb-c-binaries-from-source) and [install](#install-openeb) OpenEB. - diff --git a/docs/build-and-installation-guides/windows-build-test-and-installation.md b/docs/build-and-installation-guides/windows-build-test-and-installation.md deleted file mode 100644 index 6eee486f9..000000000 --- a/docs/build-and-installation-guides/windows-build-test-and-installation.md +++ /dev/null @@ -1,260 +0,0 @@ -# OpenEB Windows Build, Test, and Installation Guide - -Currently, we support only Windows 10. -Compilation on other versions of Windows was not tested. -For those platforms some adjustments to this guide or to the code itself may be required. - -### Upgrading OpenEB - -If you are upgrading OpenEB from a previous version, you should first read carefully the [Release Notes](https://docs.prophesee.ai/stable/release_notes.html) -as some changes may impact your usage of our SDK (e.g. [API](https://docs.prophesee.ai/stable/api.html) updates) -and cameras (e.g. [firmware update](https://support.prophesee.ai/portal/en/kb/articles/evk-firmware-versions) might be necessary). - -Then, if you have previously installed any Prophesee's software, you will need to uninstall it first. -Remove the folders where you installed Metavision artifacts (check both the `build` folder of the source code and -`C:\Program Files\Prophesee` which is the default install path of the deployment step). - -### Prerequisites - -Some steps of this procedure don't work on FAT32 and exFAT file system. -Hence, make sure that you are using a NTFS file system before going further. - -You must enable the support for long paths: - * Hit the Windows key, type gpedit.msc and press Enter - * Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem - * Double-click the "Enable Win32 long paths" option, select the "Enabled" option and click "OK" - -To compile OpenEB, you will need to install some extra tools: - - * install [git](https://git-scm.com/download/win) - * install [CMake 3.21](https://cmake.org/files/v3.21/cmake-3.21.7-windows-x86_64.msi) - * install Microsoft C++ compiler (64-bit). You can choose one of the following solutions: - * For building only, you can install MS Build Tools (free, part of Windows 10 SDK package) - * Download and run ["Build tools for Visual Studio 2022" installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) - * Select "C++ build tools", make sure Windows 10 SDK is checked, and add English Language Pack - * For development, you can also download and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) - * install [vcpkg](https://github.com/microsoft/vcpkg) that will be used for installing dependencies: - * download and extract [vcpkg version 2023.11.20](https://github.com/microsoft/vcpkg/archive/refs/tags/2023.11.20.zip) - * `cd ` - * `bootstrap-vcpkg.bat` - * install the libraries by running `vcpkg.exe install --triplet x64-windows libusb boost opencv dirent gtest glew glfw3 hdf5[cpp,threadsafe,tools,zlib]` - * Finally, download and install [ffmpeg](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z) and add the `bin` directory to your PATH. - -Note that if you are using vcpkg for various projects or multiple versions of OpenEB, you might want to optimize the -number of vcpkg install you manage. To do so, you will need the versions of the libraries we require. -Those can be found in the [vcpkg repository](https://github.com/microsoft/vcpkg/tree/2023.11.20/versions) but we list them here for convenience: - * libusb: 1.0.26 - * boost: 1.83.0 - * opencv: 4.8.0 - * dirent: 1.24.0 - * gtest: 1.14.0 - * glew: 2.2.0 - * glfw3: 3.3.8 - * hdf5: 1.14.2 - -#### Installing Python and libraries - -* Download "Windows x86-64 executable installer" for one of these Python versions: - * [Python 3.8](https://www.python.org/downloads/release/python-3810/) - * [Python 3.9](https://www.python.org/downloads/release/python-3913/) -* Add Python install and script directories in your `PATH` and make sure they are listed before - the `WindowsApps` folder which contains a Python alias launching the Microsoft Store. So, if you installed - Python 3.8 in the default path, your user `PATH` should contain those three lines in that order: - -```bash -%USERPROFILE%\AppData\Local\Programs\Python\Python38 -%USERPROFILE%\AppData\Local\Programs\Python\Python38\Scripts -%USERPROFILE%\AppData\Local\Microsoft\WindowsApps -```` - -Then install `pip` and some Python libraries: - -```bash -python -m pip install pip --upgrade -python -m pip install "opencv-python==4.5.5.64" "sk-video==1.1.10" "fire==0.4.0" "numpy==1.23.4" "h5py==3.7.0" pandas scipy -python -m pip install jupyter jupyterlab matplotlib "ipywidgets==7.6.5" pytest command_runner -``` - -#### Install pybind - -The Python bindings of the C++ API rely on the [pybind11](https://github.com/pybind) library. -You should install pybind using vcpkg in order to get the appropriate version: `vcpkg.exe install --triplet x64-windows pybind11` - -*Note* that pybind11 is required only if you plan to use the Python bindings of the C++ API. -You can opt out of creating these bindings by passing the argument `-DCOMPILE_PYTHON3_BINDINGS=OFF` at step 2 during compilation (see section "Compilation using CMake"). -In that case, you will not need to install pybind11, but you won't be able to use our Python interface to the C++ API. - -#### Prerequisites for the ML module - -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)](https://developer.nvidia.com/cuda-downloads) -and [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html) to leverage them with pytorch and libtorch. - -Then, you need to install [PyTorch 1.13.1](https://pytorch.org). -Retrieve and execute the pip command of version 1.13.1 from -the [previous versions install guide section](). - -Then install some extra Python libraries: - -```bash -python -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 - -First, retrieve the codebase: - -```bash -git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.1 -``` - -Note that 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 generated ``Source.Code.*`` archives. This is because the latter do not include -a necessary submodule. - - -#### Compilation using CMake - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the makefiles using CMake: `cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=`. - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Compile: `cmake --build . --config Release --parallel 4` - -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 (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update some environment variables using this script: - - ```bash - utils\scripts\setup_env.bat - ``` - -* Option 2 - deploying in a directory of your choice - - * To deploy OpenEB in the default folder (`C:\Program Files\Prophesee`), execute this command - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --target install - ``` - - * To deploy OpenEB in another folder, you should generate the solution again (step 2 above) - with the additional variable `CMAKE_INSTALL_PREFIX` having the value of your target folder (`OPENEB_INSTALL_DIR`). - - Similarly, to specify where the Python packages will be deployed (``PYTHON3_PACKAGES_INSTALL_DIR``), you should use - the `PYTHON3_SITE_PACKAGES` variable. - - Here is an example of a command customizing those two folders: - - ```bash - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DCMAKE_INSTALL_PREFIX= -DPYTHON3_SITE_PACKAGES= -DBUILD_TESTING=OFF - ``` - - After this command, you should launch the actual compilation and installation of OpenEB - (your console should be launched as an administrator): - - ```bash - cmake --build . --config Release --parallel 4 - cmake --build . --config Release --target install - ``` - - * You also need to manually edit some environment variables: - - * append `\bin` to `PATH` (`C:\Program Files\Prophesee\bin` if you used default configuration) - * append `\lib\metavision\hal\plugins` to `MV_HAL_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\metavision\hal\plugins` if you used default configuration) - * append `\lib\hdf5\plugin` to `HDF5_PLUGIN_PATH` (`C:\Program Files\Prophesee\lib\hdf5\plugin` if you used default configuration) - * append `` to `PYTHONPATH` (not needed if you used default configuration) - - -#### Compilation using MS Visual Studio - -Open a command prompt inside the `openeb` folder (absolute path to this directory is called `OPENEB_SRC_DIR` in next sections) and do as follows: - - 1. Create and open the build directory, where temporary files will be created: `mkdir build && cd build` - 2. Generate the Visual Studio files using CMake: `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY=` (adapt to your Visual Studio version). - Note that the value passed to the parameter `-DCMAKE_TOOLCHAIN_FILE` must be an absolute path, not a relative one. - 3. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - -Once the compilation is done, you can choose to work directly from the `build` folder -or you can deploy the OpenEB files (applications, samples, libraries etc.) in a directory of your choice. - -* Option 1 - working from the `build` folder - - * To use OpenEB directly from the `build` folder, - you need to update the environment variables as done in the script `utils\scripts\setup_env.bat` - -* Option 2 - deploying OpenEB - - * To deploy OpenEB, you need to build the `INSTALL` project. - By default, files will be deployed in `C:\Program Files\Prophesee` - - -#### Camera Plugins - -Prophesee camera plugins are included in OpenEB, but you need to install the drivers -for the cameras to be available on Windows. To do so, follow this procedure: - -1. download [wdi-simple.exe from our file server](https://files.prophesee.ai/share/dists/public/drivers/FeD45ki5/wdi-simple.exe) -2. execute the following commands in a Command Prompt launched as an administrator: - -```bash -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f4 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f5 -wdi-simple.exe -n "EVK" -m "Prophesee" -v 0x04b4 -p 0x00f3 -``` - -If you own an EVK2 or an RDK2, there are a few additional steps to complete that are detailed in our online documentation -in the [Camera Plugin section of the OpenEB install guide](https://docs.prophesee.ai/stable/installation/windows_openeb.html#camera-plugins). - -If you are using a third-party camera, you need to follow the instructions provided by the camera vendor -to install the driver and the camera plugin. Make sure that you reference the location of the plugin in -the `MV_HAL_PLUGIN_PATH` environment variable. - - -#### Getting Started - -To get started with OpenEB, you can download some [sample recordings](https://docs.prophesee.ai/stable/datasets.html) -and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/samples/modules/driver/viewer.html) -or you can stream data from your Prophesee-compatible event-based camera. - - -### Running the test suite (Optional) - -Running the test suite is a sure-fire way to ensure you did everything well with your compilation and installation process. - - * Download [the files](https://dataset.prophesee.ai/index.php/s/tiP0wl0r5aW5efL) necessary to run the tests. - Click `Download` on the top right folder. Beware of the size of the obtained archive which weighs around 1.2 Gb. - - * Extract and put the content of this archive to `/datasets`. - For instance, the correct path of sequence `gen31_timer.raw` should be `/datasets/openeb/gen31_timer.raw`. - - * To run the test suite you need to reconfigure your build environment using CMake and to recompile - - - * Compilation using CMake - - 1. Regenerate the build using CMake (note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one):: - - ``` - cd /build - cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON - ``` - 2. Compile: `cmake --build . --config Release --parallel 4` - - - * Compilation using MS Visual Studio - - 1. Generate the Visual Studio files using CMake (adapt the command to your Visual Studio version and note that `-DCMAKE_TOOLCHAIN_FILE` must be absolute path, not a relative one): - - `cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=\cmake\toolchains\vcpkg.cmake -DVCPKG_DIRECTORY= -DBUILD_TESTING=ON` - - 2. Open the solution file `metavision.sln`, select the `Release` configuration and build the `ALL_BUILD` project. - - * Running the test suite is then simply `ctest -C Release` From 19405b8144755b34a5b5f13fa828807f1f70b555 Mon Sep 17 00:00:00 2001 From: coashby <8316079+coashby@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:57:21 -0400 Subject: [PATCH 15/15] Updating the README to the correct version. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c2d06c5f3..68c011934 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ python3 -m pip install "numba==0.56.3" "profilehooks==1.12.0" "pytorch_lightning ### Compilation - 1. Retrieve the code: `git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0`. + 1. Retrieve the code: `git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.2`. (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 generated ``Source.Code.*`` archives. This is because the latter do not include @@ -324,7 +324,7 @@ python -m pip install "numba==0.56.3" "profilehooks==1.12.0" "pytorch_lightning= First, retrieve the codebase: ```bash -git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.0 +git clone https://github.com/prophesee-ai/openeb.git --branch 4.6.2 ``` Note that if you choose to download an archive of OpenEB from GitHub rather than cloning the repository, @@ -356,7 +356,7 @@ or you can deploy the OpenEB files (applications, samples, libraries etc.) in a * Option 2 - deploying in a directory of your choice - * To deploy SDK Pro in the default folder (`C:\Program Files\Prophesee`), execute this command + * To deploy OpenEB in the default folder (`C:\Program Files\Prophesee`), execute this command (your console should be launched as an administrator): ```bash