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.

Return

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.

Return

Information on the plugin software version

template<typename FacilityType>
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.

Return

A shared pointer to the facility

Template Parameters

  • FacilityType: Type of facility

Parameters

  • facility: Facility to be registered to the device

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

Builds a device.

Return

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 Status

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

Values:

enumerator Started = 0
enumerator Stopped = 1
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)

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)

~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

Return

The id of the callback. This id is unique.

Parameters

  • cb: The cb to call when the status changes

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

Return

The id of the callback. This id is unique.

Parameters

  • cb: The cb to call when a new buffer is transfered

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

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.

using type_ListSerial = std::list<std::string>

Note

type_ListSerial is deprecated since version 2.2.0 and will be removed in later releases. Please use SerialList instead.

using type_ListSystems = std::list<PluginCameraDescription>

Note

type_ListSystems is deprecated since version 2.2.0 and will be removed in later releases. Please use SystemList instead.

Public Functions

~CameraDiscovery()

Destructor.

std::string get_name() const

Gets name of Camera Discovery’s type.

Return

Name of Camera Discovery’s type

SerialList list() = 0

Lists all connected cameras’ serial numbers.

SystemList list_available_sources() = 0

Lists all PluginCameraDescription of connected cameras.

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

Discovers a device and initializes a corresponding DeviceBuilder.

Return

true if a device builder could be discovered from the parameters

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

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.

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

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

std::string to_string()

Returns the ROI as a string.

Return

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

~FileDiscovery()

Destructor.

std::string get_name() const

Gets the file discovery name.

Return

Name of the file discovery

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.

Return

true if a device builder could be discovered from the parameters

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

enum Metavision::HalErrorCode::Enum

Values:

enumerator CameraError = 0x100000

Base Hal camera error.

enumerator FailedInitialization = CameraError | 0x01000

Camera failed initialization.

enumerator CameraNotFound = FailedInitialization | 0x1

Failed initialization due to a camera not found.

enumerator GoldenFallbackBooted = FailedInitialization | 0x2

Golden fallback.

enumerator InternalInitializationError = FailedInitialization | 0x100

Metavision Internal Initialization problem.

enumerator InvalidArgument = CameraError | 0x02000

Errors related to invalid arguments.

enumerator InvalidAFKValue = InvalidArgument | 0x1

Wrong AFK arguments given.

enumerator DeprecatedFunctionCalled = CameraError | 0x03000

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

class Metavision::HalException : public std::system_error

Class for all exceptions thrown by Metavision HAL.

See

http://www.cplusplus.com/reference/system_error/system_error/

See

http://en.cppreference.com/w/cpp/error/error_code

Public Functions

HalException(HalErrorCodeType e)

Creates an exception of type e with default error message.

Parameters

  • e: Camera error code

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.

Return

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

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.

Return

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.

Return

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

std::string get_install_path()

Returns installation path of support directories (like firmwares)

Return

Installation path of support directories

std::string get_plugin_install_path()

Returns the plugins’ installation path.

Return

Plugins’ installation path