HAL Facilities API

The Metavision::Device object of HAL allows a user to access the camera functionalities by requesting access to the facilities using one of the class listed below. Note that facilities availability depends on the device type (camera or RAW file) and on the Prophesee sensor generation.

Facility Name	Class	Camera (sensor) availability	RAW File availability
Anti-flicker	`I_AntiFlickerModule`	Gen4.1, IMX636 and GenX320	No
Camera Synchronization	`I_CameraSynchronization`	Yes	No
Decoder	`I_Decoder`	Yes	Yes
Digital Crop	`I_DigitalCrop`	Gen4.1, IMX636 and GenX320	No
Digital Event Mask	`I_DigitalEventMask`	Gen4.1, IMX636 and GenX320	No
Event Rate Control (ERC)	`I_ErcModule`	Gen4.1, IMX636 and GenX320	No
Event Decoder	`I_EventDecoder`	Yes	Yes
Event Frame Decoder	`I_EventFrameDecoder`	Yes	Yes
Event Rate Activity Filter	`I_EventRateActivityFilterModule`	Gen3.1 and GenX320	No
Event Trail Filter (STC, Trail)	`I_EventTrailFilterModule`	Gen4.1, IMX636 and GenX320	No
Events Stream	`I_EventsStream`	Yes	Yes
Event Stream Decoder	`I_EventsStreamDecoder`	Yes	Yes
Geometry	`I_Geometry`	Yes	Yes
HAL Software Info	`I_HALSoftwareInfo`	Yes	Yes
Hardware Identification	`I_HW_Identification`	Yes	Yes
Hardware Register	`I_HW_Register`	Yes	No
Biases	`I_LL_Biases`	Yes	No
Monitoring	`I_Monitoring`	Dead Time available on Gen4.1, IMX636 and GenX320	No
Plugin Software Info	`I_PluginSoftwareInfo`	Yes	Yes
ROI	`I_ROI`	Yes	No
ROI Pixel Mask	`I_RoiPixelMask`	GenX320 only	No
Trigger In	`I_TriggerIn`	Yes	No
Trigger Out	`I_TriggerOut`	Depends on EVK model	No

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

Anti-flicker module.

Public Types

enum AntiFlickerMode

AntiFlicker filter mode.

BAND_PASS removes all events outside of the band sequence defined.

BAND_STOP removes all frequencies between min and max.

Values:

enumerator BAND_PASS

enumerator BAND_STOP

Public Functions

virtual bool enable(bool b) = 0

Toggles Anti-flicker activation.

Note

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

Parameters: b – Desired state. b = true means Anti-flicker active, and b = false means Anti-flicker inactive.
Returns: true on success

virtual bool is_enabled() const = 0

Returns Anti-flicker activation state.

Returns: The Anti-flicker state

virtual bool set_frequency_band(uint32_t low_freq, uint32_t high_freq) = 0

Sets anti-flicker parameters.

Defines the frequency band to be kept or removed in the range [min_supported_freq, max_supported_freq] Hz where minimum and maximum supported frequencies can be obtained with get_min_supported_frequency

Note

Facility might be reset if parameter is changed while enabled

Parameters

low_freq – Lowest frequency of the band (in Hz)
high_freq – Highest frequency of the band (in Hz)

Throws

exception – if frequencies are outside of the range [min_supported_freq, max_supported_freq] Hz

Returns

true on success

virtual uint32_t get_band_low_frequency() const = 0: Gets lowest frequency of the band.

virtual uint32_t get_band_high_frequency() const = 0: Gets highest frequency of the band.

std::pair<uint32_t, uint32_t> get_frequency_band() const: Gets frequency band setting.

virtual uint32_t get_min_supported_frequency() const = 0: Gets minimum supported frequency.

virtual uint32_t get_max_supported_frequency() const = 0: Gets maximum supported frequency.

virtual bool set_filtering_mode(AntiFlickerMode mode) = 0

Sets the anti-flicker filtering mode.

Note

Facility might be reset if parameter is changed while enabled

Parameters: mode – Anti-flicker mode
Returns: true on success

virtual AntiFlickerMode get_filtering_mode() const = 0: Gets filtering mode.

virtual bool set_duty_cycle(float duty_cycle) = 0

Sets the duty cycle for Antiflicker filter.

Parameters: duty_cycle – Target duty cycle of Antiflicker filter as a percentage
Returns: true on success, false otherwise

virtual float get_duty_cycle() const = 0

Gets the duty cycle for Antiflicker filter.

Returns: The duty cycle for Antiflicker filter as a percentage

virtual float get_min_supported_duty_cycle() const = 0: Gets minimum supported duty cycle value.

virtual float get_max_supported_duty_cycle() const = 0: Gets maximum supported duty cycle value.

virtual bool set_start_threshold(uint32_t threshold) = 0

Sets the threshold above which Antiflicker should start filtering.

Parameters: threshold – Number of successive periodic event bursts falling within the frequency band
Returns: true on success, false otherwise

virtual bool set_stop_threshold(uint32_t threshold) = 0

Sets the threshold below which Antiflicker should stop filtering.

Parameters: threshold – Number of successive periodic event bursts falling within the frequency band
Returns: true on success, false otherwise

virtual uint32_t get_start_threshold() const = 0

Gets the Antiflicker start threshold.

Returns: The threshold in number of bursts

virtual uint32_t get_stop_threshold() const = 0

Gets the Antiflicker stop threshold.

Returns: The threshold in number of bursts

virtual uint32_t get_min_supported_start_threshold() const = 0

Gets the Antiflicker start threshold minimum supported value.

Returns: Start threshold minimum supported value

virtual uint32_t get_max_supported_start_threshold() const = 0

Gets the Antiflicker start threshold maximum supported value.

Returns: Start threshold maximum supported value

virtual uint32_t get_min_supported_stop_threshold() const = 0

Gets the Antiflicker stop threshold minimum supported value.

Returns: Stop threshold minimum supported value

virtual uint32_t get_max_supported_stop_threshold() const = 0

Gets the Antiflicker stop threshold maximum supported value.

Returns: Stop threshold maximum supported value

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

Facility that controls the camera mode (standalone, master or slave)

Public Types

enum class SyncMode

Enumerate synchronization modes.

Values:

enumerator STANDALONE

enumerator MASTER

enumerator SLAVE

Public Functions

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() const = 0

Retrieves Synchronization mode.

Returns: synchronization mode

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

Subclassed by Metavision::I_RegistrableFacility< I_EventFrameDecoder< FrameType >, I_Decoder >, Metavision::I_RegistrableFacility< I_EventFrameDecoder< PointCloud >, I_Decoder >, Metavision::I_RegistrableFacility< I_EventFrameDecoder< RawEventFrameDiff >, I_Decoder >, Metavision::I_RegistrableFacility< I_EventFrameDecoder< RawEventFrameHisto >, I_Decoder >, Metavision::I_RegistrableFacility< I_EventsStreamDecoder, I_Decoder >

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

virtual void decode(const RawData *const raw_data_begin, const RawData *const raw_data_end) = 0

Decodes raw data.

Parameters

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

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 uint8_t get_raw_event_size_bytes() const = 0: Gets size of a raw event element in bytes.

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

Digital Crop feature All pixels outside of the cropping region will be dropped by the sensor.

Public Types

using Region = std::tuple<uint32_t, uint32_t, uint32_t, uint32_t>

Structure that defines a Region with 4 values :

X (horizontal) position of the start pixel of the top left region
Y (vertical) position of the start pixel of the top left region
X (horizontal) position of the end pixel of the bottom right region
Y (vertical) position of the end pixel of the bottom right region

Public Functions

virtual bool enable(bool state) = 0

Applies Digital Crop.

Parameters: state – If true, enables Digital Crop. If false, disables it
Returns: true on success

virtual bool is_enabled() const = 0

Returns Digital Crop activation state.

Returns: The Digital Crop state

virtual bool set_window_region(const Region &region, bool reset_origin = false) = 0

Defines digital crop window region.

Warning

When reset_origin is true, start_x must be a multiple of 32 and end_x a multiple of 31, if not then the function will fail and return false.

Parameters

region – The region of pixels that should be cropped
reset_origin – If true, the origin of the event output coordinates will shift to the Crop Window start

Returns

true on success

virtual Region get_window_region() const = 0

Gets the digital crop window region currently defined.

Returns: digital crop window region currently defined

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

Interface for Digital Event Mask commands.

Public Types

using I_PixelMaskPtr = std::shared_ptr<I_PixelMask>: Type of a pointer to a pixel mask.

Public Functions

virtual ~I_DigitalEventMask() = default: default destructor

virtual const std::vector<I_PixelMaskPtr> &get_pixel_masks() const = 0

Get all available masks.

Returns: a list of pixel masks pointer

class I_PixelMask

Interface for Digital Pixel Mask commands.

Note

Each mask can be associated with a pixel and enabled/disabled on demand

Public Functions

virtual ~I_PixelMask() = default: default destructor

virtual bool set_mask(uint32_t x, uint32_t y, bool enabled) = 0

Set coordinate for the pixel to be masked.

Parameters

x – the pixel horizontal coordinate
y – the pixel vertical coordinate
enabled – when true, the mask will prevent pixel from generating CD event

Returns

true on success

virtual std::tuple<uint32_t, uint32_t, bool> get_mask() const = 0

Get the current mask settings.

Returns: a tuple that packs the X and Y pixel coordinates and a boolean defining whether the mask is enabled

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

Interface for Event Rate Controller (ERC) commands.

Public Functions

virtual bool 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.
Returns: true on success

virtual bool is_enabled() const = 0

Returns ERC activation state.

Returns: The ERC state

virtual bool 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
Returns: true on success

virtual uint32_t get_min_supported_cd_event_rate() const: Gets the minimum supported value for cd_event_rate setting.

virtual uint32_t get_max_supported_cd_event_rate() const: Gets the maximum supported value for cd_event_rate setting.

virtual uint32_t get_cd_event_rate() const

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 bool 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
Returns: true on success

virtual uint32_t get_min_supported_cd_event_count() const = 0: Gets the minimum supported value for cd_event_count setting.

virtual uint32_t get_max_supported_cd_event_count() const = 0: Gets the maximum supported value for cd_event_count setting.

virtual uint32_t get_cd_event_count() const = 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.

template<class FrameType> class Metavision::I_EventFrameDecoder : public Metavision::I_RegistrableFacility<I_EventFrameDecoder<FrameType>, 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.

Subclassed by Metavision::EHCDecoder< FrameType, T >

Public Types

using EventFrameCallback_t = std::function<void(const FrameType&)>: Alias for raw data type.

Public Functions

size_t add_event_frame_callback(const EventFrameCallback_t &cb)

Sets the functions to call to each decoded frame of 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_frame_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

virtual void decode(const I_Decoder::RawData *const raw_data_begin, const I_Decoder::RawData *const raw_data_end) = 0

Decodes raw event frame data.

Warning

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

Parameters

raw_data_begin – Pointer to start of frame data
raw_data_end – Pointer after the last byte of frame data

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

std::shared_ptr<const FrameType> get_last_frame()

Returns the last complete decoded frame.

Returns: Last decoded frame, nullptr if no frame has been completely decoded yet

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

Interface for accessing the sensor event rate activity filter.

This sensor level 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 and below a given event rate. It avoids streaming background noise information without relevant activity and streaming high event rate flashing scenes, saving bandwidth and power.

Public Functions

virtual bool enable(bool enable_filter) = 0

Enables/disables the event rate activity filter.

Parameters: enable_filter – Whether to enable the filter

virtual bool is_enabled() const = 0

Returns the event rate activity filter state.

Returns: the filter state

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() const = 0

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

Returns: Event rate threshold in Kevt/s

virtual thresholds is_thresholds_supported() const = 0

Gets band pass filter hysteresis thresholds supported by the sensor.

Returns: thresholds thresholds structure with values 0/1 depending if corresponding threshold is supported.

virtual bool set_thresholds(const thresholds &thresholds_ev_s) = 0

Sets band pass filter hysteresis thresholds.

Warning

Partially initialize structure thresholds_ev_s could lead to random threshold values being set. Use is_thresholds_supported function to know which threshold values could be omitted.

Parameters: thresholds_ev_s – Event rate thresholds data structure in evt/s
Returns: true if the input value was correctly set (i.e. it falls in the range of acceptable values for the sensor)

virtual thresholds get_thresholds() const = 0

Gets band pass filter hysteresis thresholds.

Returns: thresholds event rate thresholds structure.

virtual thresholds get_min_supported_thresholds() const = 0

Gets band pass filter hysteresis minimum thresholds configuration.

Returns: thresholds event rate thresholds structure.

virtual thresholds get_max_supported_thresholds() const = 0

Gets band pass filter hysteresis maximum thresholds configuration.

Returns: thresholds event rate thresholds structure.

struct thresholds

Band pass filter hysteresis thresholds for event rate activity filter.

Note

Not all thresholds are supported given the sensor generation

Parameters

lower_bound_start – Event rate threshold for the band pass filter to start filtering incoming events. Below this threshold, no events are streamed.
lower_bound_stop – Event rate threshold for the band pass filter to stop filtering and resume streaming of incoming events. Above this threshold, events are streamed again after the filter was actively dropping events using the lower_bound_start threshold condition.
upper_bound_start – Event rate threshold for the band pass filter to start filtering incoming events. Above this threshold, no events are streamed.
upper_bound_stop – Event rate threshold for the band pass filter to stop filtering and resume streaming of incoming events. Below this threshold, events are streamed again after the filter was actively dropping events using the upper_bound_start threshold condition.

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

Noise filter module.

Public Types

enum class Type

Type of implemented filter.

TRAIL: filters out trailing events from event bursts, keeping only the first event. STC_CUT_TRAIL: after a polarity change, filters out the first event of a burst as well as trailing events after the second event, keeping only the second event from the burst. Single events are filtered out. STC_KEEP_TRAIL: after a polarity change, filters out the first event of burst, keeping all the trailing events from the burst. Single events are filtered out.

A burst is defined as events of the same polarity occurring within a threshold period.

Note

Some filter types are not available for some devices

Values:

enumerator TRAIL

enumerator STC_CUT_TRAIL

enumerator STC_KEEP_TRAIL

Public Functions

virtual std::set<Type> get_available_types() const = 0

Returns the set of available types of filters.

Returns: set of available types of filters

virtual bool enable(bool state) = 0

Enables the EventTrailFilterModule with previously configured settings. Filtering type and threshold should be set before enabling.

Parameters: state – If true, enables the module. If false, disables it
Returns: true on success

virtual bool is_enabled() const = 0

Returns EventTrailFilterModule activation state.

Returns: The EventTrailFilterModule state

virtual bool set_type(Type type) = 0

Sets the event trail filtering type.

Note

Facility might be reset if parameter is changed while enabled

Returns: true on success

virtual Type get_type() const = 0

Gets the event trail filtering type.

Returns: The event trail filtering type

virtual bool set_threshold(uint32_t threshold) = 0

Sets the event trail filtering threshold delay.

Note

Facility might be reset if parameter is changed while enabled

Parameters: threshold – Delay (in microseconds) between two bursts of events
Returns: true on success

virtual uint32_t get_threshold() const = 0

Gets the event trail filtering threshold delay (in microseconds)

Returns: The event trail filtering threshold

virtual uint32_t get_max_supported_threshold() const = 0

Gets the maximum supported value for event trail filtering threshold delay (in microseconds)

Returns: The maximum supported threshold value

virtual uint32_t get_min_supported_threshold() const = 0

Gets the minimum supported value for event trail filtering threshold delay (in microseconds)

Returns: The minimum supported threshold value

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

Class for getting buffers from cameras or files.

Public Types

enum class SeekStatus

Enumerator stating the different output of a call to seek.

Values:

enumerator Success

enumerator Failed

enumerator InputTimestampNotReachable

enumerator IndexNotAvailableYet

enumerator SeekCapabilityNotAvailable

enum class IndexStatus

Enumerator stating the status of index.

Values:

enumerator Good: Index is loaded and ready to be used.

enumerator Bad: Index failed to be loaded or built. Seek operation can not be done.

enumerator Building: Index is being built. Seek operations are not available yet.

enumerator NotBuilt: Index has not been built: index has not been called yet.

using Bookmarks = std::vector<Bookmark>: List of bookmarks in the index.

Public Functions

I_EventsStream(std::unique_ptr<DataTransfer> data_transfer, const std::shared_ptr<I_HW_Identification> &hw_identification, const std::shared_ptr<I_EventsStreamDecoder> &decoder = nullptr, const std::shared_ptr<DeviceControl> &device_control = std::shared_ptr<DeviceControl>())

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
decoder – Decoder associated to this events stream
device_control – Device control class for starting and stopping

~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

DataTransfer::BufferPtr get_latest_raw_data()

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

Returns: Pointer to a vector 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

const std::string &get_underlying_filename() const: Gets name of the file read to avoid writing in the same file when calling log_raw_data.

SeekStatus seek(timestamp target_ts_us, timestamp &reached_ts_us)

Tries to reach the input target_ts_us in the file If the seek succeeds, the next data read from the file and accessible through get_latest_raw_data will hold data from the closest bookmark (lower timestamp). The first timestamp decoded then will be reached_ts_us.

Parameters

target_ts_us – The target timestamp to reach in the RAW file
reached_ts_us – The reached timestamp if the seek succeeds

Returns

a status (SeekStatus) holding the result of the seek

IndexStatus get_seek_range(timestamp &event_start_ts_us, timestamp &event_end_ts_us) const

Gets the range of timestamp reachable through the seek method.

Parameters

event_start_ts_us – The timestamp of the first valid data in the file
event_end_ts_us – The timestamp of the last valid data in the file

Returns

true If the seek feature is implemented

void index(std::unique_ptr<Device> device_for_indexing)

Builds an index to enable navigation in a RAW file through the seek and get_seek_range routines.

To navigate efficiently, an index is created allowing to associate a timestamp with a position in the file. When this index is loaded in memory, one can get the range of timestamp that can be reached when navigating.

If the index already exists for the source RAW file, it is just loaded in memory. Otherwise it is built in a dedicated thread. Until the index is loaded in memory, seek operations are not available. The return value of get_seek_range can be used to check the current IndexStatus.

Warning

The input device must have been built with the same RAW file used to initialize this class

Parameters: device_for_indexing – The device to use to index the RAW file.

struct Bookmark: Structure representing a bookmark that composes the index.

struct Index

The index structure.

Public Members

Bookmarks bookmarks_: the bookmarks that compose the index

uint32_t bookmark_period_ = {0}: the minimum period between two successive bookmarks

timestamp ts_shift_us_ = {0}: The timeshift to apply to the data.

IndexStatus status_ = {IndexStatus::NotBuilt}: The index’s state.

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

Interface for decoding a stream of 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.

Subclassed by Metavision::AERDecoder< HAS_4_BITS_INTERFACE >, Metavision::detail::EVT3Decoder< Validator >, Metavision::EVT21GenericDecoder< RawEvent, Event_TIME_HIGH, Event_2D, Event_EXT_TRIGGER, Event_OTHERS >, Metavision::EVT2Decoder

Public Types

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

Public Functions

I_EventsStreamDecoder(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>>(), const std::shared_ptr<I_EventDecoder<EventERCCounter>> &erc_count_event_decoder = std::shared_ptr<I_EventDecoder<EventERCCounter>>())

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
erc_count_event_decoder – Optional decoder of ERC counter events

virtual void decode(const RawData *const raw_data_begin, const RawData *const raw_data_end) override

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

bool reset_timestamp(const Metavision::timestamp &timestamp)

Resets the decoder last timestamp.

Note

After this call has succeeded, that get_last_timestamp returns timestamp

Warning

If time shifting is enabled, the timestamp must be in the shifted time reference

Warning

Additional care may be required regarding the expected content of the data to be decoded after this function has been called. Refer to the constraints and limitations of a specific decoder implementation (e.g EVT2Decoder::reset_timestamp_impl, EVT21Decoder::reset_timestamp_impl and EVT3Decoder::reset_timestamp_impl)

Parameters: timestamp – Timestamp to reset the decoder to
Returns: true if the reset operation could complete, false otherwise.

bool reset_timestamp_shift(const Metavision::timestamp &shift)

Resets the decoder timestamp shift.

Note

If time shifting is disabled, this function does nothing

Parameters: shift – Timestamp shift to reset the decoder to
Returns: True if the reset operation could complete, false otherwise.

virtual bool is_decoded_event_stream_indexable() const: Returns true if the decoded events stream can be indexed.

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 std::vector<std::string> get_available_data_encoding_formats() const = 0

Returns the name of the available data encoding formats.

Note

Currently the available formats are:

EVT2
EVT21
EVT3

Returns: The available data encoding formats

virtual std::string get_current_data_encoding_format() const = 0

Returns the name of the currently used data encoding format.

See also

get_available_data_encoding_formats

Returns: The currently used data encoding 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

DeviceConfigOptionMap get_device_config_options() const

Lists device config options supported by the camera.

Returns: the map of (key,option) device config options

struct SensorInfo

Information about the type of sensor available.

Examples for Gen3.1 Sensor:

major_version = 3
minor_version = 1

Public Functions

SensorInfo() = default: Constructor.

SensorInfo(uint16_t major_version, uint16_t minor_version, const std::string &name): Constructor.

SensorInfo(const std::string &name): Constructor.

Public Members

uint16_t major_version_: Sensor Generation.

uint16_t minor_version_: Sensor Revision.

std::string name_: Sensor Name.

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 Low Level Biases.

Public Functions

I_LL_Biases(const DeviceConfig &device_config)

Constructor.

Parameters: device_config – Device configuration

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

Sets bias value.

Parameters

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

Returns

true on success

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

Gets bias value.

Parameters: bias_name – Name of the bias whose value to get
Returns: The bias value

bool get_bias_info(const std::string &bias_name, LL_Bias_Info &bias_info) const

Gets bias metadata.

Parameters

bias_name – Name of the bias whose metadata to get
bias_info – Metadata of the bias to get

Returns

true on success

virtual std::map<std::string, int> get_all_biases() const = 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) or throw on Error

virtual int get_illumination() = 0

Gets illumination.

Returns: Sensor’s illumination (in lux) or throw on Error

virtual int get_pixel_dead_time() = 0

Gets Pixel Dead Time (aka. “refractory period”). This is the minimum time latency between the generation of 2 events by a pixel.

Returns: Estimated dead time (in us) throw on Error

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

Provides information about the Plugin software.

Public Functions

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

Constructor.

Parameters

plugin_integrator_name – Name of the plugin integrator
plugin_name – Name of the plugin
software_info – Information about the HAL software version

const std::string &get_plugin_integrator_name() const

Gets plugin integrator name.

Returns: The name of the plugin integrator

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 Types

enum class Mode

Window mode.

ROI : Region of interest, any event outside the window will be discarded RONI : Region of non interest, any event inside the window will be discarded

Values:

enumerator ROI

enumerator RONI

Public Functions

virtual bool 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
Returns: true on success

virtual bool is_enabled() const = 0

Returns ROI/RONI activation state.

Returns: The ROI/RONI state

virtual bool set_mode(const Mode &mode) = 0

Sets the window mode.

Parameters: mode – window mode to set (ROI or RONI)
Returns: true on success

virtual Mode get_mode() const = 0

Gets the window mode.

Returns: the window mode

bool set_window(const Window &window)

Sets a window.

The window will be applied according to the current mode (ROI or RONI)

Parameters: window – window to set
Returns: true on success

virtual size_t get_max_supported_windows_count() const = 0

Gets the maximum number of windows.

Returns: the maximum number of windows that can be set via set_windows

bool set_windows(const std::vector<Window> &windows)

Sets multiple windows.

The windows will be applied according to the current mode (ROI or RONI) In ROI mode, enabled pixels are those inside the provided rectangles. In RONI mode, enabled pixels are those where row OR column are covered by the provided rectangle.

Parameters: windows – A vector of windows to set
Throws: an – exception if the size of windows is higher than the maximum supported number of windows (see get_max_supported_windows_count)
Returns: true on success

virtual std::vector<Window> get_windows() const = 0

Gets active ROI/RONI windows.

Returns: The vector of active windows

virtual bool get_lines(std::vector<bool> &cols, std::vector<bool> &rows) const = 0

Gets active ROI/RONI lines.

Parameters

cols – vector to store active columns
rows – vector to store active rows

Returns

true on success

virtual bool set_lines(const std::vector<bool> &cols, const std::vector<bool> &rows) = 0

Sets multiple lines and columns from row and column binary maps.

The binary maps (std::vector<bool>) arguments must have the sensor’s dimension. The lines and columns will be applied according to the current mode (ROI or RONI). In ROI mode, enabled pixels are those where row AND column are set to true. In RONI mode, disabled pixels are those where row AND column are set to false. This means that conversely, enabled pixels are those where row OR column are set to true.

Parameters

cols – Vector of boolean of size sensor’s width representing the binary map of the columns to enable
rows – Vector of boolean of size sensor’s height representing the binary map of the rows to enable

Returns

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

class Window

Defines a simple rectangular window.

Public Functions

Window(int x, int y, int width, int height): Creates a window defined by the corners {(x, y), (x + width, y + height)}.

std::string to_string() const

Returns the window as a string.

Returns: Human readable string representation of a window

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

Interface facility for ROI (Region Of Interest) pixel mask.

Public Functions

virtual bool set_pixel(const unsigned int &column, const unsigned int &row, const bool &enable) = 0

Set individual pixel ROI mask The pixel coordinates are stored in the driver and will be sent to the sensor when apply_pixels function is called.

Parameters

column – Pixel x coordinate
row – Pixel y coordinate
enable – Pixel will be masked when true

Returns

true on success

virtual void apply_pixels() = 0: Apply pixels configuration to sensor Pixels selected to be masked with the set_pixel function are applied to the sensor hardware.

virtual void reset_pixels() = 0: Reset pixels configuration applied on the sensor All previous pixels masked on the sensor will be enabled back. Pixels configuration in the driver is cleared.

virtual std::vector<std::pair<unsigned int, unsigned int>> get_pixels() const = 0

Get list of pixels selected for masking.

Returns: list of x, y coordinates

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

Interface to handle external trigger signals.

Public Types

enum class Channel

External trigger channel.

On most systems, only one (main) channel can be enabled. On some systems, an additional auxiliary and/or loopback channel may be available.

Values:

enumerator Main

enumerator Aux

enumerator Loopback

Public Functions

virtual bool enable(const Channel &channel) = 0

Enables external trigger monitoring.

Warning

External trigger monitoring is disabled by default on camera start

Parameters: channel – external trigger channel to enable
Returns: true if external trigger monitoring was successfully enabled, false otherwise

virtual bool disable(const Channel &channel) = 0

Disables external trigger monitoring.

Parameters: channel – external trigger channel to disable
Returns: true if external trigger monitoring was successfully disabled, false otherwise

virtual bool is_enabled(const Channel &channel) const = 0

Checks if external trigger monitoring is enabled.

Parameters: channel – external trigger channel to check
Returns: true if external trigger monitoring is enabled, False otherwise

virtual std::map<Channel, short> get_available_channels() const = 0

Returns the map of available channels.

The returned map lists the available channels and gives the mapping between the Channel enum and the numeric value that can be found in the corresponding event id field

See also

Metavision::EventExtTrigger

Returns: a map of available channels

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 uint32_t get_period() const = 0

Gets the trigger out signal period (in us)

Returns: the period set (in us)

virtual bool set_period(uint32_t period_us) = 0

Sets the trigger out signal period (in us)

Parameters: period_us – the period to set (in us)
Returns: true on success

virtual double get_duty_cycle() const = 0

Gets the duty cycle of the trigger out signal.

Returns: the ratio representing pulse_width_us/period_us

virtual bool 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)
Returns: true on success

virtual bool enable() = 0

Enables the trigger out.

Returns: true if trigger was successfully enabled, false otherwise

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

virtual bool is_enabled() const = 0

Checks if trigger out is enabled.

Returns: true if trigger out is enabled, False otherwise