TrackingStream Class Reference

#include <ImFusion/Stream/TrackingStream.h>

Specialization of Stream for streams producing tracking data for spatial localization. More...

Inheritance diagram for TrackingStream:

Detailed Description

Specialization of Stream for streams producing tracking data for spatial localization.

TrackingStreams are expected to emit TrackingStreamData objects containing the pose information of one or more TrackingInstruments.

The stream holds a ThreadSafeInstruments container for a set of TrackingInstruments that can be accessed and modified in a thread-safe manner by a derived class implementing an interface to a specific tracking device.

Implementations of tracking streams should derive from this class and use the ThreadSafeInstruments member to add, remove, and modify a TrackingInstrument or to update the tracking state.

A simple tracking stream example:

// Tracking stream example using the worker thread of the base class
class MyTrackingStream : public TrackingStream
{
public:
    ~MyTrackingStream() { MyTrackingStream::close(); }
 
    virtual bool openImpl() override
    {
        // creates a a TrackerID with ID "systemUID-123" and name "Tracker 1" (model number is empty)
        m_instruments->create(TrackerID{"systemUID-123", "", "Tracker 1"});
        m_instruments->create(TrackerID{"systemUID-456", "", "Tracker 2"});
 
        // alternatively, autogenerate TrackerID with ID "systemUID-0", "systemUID-1", and so on
        // m_instruments->createWithPrefix("systemUID", "Tracker 1");
        // m_instruments->createWithPrefix("systemUID", "Tracker 2");
 
        return true;
    }
 
    virtual std::optional<WorkContinuation> doWork() override
    {
        // query tracking information from device such as tracking poses (mat4)
        // and qualities [0.0-1.0] in every iteration of the stream loop while running
        mat4 matrixTracker1 = mat4::Identity();
        double qualityTracker1 = 1.0;
        mat4 matrixTracker2 = mat4::Identity();
        double qualityTracker2 = 1.0;
 
        m_instruments->update("systemUID-123", matrixTracker1, qualityTracker1);
        m_instruments->update("systemUID-456", matrixTracker2, qualityTracker2);
 
        // send out data (with current time as arrival and device timestamp)
        signalStreamData.emitSignal(createTrackingStreamData());
 
        return {};
    }
 
    // override other abstract methods
    virtual std::string uuid() override { return "MyTrackingStream"; }
    virtual bool closeImpl() override { return true; }
    virtual bool startImpl() override { return true; }
    virtual bool stopImpl() override { return true; }
};

Examples

ExampleStreams.cpp.

Public Member Functions
	TrackingStream (const std::string &name="Tracking Stream")
virtual std::vector< TrackingInstrument >	devices () const
	Returns a copy of all tracking instruments (active and inactive) with their last status.
virtual std::vector< TrackingInstrument >	instruments () const
	Returns a copy of all tracking instruments (active and inactive) with their last status.
virtual std::vector< TrackingInstrument >	activeInstruments () const
	Returns a copy of all active tracking instruments with their last status.
virtual int	numInstruments (bool activeOnly=false) const
	Returns the number of instruments (all or only active instruments).
Kind	kind () const override
	Returns the kind of stream.
void	setMainInstrument (unsigned int index)
	Sets the index of the main tracking target.
virtual bool	supportsMainInstrumentSelection () const
	Returns true if main instrument can be set from outside.
void	setMainInstrumentById (const std::string &id)
	Sets the main tracking target by the ID of the TrackingInstrument (TrackerID::m_id).
unsigned int	mainInstrumentIndex () const
	Returns the index of the main tracking target in the instruments array.
std::string	mainInstrumentId () const
	Returns the unique ID of the main instrument.
std::string	mainInstrumentName () const
	Returns the name of the main instrument.
virtual bool	supportsInstrumentRenaming () const
	Returns true if the name of an instrument can be set from outside.
void	setInstrumentName (const std::string &id, const std::string &name)
	Sets the name of the TrackingInstrument for the specified id.
void	setInstrumentActive (const std::string &id, bool active)
	Sets the tracking instrument with the given ID as either active or inactive.
bool	isInstrumentActive (const std::string &id) const
	Returns whether the instrument with the given ID is active.
std::optional< TrackingInstrument >	queryInstrument (const std::string &id) const
	Queries the instrument with the given ID from m_instruments.
std::string	describe () const override
	Provides a short description of the stream, including the number of instruments, latest stream state, and update rate information.
Public Member Functions inherited from Stream
	Stream (const std::string &name="")
	Constructor with the name for this stream.
virtual ThreadingMode	threadingMode () const
	Configures threading mode of stream.
virtual bool	supportsAsyncOperation ()
	Returns true if xxxAsync() methods support execution in a background thread.
std::shared_future< bool >	openAsync ()
	Open stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
std::shared_future< bool >	closeAsync ()
	Close stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
std::shared_future< bool >	startAsync ()
	Start stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
std::shared_future< bool >	stopAsync ()
	Stop stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
std::shared_future< bool >	pauseAsync ()
	Pause stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
std::shared_future< bool >	resumeAsync ()
	Resume stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
bool	open ()
	Open stream and wait for the operation to complete. Returns whether the operation was successful.
bool	close ()
	Close stream and wait for the operation to complete. Returns whether the operation was successful.
bool	start ()
	Start stream and wait for the operation to complete. Returns whether the operation was successful.
bool	stop ()
	Stop stream and wait for the operation to complete. Returns whether the operation was successful.
bool	pause ()
	Pause stream and wait for the operation to complete. Returns whether the operation was successful.
bool	resume ()
	Resume stream and wait for the operation to complete. Returns whether the operation was successful.
virtual bool	supportsPausing () const
	Override and return true if this stream implements the pausing and resume operations.
bool	restart ()
	Stops, closes, opens and starts the stream. Returns whether the operation was successful.
virtual bool	reset ()
	Reverts stream to first frame, if possible. Returns whether the operation was successful.
virtual bool	isRunning () const
	Return whether stream is currently running.
virtual std::string	uuid ()=0
	Unique identifier for stream.
State	currentState () const
bool	isStateOneOf (const std::vector< State > &states) const
Geometry::AlignedBox	bounds () const override
	Per default a Stream has empty/invalid bounds.
Pose::TransformationConvention	matrixConvention () const override
	Matrices of streams by default map to the world coordinate system.
virtual bool	createDefaultStreamController ()
	Indicates whether a StreamController should be created for the stream (by default returns true).
double	updateRate () const
	Average update rate in Hz of the signalStreamData.
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.
virtual bool	isAnnotationType () const
	Return whether this data type is visualized through an annotation (e.g. mesh)
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.
virtual mat4	matrix () const
	Return the transformation matrix.
virtual void	setMatrix (const mat4 &m)
	Set the transformation matrix.
Public Member Functions inherited from Configurable
virtual void	configure (const Properties *p)
	Configure this object instance by de-serializing the given Properties.
virtual void	configuration (Properties *p) const
	Serialize the current object configuration into the given Properties object.
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.
void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().
void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.
	Configurable (const Configurable &rhs)
	Configurable (Configurable &&rhs) noexcept
Configurable &	operator= (const Configurable &)
Configurable &	operator= (Configurable &&) noexcept

Public Attributes
ProtectedSignal &	signalTrackingDevicesUpdated
	Emitted when the list of instruments is updated.
ProtectedSignal	signalInstrumentsUpdated
	Emitted when the list of instruments is altered (instrument added, instrument removed, or list cleared).
ProtectedSignal< const std::string & >	signalMainInstrumentChanged
	Emitted when the main instrument has changed, with the new instrument ID.
Public Attributes inherited from Stream
ProtectedSignal< StateChange >	signalStateChanged
	Emitted after a state change has been completed with the old and new state.
ProtectedSignal	signalEnded
	Indicates that the stream reached the end of its data, e.g. when a video stream has played to the end.
ProtectedSignal< std::shared_ptr< const StreamData > >	signalStreamData
	Signal that is emitted by the stream when a new StreamData is available.
DeprecatedSignal< ProtectedSignal< std::shared_ptr< const StreamData > >, const StreamData & >	signalNewData
	Signal that is emitted by the stream when a new StreamData is available.
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 Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.

Protected Member Functions
void	emitSignals (const InstrumentUpdate &update)
	Convenience method to be called after any instrument modification.
std::unique_ptr< TrackingStreamData >	createTrackingStreamData ()
	Creates the TrackingStreamData with a copy of all instruments and sets the timestamps.
Protected Member Functions inherited from Stream
virtual bool	openImpl ()=0
	Open stream.
virtual bool	closeImpl ()=0
	Close stream.
virtual bool	startImpl ()=0
	Start stream.
virtual bool	stopImpl ()=0
	Stop stream.
virtual bool	pauseImpl ()
	Pause stream (not required to be supported).
virtual bool	resumeImpl ()
	Resume stream from pause (only required to be supported when pauseImpl() is supported).
virtual bool	workerThreadRequiresOpenGl () const
	Override and return true if worker thread should create a GL::Context.
virtual std::optional< WorkContinuation >	doWork ()=0
	Create one StreamData and publish it (this function will be called at the desired frame rate) If this is not desired, you can do the following: return std::nullopt;.
virtual bool	worksWhilePaused () const
	Override if doWork() should be called also in the Paused state.
void	changeState (State newState)
std::shared_future< bool >	attemptStateChange (std::function< bool()> work, State stateWorking, State stateSuccess, State stateError)
Protected Member Functions inherited from Data
void	swapWith (Data &other)
	Swaps the data and emits a matrix and name changed signal for both.

Protected Attributes
std::unique_ptr< ThreadSafeInstrumentsBase >	m_instruments
	Container for TrackingInstruments of this tracking stream.
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 Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Additional Inherited Members
Public Types inherited from Stream
enum class	ThreadingMode { BaseClassRunsWorkerThread , DerivedClassHandlesThreading }
	This flag represents the two supported threading modes of a Stream. More...
enum class	State {   Closed , Opening , Open , Starting ,   Running , Pausing , Paused , Resuming ,   Stopping , Closing }
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...
Static Public Member Functions inherited from Stream
static std::string	stateToString (State state)
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.

Member Function Documentation

devices()

virtual std::vector< TrackingInstrument > devices ( ) const

virtual

Returns a copy of all tracking instruments (active and inactive) with their last status.

Method internally calls TrackingStream::instrumens if not overridden by a derived class.

Deprecated

"Method devices was renamed to instruments and is deprecated. Use instruments() instead." "Derived classes should not override this method anymore as it will be removed in the future."

Reimplemented in CombinedTrackingStream, IgtlTrackingStream, RealSenseStream, KeyboardTrackingStream, RobotTrackingStream, ROSTopicTrackingStream, SeekableTrackingStream, and TrackingSubstream.

instruments()

virtual std::vector< TrackingInstrument > instruments ( ) const

virtualthreadsafe

Returns a copy of all tracking instruments (active and inactive) with their last status.

Can be called concurrently from any thread.

Reimplemented in SmoothedTrackingStream.

activeInstruments()

virtual std::vector< TrackingInstrument > activeInstruments ( ) const

virtualthreadsafe

Returns a copy of all active tracking instruments with their last status.

Can be called concurrently from any thread.

numInstruments()

virtual int numInstruments ( bool activeOnly = false ) const

virtualthreadsafe

Returns the number of instruments (all or only active instruments).

Can be called concurrently from any thread.

kind()

Kind kind ( ) const

inlineoverridevirtualthreadsafe

Returns the kind of stream.

Can be called concurrently from any thread.

Implements Data.

setMainInstrument()

void setMainInstrument

(

unsigned int

index

)

Sets the index of the main tracking target.

Requires supportsMainInstrumentSelection to be true. Otherwise, nothing happens.

Deprecated

"Identification by index is deprecated. Use the instrument ID instead"

supportsMainInstrumentSelection()

virtual bool supportsMainInstrumentSelection ( ) const

inlinevirtualthreadsafe

Returns true if main instrument can be set from outside.

Override this method to return false, if the tracking stream has a dedicated main instrument.

Can be called concurrently from any thread.

setMainInstrumentById()

void setMainInstrumentById ( const std::string & id )

threadsafe

Sets the main tracking target by the ID of the TrackingInstrument (TrackerID::m_id).

Requires supportsMainInstrumentSelection to be true. Otherwise, nothing happens.

Can be called concurrently from any thread.

mainInstrumentIndex()

unsigned int mainInstrumentIndex

(

)

const

Returns the index of the main tracking target in the instruments array.

Deprecated

"Identification by index is deprecated. Use the instrument ID instead"

mainInstrumentId()

std::string mainInstrumentId ( ) const

threadsafe

Returns the unique ID of the main instrument.

Can be called concurrently from any thread.

mainInstrumentName()

std::string mainInstrumentName ( ) const

threadsafe

Returns the name of the main instrument.

Can be called concurrently from any thread.

supportsInstrumentRenaming()

virtual bool supportsInstrumentRenaming ( ) const

inlinevirtualthreadsafe

Returns true if the name of an instrument can be set from outside.

Override this method to return false, if the tracking stream does not allow this.

Can be called concurrently from any thread.

Reimplemented in IgtlTrackingStream, and PlaybackTrackingStream.

setInstrumentName()

void setInstrumentName ( const std::string & id, const std::string & name )

threadsafe

Sets the name of the TrackingInstrument for the specified id.

Requires supportsInstrumentRenaming to be true. Otherwise, nothing happens.

Can be called concurrently from any thread.

setInstrumentActive()

void setInstrumentActive ( const std::string & id, bool active )

threadsafe

Sets the tracking instrument with the given ID as either active or inactive.

Can be called concurrently from any thread.

isInstrumentActive()

bool isInstrumentActive ( const std::string & id ) const

threadsafe

Returns whether the instrument with the given ID is active.

Can be called concurrently from any thread.

queryInstrument()

std::optional< TrackingInstrument > queryInstrument ( const std::string & id ) const

threadsafe

Queries the instrument with the given ID from m_instruments.

Can be called concurrently from any thread.

describe()

std::string describe ( ) const

overridevirtualthreadsafe

Provides a short description of the stream, including the number of instruments, latest stream state, and update rate information.

Can be called concurrently from any thread.

Reimplemented from Stream.

emitSignals()

void emitSignals ( const InstrumentUpdate & update )

protectedthreadsafe

Convenience method to be called after any instrument modification.

It checks which signals need to be emitted. Emits the signals signalInstrumentsUpdated and signalMainInstrumentChanged if needed. Additionally, calls createTrackingStreamData to create the TrackingStreamData and emits signalStreamData.

Example usage in a tracking stream class:

// instrument list modifications in `openImpl`
auto update = m_instruments->create("trackingSystem-3419", "Tracker 1");
update |= m_instruments->create("trackingSystem-334", "Tracker 2");
update |= m_instruments->setMainById("trackingSystem-334");
emitSignals(update);
 
// tracking update in `doWork`
InstrumentUpdate update;
for (auto& [id, mat] : TrackerAPI::getTrackings();
    update = m_instruments->update(id, mat, 1.0);
 
emitSignals(update);

Can be called concurrently from any thread.

createTrackingStreamData()

std::unique_ptr< TrackingStreamData > createTrackingStreamData ( )

protectedthreadsafe

Creates the TrackingStreamData with a copy of all instruments and sets the timestamps.

The arrival timestamp is set to the current system time, and the device timestamp is set to the first instrument timestamp.

Example usage in a tracking stream class:

// directly send out the tracking data
signalStreamData.emitSignal(*createTrackingStreamData());
 
// modifications to the TrackingStreamData
auto tsd = createTrackingStreamData();
tsd->setTimestampArrival(arrivalTime);
tsd->updateComponents(dataComponents);
signalStreamData.emitSignal(*tsd);

Can be called concurrently from any thread.

Member Data Documentation

signalTrackingDevicesUpdated

ProtectedSignal& signalTrackingDevicesUpdated

Emitted when the list of instruments is updated.

Deprecated

"Signal signalTrackingDevicesUpdated was renamed. Use signalInstrumentsUpdated instead."

---

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

• ImFusion/Stream/TrackingStream.h