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.