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] HzNote
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
-
virtual void
-
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
ProtocolViolationCallback_t
= std::function<void(DecoderProtocolViolation)> Alias for callback on protocol violation.
Public Functions
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 ×tamp_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.
-
using
-
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
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 void
-
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
-
virtual void
-
template<typename
Event
>
classMetavision
::
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
- 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
-
virtual void
-
class
Metavision
::
I_EventsStream
: public Metavision::I_RegistrableFacility<I_EventsStream> Class for getting buffers from cameras or files.
Public Functions
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.
-
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
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
-
using
-
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
-
virtual void
-
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
-
virtual bool
-
class
Metavision
::
I_Monitoring
: public Metavision::I_RegistrableFacility<I_Monitoring> Interface facility to monitor sensor parameters (such as temperature and illumination)
-
class
Metavision
::
I_NoiseFilterModule
: public Metavision::I_RegistrableFacility<I_NoiseFilterModule> Noise filter module.
Note
This feature is available only on Gen4.1 sensors
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.
-
virtual void
-
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
-
virtual void
-
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
-
virtual bool
-
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
-
virtual bool