HAL Utils API

class CameraDiscovery

Discovers connected devices.

Public Types

using SerialList = std::list<std::string>: Alias to list cameras’ serial numbers.

using SystemList = std::list<PluginCameraDescription>: Alias to list PluginCameraDescription.

Public Functions

virtual ~CameraDiscovery(): Destructor.

std::string get_name() const

Gets name of Camera Discovery’s type.

Returns: Name of Camera Discovery’s type

virtual SerialList list() = 0: Lists all connected cameras’ serial numbers.

virtual SystemList list_available_sources() = 0: Lists all PluginCameraDescription of connected cameras.

virtual bool discover(DeviceBuilder &device_builder, const std::string &serial, const DeviceConfig &config) = 0

Discovers a device and initializes a corresponding DeviceBuilder.

Parameters

device_builder – Device builder to configure so that it can build a Device from the parameters
serial – Serial number of the camera to open. If it is an empty string, the first available camera will be opened
config – Configuration of camera creation

Returns

true if a device builder could be discovered from the parameters

virtual bool is_for_local_camera() const: Tells if this CameraDiscovery detect camera locally plugged (USB/MIPI/…) as opposed to remote camera running on another system.

class DataTransfer

An interface that manages the data transfer from a source to high level user space.

This object behaves as master: the client of this class is notified when new buffers are transferred or the data transfer is stopped.

Warning

This class is not thread safe and is used in conjunction with the I_EventsStream or at the user’s risk

Public Types

enum class Status

Alias for a callback called when the data transfer starts or stops transferring data.

Values:

enumerator Started

enumerator Stopped

using Data = uint8_t: Alias for the type of the data transferred.

using DefaultBufferPool = SharedObjectPool<std::vector<Data>>: Convenience alias for a default object handling the buffers pool.

using DefaultBufferType = DefaultBufferPool::value_type: Convenience alias to a object type from the default type pool.

using DefaultBufferPtr = DefaultBufferPool::ptr_type: Convenience alias for a default object handling the buffers pool.

using RawDataProducerPtr = std::shared_ptr<RawDataProducer>: Alias for a shared pointer to a RawDataProducer.

using NewBufferCallback_t = std::function<void(const BufferPtr&)>: Alias for a callback to process transferred buffer of data.

using TransferErrorCallback_t = std::function<void(std::exception_ptr eptr)>: Alias for a callback to process errors that happened during transfer.

Public Functions

explicit DataTransfer(RawDataProducerPtr data_producer_ptr)

Builds a DataTransfer object.

Parameters: data_producer_ptr – A Pointer to a data producer that will provide raw event data

~DataTransfer()

Destructor.

Stops all transfers and wait for all thread to join

void start(): Starts the transfers.

void stop(): Stops the transfers.

void suspend(): Suspends the transfers.

Note

This function can be used to temporarily suspend transfers, while keeping the transfer thread alive. To resume the transfers, call resume.

void resume(): Resumes the transfers.

bool stopped() const

Check if the transfers are stopped.

Returns: True if the transfers are stopped, false otherwise

size_t add_status_changed_callback(StatusChangeCallback_t cb)

Adds a callback called when the data transfer starts or stops transferring data.

Warning

This method is not thread safe. You should add/remove the various callback before starting the transfers

Warning

It’s not allowed to add/remove a callback from the callback itself

Parameters: cb – The cb to call when the status changes
Returns: The id of the callback. This id is unique.

size_t add_new_buffer_callback(NewBufferCallback_t cb)

Adds a callback to process transferred buffer of data.

Warning

This method is not thread safe. You should add/remove the various callback before starting the transfers

Warning

It’s not allowed to add/remove a callback from the callback itself

Parameters: cb – The cb to call when a new buffer is transferred
Returns: The id of the callback. This id is unique.

size_t add_transfer_error_callback(TransferErrorCallback_t cb)

Adds a callback to process errors that happened during transfer.

Warning

This method is not thread safe. You should add/remove the various callback before starting the transfers

Warning

It’s not allowed to add/remove a callback from the callback itself

Parameters: cb – The cb to call when a new buffer is transferred
Returns: The id of the callback. This id is unique.

void remove_callback(size_t cb_id)

Removes the callback with input id.

Note

This method is not thread safe. You should add/remove the various callback before starting the transfers

Parameters: cb_id – The id of the callback to remove

inline RawDataProducerPtr get_data_producer() const: Returns the data producer used by the transfer.

template<typename T> inline void transfer_data(const T &buffer) const: Convenience function to transfer a buffer of data coming from an object pool by wrapping if to a BufferPtr.

bool should_stop() const

Returns whether the transfer must stop as requested by the base class implementation.

This method can be called safely by the child implementation to know whether the implementation of the run should return

void notify_stop()

Notify the internal thread that it shall stop.

This method makes a thread-safe update of should_stop() return value

void fire_callbacks(const BufferPtr &buffer) const

Trigger all registered callbacks.

Warning

The transferred buffer must hold coherent and continuous data.

Warning

The buffer size may not be a multiple of a RAW event byte size if the last event is split, in which case, the next buffer must contain the remaining bytes of the split event.

Warning

The implementation must resize the buffer to the actual size of the transferred data

Parameters: buffer – The data to be carried forward

Public Static Functions

template<typename T> static inline BufferPtr make_buffer_ptr(const T &buffer_ptr)

Convenience function to create a BufferPtr from a buffer that originates a Buffer Pool.

Parameters: buffer_ptr – The buffer to create a BufferPtr from
Returns: A BufferPtr holding the buffer

class BufferPtr

Generic Buffer type used by DataTransfer.

BufferPtr is a type erased wrapper around a buffer from a Buffer Pool. It is used to hold a buffer of data that can be transferred by the DataTransfer down the pipeline without having them to know about the underlying buffer implementation.

Public Types

using PtrType = const Data*: Default raw data base type.

Public Functions

BufferPtr() = default: Default constructor.

BufferPtr(std::any buffer, PtrType data, std::size_t buffer_size)

Constructor.

Parameters

buffer – The buffer to hold
data – The data pointer of the buffer
buffer_size – The size of the buffer

bool operator==(const BufferPtr &other) const: Equality operator.

operator bool() const noexcept: bool conversion operator

std::size_t size() const noexcept: Accessor to the buffer size.

PtrType data() const noexcept: Accessor to the buffer data.

PtrType begin() const noexcept: Iterator semantic to the beginning of the buffer.

PtrType end() const noexcept: Iterator semantic to the end of the buffer.

const PtrType cbegin() const noexcept: Iterator semantic to the beginning of a const buffer.

const PtrType cend() const noexcept: Iterator semantic to the end of a const buffer.

BufferPtr clone() const: Clone the buffer by reallocating the data and copying the content.

SharedCloneType any_clone_cast() const: Cast back internally stored buffer to its specific type Should throw if the type isn’t of a cloned one.

void reset() noexcept: Reset the buffer.

class RawDataProducer : public std::enable_shared_from_this<RawDataProducer>

Interface for a Raw Event Data producer Derived class are responsible from reading Raw Event buffers from the platform and feed those buffer to the DataTransfer.

Note

Buffers are obtained via a Buffer Pool object owned by the derived object. So that the derived object can customise the required underlying memory type for the specific platform.

Note

DefaultBufferPool can be used as a default buffer pool object type.

Subclassed by Metavision::FileRawDataProducer

Public Functions

virtual ~RawDataProducer() = default: Destructor.

inline virtual void start_impl()

Start transfer implementation.

This method is called before running the transfer thread. It can be used as an initialization steps for the implementation.

Note

When this method is called, should_stop returns false

virtual void run_impl(const DataTransfer&) = 0

Data transfer implementation.

This method must hold the data polling and transfer logic from a source. It is run in a thread within the base class.

When a buffer is ready to be transferred, the implementation must call DataTransfer::transfer_data with the buffer

Warning

The implementation must ensure that whenever should_stop returns true, this method returns and cleans up resources

inline virtual void stop_impl()

Stop transfer implementation.

This method is here to notify run_impl that it must stop if a call to should_stop() is not sufficient.

Warning

Resources should not be clean up in this method as run_impl could still try to use them. It is advised to do so in the scope of the run_impl method to avoid concurrent calls

enum Metavision::DecoderProtocolViolation

Values:

enumerator NullProtocolViolation

enumerator NonMonotonicTimeHigh

enumerator PartialVect_12_12_8

enumerator PartialContinued_12_12_4

enumerator NonContinuousTimeHigh

enumerator MissingYAddr

enumerator InvalidVectBase

enumerator OutOfBoundsEventCoordinate

class DeviceBuilder

Builder class to handle Device creation.

Public Functions

DeviceBuilder(std::unique_ptr<I_HALSoftwareInfo> i_hal_sw_info, std::unique_ptr<I_PluginSoftwareInfo> i_plugin_sw_info)

Constructor.

Parameters

i_hal_sw_info – Information on the HAL software version
i_plugin_sw_info – Information on the plugin software version

DeviceBuilder(DeviceBuilder&&): Move constructor.

DeviceBuilder &operator=(DeviceBuilder&&): Move operator.

const std::shared_ptr<I_HALSoftwareInfo> &get_hal_software_info() const

Gets the information on the HAL software version.

Returns: Information on the HAL software version

const std::shared_ptr<I_PluginSoftwareInfo> &get_plugin_software_info() const

Gets the information on the plugin software version.

Returns: Information on the plugin software version

template<typename FacilityType> inline std::shared_ptr<FacilityType> add_facility(std::unique_ptr<FacilityType> facility)

Convenience function to add a facility that will be registered on the created device.

Template Parameters: FacilityType – Type of facility
Parameters: facility – Facility to be registered to the device
Returns: A shared pointer to the facility

std::unique_ptr<Device> operator()()

Builds a device.

Returns: The created device

class DeviceConfigOption

Class representing options allowed for a device configuration entry.

For each key available in a DeviceConfig as reported by DeviceDiscovery::list_device_config_options””, there is a corresponding option listing the type and accepted values when opening the Device via DeviceDiscovery::open It is composed of a type (boolean, numeric or string) and a set of accepted values

See also

DeviceConfig

Note

The DeviceConfig class is string based to keep its usage simple and generic, whereas this class represent a type and optional range/set of values. The added information can be useful to guide the user when presenting the options that are available, but ultimately the value set for a specific key will be a string, so care must be taken when converting the value before calling one of the functions to set a (key,value) pair in the DeviceConfig

Public Types

enum class Type

Enumeration class representing the type of an option.

Values:

enumerator Invalid

enumerator Boolean

enumerator Int

enumerator Double

enumerator String

Public Functions

template<typename T> std::pair<T, T> get_range() const

Gets the range of accepted values.

Returns: The range of accepted values for options representing a numeric type (Int or Double)

std::vector<std::string> get_values() const

Gets the set of accepted values.

Returns: The set of accepted values for options representing a string type

template<typename T> T get_default_value() const

Gets the set of accepted values.

Returns: The default value

Type type() const

Gets the type of this class.

Returns: The type that is represented by this class

class DeviceConfig

Class storing a map of (key,values) that can be used to customize how a device should be opened.

See also

DeviceDiscovery::list_device_config_options

See also

DeviceDiscovery::open

Warning

The class stores values as string for ease of use, so proper care should be taken to make sure that the value can be properly parsed when calling one of the functions to get the (typed) value

Public Functions

std::string format() const

Gets the event format.

Returns: string representing current event format setting

void set_format(const std::string &format)

Sets the event format.

Parameters: format – String representing event format to set

bool biases_range_check_bypass() const

Gets the status of the “bypass biases range check” option.

Returns: true if biases range check should be bypassed, false otherwise

template<typename T> inline void set(const std::string &key, const T &value)

Sets a value for a named key in the config dictionary.

Parameters

key – Key of the config
value – Value of the config

void set(const std::string &key, bool value): Sets a value for a named key in the config dictionary This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void set(const std::string &key, const char *const value): Sets a value for a named key in the config dictionary This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void set(const std::string &key, const std::string &value): Sets a value for a named key in the config dictionary This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T> inline T get(const std::string &key, const T &def = T()) const

Gets the (typed) value for a named key in the config dictionary if it exists and can be extracted from the corresponding value safely or the provided default value.

Template Parameters

T – type of the value to return as

Parameters

key – Name of the config key
def – Default value if the config key is not found

Returns

Value of the config

std::string get(const std::string &key, const std::string &def = std::string()) const

Gets the (typed) value for a named key in the config dictionary if it exists and can be extracted from the corresponding value safely or the provided default value.

Parameters

key – Name of the config key
def – Default value if the config key is not found

Returns

Value of the config This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class DeviceControl

Public Functions

virtual void reset() = 0: Restarts the device and the connection with it.

virtual void start() = 0: Starts the generation of events from the camera side.

Warning

All triggers will be disabled at stop. User should re-enable required triggers before start.

virtual void stop() = 0: Stops the generation of events from the camera side.

class FileRawDataProducer : public Metavision::DataTransfer::RawDataProducer 

Standard stream reader.

Public Functions

FileRawDataProducer(std::unique_ptr<std::istream> stream, uint32_t raw_event_size_bytes, const RawFileConfig &config, DataTransfer::DefaultBufferPool buffer_pool = DataTransfer::DefaultBufferPool::make_bounded(4))

Reads the input standard stream batch by batch according to the input configuration.

Parameters

stream – The stream to read from
raw_event_size_bytes – The size of a RAW event in bytes
config – The configuration to use to read the stream
buffer_pool – The bufferpool to be used to allocate memory for the data transfer

bool seek(const std::streampos &target_position)

Seeks the target position in the file.

Parameters: target_position – The target position of the cursor to seek in the file

void get_seek_range(std::streampos &data_start_pos, std::streampos &data_end_pos) const

Gets the range of available positions when using seek.

Parameters

data_start_pos – The offset position of the first data in the file
data_end_pos – The offset position of the next position after the last data in the file

class FileDiscovery

Creates device simulating a camera streaming the raw events coming from a stream.

Public Functions

virtual ~FileDiscovery(): Destructor.

virtual std::string get_name() const

Gets the file discovery name.

Returns: Name of the file discovery

virtual bool discover(DeviceBuilder &device_builder, std::unique_ptr<std::istream> &stream, const RawFileHeader &header, const RawFileConfig &config) = 0

Discovers a device and initializes a corresponding DeviceBuilder.

The input stream is passed using a reference to a (uniquely) owned pointer, so that an implementation can take ownership of it upon successful opening. Conversely, if the stream can not be opened by the file discovery, the implementation must NOT take ownership of the stream pointer.

Warning

If the file discovery fails to open from the stream (i.e if the implementation returns a nullptr), the stream pointer must NOT have been moved from. An exception will be thrown if the stream pointer is null and a device could not be created.

Parameters

device_builder – Device builder to configure so that it can build a Device from the parameters
stream – The stream to read events from
header – Header of the input stream, containing identification information for the stream’s source
config – For building the camera from a file

Returns

true if a device builder could be discovered from the parameters

enum Metavision::HalErrorCode::Enum

Values:

enumerator CameraError: Base Hal camera error.

enumerator FailedInitialization: Camera failed initialization.

enumerator CameraNotFound: Failed initialization due to a camera not found.

enumerator GoldenFallbackBooted: Golden fallback.

enumerator InternalInitializationError: Metavision Internal Initialization problem.

enumerator InvalidArgument: Errors related to invalid arguments.

enumerator ValueOutOfRange: Value given out of supported range.

enumerator NonExistingValue: Requested value does not exist.

enumerator OperationNotPermitted: Requested operation cannot be performed on given argument.

enumerator UnsupportedValue: Value for requested setting is not supported.

enumerator DeprecatedFunctionCalled: Errors related to calling deprecated function that have no equivalent in current API.

enumerator OperationNotImplemented: Operation is not implemented.

enumerator MaximumRetriesExeeded: Operation reached maximum retries limit.

enumerator MaximumRetriesExceeded

class HalException : public Metavision::BaseException

Class for all exceptions thrown by Metavision HAL.

Public Functions

inline HalException(HalErrorCodeType e)

Creates an exception of type e with default error message.

Parameters: e – Camera error code

inline HalException(HalErrorCodeType e, const std::string &additional_info)

Creates an exception of type e with an error description in additional_info.

Parameters

e – Camera error code
additional_info – Error description

Metavision::SoftwareInfo &Metavision::get_hal_software_info()

Returns various software information, such as the version, about the Metavision HAL used at run time.

Returns: Software information

class RawFileConfig

RAW files configuration’s options.

Public Members

uint32_t n_events_to_read_ = 1000000: Number of events_byte_size blocks to read. At each read, n_events_to_read_*sizeof(RAW_event) bytes are read.

Warning

sizeof(RAW_event) is defined by the events format contained in the RAW file read.

uint32_t n_read_buffers_ = 3: The maximum number of buffers to allocate and use for reading. Each buffer contains at most n_events_to_read_ RAW events. The maximum memory allocated to read the RAW file will be read_buffers_count_ * n_events_to_read_ * sizeof(RAW_event). One can use this parameters to have a finer control on offline memory usage

bool do_time_shifting_ = true: Take the first timer high of the file as origin of time.

bool build_index_ = true: True if indexing should be performed when opening the file Alternatively, indexing can still be requested by calling I_EventsStream::index directly

class RawFileHeader : public Metavision::GenericHeader 

A dedicated class to handle RAW file headers and handle easily their mandatory fields.

Public Functions

RawFileHeader(): Default constructor.

RawFileHeader(std::istream &i)

Builds the header map by parsing the input stream.

Parameters: i – Input stream to parse GenericHeader(std::istream &)

RawFileHeader(const HeaderMap &h)

Builds the header map using a copy of the input HeaderMap.

Parameters: h – Header map to copy from

std::string get_camera_integrator_name() const

Gets the integrator name of the source used to generate the RAW file.

Returns: Returns the integrator name if any, or an empty string otherwise

void set_camera_integrator_name(const std::string &integrator_name)

Sets the name of the integrator of the source used to generate the RAW file.

Parameters: integrator_name – Name of the integrator

std::string get_plugin_integrator_name() const

Gets the integrator name of the plugin used to generate the RAW file.

Returns: Returns the integrator name if any, or an empty string otherwise

void set_plugin_integrator_name(const std::string &integrator_name)

Sets the name of the integrator of the plugin used to generate the RAW file.

Parameters: integrator_name – Name of the integrator

std::string get_plugin_name() const

Gets the name of the plugin to use to read the RAW file.

Returns: Returns the name of the plugin if any, or an empty string otherwise

void set_plugin_name(const std::string &plugin_name)

Sets the name of the plugin to use to read the RAW file.

Parameters: plugin_name – Name of the plugin

void remove_plugin_name(): Remove the name of the plugin to use to read the RAW file.

class ResourcesFolder

A dedicated class to handle resources’ installation paths.

Public Static Functions

static std::filesystem::path get_user_path()

Returns path where user settings are stored.

Returns: User settings path

static std::filesystem::path get_install_path()

Returns installation path of support directories (like firmwares)

Returns: Installation path of support directories

static std::filesystem::path get_plugin_install_path()

Returns the plugins’ installation path.

Returns: Plugins’ installation path