SDK Analytics Utils

class Metavision::ClusterTrajectory

Class to store the recent history of a cluster’s trajectory.

Public Functions

ClusterTrajectory(int id, timestamp duration, timestamp t, const cv::Point &p)

Constructor.

Parameters

  • id – Cluster’s id

  • duration – Maximum memory for the trajectory’s points

  • t – Timestamp of the first point to store

  • p – First point to store

void add_pose(timestamp t, const cv::Point &p)

Adds a point to the trajectory.

Parameters

  • t – The timestamp of the new point

  • p – The new point

void remove_old_poses(timestamp t)

Removes all points in the trajectory with a timestamp older than t - duration.

Parameters

t – Current timestamp. Points with timestamps lower than ‘t-duration’ will be removed

const Path &get_path() const

Gets the current trajectory.

Returns

The current trajectory

int id() const

Provide the trajectory id (same as cluster tracked)

Returns

The cluster (and trajectory) id

class Metavision::CountingCalibration

Class representing the counting calibration.

Public Static Functions

static Results calibrate(int width, int height, float object_min_size = 5, float object_average_speed = 5, float distance_object_camera = 300, float horizontal_fov = 56.f, float vertical_fov = 44.f, int travelled_pix_distance_during_acc_time = 9)

Finds optimal parameters for the counting algorithm.

Parameters

  • width – Sensor’s width in pixels

  • height – Sensor’s height in pixels

  • object_min_size – Approximate largest dimension of the smallest object (in mm). The value must be positive. It will be refined during the calibration

  • object_average_speed – Approximate average speed of an object to count (in m/s). It will be refined during the calibration.

  • distance_object_camera – Average distance between the flow of objects to count and the camera (in mm) Camera must look perpendicular to the object falling plane. It will be refined during the calibration

  • horizontal_fov – Horizontal field of view (half of the solid angle perceived by the sensor along the horizontal axis, in degrees)

  • vertical_fov – Vertical field of view (half of the solid angle perceived by the sensor along the vertical axis, in degrees)

  • travelled_pix_distance_during_acc_time – Distance (in pixels) travelled during the accumulation time

struct Results

Struct storing the calibration results.

class Metavision::CountingDrawingHelper

Class that superimposes line counting results on events.

Public Functions

CountingDrawingHelper() = default

Default Constructor.

CountingDrawingHelper(const std::vector<int> &line_counters_ordinates)

Constructor.

Parameters

line_counters_ordinates – Ordinates of the lines tracker in the sensor’s image

void add_line_counter(int row)

Adds a new line counter ordinate to the line_counters vector.

Parameters

row – Line ordinate

void draw(const timestamp ts, int count, cv::Mat &output_img)

Updates data to display.

Parameters

  • ts – Current timestamp

  • count – Last object count

  • output_img – Output image

enum class Metavision::CountingErrorCode : ErrorCodeType

Enum that holds runtime error codes for metavision counting.

See also

Metavision::CountingException

Values:

enumerator Error

Base metavision counting error.

enumerator InvalidArgument

Errors related to invalid arguments.

enumerator InvalidNumViews

Invalid number of views.

enumerator InvalidSize

Invalid counting input min size.

enumerator InvalidSpeed

Invalid counting input average speed.

enumerator InvalidDistance

Invalid counting input average distance object camera.

enumerator InvalidInactivityTime

Invalid counting argument inactivity time.

enumerator InvalidNotificationSampling

Invalid counting argument notification sampling.

enumerator InvalidOption

Invalid input option.

enumerator InvalidDataType

Invalid counting data type.

enumerator InvalidLinePosition

Invalid line position.

enumerator LineNotFound

Line not found (e.g., when removing a specific line)

enumerator FileDoesNotExist

File does not exist.

enumerator WrongExtension

File extension is not the one expected.

enumerator CouldNotOpenFile

Could not open file.

enumerator RuntimeError

Counting runtime errors.

enumerator InvalidEngineModification

Modification of the Engine during run time.

class Metavision::CountingException : public std::system_error

Class for all exceptions thrown from Metavision counting.

See also

http://www.cplusplus.com/reference/system_error/system_error/

See also

http://en.cppreference.com/w/cpp/error/error_code

Public Functions

CountingException(CountingErrorCode e)

Creates an exception of type e with default error message.

See also

CountingErrorCode

Parameters

e – Counting error code

CountingException(CountingErrorCode e, const std::string &additional_info)

Creates an exception of type e with precise error description contained in additional_info.

See also

CountingErrorCode

Parameters

  • e – Counting error code

  • additional_info – Message containing information about the error

class Metavision::FilteredBool

Class implementing a boolean variable that’s updated in time, and whose value only changes when the new value has been validated for a certain, configurable, time.

Public Functions

FilteredBool() = default

Default constructor.

FilteredBool(bool initial_value, timestamp rise_delay_us, timestamp fall_delay_us)

Constructor.

Parameters

  • initial_value – Initial value

  • rise_delay_us – Delay to validate a rising edge. The internal value will change from “false” to “true” only if the variable is updated to “true” for a duration >= rise_delay_us

  • fall_delay_us – Delay to validate a falling edge. The internal value will change from “true” to “false” only if the variable is updated to “false” for a duration >= fall_delay_us

void update(timestamp ts, bool value)

Updates the observed value.

Parameters

  • ts – Timestamp of the update. Successive calls must have increasing values of ts

  • value – Observed value to update

Throws

std::runtime_error – if successive values of ts are not increasing

bool value() const

Returns the filtered value.

Returns

The filtered value

bool raw_value() const

Returns the unfiltered value.

Returns

The last value updated, regardless of if it has been confirmed

timestamp last_rising_edge_ts() const

Gets the timestamp of the last time that a call to update() produced a rising edge that was then validated by >= rise_delay_us.

Returns

The last rising edge timestamp

timestamp last_falling_edge_ts() const

Gets the timestamp of the last time that a call to update() produced a falling edge that was then validated by >= fall_delay_us.

Returns

The last falling edge timestamp

class Metavision::HistogramDrawingHelper

Class that draws an histogram.

Public Functions

HistogramDrawingHelper() = default

Default Constructor.

HistogramDrawingHelper(int height, const std::vector<float> &hist_bins_centers)

Constructor.

Parameters

  • height – Height of the image

  • hist_bins_centers – Centers of the histogram bins

void draw(cv::Mat &output_img, const std::vector<unsigned int> &hist_counts)

Updates data to display.

Parameters

  • output_img – Output image

  • hist_counts – Counts of the histogram

int get_width() const

Gets width of the generated image.

class Metavision::JetMonitoringAlarms

Class that generates alarms depending on the results of the JetMonitoringAlgorithm.

Public Functions

JetMonitoringAlarms(const JetMonitoringAlarmConfig &params, timestamp jet_detection_delay_us)

Constructor.

Parameters

  • params – Alarm parameters

  • jet_detection_delay_us – The time that the jet monitoring algorithm takes to confirm a jet. This is needed so we don’t generate an alarm for a missing jet when it has already started but not yet confirmed.

~JetMonitoringAlarms() = default

Default destructor.

void reset_state()

Reset internal state.

void set_on_alarm_callback(const AlarmCallback &cb)

Sets the callback that is called when an alarm is raised.

Parameters

cb – Callback processing a const reference of EventJetAlarm

void process_jet(timestamp ts, const EventJet &jet)

Processes a jet, and generates alarms if needed, by calling callback.

void process_slice(timestamp ts, bool jet_is_present, timestamp ts_since_last_jet)

Processes a slice and generates alarms if needed, by calling callback (the main purpose is to monitor if a jet has not arrived in time)

class Metavision::JetMonitoringDrawingHelper

Class that superimposes jet monitoring results on events.

Public Functions

JetMonitoringDrawingHelper(const cv::Rect &camera_roi, const cv::Rect &jet_roi, const JetMonitoringAlgorithmConfig::Orientation &nozzle_orientation)

Constructor.

Parameters

  • camera_roi – Region of interest used by the camera (Left x, Top y, width, height)

  • jet_roi – Region of interest used by the jet-monitoring algorithm to detect jets (Left x, Top y, width, height)

  • nozzle_orientation – Nozzle orientation

void draw(const timestamp ts, int count, int er_kevps, cv::Mat &output_img)

Updates data to display.

Parameters

  • ts – Current timestamp

  • count – Last object count

  • er_kevps – Event rate in k-ev per second

  • output_img – Output image

class Metavision::JetMonitoringLogger

Class maintaining circular buffers with data of interest concerning jet monitoring, and dumping it to a set of files each time a log trigger arrives:

  • events_td.dat: CD events

  • monitoring_out.csv: Algorithm output

  • algo_parameters.json: Algorithm parameters

The intended use is:

  • Call process_events() to register events

  • Call log() to register JetMonitoringSliceData

  • (if needed) call schedule_dump(), this will dump data after the specified delay

  • Call erase data to discard unnecessary data

Public Functions

JetMonitoringLogger(cv::Size sensor_size, const cv::Rect &roi_camera, const JetMonitoringAlgorithmConfig &algo_config, const JetMonitoringAlarmConfig &alarm_config, const JetMonitoringLoggerConfig &logger_config)

Constructor: initializes the logger.

Parameters

  • sensor_size – Sensor size (width, height) in pixels, needed to log events

  • roi_camera – Camera ROI

  • algo_config – Jet Monitoring Algorithm configuration parameters

  • alarm_config – Jet Monitoring Alarm configuration parameters

  • logger_config – Jet Monitoring Logger configuration parameters

~JetMonitoringLogger()

Destructor.

template<typename InputIt>
void process_events(InputIt it_begin, InputIt it_end)

Processes a buffer of events.

Template Parameters

InputIt – Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent

Parameters

  • it_begin – Iterator to the first input event

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

void log(const JetMonitoringSliceData &history_item)

Logs data to the buffer and erases old buffers that won’t be used for log dumps.

Parameters

history_item – Item to be logged in the buffer

void process_alarm(const EventJetAlarm &alarm)

Processes alarm (dumps data)

Parameters

alarm – Alarm information from the Jet Monitoring algorithm

void schedule_dump(const timestamp ts, const std::string &trigger_description)

Schedules a log data dump, after the delay specified in the constructor by dump_delay.

Note

If several dumps are requested for the same time slice, only the last one will be kept

Parameters

  • ts – Timestamp of the dump

  • trigger_description – Description of what triggered the dump, this will be appended to the dump directory name

template<typename InputIt, typename RoiIt, typename OutputIt>
void Metavision::accumulate_events_rectangle_roi(InputIt it_begin, InputIt it_end, RoiIt roi_begin, RoiIt roi_end, OutputIt output)

Accumulates events corresponding to multiple ROIs.

Template Parameters

  • InputIt – Iterator type of an event-buffer, the elements of which have x, y and p as attributes

  • RoiIt – Iterator type of a buffer of RectangleRoi

  • OutputIt – Iterator type of a buffer of std::array<int, 2>

Parameters

  • it_begin – First iterator to a buffer of events

  • it_end – Past-end iterator to a buffer of events

  • roi_begin – First iterators to a buffer of ROIs

  • roi_end – Past-end iterator to a buffer of ROIs

  • output – Iterator to a buffer of std::array<int, 2>

struct Metavision::NoTrackZone

Public Functions

inline const cv::Point2f get_center() const

Returns the center of the cluster.

Returns

The center of the cluster

inline void write_event(void *buf, timestamp) const

Writes EventSpatterCluster to buffer.

Public Members

int radius

Radius of the no-tracking zone.

bool filter_inside

Indicates whether to filter events inside or outside the zone.

Public Static Functions

static inline NoTrackZone read_event(void *buf, const timestamp&)

Reads event 2D from buffer.

Returns

Event spatter cluster

static inline size_t get_raw_event_size()

Returns the size of the RawEvent.

Returns

The size of the RawEvent

Friends

inline friend std::ostream &operator<<(std::ostream &output, const NoTrackZone &e)

Operator <<.

struct RectangleRoi

Struct representing a rectangular ROI.

class Metavision::SlidingHistogram

Public Functions

SlidingHistogram(precision_type min_val, precision_type max_val, precision_type precision_val, timestamp accumulation_time_us, timestamp output_period_us)

Constructor.

We split the range [ min_val, max_val ] to get values spaced apart by precision_val . Bins are centered around these values and are of width precision_val so that consecutive bins touch each other. For example, given the range [3, 5] and precision_val = 1, it will compute the bin centers {3, 4, 5}, the boundaries of which are given by {2.5, 3.5, 4.5, 5.5}

Note

The histogram bins are initialized during the class construction and won’t change dynamically.

Parameters

  • min_val – Minimum included value (lower bound of the histogram bins)

  • max_val – Maximum included value (upper bound of the histogram bins)

  • precision_val – Width of the bins of the histogram (same unit as the value to estimate)

  • accumulation_time_us – Accumulation time of the histogram (in us), a negative value disables this option and old values are not discarded

  • output_period_us – Period (in us) between two histograms generations. The period is measured with the input events’ timestamp

template<typename T>
bool add_time_and_value(timestamp ts, T val)

Adds a new timestamped measure.

Parameters

  • ts – Timestamp of the measure

  • val – Measured value

Returns

false if the value is outside the extreme values of the bins

void add_time(timestamp ts)

Specifies the current processing timestamp to the class, to let it know that there’s no new measure up to this timestamp.

Parameters

ts – Current processing timestamp

inline void set_output_callback(const OutputCb &output_cb)

Function to pass a callback to know when a histogram is available.

template<typename T>
bool Metavision::init_histogram_bins(T min_val, T max_val, T step, std::vector<T> &bins_centers, std::vector<T> &bins_boundaries)

Computes the histogram bins given a minimum value, a maximum value and a step value.

We split the range [ min_val, max_val ] to get values spaced apart by step . Bins are centered around these values and are of width step so that consecutive bins touch each other. For example, given the range [3, 5] and step = 1, it will compute the bin centers {3, 4, 5}, the boundaries of which are given by {2.5, 3.5, 4.5, 5.5}

Template Parameters

T – Type used to define the type of the boundaries of the histogram bins

Parameters

  • min_val – Minimum included value (lower bound of the histogram bins)

  • max_val – Maximum included value (upper bound of the histogram bins)

  • step – Width of the bins of the histogram

  • bins_centers – Output vector containing the bin centers, e.g. {3, 4, 5}

  • bins_boundaries – Output vector containing the bin boundaries, e.g. {2.5, 3.5, 4.5, 5.5}

Returns

false if it fails

template<typename T>
bool Metavision::value_to_histogram_bin_id(const std::vector<T> &bins_boundaries, T value, size_t &output_id)

Finds the ID of the histogram bin that corresponds to the input value.

Parameters

  • bins_boundaries – Vector containing the histogram bin boundaries, e.g. {2.5, 3.5, 4.5, 5.5} when bin centers are {3, 4, 5}

  • value – Input value that is compared against the bins values

  • output_id – ID of the bin that matches the input value. N.B. This is the ID of the center, not of the boundary.

Returns

false if the value is outside the bins range

struct LineCluster

Structure that stores the begin and end position of a cluster in a line.

struct LineClusterWithId

Structure representing a 1D Cluster with its id.

struct TimedLineCluster

Structure representing a 1D cluster with its timestamp.

struct Metavision::LineParticleTrack

Structure storing information about a track of a particle matched over several rows.

Public Functions

LineParticleTrack() = default

Default Constructor.

LineParticleTrack(LineParticleTrack &&other)

Move Constructor.

Parameters

other – Object to move

LineParticleTrack &operator=(LineParticleTrack &&other)

Move assignement operator.

Parameters

other – Object to move

Public Members

std::vector<cv::Point> positions

XY Positions of the detections.

std::vector<std::vector<cv::Point2f>> centered_contours

Particle contours centered around (0,0)

float traj_coef_b

Linear Model X = a*Y + b.

float particle_size

Estimated size of the particle.

int id

Track id.

timestamp t

Timestamp.

struct Metavision::LineParticleTrackingOutput

Class collecting information about LineParticle tracks.

Public Members

OptimVector<LineParticleTrack> buffer

Vector of line particle tracks.

timestamp last_count_ts = 0

Timestamp of the last detection.

int global_counter = 0

Number of particles that have been matched over several lines.

template<typename T>
class Metavision::OptimVector

Class to avoid reallocating memory after clear() in case of a 2-dimensional vector.

The vector itself isn’t cleared, but the end() iterator is moved back to begin(). Items of type T might contain vectors. The idea is to clear an existing Item and rewrite values on it, instead of creating a new object and reallocating memory. Such T elements have only a default constructor.

To be used in the case one can only clear the vector or add an element at the end.

Template Parameters

T – Type of the elements, implementing a void clear() method

Public Functions

inline OptimVector()

Default Constructor.

Throws

std::invalid_argument – if type T doesn’t implement the void clear() method

inline OptimVector(OptimVector &&other)

Move Constructor.

Parameters

other – Object to move

inline OptimVector &operator=(OptimVector &&other)

Move assignment operator.

Parameters

other – Object to move

inline const_iterator_type cbegin() const

Returns const iterator to the begin of the vector.

inline const_iterator_type cend() const

Returns const next_it_ instead of the end of the vector, as if the items beyond this iterator have been cleared.

inline T &at(size_t pos)

Returns a reference to the element at specified location pos, with bounds checking.

Parameters

pos – Position of the element to return

inline const T &at(size_t pos) const

Returns a const reference to the element at specified location pos, with bounds checking.

Parameters

pos – Position of the element to return

inline size_t size() const

Returns the number of elements in the container, i.e. std::distance(begin(), end())

inline bool empty() const

Returns whether the vector is empty (i.e. whether its size is 0).

inline T &allocate_back()

Makes a new element available at the end of the container.

Returns

Reference to this last element in the container

inline void clear()

Makes all elements in the container unavailable by shifting the end ptr to begin.

void reserve(size_t new_cap)

Increases the capacity of the vector to a value that’s greater or equal to new_cap . If it’s greater than the current capacity(), new storage is allocated, otherwise the method does nothing.

void move_and_insert_to(OptimVector<T> &other)

Moves elements to another vector.

Parameters

other – Vector that will take ownership of the data

inline T *data()

Returns pointer to the underlying array serving as element storage.

const T *data() const

Returns const pointer to the underlying array serving as element storage.

class Metavision::LineClusterDrawingHelper

Class that superimposes event-clusters on the horizontal lines drawn on an image filled with events.

Public Functions

template<typename InputIt>
inline void draw(cv::Mat &output_img, InputIt first, InputIt last)

Draws colored segments along an horizontal line.

Template Parameters

InputIt – Iterator to a cluster such as LineClusterWithId. Required class members are x_begin, x_end and id. The ID refers to the ordinate of the line cluster

Parameters

  • output_img – Output image

  • first – First line cluster to display

  • last – Last line cluster to display

class Metavision::LineParticleTrackDrawingHelper

Class that superimposes Particle Size Measurement results on an image filled with events.

Public Functions

LineParticleTrackDrawingHelper(int persistence_time_us)

Constructor.

Parameters

persistence_time_us – Time interval (in the events-clock) during which particle contours remain visible in the visualization. Since a track is sent only once, it will appear only on one frame if we don’t keep results in memory. We need to know how long we want to display these detected tracks

template<typename InputTrackIt>
void draw(timestamp ts, cv::Mat &output_img, InputTrackIt begin, InputTrackIt end)

Stores and draws particle tracks.

Template Parameters

InputTrackIt – An iterator type over a track of type LineParticleTrack

Parameters

  • ts – Detection timestamp

  • output_img – Output image

  • begin – Begin iterator to the particle tracks to display

  • end – Past-end iterator to the particle tracks to display

struct Metavision::MonoCountingStatus

Structure to store the mono counting results on several lines.

Public Members

int global_counter

Maximum count over the line counters.

std::map<int, int> line_mono_counters

Row and counts of each line counter.

timestamp last_count_ts

Timestamp of the last triggered count.

class Metavision::SpatterTrackerCsvLogger

Class that logs the output of SpatterTrackerAlgorithm to csv format.

Public Functions

inline SpatterTrackerCsvLogger(std::string file_name)

Constructor.

Parameters

file_name – Output file name

inline void log_output(const Metavision::timestamp ts, const std::vector<EventSpatterCluster> &trackers)

Writes information about the trackers to file.

Parameters

  • ts – Timestamp

  • trackers – Trackers to write

template<typename InputIt>
void Metavision::draw_tracking_results(timestamp ts, InputIt begin, InputIt end, cv::Mat &output)

Generic function used to draw tracking results.

Results are drawn as bounding boxes with tracked objects’ ids beside.

Template Parameters

InputIt – Iterator type over a tracking result

Parameters

  • ts – Current timestamp

  • begin – First tracking result to draw

  • end – End of the tracking results buffer

  • output – The output image in which the tracking result will be drawn