HAL Facilities API

class Metavision::I_AntiFlickerModule : public Metavision::I_RegistrableFacility<I_AntiFlickerModule>

Anti-flicker module.

Note: This feature is available only on Gen4.1 sensors

Public Functions

void enable() = 0: Enables the anti-flicker filter.

void disable() = 0: Disables the anti-flicker filter.

void set_frequency(uint32_t frequency_center, uint32_t bandwidth, bool stop = true) = 0

Sets anti-flicker parameters.

Defines the frequency band to be kept or removed:

[frequency_center - bandwidth/2, frequency_center + bandwidth/2]

This frequency range should be in the range [50 - 500] Hz

Note

band-stop removes all frequencies between min and max.

band-pass removes all events outside of the band sequence defined

Parameters

frequency_center: Center of the frequency band (in Hz)
bandwidth: Range of frequencies around the frequency_center (in Hz)
stop: If true, band-stop (by default); if false, band-pass

Exceptions

exception: if frequency band is not in the range [50 - 500] Hz

void set_frequency_band(uint32_t min_freq, uint32_t max_freq, bool stop = true) = 0

Sets anti-flicker parameters.

Defines the frequency band to be kept or removed in the range [50 - 500] Hz

Note

band-stop removes all frequencies between min and max.

band-pass removes all events outside of the band sequence defined

Parameters

min_freq: Lower frequency of the band (in Hz)
max_freq: Higher frequency of the band (in Hz)
stop: If true, band-stop; if false, band-pass

Exceptions

exception: if frequencies are outside of the range [50 - 500] Hz

class Metavision::I_Decoder : public Metavision::I_RegistrableFacility<I_Decoder>

Interface for decoding events.

This class is meant to receive raw data from the camera, and dispatch parts of the buffer to instances of I_EventDecoder for specific event types.

Public Types

using RawData = uint8_t: Alias for raw data type.

using TimeCallback_t = std::function<void(timestamp)>: Alias for callback on timestamp.

Public Functions

I_Decoder(bool time_shifting_enabled, const std::shared_ptr<I_EventDecoder<EventCD>> &event_cd_decoder = std::shared_ptr<I_EventDecoder<EventCD>>(), const std::shared_ptr<I_EventDecoder<EventExtTrigger>> &event_ext_trigger_decoder = std::shared_ptr<I_EventDecoder<EventExtTrigger>>())

Constructor.

Parameters

time_shifting_enabled: If true, the timestamp of the decoded events will be shifted by the value of first event
event_cd_decoder: Optional decoder of CD events
event_ext_trigger_decoder: Optional decoder of trigger events

void decode(RawData *raw_data_begin, RawData *raw_data_end)

Decodes raw data. Identifies the events in the buffer and dispatches it to the instance of I_EventDecoder corresponding to each event type.

Warning

It is mandatory to pass strictly consecutive buffers from the same source to this method

Parameters

raw_data_begin: Pointer on first event
raw_data_end: Pointer after the last event

size_t add_time_callback(const TimeCallback_t &cb)

Adds a function that will be called from time to time, giving current timestamp.

Return

ID of the added callback

Note

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

Note

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

Parameters

cb: Callback to add

bool remove_time_callback(size_t callback_id)

Removes a previously registered time callback.

Return

true if the callback has been unregistered correctly, false otherwise.

Note

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

Parameters

callback_id: Callback ID

timestamp get_last_timestamp() const = 0

Gets the timestamp of the last event.

Return: Timestamp of the last event

bool get_timestamp_shift(Metavision::timestamp &timestamp_shift) const = 0

Finds the timestamp shift.

If the timestamp shift (timestamp of the first event in the stream) is already known, the function returns true and the parameter timestamp_shift will be set to its value. Otherwise, the function returns false and does nothing.

Return: true if the timestamp shift is already known, false otherwise

bool is_time_shifting_enabled() const: Returns true if doing timestamp shift, false otherwise.

uint8_t get_raw_event_size_bytes() const = 0: Gets size of a raw event in bytes.

class Metavision::I_DeviceControl : public Metavision::I_RegistrableFacility<I_DeviceControl>

Facility that controls camera mode and allows to start, reset and stop it.

Public Types

enum SyncMode

Enumerate synchronization modes.

Values:

enumerator STANDALONE = 0

enumerator MASTER = 1

enumerator SLAVE = 2

Public Functions

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

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.

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

bool set_mode_standalone() = 0

Sets the camera in standalone mode.

The camera does not interact with other devices.

Warning: This function must be called before starting the camera
Return: true on success

bool set_mode_master() = 0

Sets the camera as master.

The camera sends clock signal to another device

Warning: This function must be called before starting the camera
Return: true on success

bool set_mode_slave() = 0

Sets the camera as slave.

The camera receives the clock from another device

Warning: This function must be called before starting the camera
Return: true on success

SyncMode get_mode() = 0

Retrieves Synchronization mode.

Return: synchronization mode

class Metavision::I_Erc : public Metavision::I_RegistrableFacility<I_Erc>

Interface for Event Rate Controller (ERC) commands.

Note: This feature is available on Gen4 sensors and newer

Public Functions

void enable(bool b) = 0

Toggles ERC activation.

Note

When ERC is inactive, all the events generated by the sensor are transmitted. Potential bandwidth limitation might occur.

Parameters

b: Desired state. b = true means ERC active, and b = false means ERC inactive.

bool is_enabled() = 0

Returns ERC activation state.

Return: The ERC state

void set_cd_event_rate(uint32_t events_per_sec)

Sets the target CD event rate of the ERC.

Note

Event rate is computed by ERC block as the number of events generated by the sensor divided by the count period. To get the count period value, see get_count_period.

Note

This method and set_cd_event_count operate over the same register. It is Expected that after parameterizing ERC using event rate, result of get_cd_event_count also changes.

Parameters

events_per_sec: Event rate expressed in events per second

uint32_t get_cd_event_rate()

Gets the CD event rate set point of the ERC.

Return: The event rate expressed in events per second
Note: See set_cd_event_rate to define the event rate target.

uint32_t get_count_period() const = 0

Gets the count period.

Return: The count period duration expressed in microseconds

void set_cd_event_count(uint32_t event_count) = 0

Sets the maximum number of events that ERC block should let pass over the count period.

Note

If you wish to parameterize the ERC with a set point expressed with an event rate use set_cd_event_rate instead. The 2 methods operate on the same register and conversions are managed automatically.

Parameters

event_count: The desired maximum number of event per reference period

uint32_t get_cd_event_count() = 0

Gets the maximum number of events that ERC will transmit over the count period.

Return: The maximum event count
Note: See set_cd_event_count to define the event count parameter.

void set_td_event_rate(uint32_t rate)

Note: set_td_event_rate(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use set_cd_event_rate instead

uint32_t get_td_event_rate()

Note

get_td_event_rate() is deprecated since version 2.2.0 and will be removed in later releases.

Please use

get_cd_event_rate instead

template<typename Event> class Metavision::I_EventDecoder : public Metavision::I_RegistrableFacility<I_EventDecoder<Event>>

Class for decoding a specific type of event.

Template Parameters

Event: type of event decoded by the instance

Public Types

typedef std::function<void(const Event&)> AddEventCallback_t

Note: This alias is deprecated since version 2.2.0 and will be removed in next releases

typedef std::function<void(const Event *begin, const Event *end)> AddVEventCallback_t

Note: This alias is deprecated since version 2.2.0 and will be removed in next releases

typedef std::function<void(timestamp base_time)> EndDecodeCallback_t

Note: This alias is deprecated since version 2.2.0 and will be removed in next releases

Public Functions

size_t add_event_buffer_callback(const EventBufferCallback_t &cb)

Sets the functions to call to each batch of decoded events.

Return

ID of the added callback

Note

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

Note

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

Parameters

cb: Callback to add

bool remove_callback(size_t callback_id)

Removes a previously registered callback.

Return

true if the callback has been unregistered correctly, false otherwise.

See

add_event_buffer_callback

Parameters

callback_id: Callback ID

void set_add_decoded_event_callback(AddEventCallback_t, bool = true)

Note: set_add_decoded_event_callback(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use add_event_buffer_callback(…) instead

void set_add_decoded_vevent_callback(AddVEventCallback_t, bool = true)

Note: set_add_decoded_vevent_callback(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use add_event_buffer_callback(…) instead

void set_end_decode_callback(EndDecodeCallback_t, bool = true)

Note: set_end_decode_callback(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use add_event_buffer_callback(…) instead

class Metavision::I_EventRateNoiseFilterModule : public Metavision::I_RegistrableFacility<I_EventRateNoiseFilterModule>

Interface for accessing the sensor level event rate based on noise filtering of a sensor.

This sensor level noise filter is based on the event rate only. If enabled, the sensor will transfer data if and only if the event rate is above a given event rate. It avoids streaming background noise information without relevant activity information.

Note: This feature is available only on Gen3.1 sensors

Public Functions

void enable(bool enable_filter) = 0

Enables/disables the noise filter.

Parameters

enable_filter: Whether to enable the noise filtering

bool set_event_rate_threshold(uint32_t threshold_Kev_s) = 0

Sets the event rate threshold. Below this threshold, no events are streamed.

Return

true if the input value was correctly set (i.e. it falls in the range of acceptable values for the sensor)

Parameters

threshold_Kev_s: Event rate threshold in Kevt/s

uint32_t get_event_rate_threshold() = 0

Gets the event rate threshold in Kevt/s below which no events are streamed.

Return: Event rate threshold in Kevt/s

class Metavision::I_EventsStream : public Metavision::I_RegistrableFacility<I_EventsStream>

Class for getting buffers from cameras or files.

Public Functions

I_EventsStream(std::unique_ptr<DataTransfer> data_transfer, const std::shared_ptr<I_HW_Identification> &hw_identification)

Constructor.

Parameters

data_transfer: Data transfer class owned by the events stream and used to transfer data
hw_identification: Hardware identification associated to this events stream

~I_EventsStream(): Destructor.

void start(): Starts streaming events.

void stop(): Stops streaming events.

short poll_buffer()

Returns a value that informs if some events are available in the buffer from the camera or the file.

Return

Value that informs if some events are available in the buffer

1 if there are events available
0 if no events are available
-1 if an error occurred or no more events will ever be available (like when reaching end of file)

short wait_next_buffer()

Returns a value that informs if some events are available in the buffer from the camera and blocks waiting until more events are available.

Return

Value that informs if some events are available in the buffer

1 if there are events available
-1 if an error occurred or no more events will ever be available (like when reaching end of file)

RawData *get_latest_raw_data(long &n_rawbytes)

Gets latest raw data from the event buffer.

Gets raw data from the event buffer received since the last time this function was called.

Return

Pointer to an array of Event structures

Note

This function must be called to write the buffer of events in the log file defined in log_raw_data

Parameters

n_rawbytes: Address of a variable in which to put the number of bytes contained in the buffer

bool log_raw_data(const std::string &f)

Enables the logging of the stream of events in the input file f.

This methods first writes the header retrieved through I_HW_Identification. Buffers of data are then written each time get_latest_raw_data is called (i.e. in the same thread it is called).

Return

true if the file could be opened for writing, false otherwise or if the file name f is the same as the one read from

Warning

The writing of each buffer of event will have to be triggered by calls to get_latest_raw_data

Parameters

f: The file to log into

void stop_log_raw_data()

Stops logging RAW data.

Does nothing if no recording has been started

void set_underlying_filename(const std::string &filename)

Sets name of the file read to avoid writing in the same file when calling log_raw_data.

Note

This function is directly called when opening a RAW file

Parameters

filename: Name of the file from which the events are read

class Metavision::I_Geometry : public Metavision::I_RegistrableFacility<I_Geometry>

Class to access information on the size of the sensor.

Public Functions

int get_width() const = 0

Returns width of the sensor in pixels.

Return: Sensor’s width

int get_height() const = 0

Returns height of the sensor in pixels.

Return: Sensor’s height

class Metavision::I_HALSoftwareInfo : public Metavision::I_RegistrableFacility<I_HALSoftwareInfo>

Class that provides information about the HAL software.

Public Functions

I_HALSoftwareInfo(const Metavision::SoftwareInfo &software_info)

Constructor.

Parameters

software_info: Information about the HAL software version

const Metavision::SoftwareInfo &get_software_info()

Gets plugin’s software information.

Return: The plugin’s software information

class Metavision::I_HW_Identification : public Metavision::I_RegistrableFacility<I_HW_Identification>

Facility to provide information about the available system.

Public Types

using SystemInfo = std::map<std::string, std::string>

Alias to provide any useful information for the end-user.

Example of possible key-value:

”Connection” : “USB 3.0”
”System Build Date” : “YYYY-MM-DD h:m:s (example : 2017-03-08 13:36:44 ) (UTC time)”

Public Functions

I_HW_Identification(const std::shared_ptr<I_PluginSoftwareInfo> &plugin_sw_info)

Constructor.

Parameters

plugin_sw_info: Information about the plugin software version

std::string get_serial() const = 0

Returns the serial number of the camera.

Return: Serial number as a string

long get_system_id() const = 0

Returns the system id of the camera.

Return: The system id as an integer
Note: This number can be used to check the compatibility of biases file

SensorInfo get_sensor_info() const = 0

Returns the detail about the available sensor.

Return: The sensor information

long get_system_version() const = 0

Returns the version number for this system.

Return: System version as an integer

std::vector<std::string> get_available_raw_format() const = 0

Returns the name of the available RAW format.

Return

The available format

Note

Currently the available formats are:

EVT2
EVT3

std::string get_integrator() const = 0

Returns the integrator name.

Return: Name of the integrator

std::string get_manufacturer() const

Note: get_manufacturer() is deprecated since version 2.2.0 and will be removed in later releases. Please use get_integrator instead

SystemInfo get_system_info() const

Returns all available information.

Return: Map of key-value
Note: The purpose of this function is mainly for debug and display system information The class provides a basic implementation that can be enriched by inherit class

std::string get_connection_type() const = 0

Returns the connection with the camera as a string.

Return: A string providing the type of connection with the available camera

RawFileHeader get_header() const

Returns a header that can be used to log a RAW file.

Return: A header that contains information compatible with this system

struct SensorInfo

Information about the type of sensor available.

Examples for Gen3.1 Sensor:

major_version = 3
minor_version = 1

Public Functions

std::string as_string() const

Returns the sensor’s information

Return: The sensor’s version as a string

Public Members

uint16_t major_version_: Sensor Generation.

uint16_t minor_version_: Sensor Revision.

class Metavision::I_HW_Register : public Metavision::I_RegistrableFacility<I_HW_Register>

Interface facility for writing/reading hardware registers.

Public Functions

void write_register(uint32_t address, uint32_t v) = 0

Writes register.

Parameters

address: Address of the register to write
v: Value to write

void write_register(const std::string &address, uint32_t v) = 0

Writes register.

Parameters

address: Address of the register to write
v: Value to write

uint32_t read_register(uint32_t address) = 0

Reads register.

Return

Value read

Parameters

address: Address of the register to read

uint32_t read_register(const std::string &address) = 0

Reads register.

Return

Value read

Parameters

address: Address of the register to read

void write_register(const std::string &address, const std::string &bitfield, uint32_t v) = 0

Writes register.

Parameters

address: Address of the register to write
bitfield: Bit field of the register to write
v: Value to write

uint32_t read_register(const std::string &address, const std::string &bitfield) = 0

Reads register.

Return

Value read

Parameters

address: Address of the register to read
bitfield: Bit field of the register to read

class Metavision::I_LL_Biases : public Metavision::I_RegistrableFacility<I_LL_Biases>

Interface facility for Lower Level Biases.

Public Functions

bool set(const std::string &bias_name, int bias_value) = 0

Sets bias value.

Return

true on success

Parameters

bias_name: Bias to set
bias_value: Value to set the bias to

int get(const std::string &bias_name) = 0

Gets bias value.

Return

The bias value

Parameters

bias_name: Name of the bias whose value to get

std::map<std::string, int> get_all_biases() = 0

Gets all biases values.

Return: A map containing the biases values

class Metavision::I_Monitoring : public Metavision::I_RegistrableFacility<I_Monitoring>

Interface facility to monitor sensor parameters (such as temperature and illumination)

Public Functions

int get_temperature() = 0

Gets temperature.

Return: Sensor’s temperature (in C)

int get_illumination() = 0

Gets illumination.

Return: Sensor’s illumination (in lux)

class Metavision::I_NoiseFilterModule : public Metavision::I_RegistrableFacility<I_NoiseFilterModule>

Noise filter module.

Note: This feature is available only on Gen4.1 sensors

Public Types

enum Type

Type of implemented filter.

Values:

enumerator STC

enumerator TRAIL

Public Functions

void enable(Type type, uint32_t threshold) = 0

Enables the NoiseFilterModule in the mode STC or Trail with the corresponding threshold.

Note

STC keeps the second event within a burst of events with the same polarity.

Trail keeps the first event within a burst of events with the same polarity

Parameters

type: Defines the type of the filter
threshold: Delay (in microseconds) between two bursts of events

void disable() = 0

Disables filtering.

No events are removed by this filter anymore.

class Metavision::I_PluginSoftwareInfo : public Metavision::I_RegistrableFacility<I_PluginSoftwareInfo>

Provides information about the Plugin software.

Public Functions

I_PluginSoftwareInfo(const std::string &plugin_name, const Metavision::SoftwareInfo &software_info)

Constructor.

Parameters

plugin_name: Name of the plugin
software_info: Information about the HAL software version

const std::string &get_plugin_name() const

Gets plugin name.

Return: The plugin name

const Metavision::SoftwareInfo &get_software_info() const

Gets HAL’s software information.

Return: HAL’s software information

class Metavision::I_ROI : public Metavision::I_RegistrableFacility<I_ROI>

Interface facility for ROI (Region Of Interest)

Public Functions

void enable(bool state) = 0

Applies ROI.

Warning

At least one ROI should have been set before calling this function

Parameters

state: If true, enables ROI. If false, disables it

void set_ROI(const DeviceRoi &roi, bool enable = true)

Sets an ROI from DeviceRoi geometry The ROI input is translated into a bitword (register format) and then programmed in the sensor.

Parameters

roi: ROI to set
enable: If true, applies ROI

void set_ROIs_from_bitword(const std::vector<uint32_t> &vroiparams, bool enable = true) = 0

Sets an ROI from bitword (register format)

Parameters

vroiparams: ROI to set
enable: If true, applies ROI. If false, disables it

void set_ROIs(const std::vector<DeviceRoi> &vroi, bool enable = true)

Sets multiple ROIs.

The input ROIs are translated into a single bitword (register format) and then programmed in the sensor. Due to the sensor format, the final ROI is one or a set of regions (i.e. a grid).

If the input vector is composed of 2 ROIs: (0, 0, 50, 50), (100, 100, 50, 50), then in the sensor, it will give 4 regions: (0, 0, 50, 50), (0, 100, 50, 50), (100, 0, 50, 50) and (100, 100, 50, 50).

If the input vector is composed of 2 ROIs: (0, 0, 50, 50), (25, 25, 50, 50), then in the sensor it will give 1 region: (0, 0, 75, 75)

Parameters

vroi: A vector of ROIs
enable: If true, applies ROI. If false, disables it

void set_ROIs_from_file(std::string const &file_path, bool enable = true)

Sets union of several ROIs from a file with CSV format “x y width height”.

Parameters

file_path: Path to the CSV file with ROIs
enable: If true, applies ROI. If false, disables it

bool set_ROIs(const std::vector<bool> &cols_to_enable, const std::vector<bool> &rows_to_enable, bool enable = true) = 0

Sets multiple rectangular ROIs in bitword register format from two binary maps (for rows and a columns)

The binary maps (std::vector<bool>) arguments must have the sensor’s dimension

Return

true if input have the correct dimension and thus the ROI is set correctly, false otherwise

Warning

For a pixel to be enabled, it must be enabled on both its row and column

Parameters

cols_to_enable: Vector of boolean of size sensor’s width representing the binary map of the columns to disable (0) or to enable (1)
rows_to_enable: Vector of boolean of size sensor’s height representing the binary map of the rows to disable (0) or to enable (1)
enable: If true, applies ROI

std::vector<uint32_t> create_ROI(const DeviceRoi &roi)

Creates a rectangular ROI in bitword register format.

Return

The ROI in bitword register format

Parameters

roi: ROI’s geometry to transform to bitword register format

std::vector<uint32_t> create_ROIs(const std::vector<DeviceRoi> &vroi) = 0

Creates several rectangular ROIs in bitword register format.

Return

The ROIs in bitword register format

Parameters

vroi: Vector of ROI to transform to bitword register format

class Metavision::I_TriggerIn : public Metavision::I_RegistrableFacility<I_TriggerIn>

Interface to handle external trigger signals.

Public Functions

bool enable(uint32_t channel) = 0

Enables external trigger monitoring.

Return

true if trigger was successfully enabled, false otherwise

Warning

Trigger monitoring is disabled by default on camera start. So you need to call enable() to start detecting signal.

Parameters

channel: External trigger’s address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)

bool disable(uint32_t channel) = 0

Disables external trigger monitoring.

Return

true if trigger was successfully disabled, false otherwise

Parameters

channel: External trigger’s address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)

bool is_enabled(uint32_t index) = 0

Checks if the trigger in index is enabled.

Return: true if the trigger in index is enabled, False otherwise

class Metavision::I_TriggerOut : public Metavision::I_RegistrableFacility<I_TriggerOut>

Internal interface for trigger out signal configuration.

Note: The trigger out signal is a binary signal

Public Functions

bool enable() = 0

Enables the trigger out.

Return: true if trigger was successfully enabled, false otherwise

void disable() = 0: Disables the trigger out.

void set_period(uint32_t period_us) = 0

Sets the trigger out signal period (in us)

Parameters

period_us: the period to set (in us)

void set_duty_cycle(double period_ratio) = 0

Sets the duty cycle of the trigger out signal i.e. the pulse duration.

The duty cycle represents the part of the signal, during which its value is 1 (0 otherwise). Duty cycle represents the quantity pulse_width_us/period_us and thus must be in the range [0, 1]. The period is set with set_period.

Setting a duty cycle of 0.5 (50%) means that the value of the signal is 1 during the first half of each period, and 0 during the second half.

Parameters

period_ratio: the ratio representing pulse_width_us/period_us which must be in the range [0,1] (value is clamped in this range otherwise)

bool is_enabled() = 0

Checks if trigger out is enabled.

Return: true if trigger out is enabled, False otherwise

bool loopback(bool enable)

Note: loopback(bool) is deprecated since version 2.2.0 and will be removed later releases.