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 and newer

Public Functions

virtual void enable() = 0

Enables the anti-flicker filter.

virtual void disable() = 0

Disables the anti-flicker filter.

virtual 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

Throws

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

virtual 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

Throws

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.

using ProtocolViolationCallback_t = std::function<void(DecoderProtocolViolation)>

Alias for callback on protocol violation.

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.

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

Returns

ID of the added callback

bool remove_time_callback(size_t callback_id)

Removes a previously registered time callback.

Note

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

Parameters

callback_id – Callback ID

Returns

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

virtual size_t add_protocol_violation_callback(const ProtocolViolationCallback_t &cb)

Adds a function to be called when decoder protocol is breached.

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

Returns

ID of the added callback

virtual bool remove_protocol_violation_callback(size_t callback_id)

Removes a previously registered protocol violation callback.

Note

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

Parameters

callback_id – Callback ID

Returns

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

virtual timestamp get_last_timestamp() const = 0

Gets the timestamp of the last event.

Returns

Timestamp of the last event

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

Returns

true if the timestamp shift is already known, false otherwise

bool is_time_shifting_enabled() const

Returns true if doing timestamp shift, false otherwise.

virtual 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 class SyncMode

Enumerate synchronization modes.

Values:

enumerator STANDALONE

enumerator MASTER

enumerator SLAVE

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.

virtual 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

Returns

true on success

virtual 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

Returns

true on success

virtual 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

Returns

true on success

virtual SyncMode get_mode() = 0

Retrieves Synchronization mode.

Returns

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

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

virtual bool is_enabled() = 0

Returns ERC activation state.

Returns

The ERC state

virtual 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

virtual uint32_t get_cd_event_rate()

Gets the CD event rate set point of the ERC.

Note

See set_cd_event_rate to define the event rate target.

Returns

The event rate expressed in events per second

virtual uint32_t get_count_period() const = 0

Gets the count period.

Returns

The count period duration expressed in microseconds

virtual 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

virtual uint32_t get_cd_event_count() = 0

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

Note

See set_cd_event_count to define the event count parameter.

Returns

The maximum event count

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 Functions

size_t add_event_buffer_callback(const EventBufferCallback_t &cb)

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

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

Returns

ID of the added callback

bool remove_callback(size_t callback_id)

Removes a previously registered callback.

See also

add_event_buffer_callback

Parameters

callback_id – Callback ID

Returns

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

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

virtual void enable(bool enable_filter) = 0

Enables/disables the noise filter.

Parameters

enable_filter – Whether to enable the noise filtering

virtual bool set_event_rate_threshold(uint32_t threshold_Kev_s) = 0

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

Parameters

threshold_Kev_s – Event rate threshold in Kevt/s

Returns

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

virtual uint32_t get_event_rate_threshold() = 0

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

Returns

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.

Returns

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.

Returns

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.

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

Returns

Pointer to an array of Event structures

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

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

Returns

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

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

virtual int get_width() const = 0

Returns width of the sensor in pixels.

Returns

Sensor’s width

virtual int get_height() const = 0

Returns height of the sensor in pixels.

Returns

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.

Returns

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

virtual std::string get_serial() const = 0

Returns the serial number of the camera.

Returns

Serial number as a string

virtual long get_system_id() const = 0

Returns the system id of the camera.

Note

This number can be used to check the compatibility of biases file

Returns

The system id as an integer

virtual SensorInfo get_sensor_info() const = 0

Returns the detail about the available sensor.

Returns

The sensor information

virtual long get_system_version() const = 0

Returns the version number for this system.

Returns

System version as an integer

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

Returns the name of the available RAW format.

Note

Currently the available formats are:

• EVT2

• EVT3

Returns

The available format

virtual std::string get_integrator() const = 0

Returns the integrator name.

Returns

Name of the integrator

virtual SystemInfo get_system_info() const

Returns all available information.

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

Returns

Map of key-value

virtual std::string get_connection_type() const = 0

Returns the connection with the camera as a string.

Returns

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.

Returns

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

inline std::string as_string() const

Returns the sensor’s information

Returns

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

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

Writes register.

Parameters

• address – Address of the register to write

• v – Value to write

virtual 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

virtual uint32_t read_register(uint32_t address) = 0

Reads register.

Parameters

address – Address of the register to read

Returns

Value read

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

Reads register.

Parameters

address – Address of the register to read

Returns

Value read

virtual 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

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

Reads register.

Parameters

• address – Address of the register to read

• bitfield – Bit field of the register to read

Returns

Value read

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

Interface facility for Lower Level Biases.

Public Functions

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

Sets bias value.

Parameters

• bias_name – Bias to set

• bias_value – Value to set the bias to

Returns

true on success

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

Gets bias value.

Parameters

bias_name – Name of the bias whose value to get

Returns

The bias value

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

Gets all biases values.

Returns

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

virtual int get_temperature() = 0

Gets temperature.

Returns

Sensor’s temperature (in C)

virtual int get_illumination() = 0

Gets illumination.

Returns

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 class Type

Type of implemented filter.

Values:

enumerator STC

enumerator TRAIL

Public Functions

virtual 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

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

Returns

The plugin name

const Metavision::SoftwareInfo &get_software_info() const

Gets HAL’s software information.

Returns

HAL’s software information

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

Interface facility for ROI (Region Of Interest)

Public Functions

virtual 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

virtual 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

virtual 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

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

Returns

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

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

Creates a rectangular ROI in bitword register format.

Parameters

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

Returns

The ROI in bitword register format

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

Creates several rectangular ROIs in bitword register format.

Parameters

vroi – Vector of ROI to transform to bitword register format

Returns

The ROIs in bitword register format

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

Interface to handle external trigger signals.

Public Functions

virtual bool enable(uint32_t channel) = 0

Enables external trigger monitoring.

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 (depends on the camera and sensor; see camera’s documentation)

Returns

true if trigger was successfully enabled, false otherwise

virtual bool disable(uint32_t channel) = 0

Disables external trigger monitoring.

Parameters

channel – External trigger’s address (depends on the camera and sensor; see camera’s documentation)

Returns

true if trigger was successfully disabled, false otherwise

virtual bool is_enabled(uint32_t channel) = 0

Checks if the trigger in channel is enabled.

Returns

true if the trigger in channel 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

virtual bool enable() = 0

Enables the trigger out.

Returns

true if trigger was successfully enabled, false otherwise

virtual void disable() = 0

Disables the trigger out.

virtual 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)

virtual 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)

virtual bool is_enabled() = 0

Checks if trigger out is enabled.

Returns

true if trigger out is enabled, False otherwise