SDK Analytics Utils

class Metavision::CountingCalibration

Class representing the counting calibration.

Public Static Functions

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 Metavision::CountingErrorCode

Enum that holds runtime error codes for metavision counting.

See

Metavision::CountingException

Values:

enumerator Error = 0x300000

Base metavision counting error.

enumerator InvalidArgument = Error | 0x01000

Errors related to invalid arguments.

enumerator InvalidNumViews = InvalidArgument | 0x1

Invalid number of views.

enumerator InvalidSize = InvalidArgument | 0x2

Invalid counting input min size.

enumerator InvalidSpeed = InvalidArgument | 0x3

Invalid counting input average speed.

enumerator InvalidDistance = InvalidArgument | 0x4

Invalid counting input average distance object camera.

enumerator InvalidInactivityTime = InvalidArgument | 0x5

Invalid counting argument inactivity time.

enumerator InvalidNotificationSampling = InvalidArgument | 0x6

Invalid counting argument notification sampling.

enumerator InvalidOption = InvalidArgument | 0x7

Invalid input option.

enumerator InvalidDataType = InvalidArgument | 0x8

Invalid counting data type.

enumerator InvalidLinePosition = InvalidArgument | 0x9

Invalid line position.

enumerator LineNotFound = InvalidArgument | 0xa

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

enumerator FileDoesNotExist = InvalidArgument | 0xb

File does not exist.

enumerator WrongExtension = InvalidArgument | 0xc

File extension is not the one expected.

enumerator CouldNotOpenFile = InvalidArgument | 0xd

Could not open file.

enumerator RuntimeError = Error | 0x02000

Counting runtime errors.

enumerator InvalidEngineModification = RuntimeError | 0x1

Modification of the Engine during run time.

class Metavision::CountingException : public std::system_error

Class for all exceptions thrown from Metavision counting.

See

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

See

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

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

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

Exceptions
  • std::runtime_error: if successive values of ts are not increasing

bool value() const

Returns the filtered value.

Return

The filtered value

bool raw_value() const

Returns the unfiltered value.

Return

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.

Return

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.

Return

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

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 dumps 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: initialize 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 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.

Return

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

Parameters
  • ts: Timestamp of the measure

  • val: Measured value

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

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}

Return

false if it fails

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}

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.

Return

false if the value is outside the bins range

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.

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

OptimVector()

Default Constructor.

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

OptimVector(OptimVector &&other)

Move Constructor.

Parameters
  • other: Object to move

OptimVector &operator=(OptimVector &&other)

Move assignment operator.

Parameters
  • other: Object to move

const_iterator_type cbegin() const

Returns const iterator to the begin of the vector.

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.

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

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

size_t size() const

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

bool empty() const

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

T &allocate_back()

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

Return

Reference to this last element in the container

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

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>
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 width, int height, int persistence_time_us)

Constructor.

Parameters
  • width: Sensor’s width (in pixels)

  • height: Sensor’s height (in pixels)

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

SpatterTrackerCsvLogger(std::string file_name)

Constructor.

Parameters
  • file_name: Output file name

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