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 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 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 I_Decoder : public Metavision::I_RegistrableFacility<I_Decoder>

Subclassed by Metavision::I_RegistrableFacility< I_EventsStreamDecoder, I_Decoder >, Metavision::I_RegistrableFacility< I_EventFrameDecoder< FrameType >, 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 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 :

1. X (horizontal) position of the start pixel of the top left region

2. Y (vertical) position of the start pixel of the top left region

3. X (horizontal) position of the end pixel of the bottom right region

4. 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 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 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 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 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< RawEventFrameHisto, uint8_t >, Metavision::EHCDecoder< RawEventFrameDiff, int8_t >, 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

inline void decode(const DataTransfer::BufferPtr &buffer)

Decodes raw event wrapped in a BufferPtr.

Parameters

buffer – Buffer containing the raw 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 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 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

Param lower_bound_start

Event rate threshold for the band pass filter to start filtering incoming events. Below this threshold, no events are streamed.

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

Param upper_bound_start

Event rate threshold for the band pass filter to start filtering incoming events. Above this threshold, no events are streamed.

Param 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 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 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::RawDataProducer> data_producer, 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_producer – Raw data producer 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)

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_file(const std::filesystem::path &file)

Sets the path of 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

file – Path of the file from which the events are read

const std::filesystem::path &get_underlying_file() const

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

inline const DataTransfer &get_data_transfer() const

Gets the DataTransfer object used to transfer data from the device to the host.

Returns

A reference to the DataTransfer object

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 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::EVT21GenericDecoder< RawEvent, Event_TIME_HIGH, Event_2D, Event_EXT_TRIGGER, Event_OTHERS, OutputCDType >, Metavision::EVT2Decoder, Metavision::detail::EVT3Decoder< Validator >, Metavision::detail::EVT4Decoder< Validator >

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

I_EventsStreamDecoder(bool time_shifting_enabled, const std::shared_ptr<I_EventDecoder<EventCDVector>> &event_cd_vector_decoder = std::shared_ptr<I_EventDecoder<EventCDVector>>(), 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_vector_decoder – Optional decoder of CD vector 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

void decode(const DataTransfer::BufferPtr &raw_buffer)

Decode a BufferPtr of raw data Convenience method built on top of the iterator decode method version.

Parameters

raw_buffer – BufferPtr of raw data

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_last_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_last_timestamp_impl, EVT21Decoder::reset_last_timestamp_impl and EVT3Decoder::reset_last_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 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 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 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 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 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 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

void load_from_file(const std::filesystem::path &src_file)

loads biases from a bias file at biases_file_path

Throws

HalException – in case of failure. This could happen for example if given path does not exists.

Parameters

src_file – bias file to load biases from

void save_to_file(const std::filesystem::path &dest_file) const

Save the current biases into a file.

Parameters

dest_file – the destination file

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