Merge pull request #63 from prophesee-ai/v3.1.0-to-main

[3.1.0] Import 4c19f90e13c

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,7 +12,7 @@ If you encounter an issue, please attempt the following steps :
 * make sure you are using the last version of OpenEB
 
 If the earlier steps didn't solve the problem, raise an issue providing:
-* information about your system with [Metavision Platform Info Application](https://docs.prophesee.ai/stable/metavision_sdk/modules/metavision_hal/samples/platform_info.html)
+* information about your system with [Metavision Platform Info Application](https://docs.prophesee.ai/stable/metavision_sdk/modules/hal/samples/platform_info.html)
 * your operating system and its version
 * your camera type and its serial number that can be found on your camera's base (bottom) plate
 * software that has an issue, expected and actual behavior, and reproduction steps as detailed as possible 

CMakeLists.txt

@@ -9,7 +9,7 @@
 
 cmake_minimum_required(VERSION 3.5)
 
-project(metavision VERSION 3.0.2)
+project(metavision VERSION 3.1.0)
 set(PROJECT_VERSION_SUFFIX "")
 
 if(PROJECT_VERSION_SUFFIX STREQUAL "")
@@ -244,6 +244,7 @@ if (BUILD_TESTING)
     endif(CMAKE_CROSSCOMPILING)
 
     lfs_download(datasets/openeb/gen31_timer.raw)
+    lfs_download(datasets/openeb/gen31_timer_holes.raw)
     lfs_download(datasets/openeb/gen4_evt2_hand.raw)
     lfs_download(datasets/openeb/gen4_evt3_hand.raw)
     if(COMPILE_PYTHON3_BINDINGS)

README.md

@@ -17,7 +17,7 @@ OpenEB is composed of the Open modules of Metavision Intelligence:
 
 OpenEB also contains the source code of Prophesee camera plugins, enabling to stream data from our event-based cameras
 and to read recordings of event-based data. The supported cameras are:
-* EVK1 - Gen3.1 VGA
+* EVK1 - Gen3/Gen3.1 VGA
 * EVK2 - Gen4.1 HD
 * EVK3 - Gen 3.1 VGA / Gen4.1 HD
 * EVK4 - HD
@@ -131,7 +131,8 @@ with the following command: `sudo cmake --build . --target install`. In that cas
 permanently, you should add the previous command in your ~/.bashrc)
 
 *Note* that since OpenEB 3.0.0, Prophesee camera plugins are included in the OpenEB repository, so you don't need to perform
-any extra step to install them. 
+any extra step to install them. 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/metavision_sdk/modules/driver/guides/viewer.html#chapter-sdk-driver-samples-viewer)
@@ -187,6 +188,17 @@ To compile OpenEB, you will need to install some extra tools:
       you can run `setx VCPKG_DEFAULT_TRIPLET x64-windows` (you need to close the command line and re-open it to ensure that this variable is set)
   * 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/2022.03.10/versions) but we list them here for convenience:
+  * libusb: 1.0.24
+  * eigen3: 3.4.0
+  * boost: 1.78.0
+  * opencv: 4.5.5
+  * glfw3: 3.3.6
+  * glew: 2.2.0
+  * gtest: 1.11.0
+  * dirent: 1.23.2
 
 #### Install pybind
 
@@ -299,7 +311,8 @@ and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/met
 or you can stream data from your Prophesee-compatible event-based camera.
 
 *Note* that since OpenEB 3.0.0, Prophesee camera plugins are included in the OpenEB repository, so you don't need to perform
-any extra step to install them.
+any extra step to install them. If you are using a third-party camera, you need to install the plugin provided
+by the camera vendor and specify the location of the plugin using the `MV_HAL_PLUGIN_PATH` environment variable.
 
 ### Running the test suite (Optional)
 

cmake/custom_functions/add_library_version_header.cmake

@@ -8,8 +8,8 @@
 # See the License for the specific language governing permissions and limitations under the License.
 
 set(GIT_BRANCH "main")
-set(GIT_COMMIT_ID "f3107c5b0cfacb2ab97aa78ebefcdc3b4992c7c0")
-set(GIT_COMMIT_DATE "2022-06-29 13:53:08 +0200")
+set(GIT_COMMIT_ID "4c19f90e13c20548513c88b89c4e58bc8de8a1bf")
+set(GIT_COMMIT_DATE "2022-10-13 16:56:39 +0200")
 
 # If git information are not provided in command line when running cmake, try to automatically determine them
 if(NOT GIT_BRANCH OR NOT GIT_COMMIT_ID OR NOT GIT_COMMIT_DATE)

cmake/custom_functions/python3.cmake

@@ -61,7 +61,7 @@ if (COMPILE_PYTHON3_BINDINGS)
         endforeach()
     else()
         find_package(Python3 COMPONENTS Interpreter Development REQUIRED)
-        string(SUBSTRING "${Python3_VERSION}" 0 3 _short_python3_version)
+        string(CONCAT _short_python3_version "${Python3_VERSION_MAJOR}" "." "${Python3_VERSION_MINOR}")
         set(PYBIND11_PYTHON_VERSIONS "${_short_python3_version}")
         set(PYTHON_${_short_python3_version}_EXECUTABLE ${Python3_EXECUTABLE} CACHE PATH "")
         _add_global_alias_library(Python3::Python Python3::Python_${_short_python3_version})

cmake/custom_targets/README_metavision_open.md

@@ -17,7 +17,7 @@ OpenEB is composed of the Open modules of Metavision Intelligence:
 
 OpenEB also contains the source code of Prophesee camera plugins, enabling to stream data from our event-based cameras
 and to read recordings of event-based data. The supported cameras are:
-* EVK1 - Gen3.1 VGA
+* EVK1 - Gen3/Gen3.1 VGA
 * EVK2 - Gen4.1 HD
 * EVK3 - Gen 3.1 VGA / Gen4.1 HD
 * EVK4 - HD
@@ -131,7 +131,8 @@ with the following command: `sudo cmake --build . --target install`. In that cas
 permanently, you should add the previous command in your ~/.bashrc)
 
 *Note* that since OpenEB 3.0.0, Prophesee camera plugins are included in the OpenEB repository, so you don't need to perform
-any extra step to install them. 
+any extra step to install them. 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/metavision_sdk/modules/driver/guides/viewer.html#chapter-sdk-driver-samples-viewer)
@@ -187,6 +188,17 @@ To compile OpenEB, you will need to install some extra tools:
       you can run `setx VCPKG_DEFAULT_TRIPLET x64-windows` (you need to close the command line and re-open it to ensure that this variable is set)
   * 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/2022.03.10/versions) but we list them here for convenience:
+  * libusb: 1.0.24
+  * eigen3: 3.4.0
+  * boost: 1.78.0
+  * opencv: 4.5.5
+  * glfw3: 3.3.6
+  * glew: 2.2.0
+  * gtest: 1.11.0
+  * dirent: 1.23.2
 
 #### Install pybind
 
@@ -299,7 +311,8 @@ and visualize them with [metavision_viewer](https://docs.prophesee.ai/stable/met
 or you can stream data from your Prophesee-compatible event-based camera.
 
 *Note* that since OpenEB 3.0.0, Prophesee camera plugins are included in the OpenEB repository, so you don't need to perform
-any extra step to install them.
+any extra step to install them. If you are using a third-party camera, you need to install the plugin provided
+by the camera vendor and specify the location of the plugin using the `MV_HAL_PLUGIN_PATH` environment variable.
 
 ### Running the test suite (Optional)
 

hal/cpp/include/metavision/hal/facilities/future/i_decoder.h

@@ -21,6 +21,7 @@
 #include "metavision/sdk/base/utils/timestamp.h"
 #include "metavision/hal/facilities/i_event_decoder.h"
 #include "metavision/hal/facilities/i_registrable_facility.h"
+#include "metavision/hal/utils/decoder_protocol_violation.h"
 #include "metavision/sdk/base/events/event_cd.h"
 #include "metavision/sdk/base/events/event_ext_trigger.h"
 
@@ -70,6 +71,22 @@ class I_Decoder : public I_RegistrableFacility<I_Decoder> {
     /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
     bool remove_time_callback(size_t callback_id);
 
+    /// @brief Alias for callback on protocol violation
+    using ProtocolViolationCallback_t = std::function<void(DecoderProtocolViolation)>;
+
+    /// @brief Adds a function to be called when decoder protocol is breached
+    /// @param cb Callback to add
+    /// @return ID of the added callback
+    /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
+    /// @note It's not allowed to add/remove a callback from the callback itself
+    virtual size_t add_protocol_violation_callback(const ProtocolViolationCallback_t &cb);
+
+    /// @brief Removes a previously registered protocol violation callback
+    /// @param callback_id Callback ID
+    /// @return true if the callback has been unregistered correctly, false otherwise.
+    /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
+    virtual bool remove_protocol_violation_callback(size_t callback_id);
+
     /// @brief Gets the timestamp of the last event
     /// @return Timestamp of the last event
     virtual timestamp get_last_timestamp() const = 0;
@@ -90,6 +107,9 @@ class I_Decoder : public I_RegistrableFacility<I_Decoder> {
 
     /// @brief Resets the decoder last timestamp
     /// @param timestamp Timestamp to reset the decoder to
+    ///        If >= 0, reset the decoder last timestamp to the actual value @p timestamp
+    ///        If < 0, reset the decoder internal state so that the last timestamp will be found from the
+    ///        next buffer of events to decoder (the timestamp shift and overflow loop counter is not reset)
     /// @return True if the reset operation could complete, false otherwise.
     /// @note It is expected after this call has succeeded, that @ref get_last_timestamp returns @p timestamp
     /// @warning If time shifting is enabled, the @p timestamp must be in the shifted time reference
@@ -166,6 +186,9 @@ class I_Decoder : public I_RegistrableFacility<I_Decoder> {
 
     /// @brief Implementation of "reset the decoder last timestamp" operation
     /// @param timestamp Timestamp to reset the decoder to
+    ///        If >= 0, reset the decoder last timestamp to the actual value @p timestamp
+    ///        If < 0, reset the decoder internal state so that the last timestamp will be found from the
+    ///        next buffer of events to decoder (the timestamp shift and overflow loop counter is not reset)
     /// @return True if the reset operation could complete, false otherwise.
     /// @note It is expected after this call has succeeded, that @ref get_last_timestamp returns @p timestamp
     /// @warning If time shifting is enabled, the @p timestamp must be in the shifted time reference

hal/cpp/include/metavision/hal/facilities/i_antiflicker_module.h

@@ -19,7 +19,7 @@
 namespace Metavision {
 
 /// @brief Anti-flicker module
-/// @note This feature is available only on Gen4.1 sensors
+/// @note This feature is available only on Gen4.1 sensors and newer
 class I_AntiFlickerModule : public I_RegistrableFacility<I_AntiFlickerModule> {
 public:
     /// @brief Enables the anti-flicker filter

hal/cpp/include/metavision/hal/facilities/i_decoder.h

@@ -20,6 +20,7 @@
 #include "metavision/sdk/base/utils/timestamp.h"
 #include "metavision/hal/facilities/i_event_decoder.h"
 #include "metavision/hal/facilities/i_registrable_facility.h"
+#include "metavision/hal/utils/decoder_protocol_violation.h"
 #include "metavision/sdk/base/events/event_cd.h"
 #include "metavision/sdk/base/events/event_ext_trigger.h"
 
@@ -68,6 +69,22 @@ class I_Decoder : public I_RegistrableFacility<I_Decoder> {
     /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
     bool remove_time_callback(size_t callback_id);
 
+    /// @brief Alias for callback on protocol violation
+    using ProtocolViolationCallback_t = std::function<void(DecoderProtocolViolation)>;
+
+    /// @brief Adds a function to be called when decoder protocol is breached
+    /// @param cb Callback to add
+    /// @return ID of the added callback
+    /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
+    /// @note It's not allowed to add/remove a callback from the callback itself
+    virtual size_t add_protocol_violation_callback(const ProtocolViolationCallback_t &cb);
+
+    /// @brief Removes a previously registered protocol violation callback
+    /// @param callback_id Callback ID
+    /// @return true if the callback has been unregistered correctly, false otherwise.
+    /// @note This method is not thread safe. You should add/remove the various callback before starting the streaming
+    virtual bool remove_protocol_violation_callback(size_t callback_id);
+
     /// @brief Gets the timestamp of the last event
     /// @return Timestamp of the last event
     virtual timestamp get_last_timestamp() const = 0;
@@ -77,6 +94,7 @@ class I_Decoder : public I_RegistrableFacility<I_Decoder> {
     /// If the timestamp shift (timestamp of the first event in the stream) is already known,
     /// the function returns true and the parameter @p timestamp_shift will be set to its value.
     /// Otherwise, the function returns false and does nothing.
+    ///
     /// @return true if the timestamp shift is already known, false otherwise
     virtual bool get_timestamp_shift(Metavision::timestamp &timestamp_shift) const = 0;
 

hal/cpp/include/metavision/hal/facilities/i_device_control.h

@@ -38,20 +38,23 @@ class I_DeviceControl : public I_RegistrableFacility<I_DeviceControl> {
     /// @brief Sets the camera in standalone mode.
     ///
     /// The camera does not interact with other devices.
+    ///
     /// @warning This function must be called before starting the camera
     /// @return true on success
     virtual bool set_mode_standalone() = 0;
 
     /// @brief Sets the camera as master
     ///
     /// The camera sends clock signal to another device
+    ///
     /// @warning This function must be called before starting the camera
     /// @return true on success
     virtual bool set_mode_master() = 0;
 
     /// @brief Sets the camera as slave
     ///
     /// The camera receives the clock from another device
+    ///
     /// @warning This function must be called before starting the camera
     /// @return true on success
     virtual bool set_mode_slave() = 0;

hal/cpp/include/metavision/hal/facilities/i_events_stream.h

@@ -18,6 +18,7 @@
 #include <mutex>
 #include <condition_variable>
 #include <queue>
+#include <unordered_set>
 
 #include "metavision/hal/facilities/i_registrable_facility.h"
 #include "metavision/hal/utils/data_transfer.h"
@@ -63,6 +64,7 @@ class I_EventsStream : public I_RegistrableFacility<I_EventsStream> {
     /// @brief Gets latest raw data from the event buffer
     ///
     /// Gets raw data from the event buffer received since the last time this function was called.
+    ///
     /// @param n_rawbytes Address of a variable in which to put the number of bytes contained in the buffer
     /// @return Pointer to an array of Event structures
     /// @note This function must be called to write the buffer of events in the log file defined in @ref log_raw_data
@@ -73,6 +75,7 @@ class I_EventsStream : public I_RegistrableFacility<I_EventsStream> {
     /// This methods first writes the header retrieved through @ref I_HW_Identification.
     /// Buffers of data are then written each time @ref get_latest_raw_data is called (i.e. in the same thread it is
     /// called).
+    ///
     /// @param f The file to log into
     /// @return true if the file could be opened for writing, false otherwise or if the file name @a f is the same as
     /// the one read from
@@ -109,7 +112,7 @@ class I_EventsStream : public I_RegistrableFacility<I_EventsStream> {
     // buffer pool full when resuming streaming
     const bool stop_should_release_buffers_;
     DataTransfer::BufferPool tmp_buffer_pool_;
-    std::vector<DataTransfer::BufferPtr::element_type *>
+    std::unordered_set<DataTransfer::BufferPtr::element_type *>
         data_transfer_buffer_ptrs_; // for quick check if copying is necessary
 
     std::mutex start_stop_safety_;

hal/cpp/include/metavision/hal/facilities/i_trigger_in.h

@@ -22,20 +22,20 @@ namespace Metavision {
 class I_TriggerIn : public I_RegistrableFacility<I_TriggerIn> {
 public:
     /// @brief Enables external trigger monitoring
-    /// @param channel External trigger's address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)
+    /// @param channel External trigger's address (depends on the camera and sensor; see camera's documentation)
     /// @return true if trigger was successfully enabled, false otherwise
     /// @warning Trigger monitoring is disabled by default on camera start.
     /// So you need to call ``enable()`` to start detecting signal.
     virtual bool enable(uint32_t channel) = 0;
 
     /// @brief Disables external trigger monitoring
-    /// @param channel External trigger's address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)
+    /// @param channel External trigger's address (depends on the camera and sensor; see camera's documentation)
     /// @return true if trigger was successfully disabled, false otherwise
     virtual bool disable(uint32_t channel) = 0;
 
-    /// @brief Checks if the trigger in index is enabled
-    /// @return true if the trigger in index is enabled, False otherwise
-    virtual bool is_enabled(uint32_t index) = 0;
+    /// @brief Checks if the trigger in channel is enabled
+    /// @return true if the trigger in channel is enabled, False otherwise
+    virtual bool is_enabled(uint32_t channel) = 0;
 };
 
 } // namespace Metavision