SDK Analytics Utils

class 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 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 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 CountingException : public Metavision::BaseException

Class for all exceptions thrown from Metavision counting.

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

float vx: Estimated speed of the particle along X-axis (in pix/us)

float vy: Estimated speed of the particle along Y-axis (in pix/us)

timestamp t: Timestamp.

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

inline const T *data() const: Returns const pointer to the underlying array serving as element storage.

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

Class that logs the output of SpatterTrackerAlgorithm to csv format.

Public Functions

inline SpatterTrackerCsvLogger(const std::filesystem::path &file_path)

Constructor.

Parameters: file_path – Output file path

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