Merge pull request #81 from prophesee-ai/v4.1.0-to-main

[v4.1.0] Release update

CMakeLists.txt

@@ -17,7 +17,7 @@ endif(NOT CMAKE_BUILD_TYPE)
 
 cmake_minimum_required(VERSION 3.5)
 
-project(metavision VERSION 4.0.1)
+project(metavision VERSION 4.1.0)
 set(PROJECT_VERSION_SUFFIX "")
 
 if(PROJECT_VERSION_SUFFIX STREQUAL "")

README.md

@@ -131,7 +131,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.0.1`.
+ 1. Retrieve the code `git clone https://github.com/prophesee-ai/openeb.git --branch 4.1.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
@@ -322,7 +322,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.0.1
+git clone https://github.com/prophesee-ai/openeb.git --branch 4.1.0
 ```
 
 Note that if you choose to download an archive of OpenEB from GitHub rather than cloning the repository,

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 "7b1f92e06fe2ecc12cfd99297d2b171d673eab48")
-set(GIT_COMMIT_DATE "2023-04-20 13:39:06 +0200")
+set(GIT_COMMIT_ID "1c455ed1cbfc8ec26cae354b8da911c2d0d61ecb")
+set(GIT_COMMIT_DATE "2023-05-15 10:39:05 +0200")
 
 find_program(GIT_SCM git DOC "Git version control" HINTS "C:\\Program Files\\Git\\bin\\")
 

cmake/custom_targets/README_metavision_open.md

@@ -131,7 +131,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.0.1`.
+ 1. Retrieve the code `git clone https://github.com/prophesee-ai/openeb.git --branch 4.1.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
@@ -322,7 +322,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.0.1
+git clone https://github.com/prophesee-ai/openeb.git --branch 4.1.0
 ```
 
 Note that if you choose to download an archive of OpenEB from GitHub rather than cloning the repository,

cmake/custom_targets/create_metavision_open_archive_folder.cmake

@@ -20,7 +20,7 @@ set(HAL_OPEN_PLUGIN_FILES apps biasgen cmake CMakeLists.txt lib resources sample
 set(HAL_OPEN_PLUGIN_INCLUDES boards utils geometries plugin devices/common devices/utils devices/others)
 set(HAL_OPEN_PLUGIN_HW_LAYER_INCLUDES boards facilities utils devices/common devices/utils devices/psee-video)
 set(HAL_OPEN_PLUGIN_SOURCES boards CMakeLists.txt facilities plugin utils devices/common devices/utils devices/psee-video devices/others devices/CMakeLists.txt)
-set(HAL_OPEN_PLUGIN_DEVICES gen31 gen41 imx636 treuzell)
+set(HAL_OPEN_PLUGIN_DEVICES gen31 gen41 imx636 genx320 treuzell)
 
 foreach (open_device ${HAL_OPEN_PLUGIN_DEVICES})
     list(APPEND HAL_OPEN_PLUGIN_INCLUDES devices/${open_device})

hal/cpp/CMakeLists.txt

@@ -32,10 +32,6 @@ file(GENERATE
 # This header is used by file hal/src/utils/software_info.cpp.
 set(VERSION_FILE_RELATIVE_PATH include/metavision/hal/version.h)
 set(VERSION_FILE_OUTPUT_PATH ${GENERATE_FILES_DIRECTORY}/${VERSION_FILE_RELATIVE_PATH})
-add_library_version_header(generate_metavision_hal_version_header
-                           ${VERSION_FILE_OUTPUT_PATH}
-                           metavision_hal
-)
 
 # Add libraries (hal and hal_discovery)
 set(metavision_hal_include_dir "${CMAKE_CURRENT_SOURCE_DIR}/include")

hal/cpp/include/metavision/hal/decoders/evt21/evt21_decoder.h

@@ -15,6 +15,7 @@
 #include "metavision/sdk/base/events/event_cd.h"
 #include "metavision/sdk/base/events/event_ext_trigger.h"
 #include "metavision/sdk/base/events/event_erc_counter.h"
+#include "metavision/sdk/base/utils/detail/bitinstructions.h"
 #include "metavision/hal/facilities/i_event_decoder.h"
 #include "metavision/hal/facilities/i_events_stream_decoder.h"
 #include "metavision/hal/decoders/base/event_base.h"
@@ -115,20 +116,12 @@ class EVT21GenericDecoder : public I_EventsStreamDecoder {
                 uint32_t valid     = ev_td->valid;
                 const RawEvent *ev = reinterpret_cast<const RawEvent *>(cur_ev);
                 bool pol           = ev->type == static_cast<EventTypesUnderlying_t>(Evt21EventTypes_4bits::EVT_POS);
-#if defined(__x86_64__) || defined(__aarch64__)
-                uint16_t off = 0;
+                uint16_t off       = 0;
                 while (valid) {
-                    off = __builtin_ctz(valid);
+                    off = ctz_not_zero(valid);
                     valid &= ~(1 << off);
                     cd_forwarder.forward(last_x + off, y, static_cast<short>(pol), last_timestamp<DO_TIMESHIFT>());
                 }
-#else
-                for (uint16_t i = last_x; i != last_x + 32; ++i) {
-                    if (valid & 0x1)
-                        cd_forwarder.forward(i, y, static_cast<short>(pol), last_timestamp<DO_TIMESHIFT>());
-                    valid >>= 1;
-                }
-#endif
                 ++cur_ev;
             } else if (type == static_cast<EventTypesUnderlying_t>(Evt21EventTypes_4bits::EVT_TIME_HIGH)) {
                 const Event_TIME_HIGH *ev_timehigh = reinterpret_cast<const Event_TIME_HIGH *>(cur_ev);

hal/cpp/include/metavision/hal/decoders/evt3/evt3_decoder.h

@@ -18,6 +18,7 @@
 
 #include "metavision/sdk/base/events/event_cd.h"
 #include "metavision/sdk/base/events/event_erc_counter.h"
+#include "metavision/sdk/base/utils/detail/bitinstructions.h"
 #include "metavision/hal/facilities/i_event_decoder.h"
 #include "metavision/hal/decoders/base/event_base.h"
 #include "metavision/hal/facilities/i_geometry.h"
@@ -188,26 +189,14 @@ class EVT3Decoder : public I_EventsStreamDecoder {
                     uint32_t valid = m.valid;
 
                     uint16_t last_x = state[(int)EventTypesEnum::VECT_BASE_X] & NOT_POLARITY_MASK;
-#if defined(__x86_64__) || defined(__aarch64__)
-                    uint16_t off = 0;
+                    uint16_t off    = 0;
                     while (valid) {
-                        off = __builtin_ctz(valid);
+                        off = ctz_not_zero(valid);
                         valid &= ~(1 << off);
                         cd_forwarder.forward_unsafe(last_x + off, state[(int)EventTypesEnum::EVT_ADDR_Y],
                                                     (bool)(state[(int)EventTypesEnum::VECT_BASE_X] & POLARITY_MASK),
                                                     last_timestamp<DO_TIMESHIFT>());
                     }
-#else
-                    uint16_t end = last_x + nb_bits;
-                    for (uint16_t i = last_x; i != end; ++i) {
-                        if (valid & 0x1) {
-                            cd_forwarder.forward_unsafe(i, state[(int)EventTypesEnum::EVT_ADDR_Y],
-                                                        (bool)(state[(int)EventTypesEnum::VECT_BASE_X] & POLARITY_MASK),
-                                                        last_timestamp<DO_TIMESHIFT>());
-                        }
-                        valid >>= 1;
-                    }
-#endif
                 }
                 if (validator.has_valid_vect_base()) {
                     state[(int)EventTypesEnum::VECT_BASE_X] += nb_bits;

hal/cpp/include/metavision/hal/device/device_discovery.h

@@ -83,18 +83,22 @@ class DeviceDiscovery {
     static SerialList list();
 
     /// @brief Lists serial numbers of local available sources.
+    /// @note A camera is considered local if we communicate directly with it.
     static SerialList list_local();
 
     /// @brief Lists serial numbers of remote available sources.
+    /// @note A camera is considered remote if it is part of another SoC and hence communication is indirect.
     static SerialList list_remote();
 
     /// @brief Lists available sources, including remote cameras
     static SystemList list_available_sources();
 
     /// @brief Lists only local available sources.
+    /// @note A source is considered local if we communicate directly with it.
     static SystemList list_available_sources_local();
 
     /// @brief Lists only remote available sources.
+    /// @note A source is considered remote if it is part of another SoC and hence communication is indirect.
     static SystemList list_available_sources_remote();
 
     /// @brief Lists DeviceConfig options supported by the camera

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

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

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

@@ -18,7 +18,6 @@ namespace Metavision {
 
 /// @brief Digital Crop feature
 /// All pixels outside of the cropping region will be dropped by the sensor
-/// @note This feature is available from Gen4.1
 class I_DigitalCrop : public I_RegistrableFacility<I_DigitalCrop> {
 public:
     ///  @brief Structure that defines a Region with 4 values :

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

@@ -20,7 +20,6 @@
 namespace Metavision {
 
 /// @brief Interface for Digital Event Mask commands.
-/// @note This feature is available on Gen41 and newer
 class I_DigitalEventMask : public I_RegistrableFacility<I_DigitalEventMask> {
 public:
     /// @brief Interface for Digital Pixel Mask commands.

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

@@ -20,7 +20,6 @@
 namespace Metavision {
 
 /// @brief Interface for Event Rate Controller (ERC) commands
-/// @note This feature is available on Gen4 sensors and newer
 class I_ErcModule : public I_RegistrableFacility<I_ErcModule> {
 public:
     /// @brief Toggles ERC activation

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

@@ -23,8 +23,6 @@ namespace Metavision {
 /// This sensor level noise filter is based on the event rate only. If enabled, the sensor will transfer data if and
 /// only if the event rate is above a given event rate. It avoids streaming background noise information without
 /// relevant activity information.
-///
-/// @note This feature is available only on Gen3.1 sensors
 class I_EventRateNoiseFilterModule : public I_RegistrableFacility<I_EventRateNoiseFilterModule> {
 public:
     /// @brief Enables/disables the noise filter

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

@@ -20,7 +20,6 @@
 namespace Metavision {
 
 /// @brief Noise filter module
-/// @note This feature is available only on Gen4.1 sensors and newer
 class I_EventTrailFilterModule : public I_RegistrableFacility<I_EventTrailFilterModule> {
 public:
     /// @brief Type of implemented filter

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

@@ -30,7 +30,6 @@ class I_Monitoring : public I_RegistrableFacility<I_Monitoring> {
     /// @brief Gets Pixel Dead Time (aka. "refractory period").
     /// This is the minimum time latency between the generation of 2 events by a pixel
     /// @return Estimated dead time (in us) throw on Error
-    /// @note This feature is available on Gen4 sensors and newer
     virtual int get_pixel_dead_time() = 0;
 };
 

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

@@ -81,6 +81,9 @@ class I_ROI : public I_RegistrableFacility<I_ROI> {
     /// @brief Sets multiple windows
     ///
     /// The windows will be applied according to the current mode (ROI or RONI)
+    /// In ROI mode, enabled pixels are those inside the provided rectangles.
+    /// In RONI mode, enabled pixels are those where row OR column are covered by the provided rectangle.
+    ///
     /// @param windows A vector of windows to set
     /// @return true on success
     /// @throw an exception if the size of @p windows is higher than the maximum supported number
@@ -89,15 +92,17 @@ class I_ROI : public I_RegistrableFacility<I_ROI> {
 
     /// @brief Sets multiple lines and columns from row and column binary maps
     ///
-    /// The binary maps (std::vector<bool>) arguments must have the sensor's dimension
-    /// The lines and columns will be applied according to the current mode (ROI or RONI)
+    /// The binary maps (std::vector<bool>) arguments must have the sensor's dimension.
+    /// The lines and columns will be applied according to the current mode (ROI or RONI).
+    /// In ROI mode, enabled pixels are those where row AND column are set to true.
+    /// In RONI mode, disabled pixels are those where row AND column are set to false.
+    /// This means that conversely, enabled pixels are those where row OR column are set to true.
     ///
     /// @param cols Vector of boolean of size sensor's width representing the binary map of the columns to
     /// enable
     /// @param rows Vector of boolean of size sensor's height representing the binary map of the rows to
     /// enable
     /// @return true if input have the correct dimension and the ROI is set correctly, false otherwise
-    /// @warning For a pixel to be enabled, it must be enabled on both its row and column
     virtual bool set_lines(const std::vector<bool> &cols, const std::vector<bool> &rows) = 0;
 
 private:

hal/cpp/include/metavision/hal/utils/camera_discovery.h

@@ -56,7 +56,7 @@ class CameraDiscovery {
     virtual bool discover(DeviceBuilder &device_builder, const std::string &serial, const DeviceConfig &config) = 0;
 
     /// @brief Tells if this CameraDiscovery detect camera locally plugged (USB/MIPI/...) as opposed to remote
-    /// camera shared over a network
+    /// camera running on another system
     virtual bool is_for_local_camera() const;
 };
 

hal/cpp/include/metavision/hal/utils/device_config.h

@@ -93,13 +93,13 @@ using DeviceConfigOptionMap = std::map<std::string, DeviceConfigOption>;
 /// @sa @ref DeviceDiscovery::open
 class DeviceConfig {
 public:
-    static std::string get_evt_format_key();
+    static std::string get_format_key();
 
     /// @brief Gets the event format
     /// @return string representing current event format setting
-    std::string evt_format() const;
+    std::string format() const;
 
-    void set_evt_format(const std::string &format);
+    void set_format(const std::string &format);
 
     static std::string get_biases_range_check_bypass_key();
 
@@ -148,6 +148,14 @@ class DeviceConfig {
     /// @overload
     std::string get(const std::string &key, const std::string &def = std::string()) const;
 
+    [[deprecated(
+        "This function is deprecated since version 4.1.0. Please use get_format_key() instead.")]] static std::string
+        get_evt_format_key();
+    [[deprecated("This function is deprecated since version 4.1.0. Please use format() instead.")]] std::string
+        evt_format() const;
+    [[deprecated("formatThis function is deprecated since version 4.1.0. Please use set_format() instead.")]] void
+        set_evt_format(const std::string &);
+
 private:
     // private get<T> helper, to avoid template specialization errors on GCC
     template<typename T, typename U = typename std::enable_if<!std::is_same<std::string, T>::value>::type>

hal/cpp/include/metavision/hal/utils/hal_software_info.h

@@ -18,7 +18,7 @@
 
 namespace Metavision {
 
-/// @brief Returns various software information such as the version
+/// @brief Returns various software information, such as the version, about the Metavision HAL used at run time
 /// @return Software information
 Metavision::SoftwareInfo &get_hal_software_info();
 

hal/cpp/include/metavision/hal/utils/resources_folder.h

@@ -12,13 +12,20 @@
 #ifndef METAVISION_HAL_RESOURCES_FOLDER_H
 #define METAVISION_HAL_RESOURCES_FOLDER_H
 
+#include <filesystem>
 #include <string>
 
 namespace Metavision {
 
 /// @brief A dedicated class to handle resources' installation paths
 class ResourcesFolder {
 public:
+#ifndef __ANDROID__
+    /// @brief Returns path where user settings are stored
+    /// @return User settings path
+    static std::filesystem::path get_user_path();
+#endif
+
     /// @brief Returns installation path of support directories (like firmwares)
     /// @return Installation path of support directories
     static std::string get_install_path();

hal/cpp/lib/CMakeLists.txt

@@ -7,31 +7,8 @@
 # on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and limitations under the License.
 
-#### Create obj library with software info
-add_library(metavision_hal_info_obj OBJECT)
-# The following line is needed becase when linking a shared library to an object one,
-# the object library needs to be compiled with -fPIC
-# cf https://stackoverflow.com/questions/50600708/combining-cmake-object-libraries-with-shared-libraries
-set_target_properties(metavision_hal_info_obj
-    PROPERTIES
-        POSITION_INDEPENDENT_CODE ON
-)
-
-target_include_directories(metavision_hal_info_obj
-    PUBLIC
-        ${metavision_hal_include_dir}
-    PRIVATE
-        ${GENERATE_FILES_DIRECTORY}/include # For software_info.cpp
-)
-target_link_libraries(metavision_hal_info_obj
-    PUBLIC
-        MetavisionSDK::base
-)
-add_dependencies(metavision_hal_info_obj generate_metavision_hal_version_header)
-
 #### metavision_hal
 add_library(metavision_hal SHARED)
-target_sources(metavision_hal PRIVATE $<TARGET_OBJECTS:metavision_hal_info_obj>)
 target_include_directories(metavision_hal
     PUBLIC
         $<BUILD_INTERFACE:${metavision_hal_include_dir}>
@@ -44,8 +21,6 @@ target_link_libraries(metavision_hal
     PUBLIC
         MetavisionSDK::base
         Threads::Threads
-    PRIVATE
-        metavision_hal_info_obj
 )
 
 include(GenerateExportHeader)
@@ -87,7 +62,6 @@ target_link_libraries(metavision_hal_discovery
     PUBLIC
         metavision_hal
     PRIVATE
-        metavision_hal_info_obj
         ${CMAKE_DL_LIBS}
 )
 

hal/cpp/samples/metavision_hal_sample_plugin/include/sample_camera_discovery.h

@@ -42,7 +42,7 @@ class SampleCameraDiscovery : public Metavision::CameraDiscovery {
                   const Metavision::DeviceConfig &config) override;
 
     /// @brief Tells if this CameraDiscovery detects camera locally plugged (USB/MIPI/...) as opposed to remote
-    ///
+    /// camera running on another system
     /// @return true if this camera discovery connect local devices
     bool is_for_local_camera() const override final;
 };

hal/cpp/src/utils/CMakeLists.txt

@@ -13,11 +13,9 @@ target_sources(metavision_hal PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}/demangle.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/device_builder.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/device_config.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/hal_software_info.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/file_data_transfer.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/file_discovery.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/raw_file_header.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/resources_folder.cpp
 )
-target_sources(metavision_hal_info_obj PRIVATE
-    ${CMAKE_CURRENT_SOURCE_DIR}/hal_software_info.cpp
-)