#include <ImFusion/Stream/ThreadSafeInstruments.h>

Specialized class of ThreadSafeInstrumentsBase with the option to manage additional metadata, which is held in a struct/class Special next to the TrackingInstrument. More...

Inheritance diagram for ImFusion::ThreadSafeInstruments< Special >:

Detailed Description

template<class Special = UnusedSpecial>
class ImFusion::ThreadSafeInstruments< Special >

Specialized class of ThreadSafeInstrumentsBase with the option to manage additional metadata, which is held in a struct/class Special next to the TrackingInstrument.

For example, when implementing a TrackingStream for inertial measurement units, the TrackingInstrument could hold estimated absolute poses, while the raw IMU measurements would be stored in a class that is used as the Special template parameter.

The objects of type Special can be copied out if the class implements the Clonable interface. Additionally, there are accessor methods to modify or access them in-place.

Without specifying the metadata template class, this class provides basic functionality according to the ThreadSafeInstrumentsBase interface and all additional methods to manage the Special class are disabled.

Note: Threadsafe class: Member functions can be called concurrently from any thread.

Public Member Functions
std::vector< TrackingInstrument >	instruments () const override
	Returns a vector of tracking instruments.
std::optional< TrackingInstrument >	mainInstrument () const override
	Returns the main tracking instrument, if any.
InstrumentUpdate	setMain (unsigned int index) override
InstrumentUpdate	setMainById (const std::string &id) override
	Sets the main tracking instrument by tracking ID.
unsigned int	mainIndex () const override
const std::string &	mainId () const override
	Returns the ID of the main tracking instrument.
std::string	mainName () const override
	Returns the name of the main tracking instrument.
void	setActive (const std::string &id, bool active) override
	Sets the active flag of an instrument.
bool	isActive (const std::string &id) const override
	Returns whether a tracking instrument is active.
InstrumentUpdate	create (TrackerID trackerID, bool active=true) override
	Creates a new instrument with the given TrackerID and active state.
InstrumentUpdate	createWithPrefix (const std::string &prefix, const std::string &name, const std::string &modelNum="", bool active=true) override
	Creates a new instrument with the given name and optional model number and active state.
SPECIAL_USED InstrumentUpdate	create (TrackerID trackerID, std::unique_ptr< Special > extra, bool active=true)
	Creates a new instrument with the given TrackerID and active state, and an object of the Special class, which is assigned to the created instrument.
SPECIAL_USED InstrumentUpdate	createWithPrefix (const std::string &prefix, const std::string &name, std::unique_ptr< Special > extra, const std::string &modelNum="", bool active=true)
	Creates a new instrument with the given name and optional model number and active state.
InstrumentUpdate	remove (const std::string &id) override
	Removes the instrument with the given ID.
InstrumentUpdate	clear () override
	Clears the entire instrument list and resets the main instrument selection.
InstrumentUpdate	prepareUpdate (unsigned long long timestamp) override
	Prepares a subsequent tracking update by setting the device timestamp, resetting the matrix to identity, and setting the quality and status flag to zero for all instruments.
InstrumentUpdate	update (const std::string &id, mat4 matrix, double quality, unsigned long long timestamp=0, int statusFlags=0x0) override
	Updates the instrument with the specified ID to the new tracking matrix and quality, and an optional timestamp and status flag.
int	size () const override
	Returns the number of instruments.
std::optional< TrackingInstrument >	find (const std::string &id) const override
	Finds a specific tracking instrument by ID.
InstrumentUpdate	modify (const std::string &id, const std::function< void(const std::string &, TrackingInstrument &)> &fun) override
	Accessor method to apply a function to a specific instrument with the given ID.
InstrumentUpdate	modifyAll (const std::function< void(const std::string &, TrackingInstrument &)> &fun) override
	Accessor method to apply a function to all instruments.

Additional accessor and modifier methods on extra data structure Special
SPECIAL_USED void	modify (const std::string &id, const std::function< void(const std::string &, Special &)> &fun)
	Accesses the extra data structure Special associated with a TrackingInstrument.
SPECIAL_USED InstrumentUpdate	modify (const std::string &id, const std::function< void(const std::string &, TrackingInstrument &, Special &)> &fun)
	Accesses both the TrackingInstrument and its associated Special data structure simultaneously.
SPECIAL_USED void	modifyAll (const std::function< void(const std::string &, Special &)> &fun)
	Iterates over all instruments to access the extra data structure Special.
SPECIAL_USED InstrumentUpdate	modifyAll (const std::function< void(const std::string &, TrackingInstrument &, Special &)> &fun)
	Iterates over all instruments to access TrackingInstruments and their associated Special data structures simultaneously.
SPECIAL_USED void	setSpecial (const std::string &id, std::unique_ptr< Special > special)
	Sets the extra data structure Special associated with a TrackingInstrument.
SPECIAL_CLONABLE std::unique_ptr< Special >	getSpecial (const std::string &id) const
	Returns the Special object associated with the given TrackingInstrument id.
SPECIAL_CLONABLE std::map< std::string, std::unique_ptr< Special > >	getAllSpecials () const
	Returns a map with instrument ID keys and the Special objects associated with them.
SPECIAL_CLONABLE std::vector< std::pair< TrackingInstrument, std::unique_ptr< Special > > >	getInstrumentsWithSpecial () const
	Returns a vector with pairs of TrackingInstrument and the associated Special object.

Member Function Documentation

◆ instruments()

template<class Special>

std::vector< TrackingInstrument > ImFusion::ThreadSafeInstruments< Special >::instruments ( ) const

overridevirtual

Returns a vector of tracking instruments.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ mainInstrument()

template<class Special>

std::optional< TrackingInstrument > ImFusion::ThreadSafeInstruments< Special >::mainInstrument ( ) const

overridevirtual

Returns the main tracking instrument, if any.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ setMain()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::setMain ( unsigned int index )

overridevirtual

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

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ setMainById()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::setMainById ( const std::string & id )

overridevirtual

Sets the main tracking instrument by tracking ID.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ mainIndex()

template<class Special>

unsigned int ImFusion::ThreadSafeInstruments< Special >::mainIndex ( ) const

overridevirtual

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

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ mainId()

template<class Special>

const std::string & ImFusion::ThreadSafeInstruments< Special >::mainId ( ) const

overridevirtual

Returns the ID of the main tracking instrument.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ mainName()

template<class Special>

std::string ImFusion::ThreadSafeInstruments< Special >::mainName ( ) const

overridevirtual

Returns the name of the main tracking instrument.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ setActive()

template<class Special>

void ImFusion::ThreadSafeInstruments< Special >::setActive	(	const std::string &	id,
		bool	active )

overridevirtual

Sets the active flag of an instrument.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ isActive()

template<class Special>

bool ImFusion::ThreadSafeInstruments< Special >::isActive ( const std::string & id ) const

overridevirtual

Returns whether a tracking instrument is active.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ create()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::create	(	TrackerID	trackerID,
		bool	active = true )

overridevirtual

Creates a new instrument with the given TrackerID and active state.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ createWithPrefix() [1/2]

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::createWithPrefix	(	const std::string &	prefix,
		const std::string &	name,
		const std::string &	modelNum = "",
		bool	active = true )

overridevirtual

Creates a new instrument with the given name and optional model number and active state.

Auto-assigns a new unique ID based on a tracking stream-specific prefix. It assigns an ID of the form "prefix-<number>" with the smallest available positive number.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ createWithPrefix() [2/2]

template<class Special>

SPECIAL_USED_DEFINITION InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::createWithPrefix	(	const std::string &	prefix,
		const std::string &	name,
		std::unique_ptr< Special >	extra,
		const std::string &	modelNum = "",
		bool	active = true )

Creates a new instrument with the given name and optional model number and active state.

Auto-assigns a new unique ID based on a tracking stream-specific prefix. It assigns an ID of the form "prefix-<number>" with the smallest available positive number. Additionally, an object of the Special class is assigned to the created instrument.

◆ remove()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::remove ( const std::string & id )

overridevirtual

Removes the instrument with the given ID.

Updates the main instrument to the first instrument in the list if the removed instrument was the main instrument.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ clear()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::clear ( )

overridevirtual

Clears the entire instrument list and resets the main instrument selection.

The main instrument ID is reset to "".

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ prepareUpdate()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::prepareUpdate ( unsigned long long timestamp )

overridevirtual

Prepares a subsequent tracking update by setting the device timestamp, resetting the matrix to identity, and setting the quality and status flag to zero for all instruments.

This is a convenience method intended to be used when the stream's tracking update iterates over received tracking data, where we cannot be sure that all tracking instruments are included.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ update()

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::update	(	const std::string &	id,
		mat4	matrix,
		double	quality,
		unsigned long long	timestamp = 0,
		int	statusFlags = 0x0 )

overridevirtual

Updates the instrument with the specified ID to the new tracking matrix and quality, and an optional timestamp and status flag.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ size()

template<class Special>

int ImFusion::ThreadSafeInstruments< Special >::size ( ) const

overridevirtual

Returns the number of instruments.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ find()

template<class Special>

std::optional< TrackingInstrument > ImFusion::ThreadSafeInstruments< Special >::find ( const std::string & id ) const

overridevirtual

Finds a specific tracking instrument by ID.

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ modify() [1/3]

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::modify	(	const std::string &	id,
		const std::function< void(const std::string &, TrackingInstrument &)> &	fun )

overridevirtual

Accessor method to apply a function to a specific instrument with the given ID.

Calls fun(id, ti) on the TrackingInstrument ti that has the identifier id. This method allows modification of the members of the TrackingInstrument beyond the provided default methods (e.g., update, prepareUpdate, setActive, etc.).

Example usage in a tracking stream class:

std::string newName = "New tracking instrument name";
auto renameTrackingInstrument = [&newName] (const std::string& id , TrackingInstrument& ti) {
    ti.id.setName(newName);
};
 
m_instruments->modify("tracker-id", renameTrackingInstrument);

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ modifyAll() [1/3]

template<class Special>

InstrumentUpdate ImFusion::ThreadSafeInstruments< Special >::modifyAll ( const std::function< void(const std::string &, TrackingInstrument &)> & fun )

overridevirtual

Accessor method to apply a function to all instruments.

Calls fun(id, ti) on all the TrackingInstruments ti with identifier id.

Example usage in a tracking stream class:

auto setCustomStatus = [] (const std::string& id , TrackingInstrument& ti) {
    ti.statusFlags = 1 << 3;
};
 
m_instruments->modifyAll(setCustomStatus);

Implements ImFusion::ThreadSafeInstrumentsBase.

◆ modify() [2/3]

template<class Special>

SPECIAL_USED_DEFINITION void ImFusion::ThreadSafeInstruments< Special >::modify	(	const std::string &	id,
		const std::function< void(const std::string &, Special &)> &	fun )

Accesses the extra data structure Special associated with a TrackingInstrument.

Calls fun(id, extra) with the Special data structure extra associated with the TrackingInstrument identified by id.