HAL Utils API

class Metavision::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 Metavision::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

Subclassed by Metavision::FileDataTransfer

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 Buffer = std::vector<Data>: Alias for the type of the internal buffer of data.

using BufferPool = SharedObjectPool<Buffer>: Alias for the object handling the buffers pool.

using BufferPtr = BufferPool::ptr_type: Alias for the ptr type returned by the buffer pool.

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

Public Functions

DataTransfer(uint32_t raw_event_size_bytes)

Builds a DataTransfer object.

Parameters: raw_event_size_bytes – The size of a RAW event in bytes

DataTransfer(uint32_t raw_event_size_bytes, const BufferPool &buffer_pool, bool allow_buffer_drop = false)

Builds a DataTransfer object.

Parameters

raw_event_size_bytes – The size of a RAW event in bytes
buffer_pool – A user defined buffer pool to use instead of the default one (unbounded, ObjectPool)
allow_buffer_drop – When transferring data buffers using an empty bounded buffer pool, buffers are dropped (transfer_data)

virtual ~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.

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 bool has_available_buffer() const: Returns whether a buffer can be used from the pool.

Note

Always return true for a unbounded pool, as it could allocate a new object on the spot if the pool is empty

enum Metavision::DecoderProtocolViolation

Values:

enumerator NullProtocolViolation

enumerator NonMonotonicTimeHigh

enumerator PartialVect_12_12_8

enumerator PartialContinued_12_12_4

enumerator NonContinuousTimeHigh

enumerator MissingYAddr

enumerator InvalidVectBase

class Metavision::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 Metavision::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 Metavision::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 Metavision::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 Metavision::FileDataTransfer : public Metavision::DataTransfer 

Standard stream reader.

Public Functions

FileDataTransfer(std::unique_ptr<std::istream> stream, uint32_t raw_event_size_bytes, const RawFileConfig &config)

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

~FileDataTransfer(): Stops ongoing transfers.

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 Metavision::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 Metavision::HalException : public std::system_error

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 Metavision::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 Metavision::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 Metavision::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::string get_install_path()

Returns installation path of support directories (like firmwares)

Returns: Installation path of support directories

static std::string get_plugin_install_path()

Returns the plugins’ installation path.

Returns: Plugins’ installation path