#include <ImFusion/Base/TrackingSequence.h>

Sequence of rigid tracking data with optional timestamps, quality values and flags. More...

Inheritance diagram for TrackingSequence:

Detailed Description

Sequence of rigid tracking data with optional timestamps, quality values and flags.

By convention, TrackingSequences are either owned by the data model and thus shown in the data widget, or by some other class, for instance TrackedSharedImageSet.

All transformations map to the world coordinate system. The method matrix() without any arguments contains the registration matrix of the entire tracking sequence. This allows using common suite features, for instance linking the tracking sequence with images, moving everything coherently. Querying a specific matrix M (matrix(int) with an index or matrix(double) with a time stamp) will obtain the following sequence of transformations: \(M = R \cdot M[i] \cdot C\), where R is the registration matrix, C the calibration matrix, and M[i] the specific matrix queried for.

Note: In older versions of the SDK this class was called "TrackingStream" and was only later renamed to TrackingSequence in order to avoid confusion with the ImFusion::Stream interface. Therefore, at some places that have not yet been adapted, documentation or member names may still refer to a "tracking stream" even though it means a TrackingSequence.

Classes
class	TrackingSequenceIterator
	Iterator class for iteration over tracking sequence data, for instance in for-each loops. More...

class	TrackingTuple
	Tuple returned by iterator, similar to std::pair used when iterating over maps. More...

Public Types
enum	FilterMode { None = 0 , Position , PositionRotation }
	Set spatial filtering of the tracking data (0=None, 1=Position, 2=Position+Rotation). More...

using	const_iterator = TrackingSequenceIterator
	Typedef for standard naming convention.

Public Types inherited from Data
enum	Kind { UNKNOWN = 0 , IMAGE = 1 , VOLUME = 2 , IMAGESET = 3 , VOLUMESET = 4 , IMAGESTREAM = 5 , VOLUMESTREAM = 6 , POINTSET = 7 , SURFACE = 8 , TRACKINGSTREAM = 9 , LIVETRACKINGSTREAM = TRACKINGSTREAM , TRACKINGDATA = 10 , TREE = 11 , TENSOR = 12 , POLYDATASTREAM = 13 , STEREOIMAGESET = 14 , STEREOIMAGESTREAM = 15 , VOLUMETRICMESH = 16 }
	Kind of data. More...

enum	Modality { NA = 0 , XRAY = 1 , CT = 2 , MRI = 3 , ULTRASOUND = 4 , VIDEO = 5 , NM = 6 , OCT = 7 , LABEL = 8 , DISTANCE = 9 }
	Image modality of the data. More...

Public Member Functions
	TrackingSequence (const std::string &name="")

	TrackingSequence (const TrackingSequence &other)
	Copy constructor.

TrackingSequence &	operator= (const TrackingSequence &other)
	Overloaded assignment operator to synchronize multi-thread accesses while copying.

Kind	kind () const override
	Return the kind of this data.

std::string	describe () const override
	Human readable description of the data for showing in the info bar.

Geometry::AlignedBox	bounds () const override
	Return the axis-aligned bounding box of all tracking poses in world space.

void	setMatrix (const mat4 &m) override
	Set the registration matrix (matrix mapping from the tracker to the world coordinate origin)

bool	isAnnotationType () const override
	Return whether this data type is visualized through an annotation (e.g. mesh)

Pose::TransformationConvention	matrixConvention () const override
	Tracking sequence transformations map to the world coordinate system.

void	clear ()
	Clear all tracking samples (including timestamps, quality and flags)

void	remove (int pos, int count=1)
	Remove the selected tracking entries.

void	setCalibration (const mat4 &mat)
	Set the calibration matrix (matrix mapping from the image center to the tracker)

void	setRegistration (const mat4 &mat)
	Set the registration matrix (matrix mapping from the tracker to the world coordinate origin)

void	setTemporalOffset (double val)
	Set the temporal offset (lag) value, in seconds.

void	setInvert (bool flag)
	Specify if inverted tracking matrices should be provided.

void	setRelativeTracking (const TrackingSequence *sequence)
	Specify another tracking sequence to which relative matrices should be provided.

void	setRelativeToFirst (bool flag)
	Specify whether a relative tracking sequence shall be used with respect to its first frame.

void	setFilterMode (int val)

void	setFilterSize (int val)
	Specify half width of filter window.

void	setFilterGaussian (bool flag)
	If true, a Gaussian filter with 3 sigma cutoff will be used, a box filter otherwise.

void	setFilterConsiderTime (bool flag)
	If true, the filter will accommodate varying timestamps.

void	setFilterBalance (bool flag)
	If true, filtering balances the number of samples before and after the central one.

void	shiftTimestamps (double shift)
	Add the `shift` value to all timestamps.

mat4	matrix (int num) const
	Return matrix (with registration and calibration applied) of a tracking sample.

mat4	rawMatrix (double time) const
	Return raw tracking matrix without multiplying anything (registration, calibration, etc.) on it at a particular time.

mat4	rawMatrix (int num) const
	Return raw tracking matrix without multiplying anything (registration, calibration, etc.) on it.

void	setRawMatrix (int idx, const mat4 &value)
	Set the raw tracking matrix (as retrieved from the tracking system, without registration, calibration, etc. considered)

mat4	closestRawMatrix (double time) const
	Return closest raw matrix at the given timestamp. Does not perform interpolation.

double	closestTimestamp (double time) const
	Return closest timestamp at the given timestamp. Does not perform interpolation.

int	closestTimestampIndex (double time) const
	Return the index of the closest timestamp at the given timestamp. Does not perform interpolation.

mat4	matrix (double time) const
	Return matrix (with registration and calibration applied) at a particular time, in seconds.

bool	hasTimestamps () const
	Return true if the tracking sequence has correct timestamps.

bool	checkTimestamps (std::ostream *out=nullptr)
	Sort all tracking frames by their timestamp, compute the median timestamp increment, and return true if there are gaps (i.e.

double	timestamp (int num) const
	Return the timestamp of a tracking sample in seconds.

void	setTimestamp (int idx, double value)
	Set the timestamp of a tracking sample.

std::vector< double >	timestamps () const
	Returns all tracking sample timestamps.

void	setMaxTimestepBetweenSamples (double val)
	Set the maxtimestep between samples as the average of the time stamp between consecutive samples.

bool	isWithinTimestepLimit (double timestamp1, double timestamp2) const
	Return true if the timestep between the provided timestamps is within m_maxTimestepBetweenSamples.

double	rawQuality (int num) const
	Return the quality value of a tracking sample, without consideration of relative streams.

void	setRawQuality (int idx, double value)
	Set the quality of a tracking sample directly.

std::vector< double >	rawQualities () const
	Return all tracking sample qualities.

double	quality (int num) const
	Return the quality value of a tracking sample.

double	quality (double time, bool checkDistance, bool ignoreRelative=false) const
	Return the quality value at a particular time.

bool	hasQuality () const
	Return true if the tracking sequence has quality data.

int	flags (int num) const
	Return the flags of a tracking sample.

bool	hasFlags () const
	Return true if the tracking sequence has flags data.

const mat4 &	calibration () const
	Return the calibration matrix.

const mat4 &	registration () const
	Return the registration matrix.

double	temporalOffset () const
	Return the temporal offset (lag) value, in seconds.

bool	invert () const
	Return the inversion flag.

const TrackingSequence *	relativeTracking () const
	Return relative tracking sequence if enabled. Can be pointer to itself.

bool	relativeToFirst () const
	Return whether a relative tracking sequence is used with respect to its first frame.

int	filterMode () const
	Return matrix filtering mode.

int	filterSize () const
	Return matrix filtering size.

bool	filterGaussian () const
	Return the Gaussian filtering flag.

bool	filterConsiderTime () const
	Return the filter consider time flag.

bool	filterBalance () const
	Return the filter balance flag.

double	maxTimestepBetweenSamples ()
	Return the maxtimestep between samples expressed in sec.

void	printInfo (std::ostream *out=nullptr) const
	Print some statistics about the tracking sequence.

vec3	center () const
	Compute and return the 3D center of the tracking sequence.

int	size () const override
	Return the size of the tracking sequence.

double	medianTimeStep () const
	Return the median time step between tracking samples in case there are gaps, and zero otherwise.

void	setInstrumentMetaData (unsigned int id, const std::string &name, const std::string &model)

void	setTrackerID (const TrackerID &id)
	Set the ID (should be unique), name, and model number of the tracking instrument at once.

unsigned int	instrumentID () const
	Return the tracking instrument ID.

std::string	instrumentName () const
	Return the tracking instrument name.

std::string	instrumentModelNumber () const
	Return the tracking instrument model number.

const TrackerID	trackerID () const
	Return the TrackerID containing info about the unique ID, the model number, and the name of the instrument.

bool	isRelativeSequenceCompatible (const TrackingSequence *ts) const
	Return true of the provided tracking sequence fulfils the requirements obtained during loading.

std::string	filename () const
	Return original filename the sequence was loaded from.

void	setFilename (const std::string &file)
	Set the original filename the sequence was loaded from.

void	emitTrackingChanged ()
	Emits signalTrackingChanged.

bool	isRelativeStreamCompatible (const TrackingSequence *ts) const

virtual mat4	matrix () const
	To prevent overloading warning.

const DataComponentList &	components () const
	Returns the list of DataComponents for this data.

DataComponentList &	components ()

const DataComponentList &	components (int i) const
	Returns the DataComponents associated to the element with that index.

Public Member Functions inherited from Data
	Data (const std::string &name="")

	Data (const Data &other)

Data &	operator= (const Data &other)

virtual	~Data ()
	Mandatory virtual destructor.

virtual Modality	modality () const
	Return the modality of this data.

const std::string &	name () const
	Return the name of this data.

void	setName (const std::string &name)
	Sets the name of this data.

const DataComponentList &	components () const
	Returns the list of DataComponents for this data.

DataComponentList &	components ()

virtual void	setMatrixFromWorld (const mat4 &m)
	Set matrix mapping from the world coordinate system to the data coordinate system.

virtual void	setMatrixToWorld (const mat4 &m)
	Set matrix mapping from the data coordinate system to the world coordinate system.

virtual mat4	matrixFromWorld () const
	Get matrix mapping from the world coordinate system to the data coordinate system.

virtual mat4	matrixToWorld () const
	Get matrix mapping from the data coordinate system to the world coordinate system.

Public Member Functions inherited from ElementwiseDataComponentData
ElementwiseDataComponentList &	elementwiseComponents ()
	Returns elementwise data component list.

const ElementwiseDataComponentList &	elementwiseComponents () const
	Returns elementwise data component list.

DataComponentList &	mutableComponents (int i)
	Returns the DataComponents associated to the element with that index, creating it if necessary.

const DataComponentList &	components (int i) const
	Returns the DataComponents associated to the element with that index.

Public Member Functions inherited from SignalReceiver
	SignalReceiver ()=default
	Default constructor.

	SignalReceiver (const SignalReceiver &other)
	Copy constructor, does not copy any existing signal connections from other.

SignalReceiver &	operator= (SignalReceiver rhs)
	Assignment operator, disconnects all existing connections, does not copy any existing signal connections from rhs.

virtual	~SignalReceiver ()
	Virtual destructor disconnects from all connected signals.

Public Member Functions inherited from Selectable
	Selectable (const Selectable &)

	Selectable (Selectable &&)

Selectable &	operator= (const Selectable &)

Selectable &	operator= (Selectable &&)

virtual Selection	selection () const

virtual int	focus () const

virtual void	setSelection (const Selection &sel)
	Set the underlying selection.

virtual void	setFocus (int index)
	Set focus of the selection.

Static Public Member Functions
template<typename T>
static void	printTimeInfo (const T &data, std::ostream *out=nullptr)
	Print information regarding the timestamp range and increments.

Static Public Member Functions inherited from Data
static std::string	modalityString (Data::Modality m)
	Return the name of an image modality.

static Data::Modality	stringToModality (const std::string &s)
	Returns the modality corresponding to a modality string or NA if nothing matches.

Public Attributes
Signal	signalTrackingChanged
	Signal emitted when the tracking sequence data has changed.

Signal &	signalTrackingStreamChanged = signalTrackingChanged

Public Attributes inherited from Data
Signal< const Data * >	signalDeleted
	Signal emitted when this instance is deleted.

Signal< const Data * >	signalMatrixChanged
	Signal emitted when the transformation of this Data has changed.

Signal< std::string >	signalNameChanged
	Signal emitted when the name changed.

Public Attributes inherited from Selectable
ProtectedSignal	signalSelectionChanged
	Signals that the selection or size might have changed.

Protected Member Functions
template<typename T>
double	retrieveSampleForInterpolation (double time, T(TrackingSequence::*lookupFunc)(int) const, bool checkDistance, T &outSample1, T &outSample2) const
	Internal helper method to perform a timestamp-based look-up of matrices, qualities, etc.

Protected Member Functions inherited from Data
void	swapWith (Data &other)
	Swaps the data and emits a matrix and name changed signal for both.

Protected Member Functions inherited from SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Static Protected Member Functions
template<typename T>
static void	analyzeSeries (const T &data, int mode, double &avg, double &std, double &min, double &max)
	Compute basic statistics on a scalar vector of data.

Protected Attributes
Transform< TrackingCS::Tracker, TrackingCS::Calibrated >	m_calibration
	Calibration matrix (applied right of the tracking)

Transform< GlobalCS::World, GlobalCS::Data >	m_regOrig
	Original registration matrix in case of relative tracking.

double	m_temporalOfs
	Temporal offset (lag)

double	m_medianTimeStep
	Median time step if there are outliers.

double	m_maxTimestepBetweenSamples
	Max allowed timestep between two samples for non-zero quality, set to 0 for no limit.

std::deque< Transform< GlobalCS::Data, TrackingCS::Tracker > >	m_matrices
	The rigid tracking matrices.

std::deque< Transform< GlobalCS::Data, TrackingCS::Tracker > >	m_matOrig
	Original tracking matrices if filtering is enabled.

std::deque< double >	m_timestamps
	Timestamps, if available.

std::deque< double >	m_quality
	Quality values, if available.

std::deque< int >	m_flags
	Binary flags, if available.

TrackerID	m_trackerID
	ID of the tracking instrument.

int	m_filterMode
	Spatial filtering of tracking data (0 if disabled)

int	m_filterSize
	Size of the filter window (number of samples)

bool	m_filterSizeChanged
	If true, setFilterMode filters all samples and changes the flag to false.

bool	m_filterGauss
	Gaussian vs. box filter mode.

bool	m_filterTime
	Filtering considers timestamps.

bool	m_filterBalance
	Filtering balances before and after samples.

bool	m_invert
	Provide inverted tracking matrices.

bool	m_relToFirst
	Relative tracking sequence applied wrt. its first frame.

const TrackingSequence *	m_relSequence
	Provide relative matrices wrt. another sequence.

std::string	m_tempRelStreamInfo
	During loading, instrument ID, name, and model number are stored here to allow for later assignment of the relative tracking sequence.

std::string	m_filename
	Stores file name the TrackingSequence was loaded from.

std::recursive_mutex	m_dataMtx
	Internally synchronizes access to data members.

Geometry::AlignedBox	m_bounds
	axis-aligned bounding box of this data in world space

bool	m_updateBounds
	flag which indicates whether the bounds of this data should be re-computed

Protected Attributes inherited from Data
mat4	m_matrix
	Transformation matrix.

std::recursive_mutex *	m_matrixMutex
	Used to internally synchronize access to the matrix of data.

DataComponentList	m_dataComponentList
	The list of DataComponents for this data.

Protected Attributes inherited from ElementwiseDataComponentData
ElementwiseDataComponentList	m_elementwiseComponents
	Encodes elementwise data components.

Protected Attributes inherited from Selectable
std::mutex	m_selectionMutex
	Mutex protecting the selection.

Selection	m_sel

Adding a tracking sample, only one of these methods must be used
void	add (const mat4 &mat)
	Add a single tracking matrix.

void	add (const mat4 &mat, double timestamp)
	Add a tracking matrix with corresponding timestamp.

void	add (const mat4 &mat, double timestamp, double quality)
	Add a tracking matrix with timestamp and quality information.

void	add (const mat4 &mat, double timestamp, double quality, int flags)
	Add a tracking matrix with timestamp, quality and further flags such as button states.

Iterators for matrix traversal
const_iterator	begin () const

const_iterator	end () const

Member Enumeration Documentation

◆ FilterMode

enum FilterMode

Set spatial filtering of the tracking data (0=None, 1=Position, 2=Position+Rotation).

The set of filtered matrices are computed in this method, and the original ones backed up. If a filter is set, new tracking data can only be added to the end of the sequence and old tracking data can only be removed from the beginning of the sequence. After adding or removing (one or multiple) samples this method must be called. Adding and removing samples must not be done together in between two calls.

Constructor & Destructor Documentation

◆ TrackingSequence()

TrackingSequence ( const TrackingSequence & other )

Copy constructor.

If the relative tracking sequence of other is other itself, the intended recursion to the this-pointer is maintained.

Member Function Documentation

◆ operator=()

TrackingSequence & operator= ( const TrackingSequence & other )

Overloaded assignment operator to synchronize multi-thread accesses while copying.

If the relative tracking sequence of other is other itself, the intended recursion to the this-pointer is maintained.

◆ kind()

Kind kind ( ) const

inlineoverridevirtual

Return the kind of this data.

Implements Data.

◆ describe()

std::string describe ( ) const

overridevirtual

Human readable description of the data for showing in the info bar.

Reimplemented from Data.

◆ bounds()

Geometry::AlignedBox bounds ( ) const

overridevirtual

Return the axis-aligned bounding box of all tracking poses in world space.

Implements Data.

◆ setMatrix()

void setMatrix ( const mat4 & m )

overridevirtual

Set the registration matrix (matrix mapping from the tracker to the world coordinate origin)

Reimplemented from Data.

◆ isAnnotationType()

bool isAnnotationType ( ) const

inlineoverridevirtual

Return whether this data type is visualized through an annotation (e.g. mesh)

Reimplemented from Data.

◆ matrixConvention()

Pose::TransformationConvention matrixConvention ( ) const

inlineoverridevirtual

Tracking sequence transformations map to the world coordinate system.

Implements Data.

◆ remove()

void remove	(	int	pos,
		int	count = 1 )

Remove the selected tracking entries.

Will remove associated ElementwiseDataComponent as well.

◆ setRelativeTracking()

void setRelativeTracking ( const TrackingSequence * sequence )

Specify another tracking sequence to which relative matrices should be provided.

The temporal offset value of the provided tracking sequence instance relates it to this instance, e.g. it should generally be set to zero (not the value in here). Note that it can be set to itself, which will result in all calls to matrix() return an identity matrix.

◆ rawMatrix()

mat4 rawMatrix ( double time ) const

Return raw tracking matrix without multiplying anything (registration, calibration, etc.) on it at a particular time.

If required, interpolation between neighboring tracking matrices is used.

◆ matrix() [1/2]

mat4 matrix ( double time ) const

Return matrix (with registration and calibration applied) at a particular time, in seconds.

If required, interpolation between neighboring tracking matrices is used.

◆ checkTimestamps()

bool checkTimestamps ( std::ostream * out = nullptr )

Sort all tracking frames by their timestamp, compute the median timestamp increment, and return true if there are gaps (i.e.

lost tracking). Will also remove data with unreasonable timestamps, and sort ElementwiseDataComponentList as well.

◆ setTimestamp()

void setTimestamp	(	int	idx,
		double	value )

Set the timestamp of a tracking sample.

Attention: Different parameter order than in SharedImageSet!

◆ quality()

double quality	(	double	time,
		bool	checkDistance,
		bool	ignoreRelative = false ) const

Return the quality value at a particular time.

If checkDistance is enabled, a quality of zero is returned when the time is before or after the range of the timestamps, or within a gap. If ignoreRelative is enabled, the quality is calculated from this tracking sequence only and not multiplied with the tracking quality of the reference tracker (only relevant if relative tracking sequence is set).

◆ size()

int size ( ) const

inlineoverridevirtual

Return the size of the tracking sequence.

Implements Selectable.

◆ setInstrumentMetaData()

void setInstrumentMetaData	(	unsigned int	id,
		const std::string &	name,
		const std::string &	model )

Deprecated: "Use setTrackerID(const TrackerID& id) instead"

◆ instrumentID()

unsigned int instrumentID ( ) const

Return the tracking instrument ID.

Deprecated: "Use trackerID().ID() instead"

◆ instrumentName()

std::string instrumentName ( ) const

inline

Return the tracking instrument name.

Deprecated: "Use trackerID().name() instead"

◆ instrumentModelNumber()

std::string instrumentModelNumber ( ) const

inline

Return the tracking instrument model number.

Deprecated: "Use trackerID().modelNumber() instead"

◆ isRelativeStreamCompatible()

bool isRelativeStreamCompatible ( const TrackingSequence * ts ) const

inline

Deprecated

◆ retrieveSampleForInterpolation()

template<typename T>

double retrieveSampleForInterpolation	(	double	time,
		T(TrackingSequence::*	lookupFunc )(int) const,
		bool	checkDistance,
		T &	outSample1,
		T &	outSample2 ) const

protected

Internal helper method to perform a timestamp-based look-up of matrices, qualities, etc.

Returns the fraction between 0 and 1 for outSample1 and outSample2 to be interpolated. outSample2 might not be set of fraction == 0.0.

◆ matrix() [2/2]

virtual mat4 matrix ( ) const

virtual

To prevent overloading warning.

Reimplemented from Data.

Member Data Documentation

◆ signalTrackingStreamChanged

Signal& signalTrackingStreamChanged = signalTrackingChanged

Deprecated: "Use signalTrackingChanged instead"

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

ImFusion/Base/TrackingSequence.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Adding a tracking sample, only one of these methods must be used

Iterators for matrix traversal

Member Enumeration Documentation

◆ FilterMode

Constructor & Destructor Documentation

◆ TrackingSequence()

Member Function Documentation

◆ operator=()

◆ kind()

◆ describe()

◆ bounds()

◆ setMatrix()

◆ isAnnotationType()

◆ matrixConvention()

◆ remove()

◆ setRelativeTracking()

◆ rawMatrix()

◆ matrix() [1/2]

◆ checkTimestamps()

◆ setTimestamp()

◆ quality()

◆ size()

◆ setInstrumentMetaData()

◆ instrumentID()

◆ instrumentName()

◆ instrumentModelNumber()

◆ isRelativeStreamCompatible()

◆ retrieveSampleForInterpolation()

◆ matrix() [2/2]

Member Data Documentation

◆ signalTrackingStreamChanged