SDK Core Algorithms

class Metavision::AdaptiveRateEventsSplitterAlgorithm

Class used to split a stream of events into slices of variable duration and variable number of events.

This algorithm produces reasonably sharp slices of events, based on the content of the stream itself Internally, it computes the variance per event as a criterion for the sharpness of the current slice of events. An additional criterion is the maximum proportion of active pixels containing both positive and negative events.

Public Functions

AdaptiveRateEventsSplitterAlgorithm(int height, int width, float thr_var_per_event = 5e-4f, int downsampling_factor = 2)

Constructs a new AdaptiveRateEventsSplitterAlgorithm.

Parameters

  • height – height of the input frame of events

  • width – width of the input frame of events

  • thr_var_per_event – minimum variance per pixel value to reach before considering splitting the slice

  • downsampling_factor – performs a downsampling of the input before computing the statistics. Original coordinates will be multiplied by 2**(-downsampling_factor)

inline ~AdaptiveRateEventsSplitterAlgorithm()

Destructor.

template<typename InputIt>
bool process_events(InputIt begin, InputIt end)

Process a slice of events, and determines if slicing should be performed or not at the end.

Parameters

  • begin – Iterator pointing to the beginning of the events buffer

  • end – Iterator pointing to the end of the events buffer

Returns

true if the slice is ready, false is more events should be gathered before splitting

inline void retrieve_events(std::vector<EventCD> &out_vec)

Retrieves the slice of events and resets internal state.

Parameters

out_vec – output vector of events

template<typename Impl>
class Metavision::AsyncAlgorithm

An asynchronous events processor class.

Here, asynchronous means that the output of the processing is at variable frequency. This is useful when one wants to apply a process on events on the fly, and another specific one when a condition is fulfilled.

As opposed to frames that arrive at a fixed frequency, events are asynchronous. The event rate depends on the activity, and so the rate varies with time. In the context of event-based processing, it is often that one wants to apply a processing to events on the fly (online processing such as filling an histogram for instance) and another process when it is considered that enough events have been received (for example in term of events processed count, or time slice of events).

The only entry point of this algorithm is the public process_events method. This method will then call two internal processing methods (process_online and process_async) that should be defined by the user and be private. While the first one processes all events that are passed to process_events, the latter one is called whenever the asynchronous condition is met.

The asynchronous condition is user defined, and set via the various ‘set’ methods. See Processing for more details.

Note

Also see EventBufferReslicerAlgorithm, an implementation that offers a similar functionality but is designed to be used via aggregation rather than via inheritance.

Warning

This class uses a Curiously Recursive Template Pattern design. The input template parameter is expected to inherit from this class and this class should be declared as friend of the derived class.

Template Parameters

Impl – The Asynchronous process implementation.

Public Types

enum class Processing

Processing types.

Processing policies that define the state to rely on to call the asynchronous process (process_async).

N_EVENTS: event count processing policy. Relies on the number of events processed.

N_US: time slice processing policy. Relies on the timestamp of the input events. A time slice T holds events between [(n-1)*T; n*T[.

MIXED: a mix between N_US and N_EVENTS processing policy. In this policy, the time slice has priority over the events count.

SYNC: synchronous condition. process_async is called at the end of the process_events method.

EXTERNAL: Relies on an external condition. process_async is called at each flush call.

Values:

enumerator N_EVENTS
enumerator N_US
enumerator MIXED
enumerator SYNC
enumerator EXTERNAL

Public Functions

void set_processing_n_events(const int delta_n_events)

Function to call process_async every n events.

Note

This call can trigger a flush in case where the new condition is already satisfied by the events processed so far. However, be careful in that case because the produced events buffer is likely to be bigger than what expected with the new condition. Indeed, if you decrease the delta_n_events condition, the condition gets more strict and you might end up with a buffer having an intermediate size: [ delta_n1 ] -> [ tmp ] -> [ delta_n2 ], with [ N ] being a buffer of size N events and delta_n1 > tmp >= delta_n2. In case where you increase the delta_n_events condition, the condition gets less strict and the transition is perfect, no flush occurs: [ delta_n1 ] -> [ delta_n2 ] with delta_n1 < delta_n2

inline int get_processing_n_events()

Getter to retrieve the number of events between two consecutive process_async calls (in N_EVENTS mode).

void set_processing_n_us(const timestamp delta_ts)

Function to call process_async every n microseconds.

Note

This call can trigger a flush in case where the new condition is already satisfied by the events processed so far. However, be careful in that case because the produced time slice is likely to be longer than what expected with the new condition. Indeed, if you decrease the delta_ts condition, the condition gets more strict and you might end up with a buffer having an intermediate duration: [ dt_1 ] -> [ tmp ] -> [ dt_2 ], with [ dt ] being a time slice of duration dt us and dt_1 > tmp >= dt_2. In case where you increase the delta_ts condition, the condition gets less strict and the transition is perfect, no flush occurs: [ dt_1 ] -> [ dt_2 ] with dt_1 < dt_2

inline timestamp get_processing_n_us()

Getter to retrieve the period at which process_async gets called (in N_US mode).

void set_processing_mixed(const int delta_n_events, const timestamp delta_ts)

Function to call process_async every n events and n microseconds. The processing is done if at least one of the conditions is fulfilled.

Note

This call can trigger a flush in case where at least one of the new conditions is already satisfied by the events processed so far. However, be careful in that case because the produced time slice / events buffer is likely to be bigger (i.e. in terms of number of events) and/or longer (i.e. in terms of duration) than what expected with the new condition (see set_processing_n_events and set_processing_n_us for further details).

void set_processing_sync()

Function to call process_async after each process online.

Note

This call can trigger a flush if some events have already been processed

void set_processing_external()

Function to only call process_events without calling process_async.

This is especially useful if the condition to trigger the creation of a buffer is independent from the content of the processed events (for instance, an external trigger events, an other algorithm condition, etc.). The user must then call flush when the condition is fulfilled.

Note

This call can trigger a flush if some events have already been processed

void reset()

Resets the internal state of the algorithm.

This is to be called when one wants to process events older than those already processed (e.g. in the case one wants to switch the source producing the events).

Note

This method doesn’t change the algorithm’s processing mode (see Processing) nor flushes the ongoing time slice. It is the user’s responsibility to call flush before this method to retrieve the incomplete time slice if needed.

inline void flush()

Forces a call to process_async.

The resulting processed time slice corresponds to all the events processed since the last call to process_async (i.e. the time slice’s timestamp is the last processed event’s timestamp + 1)

Note

The internal state is updated so that the next time slice will start just after this one (i.e. [last event’s timestamp + 1, next_processing_ts_[).

template<typename InputIt>
inline 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

template<typename InputIt>
inline void process_events(const timestamp ts, 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

  • ts – End timestamp of the buffer. Used if higher than the timestamp of the last event

  • it_begin – Iterator to the first input event

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

class Metavision::BaseFrameGenerationAlgorithm

Base class whose purpose is to generate a frame from accumulated events when the user makes the request.

Both OnDemandFrameGenerationAlgorithm and PeriodicFrameGenerationAlgorithm inherit from this class.

It features basic logic to allow child class to generate frames with various constraints such as using over accumulation, regenerating a frame with different colors or accumulation time

To generate a frame from events:

  • Each event has an x, y, p and t information (EventCD)

  • Each pixel of the generated frame can be updated with 3 colors: a background color, a positive contrast detection event color, a negative contrast detection color

  • An event with coordinate {x, y} updates the corresponding pixel in the frame with one of the above color depending on its polarity p (0 - negative contrast detection - or 1 - positive contrast detection)

  • A pixel in the generated frame will have a background color if no event occurred at this position

  • One can accumulate a specific time interval of events in the frame. This time interval is called accumulation time.

  • An accumulation time of dt microseconds means that only the events that occurred in the last dt microseconds are used to generate the frame.

The static method generate_frame_from_events allows generating a frame from an event-buffer, an accumulation time and a color palette

Subclassed by Metavision::OnDemandFrameGenerationAlgorithm, Metavision::PeriodicFrameGenerationAlgorithm

Public Functions

virtual ~BaseFrameGenerationAlgorithm() = default

Destructor.

void set_colors(const cv::Scalar &bg_color, const cv::Scalar &on_color, const cv::Scalar &off_color, bool colored)

Sets the color used to generate the frame.

Parameters

  • bg_color – Color used as background, when no events were received for a pixel

  • on_color – Color used for on events

  • off_color – Color used for off events

  • colored – If the generated frame should be grayscale (single channel) or in color (three channels)

void set_color_palette(const Metavision::ColorPalette &palette)

Sets the color used to generate the frame.

Parameters

palette – The Prophesee’s color palette to use

void set_parameters(const cv::Vec4b &bg_color, const cv::Vec4b &on_color, const cv::Vec4b &off_color, int flags)

Sets the parameters used to generate the frame.

Parameters

  • bg_color – Color used as background, when no events were received for a pixel

  • on_color – Color used for on events

  • off_color – Color used for off events

  • flags – A combination of Parameters

void set_parameters(const Metavision::ColorPalette &palette, int flags)

Sets the parameters used to generate the frame.

Parameters

  • palette – The Prophesee’s color palette to use

  • flags – A combination of Parameters

void get_dimension(uint32_t &height, uint32_t &width, uint32_t &channels) const

Gets the frame’s dimension.

Parameters

  • height – Frame’s height

  • width – Frame’s width

  • channels – Frames’s number of channels. 3 if the image is colored, 1 otherwise

Public Static Functions

static inline constexpr Metavision::ColorPalette default_palette()

Returns the default palette used by the frame generation.

static const cv::Vec3b &bg_color_default()

Returns default Prophesee dark palette background color.

static const cv::Vec3b &on_color_default()

Returns default Prophesee dark palette positive event color.

static const cv::Vec3b &off_color_default()

Returns default Prophesee dark palette negative event color.

template<typename EventIt>
static void generate_frame_from_events(EventIt it_begin, EventIt it_end, cv::Mat &frame, const uint32_t accumulation_time_us = 0, const Metavision::ColorPalette &palette = default_palette())

Stand-alone (static) method to generate a frame from events.

All events in the interval ]t - dt, t] are used where t the timestamp of the last event in the buffer, and dt the input accumulation_time_us. If accumulation_time_us is kept to 0, all input events are used.

Note

Even if there’s no events, a frame filled with the background color will be generated

Warning

The input frame must be allocated beforehand

Template Parameters

EventIt – Input 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

  • frame – Pre-allocated frame that will be filled with CD events. It must have the same geometry as the input event source, and the color corresponding to the given palette (3 channels by default)

  • accumulation_time_us – Time range of events to update the frame with (in us)

  • palette – The Prophesee’s color palette to use

Throws

invalid_argument – if frame does not have the expected type (CV_8U or CV_8UC3)

template<bool enable_interruptions>
class Metavision::EventBufferReslicerAlgorithmT : public Metavision::BaseEventBufferReslicerAlgorithmT<enable_interruptions>

class reslicing input event buffers in a user-specified way.

This class plays the same role than AsyncAlgorithm, but is designed to be used via aggregation rather than inheritance. This class is not protected against concurrent accesses and assumes input event buffers are sorted in chronological order.

The role of this class is to reslice input event buffers according to a specified condition. Input event buffers are provided to this class using the process_events function. Output event buffers are defined by successive calls to two callbacks: 1/ the event callback on_events_cb, provided to the process_event function, and 2/ the slicing callback on_new_slice_cb, configured independently in this class.

As an example, the reslicing operation can occur as follow:

  • reslicer.process_events(input1_beg, input1_end, on_events_cb)

    • on_events_cb(input1_beg1, input1_end1)

    • on_new_slice_cb(output1_ts, output1_nevents)

    • on_events_cb(input1_beg2, input1_end2)

  • reslicer.process_events(input2_beg, input2_end, on_events_cb)

    • on_events_cb(input2_beg, input2_end)

  • reslicer.process_events(input3_beg, input3_end, on_events_cb)

    • on_events_cb(input3_beg1, input3_end1)

    • on_new_slice_cb(output2_ts, output2_nevents)

    • on_events_cb(input3_beg2, input3_end2)

    • on_new_slice_cb(output3_ts, output3_nevents)

    • on_events_cb(input3_beg3, input3_end3)

  • etc

Public Types

using OnNewSliceCb = std::function<void(ConditionStatus, timestamp, std::size_t)>

Type of the callback called when the specified slicing condition is met. This callback marks the end of a new output slice and, when called, is provided with the condition met status, the slicing timestamp and the number of events in the slice. The events included in the slice are provided separately, through the callback passed to the process_events function.

Warning

The slicing timestamp is here defined as the upper bound of the temporal range of the current slice. In case of a slicing status of MET_N_US, this means the first timestamp of the temporal range of the next slice. In all other cases, this means the timestamp of the last event in the slice.

Public Functions

EventBufferReslicerAlgorithmT(OnNewSliceCb on_new_slice_cb = nullptr, const Condition &condition = Condition())

Constructor.

Parameters

  • on_new_slice_cb – callback to be called to mark the end of a new output slice.

  • condition – definition of the slicing condition monitored by the slicer, set to identity by default.

void set_on_new_slice_callback(OnNewSliceCb on_new_slice_cb)

Updates the callback to be called to mark the end of a new output slice.

Parameters

on_new_slice_cb – new callback.

void set_slicing_condition(const Condition &condition)

Updates the slicing condition.

Note

In case the new condition is already satisfied by the events processed so far, which can happen if the new slicing condition is more strict than the previous one, this call will trigger a call to the flush function. If the new condition is less strict, then the transition is perfect and no call to flush occurs.

Parameters

condition – definition of the slicing condition monitored by the slicer.

inline const Condition &get_slicing_condition() const

Getter to retrieve the policy used to slice event buffers.

void reset()

Resets the internal state of the slicing algorithm.

This may for instance be called when one wants to process events older than those already processed (e.g. in the case one wants to switch the source producing the events).

Note

This method doesn’t change the algorithm’s slicing condition nor flushes the ongoing time slice. It is the user’s responsibility to call flush before this method to retrieve the incomplete time slice if needed.

void flush()

Forces the generation of a new output slice.

The resulting output slice corresponds to all the events processed since the last output slice, and the internal state is updated so that the next time slice will start with the next event.

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

Processes a buffer of events.

Note

If enable_interruptions is true, this function can be interrupted asynchronously, with no guarantees on when the interruption will happen or what events will have been processed. In case of interruption, the user is left in charge of making a synchronous call to reset to recover a valid state.

Template Parameters

  • InputIt – Read-Only input event iterator type. Works for iterators over buffers of EventCD or equivalent. Underlying event instances must have a t field representing the timestamp.

  • OnEventsCbT – Type of the callback used to forward re-sliced event buffers for down-stream processing, which should match the following signature: void(InputIt, InputIt). The events forwarded via this callback are part of the current output slice, whose end will be notified by a call to the slicing callback.

Parameters

  • it_begin – Iterator to the first input event

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

  • on_events_cb – event callback to be called when a new output buffer has been sliced, providing the begin and end iterators, the event timestamp and number of processed events when the slicing condition was met.

void notify_elapsed_time(timestamp ts)

Notifies the reslicing algorithm that time has elapsed without new events, which may trigger several calls to the slicing callback depending on the configured slicing condition.

Note

If enable_interruptions is true, this function can be interrupted asynchronously, with no guarantees on when the interruption will happen or what events will have been processed. In case of interruption, the user is left in charge of making a synchronous call to reset to recover a valid state.

Parameters

ts – current timestamp

class Metavision::EventFrameDiffGenerationAlgorithm

Produces diff event frames from a stream of events.

This class implements the algorithm for producing diff event frames from a stream of events. This algorithm computes, at each pixel, the sum of polarities of all processed events. Generated event frames are stored using row-major convention.

Public Functions

EventFrameDiffGenerationAlgorithm(unsigned int width, unsigned int height, unsigned int bit_size = 8, bool allow_rollover = true, timestamp min_generation_period_us = 1000)

Constructor for the EventFrameDiffGenerationAlgorithm class.

Parameters

  • width – The width of the event stream.

  • height – The height of the event stream.

  • bit_size – Number of bits used to represent the sum of events. The supported range is [2;8].

  • allow_rollover – Flag indicating whether to allow overflow / underflow when summing polarities in the 8-bit signed counters (default: true).

  • min_generation_period_us – minimum duration between two successive calls to the generate function, to optionally simulate a limited transfer bandwidth (default: 1000 us).

Throws

invalid_argument – if the bit size is outside the supported range of [2;8].

inline bool is_rollover_allowed() const

Getter for the allow_rollover setting.

inline const RawEventFrameDiffConfig &get_config() const

Getter for the event frame configuration.

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

Processes a range of events and updates the sum of polarities at each pixel.

Template Parameters

InputIt – The type of the input iterator for the range of events.

Parameters

  • it_begin – An iterator pointing to the beginning of the events range.

  • it_end – An iterator pointing to the end of the events range.

void generate(RawEventFrameDiff &event_frame)

Retrieves the diff event frame aggregating the events processed so far, and resets the internal counters for upcoming calls to process_events.

Note

This version of the function does not simulate the limited transfer bandwidth typically met on hardware implementations and hence ignores the practical lower-bound on event frame generation frequency.

Parameters

event_frame – diff event frame.

bool generate(timestamp ts_event_frame, RawEventFrameDiff &event_frame)

Retrieves the diff event frame aggregating the events processed so far, and resets the aggregation for upcoming calls to process_events. This version of the function simulates the limited transfer bandwidth typically met on hardware implementations and hence may fail to retrieve the event frame. Internal counters are only reset if the event frame retrieval is successful.

Parameters

  • ts_event_frame – diff event frame.

  • event_frame – diff event frame.

Returns

False if the time since the last call to generate is below the lower-bound generation period, true otherwise.

void reset()

Forces a reset of the internal counters.

class Metavision::EventFrameHistoGenerationAlgorithm

Produces histo event frames from a stream of events.

This class implements the algorithm for producing histo event frames from a stream of events. This algorithm computes, separately at each pixel, the sum of positive and negative events received between two calls to the ‘generate’ function. Generated event frames are stored using row-major convention, either splitting or interleaving polarities. The histogram values will saturate if more events than the maximum representable integers are received at a given pixel for a given polarity. Generated event frames are stored using row-major convention with interleaved channels for each polarity.

Public Functions

EventFrameHistoGenerationAlgorithm(unsigned int width, unsigned int height, unsigned int channel_bit_neg = 4, unsigned int channel_bit_pos = 4, bool packed = false, timestamp min_generation_period_us = 1000)

Constructor for the EventFrameHistoGenerationAlgorithm class.

Parameters

  • width – The width of the event stream.

  • height – The height of the event stream.

  • channel_bit_neg – Number of bits used to represent the sum of negative events. This should be strictly positive and the sum of negative and positive channels bit sizes should be less than 8.

  • channel_bit_pos – Number of bits used to represent the sum of positive events. This should be strictly positive and the sum of negative and positive channels bit sizes should be less than 8.

  • packed – Flag indicating whether sum counter are stored in an aligned way in memory, by padding with zeros, or in a packed way.

  • min_generation_period_us – minimum duration between two successive calls to the generate function, to optionally simulate a limited transfer bandwidth (default: 1000 us).

Throws

invalid_argument – if the sum of negative and positive channels bit sizes is more than 8 or either one is zero.

inline const RawEventFrameHistoConfig &get_config() const

Getter for the event frame configuration.

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

Processes a range of events and updates the sum of events at each pixel & polarity.

Template Parameters

InputIt – The type of the input iterator for the range of events.

Parameters

  • it_begin – An iterator pointing to the beginning of the events range.

  • it_end – An iterator pointing to the end of the events range.

void generate(RawEventFrameHisto &event_frame)

Retrieves the histo event frame aggregating events since the last call to generate, and resets the aggregation for upcoming calls to process_events.

Note

in packed mode, a packed copy of the accumulation data will be returned, incurring a slight performance cost compared to unpacked mode.

Note

This version of the function does not simulate the limited transfer bandwidth typically met on hardware implementations and hence ignores the practical lower-bound on event frame generation frequency.

Parameters

event_frame – histo event frame.

bool generate(timestamp ts_event_frame, RawEventFrameHisto &event_frame)

Retrieves the diff event frame aggregating the events processed so far, and resets the aggregation for upcoming calls to process_events. This version of the function simulates the limited transfer bandwidth typically met on hardware implementations and hence may fail to retrieve the event frame. Internal counters are only reset if the event frame retrieval is successful.

Parameters

  • ts_event_frame – diff event frame.

  • event_frame – diff event frame.

Returns

False if the time since the last call to generate is below the lower-bound generation period, true otherwise.

void reset()

Forces a reset of the internal counters.

template<class Event>
class Metavision::FileProducerAlgorithmT

Public Functions

FileProducerAlgorithmT(std::string filename, bool loop = false, timestamp loop_delay = 0)

Builds a new FileProducerAlgorithmT object.

Parameters

  • filename – Name of the file to read data from

  • loop – If true, the reading from the file will be looped

  • loop_delay – Time interval (in us) between two consecutive loops

~FileProducerAlgorithmT()

Destructor.

template<class OutputIt>
inline void process_events(OutputIt d_first, timestamp ts)

Processes events until a given timestamp.

bool is_done()

If all events have been processed, returns true.

inline timestamp get_time_at(timestamp time_window, bool backward)

Gets the timestamp in a given time window.

Parameters

  • time_window – Time difference (in us) with the first (or last) event in the file

  • backward – If true, search will be from the end of the file (thus giving time last event - time_window)

inline void start_at_time(timestamp start_time)

Starts reproducing the file from a given time.

Parameters

start_time – Start time

uint64_t get_n_tot_ev() const

Gets the total number of events in the file.

void load_to_ram()

Loads file events to ram.

int get_width() const

Gets the width of the sensor producer that recorded the data.

Returns

Width of the sensor

int get_height() const

Gets the height of the sensor producer that recorded the data.

Returns

Height of the sensor

std::string get_date() const

Gets the date.

Note

If the date was not found in the header of the file, an empty string is returned

Returns

String of the form YYYY-MM-DD h:m:s (example: 2017-03-08 13:36:44 ) (UTC time)

Public Static Functions

static void reset_max_loop_length()

Resets the loop length to zero.

class Metavision::FlipXAlgorithm

Class that allows to mirror the X axis of an event stream.

The transfer function of this filter impacts only the X coordinates of the Event2d by:

x = width_minus_one - x

Public Functions

inline explicit FlipXAlgorithm(std::int16_t width_minus_one)

Builds a new FlipXAlgorithm object with the given width.

Parameters

width_minus_one – Maximum X coordinate of the events (width-1)

~FlipXAlgorithm() = default

Default destructor.

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

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

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

inline std::int16_t width_minus_one() const

Returns the maximum X coordinate of the events.

Returns

Maximum X coordinate of the events

inline 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

inline void operator()(Event2d &ev) const

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

Parameters

ev – Event2d to be updated

class Metavision::FlipYAlgorithm

Class that allows to mirror the Y axis of an event stream.

The transfer function of this filter impacts only the Y coordinates of the Event2d by:

y = height_minus_one - y

Public Functions

inline explicit FlipYAlgorithm(std::int16_t height_minus_one)

Builds a new FlipYAlgorithm object with the given height.

Parameters

height_minus_one – Maximum Y coordinate of the events

~FlipYAlgorithm() = default

Default destructor.

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

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

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

inline std::int16_t height_minus_one() const

Returns the maximum Y coordinate of the events.

Returns

Maximum Y coordinate of the events

inline 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

inline void operator()(Event2d &ev) const

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

Parameters

ev – Event2d to be updated

template<class EventType>
class Metavision::GenericProducerAlgorithm

Allows insertion and storage of events from any source via register_new_event_buffer.

The events will then be produced in a chronological manner with process_events.

A maximum duration defined by the difference of timestamps between first and last stored event can be set to limit the number of events stored. To enforce this constraint, the producer will either wait for events to be consumed or drop enough events to be able to insert new events, set_max_duration_stored and set_allow_drop_when_overfilled.

Conversely, a timeout can be set, to avoid the producer waiting indefinitely for events to be inserted. According to the timeout value, the producer will either not wait, wait indefinitely or wait for a predefined amount of time before returning the events,

See also

set_timeout.

Public Functions

inline GenericProducerAlgorithm(timestamp timeout = 0, uint32_t max_events_per_second = 0, timestamp max_duration_stored = std::numeric_limits<timestamp>::max(), bool allow_drop_when_overfilled = false)

Constructor.

Parameters

  • timeout – Maximum time to wait for events (in us). If equal 0, no timeout is set (equivalent to infinite timeout); if negative, there will be no wait at all.

  • max_events_per_second – Maximum event rate when “processing” events up to some time, the latest k events will be output, where k is max_events_per_second * (req_ts - last_ts), the preceding events will simply be dropped

  • max_duration_stored – Maximum time difference (in us) between first and last event stored by the producer if the producer already stores enough events, when new events must be added, the oldest events will be dropped if @ref allow_drop_when_overfilled is true, otherwise the producer will wait for enough events to be consumed before continuing

  • allow_drop_when_overfilled – If true, the oldest events (i.e. event for which the timestamp if older than latest.t - max_duration_stored) are dropped, otherwise, the producer blocks until the oldest events are consumed

template<typename IteratorEv>
inline void register_new_event_buffer(IteratorEv start, IteratorEv end)

method to add a new buffer of events

When inserting events, a maximum duration stored by the producer can be set. It is disabled by default, so that the producer storage may grow indefinitely if no events are produced, or the production is too slow. If a maximum duration is set, the producer will never store events such that the difference between the first and last event stored is greater than the maximum duration. To achieve this effect, it will either wait for events to be produced if drop is disabled when the producer has overfilled set_allow_drop_when_overfilled, or it will drop enough events so that this condition is met if drop is enabled.

template<class OutputIt, typename TimingProfilerType = TimingProfiler<false>>
inline void process_events(timestamp ts, OutputIt inserter, TimingProfilerType *timing_profiler = TimingProfilerType::instance())

Produces events up to some timestamp.

If the timeout has a positive value, it will wait at most timeout us before returning the events “generated”. If the timeout has a negative value, it will immediately return the events generated. If the timeout is zero, it will wait until at least one event with a timestamp greater than ts is registered, before returning the events with a timestamp less or equal to ts.

Parameters

  • ts – Timestamp before which to include events.

  • inserter – Output iterator or back inserter

  • timing_profiler – Profiler to debug

inline void set_timeout(timestamp timeout)

Sets timeout.

Parameters

timeout – Maximum time to wait for events (in us). If equal 0, no timeout is set (equivalent to infinite timeout); if negative, there will be no wait at all.

inline timestamp get_timeout() const

Gets timeout.

Returns

Timeout

inline void set_max_events_per_second(uint32_t max_events_per_second)

Sets max events per second.

Parameters

max_events_per_second – Maximum event rate when “processing” events up to some time, the latest k events will be output, where k is max_events_per_second * (req_ts - last_ts), the preceding events will simply be dropped

inline uint32_t get_max_events_per_second() const

Gets max events per second.

Returns

Max events per second

inline void set_max_duration_stored(timestamp max_duration_stored)

Sets max duration stored.

Parameters

max_duration_stored – Maximum time difference (in us) between first and last event stored by the producer if the producer already stores enough events, when new events must be added, the oldest events will be dropped if @ref allow_drop_when_overfilled is true, otherwise the producer will wait for enough events to be consumed before continuing

inline uint32_t get_max_duration_stored() const

Gets max duration stored.

Returns

Max duration stored

inline void set_allow_drop_when_overfilled(bool allow_drop_when_overfilled)

Enables/disables drop.

Parameters

allow_drop_when_overfilled – If true, the oldest events (i.e. event for which the timestamp if older than latest.t - max_duration_stored) are dropped, otherwise, the producer blocks until the oldest events are consumed

inline bool get_allow_drop_when_overfilled() const

Gets value of drop when overfilled.

Returns

true if the oldest events (i.e. event for which the timestamp if older than latest.t - max_duration_stored) are dropped, false otherwise

inline void set_source_as_done()

Sets source as done to let the producer know that no new events will be received.

inline bool is_source_done() const

Checks if source is done providing events.

Returns

true if source is done, false otherwise

inline bool is_done() const

Checks if producer has finished processing all input events.

Returns

true if all events have been processed, false otherwise

inline timestamp latest_event_timestamp_available() const

Get time of latest event received.

Returns

Time of latest event

class Metavision::OnDemandFrameGenerationAlgorithm : public Metavision::BaseFrameGenerationAlgorithm

Algorithm that generates a CD frame on demand.

After providing events to the class through the process_events method, the user can request a frame generation at any timestamp using the generate method. Note that generate is expected to be called with timestamps increasing monotonically.

The class allows managing the generation of overlapping frames, i.e. the time between two consecutive frame generations can be shorter than the accumulation time.

Note

It’s possible to generate a frame at any timestamp even though more recent events have already been provided. It allows the user not to worry about the event buffers he or she is sending.

Warning

This class shouldn’t be used in case the user prefers to register to an output callback rather than having to manually ask the algorithm to generate the frames (See PeriodicFrameGenerationAlgorithm).

Public Functions

OnDemandFrameGenerationAlgorithm(int width, int height, uint32_t accumulation_time_us = 0, const Metavision::ColorPalette &palette = default_palette())

Constructor.

Parameters

  • width – Sensor’s width (in pixels)

  • height – Sensor’s height (in pixels)

  • accumulation_time_us – Time range of events to update the frame with (in us) (See set_accumulation_time_us)

  • palette – The Prophesee’s color palette to use

template<typename EventIt>
inline void process_events(EventIt it_begin, EventIt it_end)

Processes a buffer of events.

Warning

Call reset before starting processing events from a timestamp in the past

Warning

This method is expected to be called with timestamps increasing monotonically and events from the past

Template Parameters

EventIt – 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 generate(timestamp ts, cv::Mat &frame, bool allocate = true)

Generates a frame.

Warning

This method is expected to be called with timestamps increasing monotonically.

Parameters

  • ts – Timestamp at which to generate the frame

  • frame – Frame that will be filled with CD events

  • allocate – Allocates the frame if true. Otherwise, the user must ensure the validity of the input frame. This is to be used when the data ptr must not change (external allocation, ROI over another cv::Mat, …)

Throws

  • invalid_argument – if ts is older than the last frame generation and reset method hasn’t been called in the meantime

  • invalid_argument – if the frame doesn’t have the expected type and geometry

void set_accumulation_time_us(uint32_t accumulation_time_us)

Sets the accumulation time (in us) to use to generate a frame.

Frame generated will only hold events in the interval [t - dt, t[ where t is the timestamp at which the frame is generated, and dt the accumulation time. However, if accumulation_time_us is set to 0, all events since the last generated frame are used

Parameters

accumulation_time_us – Time range of events to update the frame with (in us)

uint32_t get_accumulation_time_us() const

Returns the current accumulation time (in us).

void reset()

Resets the internal states.

The method generate must be called with timestamps increasing monotonically. However there are no constraints on the timestamp of the first generation following the reset call. It allows the user to restart the algo from any timestamp

class Metavision::PeriodicFrameGenerationAlgorithm : public Metavision::BaseFrameGenerationAlgorithm

Algorithm that generates frames from events at a fixed rate (fps). The reference clock used is the one of the input events.

As an asynchronous algorithm, this class processes any stream of events and triggers the frames generation by itself to output frames regularly spaced in time through its output callback. Note that the implementation of this class uses EventBufferReslicerAlgorithm in place of AsyncAlgorithm, with the same overall behavior.

The elapsed time between two frame generations (frame period = 1 / fps) and the accumulation time can be updated on the fly.

This class should be used when the user prefers to register to an output callback than having to manually ask the algorithm to generate the frames for increasing multiples of the frame period. However, this class shouldn’t be used in case the user wants to generate a frame inside the callback of an algorithm (See OnDemandFrameGenerationAlgorithm)

Public Types

using OutputCb = std::function<void(timestamp, cv::Mat&)>

Alias for frame generated callback.

Public Functions

PeriodicFrameGenerationAlgorithm(int sensor_width, int sensor_height, uint32_t accumulation_time_us = 10000, double fps = 0., const Metavision::ColorPalette &palette = default_palette())

Constructor.

Parameters

  • sensor_width – Sensor’s width (in pixels)

  • sensor_height – Sensor’s height (in pixels)

  • accumulation_time_us – Time range of events to update the frame with (in us)

  • fps – The fps at which to generate the frames. The time reference used is the one from the input events. If the fps is 0, the accumulation time is used to compute it (set_fps).

  • palette – The Prophesee’s color palette to use (set_color_palette)

Throws

std::invalid_argument – If the input fps is negative

void set_output_callback(const OutputCb &output_cb)

Sets the callback to call when an image has been generated.

Warning

For efficiency purpose, the frame passed in the callback is a non const reference. If it is to be used outside the scope of the callback, the user must ensure to swap or copy it to another object

template<typename EventIt>
inline void process_events(EventIt it_begin, EventIt it_end)

Processes a buffer of events to update the internal time surface for the frame generation.

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 notify_elapsed_time(timestamp ts)

Notify the frame generator that time has elapsed without new events, which may trigger several calls to the image generated callback depending on the configured slicing condition.

Parameters

ts – current timestamp

void force_generate()

Forces the generation of a frame for the current period with the input events that have been processed.

This is intended to be used at the end of a process if one wants to generate frames with the remaining events This effectively calls the output_cb and updates the next timestamp at which a frame is to be generated

void set_fps(double fps)

Sets the fps at which to generate frames and thus the frequency of the asynchronous calls.

The time reference used is the one from the input events

Parameters

fps – The fps to use. If the fps is 0, the current accumulation time is used to compute it

Throws

std::invalid_argument – If the input fps is negative

double get_fps()

Returns the current fps at which frames are generated.

void set_accumulation_time_us(uint32_t accumulation_time_us)

Sets the accumulation time (in us) to use to generate a frame.

Frame generated will only hold events in the interval [t - dt, t[ where t is the timestamp at which the frame is generated, and dt the accumulation time

Parameters

accumulation_time_us – Time range of events to update the frame with (in us)

uint32_t get_accumulation_time_us()

Returns the current accumulation time (in us).

void skip_frames_up_to(timestamp ts)

Skips the generation of frames up to the timestamp ts.

Parameters

ts – Timestamp up to which only one image will be generated, i.e. the closest full timeslice before this timestamp

void reset()

Resets the internal states.

Warning

the user is responsible for explicitly calling force_generate if needed to retrieve the frame for the last processed events.

class Metavision::PolarityFilterAlgorithm

Class filter that only propagates events of a certain polarity.

Public Functions

inline explicit PolarityFilterAlgorithm(std::int16_t polarity)

Creates a PolarityFilterAlgorithm class with the given polarity.

Parameters

polarity – Polarity to keep

~PolarityFilterAlgorithm() = default

Default destructor.

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

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

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

Returns

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

inline bool operator()(const Event2d &ev) const

Basic operator to check if an event is accepted.

Parameters

ev – Event2D to be tested

inline void set_polarity(std::int16_t polarity)

Sets the polarity of the filter.

Parameters

polarity – Polarity to be used in the filtering process

inline std::int16_t polarity() const

Returns the polarity used to filter the events.

Returns

Current polarity used in the filtering process

class Metavision::PolarityInverterAlgorithm

Class that implements a Polarity Inverter filter.

The filter changes the polarity of all the filtered events.

Public Functions

PolarityInverterAlgorithm() = default

Builds a new PolarityInverterAlgorithm object.

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

Processes a buffer of events and outputs filtered events.

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

inline void operator()(Event2d &ev) const

Changes the polarity of an events.

Parameters

ev – Event2D that want to be changed

class Metavision::RoiFilterAlgorithm

Class that only propagates events which are contained in a certain window of interest defined by the coordinates of the upper left corner and the lower right corner.

Public Functions

inline RoiFilterAlgorithm(std::int32_t x0, std::int32_t y0, std::int32_t x1, std::int32_t y1, bool output_relative_coordinates = false)

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

Parameters

  • x0 – X coordinate of the upper left corner of the ROI window

  • y0 – Y coordinate of the upper left corner of the ROI window

  • x1 – X coordinate of the lower right corner of the ROI window

  • y1 – Y coordinate of the lower right corner of the ROI window

  • output_relative_coordinates – If false, events that passed the ROI filter are expressed in the whole image coordinates. If true, they are expressed in the ROI coordinates system

template<class InputIt, class OutputIt>
inline 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.

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

Returns

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

inline bool is_resetting() const

Returns true if the algorithm returns events expressed in coordinates relative to the ROI.

Returns

true if the algorithm is resetting the filtered events

inline std::int32_t x0() const

Returns the x coordinate of the upper left corner of the ROI window.

Returns

X coordinate of the upper left corner

inline std::int32_t y0() const

Returns the y coordinate of the upper left corner of the ROI window.

Returns

Y coordinate of the upper left corner

inline std::int32_t x1() const

Returns the x coordinate of the lower right corner of the ROI window.

Returns

X coordinate of the lower right corner

inline std::int32_t y1() const

Returns the y coordinate of the lower right corner of the ROI window.

Returns

Y coordinate of the lower right corner

inline void set_x0(std::int32_t x0)

Sets the x coordinate of the upper left corner of the ROW window.

Parameters

x0 – X coordinate of the upper left corner

inline void set_y0(std::int32_t y0)

Sets the y coordinate of the upper left corner of the ROW window.

Parameters

y0 – Y coordinate of the upper left corner

inline void set_x1(std::int32_t x1)

Sets the x coordinate of the lower right corner of the ROW window.

Parameters

x1 – X coordinate of the lower right corner

inline void set_y1(std::int32_t y1)

Sets the x coordinate of the lower right corner of the ROW window.

Parameters

y1 – Y coordinate of the lower right corner

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

Operator applied when output_relative_coordinates is true, and the event is accepted.

Parameters

ev – Event to be updated

template<typename T>
inline void operator()(T &ev) const

Operator applied when output_relative_coordinates == true, and the event is accepted.

Parameters

ev – Event to be updated

template<typename EventT>
class Metavision::SharedEventsBufferProducerAlgorithm : public Metavision::AsyncAlgorithm<SharedEventsBufferProducerAlgorithm<EventT>>

A utility class to generate shared ptr around a vector of events according to a processing policy (e.g. AsyncAlgorithm::Processing from AsyncAlgorithm)

The events buffers are allocated within a bounded memory pool (SharedObjectPool) to reuse the memory and avoid memory allocation.

Template Parameters

EventT – The type of events contained in the buffer.

Public Types

using EventsBufferPool = ObjectPool<EventsBuffer, true>

ObjectPool. We use a bounded one to avoid reallocation

using SharedEventsBufferProducedCb = std::function<void(timestamp, const SharedEventsBuffer&)>

Alias of callback to process a generated SharedEventsBuffer

Public Functions

SharedEventsBufferProducerAlgorithm(SharedEventsBufferProducerParameters params, SharedEventsBufferProducedCb buffer_produced_cb)

Constructor.

Supported mode from (e.g. AsyncAlgorithm::Processing from AsyncAlgorithm): N_EVENTS, N_US, MIXED, NONE.

Setting SharedEventsBufferProducerParameters::buffers_events_count_ to 0 calls set_processing_n_us (unless buffers_time_slice_us_ is 0 as well).

Setting SharedEventsBufferProducerParameters::buffers_time_slice_us_ to 0 calls set_processing_n_events (unless SharedEventsBufferProducerParameters::buffers_events_count_ is 0 as well).

Setting SharedEventsBufferProducerParameters::buffers_events_count_ and SharedEventsBufferProducerParameters::buffers_time_slice_us_ to 0 calls set_processing_external.

Setting non zero value to both SharedEventsBufferProducerParameters::buffers_events_count_ and SharedEventsBufferProducerParameters::buffers_time_slice_us_ calls set_processing_mixed.

The mode can be overridden after calling the constructor.

Parameters

  • params – An SharedEventsBufferProducerParameters object containing the parameters.

  • buffer_produced_cb – A callback called (SharedEventsBufferProducedCb) whenever a buffer is created.

inline SharedEventsBufferProducerParameters params() const

Get the parameters used to construct this object.

inline void clear()

Resets the internal states of the policy.

class Metavision::StreamLoggerAlgorithm

Logs the stream to a file.

Public Functions

inline StreamLoggerAlgorithm(const std::string &filename, std::size_t width, std::size_t height)

Builds a new StreamLogger object with given geometry.

Parameters

  • filename – Name of the file to write into. If the file already exists, its previous content will be lost.

  • width – Width of the producer

  • height – Height of the producer

~StreamLoggerAlgorithm() = default

Default destructor.

inline void enable(bool state, bool reset_ts = true, std::int32_t split_time_seconds = InvalidTimestamp)

Enables or disables data logging.

Parameters

  • state – Flag to enable/disable the logger

  • reset_ts – Flag to reset the timestamp, the timestamp used in the last call to update will be considered as timestamp zero

  • split_time_seconds – Time in seconds to split the file. By default is disabled: InvalidTimestamp (-1).

Throws

std::runtime_error – If the user tries to reset the timestamp or split the stream while the StreamLogger is enabled and running.

inline bool is_enable() const

Returns state of data logging.

Returns

true if data logging in enabled false otherwise

inline void change_destination(const std::string &filename, bool reset_ts = true)

Changes the destination file of the logger.

Parameters

  • filename – Name of the file to write into.

  • reset_ts – If we are currently recording, the timestamp used in the last call to update will be considered as timestamp zero

template<class InputIt>
inline void process_events(InputIt it_begin, InputIt it_end, timestamp ts)

Exports the information in the input buffer into the StreamLogger.

Template Parameters

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

Parameters

  • it_begin – Iterator to the first input event

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

  • ts – Input buffer timestamp

inline void close()

Closes the streaming.

class Metavision::TimeDecayFrameGenerationAlgorithm

Algorithm that generates a time decay visualization of input CD events on demand.

After processing events through the process_events method, the user can request the generation of a time decay visualization at the current timestamp using the generate method.

Public Functions

TimeDecayFrameGenerationAlgorithm(int width, int height, timestamp exponential_decay_time_us, Metavision::ColorPalette palette)

Constructor.

Parameters

  • width – Sensor’s width (in pixels)

  • height – Sensor’s height (in pixels)

  • exponential_decay_time_us – Characteristic time for the exponential decay (in us)

  • palette – The color palette to use for the visualization

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

Processes a buffer of events.

Warning

Call reset before starting processing events from a timestamp in the past after later events have been processed.

Template Parameters

EventIt – 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 generate(cv::Mat &frame, bool allocate = true)

Generates a frame.

Parameters

  • frame – Frame that will be filled with CD events

  • allocate – Allocates the frame if true. Otherwise, the user must ensure the validity of the input frame. This is to be used when the data ptr must not change (external allocation, ROI over another cv::Mat, …)

Throws

invalid_argument – if the frame doesn’t have the expected type and geometry

void set_exponential_decay_time_us(timestamp exponential_decay_time_us)

Sets the characteristic time of the exponential decay to use.

Parameters

exponential_decay_time_us – Characteristic time for the exponential decay (in us)

timestamp get_exponential_decay_time_us() const

Returns the current characteristic time of the exponential decay (in us).

void set_color_palette(Metavision::ColorPalette palette)

Sets the color palette used to generate the frame.

Parameters

palette – The color palette to use for the visualization

void reset()

Resets the internal states.

Note

This method needs to be called before processing events from a timestamp in the past after later events have been processed.

template<int CHANNELS = 1>
class Metavision::TimeSurfaceProducerAlgorithm : public Metavision::AsyncAlgorithm<TimeSurfaceProducerAlgorithm<1>>

Class that produces a MostRecentTimestampBuffer (a.k.a. time surface) from events.

This algorithm is asynchronous in the sense that it can be configured to produce a time surface every N events, every N microseconds or a mixed condition of both (see AsyncAlgorithm).

Like in other asynchronous algorithms, in order to retrieve the produced time surface, the user needs to set a callback that will be called when the above condition is fulfilled. However, as opposed to other algorithms, the user doesn’t have here the capacity to take ownership of the produced time surface (using a swap mechanism for example). Indeed, swapping the time surface would make the producer lose the whole history. If the user needs to use the time surface out of the output callback, then a copy must be done.

Template Parameters

CHANNELS – Number of channels to use for producing the time surface. Only two values are possible for now: 1 or 2. When a 1-channel time surface is used, events with different polarities are stored all together while they are stored separately when using a 2-channels time surface.

Public Functions

TimeSurfaceProducerAlgorithm(int width, int height)

Constructs a new time surface producer.

Parameters

  • width – Sensor’s width

  • height – Sensor’s height

void set_output_callback(const OutputCb &cb)

Sets a callback to retrieve the produced time surface.

A constant reference of the internal time surface is passed to the callback, allowing to process (i.e. read only) it inside the callback. If the time surface needs to be accessed from outside the callback, then a copy must be done.

Parameters

cb – The callback called when the time surface is ready