HAL Utils API

class Metavision::DeviceConfig

Device’s configuration’s options.

Subclassed by Metavision::Future::RawFileConfig, Metavision::RawFileConfig

Public Members

std::string event_format_

Switch the event format if supported.

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::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.

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

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 shared over a network.

class Metavision::DeviceRoi

Defines a simple rectangular region.

Public Functions

~DeviceRoi() = default

Destructor.

inline DeviceRoi(int x, int y, int width, int height)

Creates a rectangle defined by the corner {(x, y), (x + width, y + height)}.

inline std::string to_string()

Returns the ROI as a string.

Returns

Human readable string representation of an ROI

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.

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 InvalidAFKValue

Wrong AFK arguments given.

enumerator DeprecatedFunctionCalled

Errors related to calling deprecated function that have no equivalent in current API.

enumerator OperationNotImplemented

Operation is not implemented.

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.

Returns

Software information

class Metavision::RawFileConfig : public Metavision::DeviceConfig

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.

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_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_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_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.