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

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

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