SDK CV Algorithms

template<typename Use64Bits = std::true_type>
class Metavision::ActivityNoiseFilterAlgorithm

Filter that accepts events if a similar event has happened during a certain time window in the past, in the neighborhood of its coordinates.

Public Functions

ActivityNoiseFilterAlgorithm(std::uint32_t width, std::uint32_t height, timestamp threshold)

Builds a new ActivityNoiseFilterAlgorithm object.

Parameters
  • width: Maximum X coordinate of the events in the stream

  • height: Maximum Y coordinate of the events in the stream

  • threshold: Length of the time window for activity filtering (in us)

~ActivityNoiseFilterAlgorithm() = default

Default destructor.

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the Activity Noise filter to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<class InputIt, class OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

timestamp get_threshold()

Returns the current threshold.

Return

Threshold applied while filtering

void set_threshold(timestamp threshold)

Sets the threshold.

Parameters
  • threshold: threshold

bool operator()(const Event2d &event)

Checks if the event is filtered.

Return

true if the event is filtered

class Metavision::AntiFlickerAlgorithm

Algorithm used to remove flickering events given a frequency interval.

Public Functions

AntiFlickerAlgorithm(int width, int height, const FrequencyEstimationConfig &config)

Builds a new AntiFlickerAlgorithm object.

Parameters
  • width: Sensor’s width

  • height: Sensor’s height

  • config: Frequency estimation’s configuration

~AntiFlickerAlgorithm() = default

Destructor.

bool set_min_freq(double min_freq)

Sets minimum frequency of the flickering interval.

Note

The value given has to be strictly inferior to maximum frequency

Return

false if value could not be set (invalid value)

Parameters
  • min_freq: Minimum frequency of the flickering interval

bool set_max_freq(double max_freq)

Sets maximum frequency of the flickering interval.

Note

The value given has to be strictly superior to minimum frequency

Return

false if value could not be set (invalid value)

Parameters
  • max_freq: Maximum frequency of the flickering interval

bool set_filter_length(unsigned int filter_length)

Sets filter’s length.

Return

false if value could not be set (invalid value)

Parameters
  • filter_length: Number of values in the output median filter

void set_difference_threshold(double diff_thresh)

Sets the difference allowed between two periods to be considered the same.

Parameters
  • diff_thresh: Maximum difference allowed between two successive periods to be considered the same

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Processes a buffer of events and outputs the non-flickering ones.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<typename Converter>
class Metavision::EventConverterAlgorithm

This algorithm applies the () operator of the Converter class to the input.

Public Functions

constexpr EventConverterAlgorithm(const Converter &converter = Converter())

Constructor

Parameters
  • converter: Instance of the Converter class

class Metavision::EventCounterAlgorithm

This class counts the number of events happening during a simulation step.

Public Functions

EventCounterAlgorithm(double threshold = 19)

Builds a new EventCounterAlgorithm object.

Parameters
  • threshold: Threshold in average rate for the analog_output overlay in Mev/S

EventCounterAlgorithm(const std::string &output_filename, timestamp step_time, timestamp scaling_time, bool enable_log = true, double threshold = 19., bool compute_variance = false)

Builds a new EventCounterAlgorithm object.

Parameters
  • output_filename: Name of the output file to be generated

  • step_time: Time interval (in us) used to compute the peak event rate

  • scaling_time: Time interval (in us) used to compute the average event rate

  • enable_log: true to save a log file

  • threshold: Threshold in average rate for the analog_output overlay in Mev/S

  • compute_variance: true to compute the variance

~EventCounterAlgorithm()

Destructor.

void enable_log(bool state)

Enables or disables data logging.

Parameters
  • state: If true, the logging will start, otherwise it will stop

void set_log_destination(const std::string &csv_file_name)

Sets the output file.

void set_step_time_us(timestamp step_time_us)

Sets step time.

Parameters
  • step_time_us: Time interval (in us) used to compute the peak event rate during the step time (must be smaller than scaling time). Default is 1 ms.

void set_scaling_time_us(timestamp scaling_time_us)

Sets scaling time.

Parameters
  • scaling_time_us: Time interval (in us) used to compute the average event rate during the scaling time. Default is 1000 ms

void polarity_to_count(int polarity)

Counts only the events that have the input polarity.

All events are counted by default. Use -1 to disable the filter after setting a value If the event doesn’t have a polarity, the compilation will fail

Parameters
  • polarity: The polarity to count

void print_stats()

Prints statistics.

std::pair<double, double> get_average_rate()

Gets the average rate last computed.

Return

End time (in seconds) of the last average rate that has been computed (first element of the pair) and the average rate (kEv per second) during this interval

std::pair<double, double> get_peak_rate()

Gets the peak rate last computed.

Return

Time (in seconds) of the last peak rate that has been computed (first element of the pair) and the average peak rate (kEv per second)

uint64_t get_events_number()

Gets number of events.

Return

Total number of events counted from the input producer since the beginning

uint64_t get_events_number_by_polarity()

Gets number of events of the polarity set by polarity_to_count.

Return

Total number of events of the polarity set by polarity_to_count counted from the input producer since the beginning

size_t add_callback_on_scale(const std::function<void(double, double)> &cb)

Adds a function to be called every time an event rate has been computed.

Return

Callback id

Parameters
  • cb: Function that takes as input the timestamp (in seconds) of the last event the average event rate has been computed on and the average event rate (kEv per second)

void remove_callback_on_scale(size_t cb_id)

Removes the function to call every time an event rate has been computed.

Parameters
  • cb_id: Callback id

template<typename InputIt>
std::enable_if_t<!std::is_base_of<Metavision::Event2d, typename Metavision::iterator_traits<InputIt>::value_type>::value> process(InputIt it, InputIt it_end, timestamp ts)

Processes a set of events using iterators.

Note

Two implementations are provided, the first one for events derived from Event2d, the other one for non Event2d-derived events

Parameters
  • it: Iterator to the first event

  • it_end: Iterator to the past-the-end event

  • ts: Timestamp of current timeslice

class Metavision::FlowFrameGeneratorAlgorithm

Public Functions

template<typename InputIt>
void add_flow_for_frame_update(InputIt first, InputIt last)

Stores one motion arrow per centroid (several optical flow events may have the same centroid) in the motion arrow map to be displayed later using the update_frame_with_flow method.

void update_frame_with_flow(cv::Mat &display_mat)

Updates the input frame with the centroids’ motion stored in the history.

Clears the history afterwards

class Metavision::FrequencyAlgorithm

Algorithm used to estimate the flickering frequency (Hz) of the pixels of the sensor.

Public Functions

FrequencyAlgorithm(int width, int height, const FrequencyEstimationConfig &frequency_config)

Builds a new FrequencyAlgorithm object.

Parameters
  • width: Sensor’s width

  • height: Sensor’s height

  • frequency_config: Frequency estimation’s configuration

~FrequencyAlgorithm()

Destructor.

bool set_min_freq(double min_freq)

Sets minimum frequency to output.

Note

The value given has to be < maximum frequency

Return

false if value could not be set (invalid value)

Parameters
  • min_freq: Minimum frequency to output

bool set_max_freq(double max_freq)

Sets maximum frequency to output.

Note

The value given has to be > minimum frequency

Return

false if value could not be set (invalid value)

Parameters
  • max_freq: Maximum frequency to output

bool set_filter_length(unsigned int filter_length)

Sets filter filter length.

Return

false if value could not be set (invalid value)

Parameters
  • filter_length: Number of values in the output median filter

void set_difference_threshold(period_precision diff_thresh)

Sets the difference allowed between two periods to be considered the same.

Parameters
  • diff_thresh: Maximum difference allowed between two successive periods to be considered the same

template<class InputIt, class OutputIt>
void process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Processes a buffer of events and output inserter for Event2dFrequency<float>

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of Event2dFrequency

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter for Event2dFrequency<float>

class Metavision::PeriodAlgorithm

Algorithm used to estimate the flickering period of the pixels of the sensor.

Public Types

using period_precision = float

Timestamp precision.

Public Functions

PeriodAlgorithm(int width, int height, const PeriodEstimationConfig &config)

Builds a new PeriodAlgorithm object.

Parameters
  • width: Sensor’s width

  • height: Sensor’s height

  • config: period estimation’s configuration

~PeriodAlgorithm()

Destructor.

bool set_min_period(double min_period)

Sets minimum period to output.

Note

The value min_period has to be smaller than the maximum period

Return

false if value could not be set (invalid value)

Parameters
  • min_period: Minimum period (us) to output

bool set_max_period(double max_period)

Sets maximum period to output.

Note

The value max_period has to be larger than the minimum period

Return

false if value could not be set (invalid value)

Parameters
  • max_period: Maximum period to output

bool set_filter_length(unsigned int filter_length)

Sets filter filter length.

Return

false if value could not be set (invalid value)

Parameters
  • filter_length: Number of values in the output median filter

void set_difference_threshold(period_precision diff_thresh)

Sets the difference allowed between two periods to be considered the same.

Parameters
  • diff_thresh: Maximum difference allowed between two successive periods to be considered the same

template<class InputIt, class OutputIt>
void process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Processes a buffer of events and output inserter for Event2dPeriod<T>

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of Event2dPeriod

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter for Event2dPeriod<T>

template<class InputIterator, class InsertIterator>
void process_output(InputIterator first, InputIterator last, InsertIterator inserter)

Note

process_output(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

class Metavision::RoiMaskAlgorithm

Class that only propagates events which are contained in a certain region of interest.

The Region Of Interest (ROI) is defined by a mask (cv::Mat). An event is validated if the mask at the event position stores a positive number.

Alternatively, the user can enable different rectangular regions defined by the upper left corner and the bottom right corner that propagates any event inside them.

Public Functions

RoiMaskAlgorithm(const cv::Mat &pixel_mask)

Builds a new RoiMaskAlgorithm object which propagates events in the given window.

Parameters
  • pixel_mask: Mask of pixels that should be retained (pixel <= 0 is filtered)

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the ROI Mask filter to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<class InputIt, class OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

void enable_rectangle(int x0, int y0, int x1, int y1)

Enables a rectangular region defined by the upper left corner and the bottom right corner that propagates any event inside them.

Parameters
  • x0: X coordinate of the upper left corner

  • y0: Y coordinate of the upper left corner

  • x1: X coordinate of the lower right corner

  • y1: Y coordinate of the lower right corner

int max_height() const

Returns the maximum number of pixels (height) of the mask.

Return

Maximum height of the mask

int max_width() const

Returns the maximum number of pixels (width) of the mask.

Return

Maximum width of the mask

const cv::Mat &pixel_mask() const

Returns the pixel mask of the filter.

Return

cv::Mat containing the pixel mask of the filter

void set_pixel_mask(const cv::Mat &mask)

Sets the pixel mask of the filter.

Parameters
  • mask: Pixel mask to be used while filtering

template<typename T>
bool operator()(const T &ev) const

Basic operator to check if an element is filtered.

Parameters
  • ev: Event to check

bool operator()(int x, int y) const

Basic operator to check if a position is filtered.

Parameters
  • x: X coordinate or the position to check

  • y: Y coordinate or the position to check

class Metavision::RotateEventsAlgorithm

class that allows to rotate an event stream.

Note

We assume the rotation to happen with respect to the center of the image

Public Functions

RotateEventsAlgorithm(std::int16_t width_minus_one, std::int16_t height_minus_one, float rotation)

Builds a new RotateEventsAlgorithm object with the given width and height.

Parameters
  • width_minus_one: Maximum X coordinate of the events (width-1)

  • height_minus_one: Maximum Y coordinate of the events (height-1)

  • rotation: Value in radians used for the rotation

~RotateEventsAlgorithm() = default

Default destructor.

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the rotate event filter to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<class InputIt, class OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

std::int16_t width_minus_one() const

Returns the maximum X coordinate of the events.

Return

Maximum X coordinate of the events

void set_width_minus_one(std::int16_t width_minus_one)

Sets the maximum X coordinate of the events.

Parameters
  • width_minus_one: Maximum X coordinate of the events

std::int16_t height_minus_one() const

Returns the maximum Y coordinate of the events.

Return

Maximum Y coordinate of the events

void set_height_minus_one(std::int16_t height_minus_one)

Sets the maximum Y coordinate of the events.

Parameters
  • height_minus_one: Maximum Y coordinate of the events

void set_rotation(const float new_angle)

Sets the new rotation angle.

Parameters
  • new_angle: New angle in rad

class Metavision::SparseOpticalFlowAlgorithm

Public Functions

template<typename InputIt, typename OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the optical flow algorithm to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Note

the available implementations provided are:

  • InputIt = std::vector<Event2d>::iterator, OutputIt = std::back_insert_iterator<std::vector<EventOpticalFlow>>

  • InputIt = std::vector<Event2d>::const_iterator, OutputIt = std::back_insert_iterator<std::vector<EventOpticalFlow>>

  • InputIt = std::vector<Event2d>::iterator, OutputIt = std::vector<EventOpticalFlow>::iterator

  • InputIt = std::vector<Event2d>::const_iterator, OutputIt = std::vector<EventOpticalFlow>::iterator

  • InputIt = const Event2d *, OutputIt = EventOpticalFlow *

Template Parameters
  • InputIt: Read-Only input event iterator type

  • OutputIt: Read-Write output event iterator type

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<typename InputIt, typename OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

struct Parameters

Spatial dimensions of the input stream of events.

template<class itype>
class Metavision::SpatioTemporalContrastAlgorithmT

The SpatioTemporalContrast Filter is a noise filter using the exponential response of a pixel to a change of light to filter out wrong detections and trails.

For an event to be forwarded, it needs to be preceded by another one in a given time window, this ensures that the spatio temporal contrast detection is strong enough. It is also possible to then cut all the following events up to a change of polarity in the stream for that particular pixel (strong trail removal). Note that this will remove signal if 2 following edges of the same polarity are detected (which should not happen that frequently).

Note

The timestamp may be stored in different types 64 bits, 32 bits or 16 bits. The behavior may vary from one size to the other since the number of significant bits may change. Before using the version with less than 32 bits check that the behavior is still valid for the usage.

Public Functions

SpatioTemporalContrastAlgorithmT(int width, int height, timestamp threshold, bool cut_trail = true)

Builds a new SpatioTemporalContrast object.

Parameters
  • width: Maximum X coordinate of the events in the stream

  • height: Maximum Y coordinate of the events in the stream

  • threshold: Length of the time window for filtering (in us)

  • cut_trail: If true, after an event goes through, it removes all events until change of polarity

template<typename InputIt, typename OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Processes a buffer of events and outputs filtered events.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<typename InputIt, typename OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

timestamp get_threshold()

Returns the threshold for STC filtering.

Return

Threshold applied while STC filtering (in us)

void set_threshold(timestamp threshold)

Sets the threshold for STC filtering.

Parameters
  • threshold: Length of the time window for STC filtering (in us)

bool get_cut_trail()

Returns the cut_trail parameter for STC filtering.

Return

The cut_trail parameter for STC filtering used for STC filtering

void set_cut_trail(bool v)

Sets the cut_trail parameter for STC filtering.

Parameters
  • v: If true, after an event goes through, it removes all events until change of polarity

template<typename TTimestampType>
class Metavision::TTrailFilterAlgorithm

Filter that accepts an event either if the last event at the same coordinates was of different polarity, or if it happened at least a given amount of time after the last event.

Public Functions

TTrailFilterAlgorithm(uint16_t width, uint16_t height, TTimestampType threshold)

Builds a new TTrailFilterAlgorithm object.

Parameters
  • width: Maximum X coordinate of the events in the stream

  • height: Maximum Y coordinate of the events in the stream

  • threshold: Length of the time window for activity filtering (in us)

~TTrailFilterAlgorithm() = default

Default destructor.

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the Trail filter to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of Event2d or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of Event2d or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<class InputIt, class OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

TTimestampType get_threshold() const

Returns the current threshold.

Return

Threshold applied while filtering

void set_threshold(TTimestampType threshold)

Set the current threshold.

Parameters
  • threshold: Current threshold

bool operator()(const Event2d &event)

Check if the event is filtered.

Return

true if the event is filtered

class Metavision::TransposeEventsAlgorithm

Class that switches X and Y coordinates of an event stream. This filter changes the dimensions of the corresponding frame (width and height are switched)

Public Functions

template<class InputIt, class OutputIt>
OutputIt process_events(InputIt it_begin, InputIt it_end, OutputIt inserter)

Applies the Transpose filter to the given input buffer storing the result in the output buffer.

Return

Iterator pointing to the past-the-end event added in the output

Template Parameters
  • InputIt: Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

  • OutputIt: Read-Write output event iterator type. Works for iterators over containers of EventCD or equivalent

Parameters
  • it_begin: Iterator to first input event

  • it_end: Iterator to the past-the-end event

  • inserter: Output iterator or back inserter

template<class InputIt, class OutputIt>
OutputIt process(InputIt first, InputIt last, OutputIt d_first)

Note

process(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use process_events(…) instead

void operator()(Event2d &ev) const

Applies the Transpose filter to the given input buffer storing the result in the output buffer.

Parameters
  • ev: Event2d to be updated