Approximate time policy. More...

#include <approximate_time.h>

Inheritance diagram for fkie_message_filters::combiner_policies::ApproximateTime< IOs >:

Public Member Functions
	ApproximateTime ()
	Constructor. More...

ApproximateTime &	set_max_age (const ros::Duration &max_age) noexcept
	Set maximum age of any data in the queue. More...

ApproximateTime &	set_max_queue_size (std::size_t queue_size, const boost::optional< ros::Duration > &max_age=boost::none) noexcept
	Set maximum queue size. More...

ApproximateTime &	set_max_timespan (const ros::Duration &max_delta) noexcept
	Set maximum permissible timestamp difference of matched messages. More...

ApproximateTime &	set_min_distance (std::size_t i, const ros::Duration &min_dist) noexcept
	Set the minimum distance between consecutive messages on a source. More...

Public Member Functions inherited from fkie_message_filters::combiner_policies::PolicyBase< IOs... >
virtual	~PolicyBase ()

Protected Member Functions
template<std::size_t N>
void	add (std::unique_lock< std::mutex > &, const std::tuple_element_t< N, IncomingTuples > &)
	Input function. More...

void	reset () noexcept override
	Reset internal state. More...

Protected Member Functions inherited from fkie_message_filters::combiner_policies::PolicyBase< IOs... >
void	emit (const OutgoingTuple &out)
	Emit data. More...

void	set_emitter_callback (const EmitterCB &) noexcept
	Set output function. More...

Private Types
using	IncomingQueues = std::tuple< std::deque< helpers::io_tuple_t< IOs > >... >

Private Member Functions
bool	can_still_improve () noexcept

template<std::size_t N>
bool	can_still_improve_at () noexcept

bool	determine_pivot () noexcept

void	discard_expired (const ros::Time &cutoff) noexcept

template<std::size_t N>
void	discard_expired_at (const ros::Time &cutoff) noexcept

void	drop_pivot () noexcept

void	emit_heads (std::unique_lock< std::mutex > &)

ros::Duration	heads_timespan () noexcept

ros::Duration	pivot_timedelta (const ros::Time &ts) noexcept

template<std::size_t N>
void	prune_queue_at (std::size_t queue_size) noexcept

Private Attributes
MaybeOutgoingTuples	heads_

boost::optional< ros::Duration >	max_age_

boost::optional< ros::Duration >	max_delta_

std::size_t	max_queue_size_

std::array< ros::Duration, NUM_SLOTS >	min_dist_

std::size_t	pivot_

ros::Time	pivot_ts_

IncomingQueues	queues_

Static Private Attributes
static constexpr std::size_t	NUM_SLOTS = sizeof...(IOs)

static constexpr std::size_t	UNSET = NUM_SLOTS

Friends
template<template< typename... > class, class... >
class	fkie_message_filters::Combiner

Additional Inherited Members
Public Types inherited from fkie_message_filters::combiner_policies::PolicyBase< IOs... >
using	EmitterCB = std::function< void(const OutgoingTuple &)>
	Callback for assembled outputs. More...

using	IncomingTuples = std::tuple< helpers::io_tuple_t< IOs >... >
	Tuple type of incoming data tuples. More...

using	OutgoingTuple = helpers::io_tuple_t< helpers::io_concat_t< IOs... > >
	Combined tuple type for data output. More...

Protected Types inherited from fkie_message_filters::combiner_policies::PolicyBase< IOs... >
using	MaybeOutgoingTuples = std::tuple< boost::optional< helpers::io_tuple_t< IOs > >... >
	Tuple of outgoing tuple candidates. More...

Detailed Description

template<typename... IOs>
class fkie_message_filters::combiner_policies::ApproximateTime< IOs >

Approximate time policy.

This is a policy for the Combiner class. It will associate data from the connected sources, but unlike ExactTime, it can match messages even when their ROS header timestamps do not match perfectly. If an input source is not unary, only the first argument will be examined to determine the timestamp. It must have an accessible ROS header, which is determined using the ros::message_traits template.

The policy employs a modified version of the ROS ApproximateTime algorithm. Like its predecessor, the algorithm is not merely applying an epsilon to account for time differences, but tries to find the best possible match. Each set of grouped messages which are output by the policy, satisfies the following criteria:

Each message is used only once. Two sets will never share the same message, but some messages can be dropped.
Messages are used in order. Unlike the original algorithm, we do not guarantee that sets as a whole do not overlap, but we guarantee that for each topic, messages will be used in time stamp order. We found that revising this criterion improves match quality for high-frequency topics, such as stereo vision systems with depth images, in the presence of transient jitter.
Sets are contiguous. This means that you cannot form a valid set from the dropped messages.
Sets have minimal timespan. This means that the time stamp difference among messages in a set cannot be smaller without violating the previous property.
The output only depends on the time stamps, not on the arrival time of messages. The messages have to arrive in order on each topic, but not necessarily across topics, as long as the queue size is large enough to accommodate for the differences.

Optional parameters:

Set timespan: the time difference of two messages in the same set will never exceed this value. By default, the policy does not constrain the timespan. If you set this value, the policy will avoid "wasting" messages in sets which are ultimately rejected anyway. Oftentimes, this will give you more valid sets in total.
Message distance: if messages of a particular topic cannot be closer together than a known interval, providing this lower bound will not change the output but will allow the algorithm to conclude earlier that a given set is optimal, thereby reducing output lag. The default lower bound is zero. An incorrect lower bound will result in suboptimal sets being selected.

The algorithm works as follows:

Wait until each input queue has at least one message available.
Pick the latest message among the heads of all queues, which is going to be the pivot. The pivot belongs to every set that is contiguous to the previous set, so it must belong to the newly formed set.
For all other input queues except the pivot, advance to the next message until the time difference to the pivot message is minimal. Proving optimality depends on the minimum message distance and the fact that on every topic, messages will arrive in time stamp order. If any queue is exhausted and, at least theoretically, the next message could still be closer to the pivot, wait for the next message to arrive.
Once all input queues have reached their optimum, send the resulting set. If the set violates the user-specified timespan constraint, drop the pivot element instead, and restart from scratch with the remaining messages.
If messages arrive out of order (i.e. a message on a topic has a time stamp that is earlier than the previously received one), all queues are flushed and the policy restarts from scratch.
If messages need to be dropped because the maximum queue size or the message age limit is exceeded, the pivot element is chosen again from the new queue heads. By default, the policy will buffer arbitrary many messages for at most one second.

Definition at line 82 of file approximate_time.h.

Member Typedef Documentation

◆ IncomingQueues

template<typename... IOs>

using fkie_message_filters::combiner_policies::ApproximateTime< IOs >::IncomingQueues = std::tuple<std::deque<helpers::io_tuple_t<IOs> >...>

private

Definition at line 146 of file approximate_time.h.

Constructor & Destructor Documentation

◆ ApproximateTime()

template<typename... IOs>

fkie_message_filters::combiner_policies::ApproximateTime< IOs >::ApproximateTime ( )

Constructor.

Definition at line 36 of file approximate_time_impl.h.

Member Function Documentation

◆ add()

template<typename... IOs>

template<std::size_t N>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::add	(	std::unique_lock< std::mutex > &	lock,
		const std::tuple_element_t< N, IncomingTuples > &	in
	)

protected

Input function.

This function will be called by the Combiner class for incoming data.

Definition at line 73 of file approximate_time_impl.h.

◆ can_still_improve()

template<typename... IOs>

bool fkie_message_filters::combiner_policies::ApproximateTime< IOs >::can_still_improve ( )

privatenoexcept

Definition at line 197 of file approximate_time_impl.h.

◆ can_still_improve_at()

template<typename... IOs>

template<std::size_t N>

bool fkie_message_filters::combiner_policies::ApproximateTime< IOs >::can_still_improve_at ( )

privatenoexcept

Definition at line 169 of file approximate_time_impl.h.

◆ determine_pivot()

template<typename... IOs>

bool fkie_message_filters::combiner_policies::ApproximateTime< IOs >::determine_pivot ( )

privatenoexcept

Definition at line 324 of file approximate_time_impl.h.

◆ discard_expired()

template<typename... IOs>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::discard_expired ( const ros::Time & cutoff )

privatenoexcept

Definition at line 240 of file approximate_time_impl.h.

◆ discard_expired_at()

template<typename... IOs>

template<std::size_t N>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::discard_expired_at ( const ros::Time & cutoff )

privatenoexcept

Definition at line 214 of file approximate_time_impl.h.

◆ drop_pivot()

template<typename... IOs>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::drop_pivot ( )

privatenoexcept

Definition at line 304 of file approximate_time_impl.h.

◆ emit_heads()

template<typename... IOs>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::emit_heads ( std::unique_lock< std::mutex > & lock )

private

Definition at line 138 of file approximate_time_impl.h.

◆ heads_timespan()

template<typename... IOs>

ros::Duration fkie_message_filters::combiner_policies::ApproximateTime< IOs >::heads_timespan ( )

privatenoexcept

Definition at line 272 of file approximate_time_impl.h.

◆ pivot_timedelta()

template<typename... IOs>

ros::Duration fkie_message_filters::combiner_policies::ApproximateTime< IOs >::pivot_timedelta ( const ros::Time & ts )

privatenoexcept

Definition at line 297 of file approximate_time_impl.h.

◆ prune_queue_at()

template<typename... IOs>

template<std::size_t N>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::prune_queue_at ( std::size_t queue_size )

privatenoexcept

Definition at line 247 of file approximate_time_impl.h.

◆ reset()

template<typename... IOs>

void fkie_message_filters::combiner_policies::ApproximateTime< IOs >::reset ( )

overrideprotectedvirtualnoexcept

Reset internal state.

This function is called by the Combiner if the filter is reset.

Implements fkie_message_filters::combiner_policies::PolicyBase< IOs... >.

Definition at line 259 of file approximate_time_impl.h.

◆ set_max_age()

template<typename... IOs>

ApproximateTime< IOs... > & fkie_message_filters::combiner_policies::ApproximateTime< IOs >::set_max_age ( const ros::Duration & max_age )

noexcept

Set maximum age of any data in the queue.

This is equivalent to

set_max_queue_size(0, max_age);

max_age maximum age

Definition at line 42 of file approximate_time_impl.h.

◆ set_max_queue_size()

template<typename... IOs>

ApproximateTime< IOs... > & fkie_message_filters::combiner_policies::ApproximateTime< IOs >::set_max_queue_size	(	std::size_t	queue_size,
		const boost::optional< ros::Duration > &	max_age = `boost::none`
	)

noexcept

Set maximum queue size.

queue_size maximum queue size per slot (zero means unlimited)
max_age the maximum age of any data in the queue (none means unlimited)

Definition at line 50 of file approximate_time_impl.h.

◆ set_max_timespan()

template<typename... IOs>

ApproximateTime< IOs... > & fkie_message_filters::combiner_policies::ApproximateTime< IOs >::set_max_timespan ( const ros::Duration & max_delta )

noexcept

Set maximum permissible timestamp difference of matched messages.

max_delta the maximum permissible timestamp difference of matched messages

Definition at line 58 of file approximate_time_impl.h.

◆ set_min_distance()

template<typename... IOs>

ApproximateTime< IOs... > & fkie_message_filters::combiner_policies::ApproximateTime< IOs >::set_min_distance	(	std::size_t	i,
		const ros::Duration &	min_dist
	)

noexcept

Set the minimum distance between consecutive messages on a source.

If it is known in advance that messages from a certain source cannot arrive closer together than min_dist, the policy can conclude earlier that a set of matched messages is optimal, thereby reducing the introduced lag. A typical example would be a camera with fixed frame rate F, where the minimum distance between consecutive messages can be assumed to be at least 0.5/F.

i the input source slot
min_dist the minimum temporal distance between consecutive messages

Definition at line 65 of file approximate_time_impl.h.

Friends And Related Function Documentation

◆ fkie_message_filters::Combiner

template<typename... IOs>

template<template< typename... > class, class... >

friend class fkie_message_filters::Combiner

friend

Definition at line 85 of file approximate_time.h.

Member Data Documentation

◆ heads_

template<typename... IOs>

MaybeOutgoingTuples fkie_message_filters::combiner_policies::ApproximateTime< IOs >::heads_

private

Definition at line 167 of file approximate_time.h.

◆ max_age_

template<typename... IOs>

boost::optional<ros::Duration> fkie_message_filters::combiner_policies::ApproximateTime< IOs >::max_age_

private

Definition at line 160 of file approximate_time.h.

◆ max_delta_

template<typename... IOs>

boost::optional<ros::Duration> fkie_message_filters::combiner_policies::ApproximateTime< IOs >::max_delta_

private

Definition at line 162 of file approximate_time.h.

◆ max_queue_size_

template<typename... IOs>

std::size_t fkie_message_filters::combiner_policies::ApproximateTime< IOs >::max_queue_size_

private

Definition at line 161 of file approximate_time.h.

◆ min_dist_

template<typename... IOs>

std::array<ros::Duration, NUM_SLOTS> fkie_message_filters::combiner_policies::ApproximateTime< IOs >::min_dist_

private

Definition at line 165 of file approximate_time.h.

◆ NUM_SLOTS

template<typename... IOs>

constexpr std::size_t fkie_message_filters::combiner_policies::ApproximateTime< IOs >::NUM_SLOTS = sizeof...(IOs)

staticprivate

Definition at line 143 of file approximate_time.h.

◆ pivot_

template<typename... IOs>

std::size_t fkie_message_filters::combiner_policies::ApproximateTime< IOs >::pivot_

private

Definition at line 163 of file approximate_time.h.

◆ pivot_ts_

template<typename... IOs>

ros::Time fkie_message_filters::combiner_policies::ApproximateTime< IOs >::pivot_ts_

private

Definition at line 164 of file approximate_time.h.

◆ queues_

template<typename... IOs>

IncomingQueues fkie_message_filters::combiner_policies::ApproximateTime< IOs >::queues_

private

Definition at line 166 of file approximate_time.h.

◆ UNSET

template<typename... IOs>

constexpr std::size_t fkie_message_filters::combiner_policies::ApproximateTime< IOs >::UNSET = NUM_SLOTS

staticprivate

Definition at line 144 of file approximate_time.h.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Additional Inherited Members

Detailed Description

template<typename... IOs> class fkie_message_filters::combiner_policies::ApproximateTime< IOs >

Member Typedef Documentation

◆ IncomingQueues

Constructor & Destructor Documentation

◆ ApproximateTime()

Member Function Documentation

◆ add()

◆ can_still_improve()

◆ can_still_improve_at()

◆ determine_pivot()

◆ discard_expired()

◆ discard_expired_at()

◆ drop_pivot()

◆ emit_heads()

◆ heads_timespan()

◆ pivot_timedelta()

◆ prune_queue_at()

◆ reset()

◆ set_max_age()

◆ set_max_queue_size()

◆ set_max_timespan()

◆ set_min_distance()

Friends And Related Function Documentation

◆ fkie_message_filters::Combiner

Member Data Documentation

◆ heads_

◆ max_age_

◆ max_delta_

◆ max_queue_size_

◆ min_dist_

◆ NUM_SLOTS

◆ pivot_

◆ pivot_ts_

◆ queues_

◆ UNSET

template<typename... IOs>
class fkie_message_filters::combiner_policies::ApproximateTime< IOs >