ImFusion SDK 4.3
ThreadSafeInstruments< Special > Class Template Referencefinalthreadsafe

#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 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< TrackingInstrumentinstruments () const override
 Returns a vector of tracking instruments.
 
std::optional< TrackingInstrumentmainInstrument () 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::stringmainId () 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< TrackingInstrumentfind (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 > instruments ( ) const
overridevirtual

Returns a vector of tracking instruments.

Implements ThreadSafeInstrumentsBase.

◆ mainInstrument()

template<class Special>
std::optional< TrackingInstrument > mainInstrument ( ) const
overridevirtual

Returns the main tracking instrument, if any.

Implements ThreadSafeInstrumentsBase.

◆ setMain()

template<class Special>
InstrumentUpdate setMain ( unsigned int index)
overridevirtual
Deprecated
"Identification by index is deprecated. Use the instrument ID instead"

Implements ThreadSafeInstrumentsBase.

◆ setMainById()

template<class Special>
InstrumentUpdate setMainById ( const std::string & id)
overridevirtual

Sets the main tracking instrument by tracking ID.

Implements ThreadSafeInstrumentsBase.

◆ mainIndex()

template<class Special>
unsigned int mainIndex ( ) const
overridevirtual
Deprecated
"Identification by index is deprecated. Use the instrument ID instead"

Implements ThreadSafeInstrumentsBase.

◆ mainId()

template<class Special>
const std::string & mainId ( ) const
overridevirtual

Returns the ID of the main tracking instrument.

Implements ThreadSafeInstrumentsBase.

◆ mainName()

template<class Special>
std::string mainName ( ) const
overridevirtual

Returns the name of the main tracking instrument.

Implements ThreadSafeInstrumentsBase.

◆ setActive()

template<class Special>
void setActive ( const std::string & id,
bool active )
overridevirtual

Sets the active flag of an instrument.

Implements ThreadSafeInstrumentsBase.

◆ isActive()

template<class Special>
bool isActive ( const std::string & id) const
overridevirtual

Returns whether a tracking instrument is active.

Implements ThreadSafeInstrumentsBase.

◆ create()

template<class Special>
InstrumentUpdate create ( TrackerID trackerID,
bool active = true )
overridevirtual

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

Implements ThreadSafeInstrumentsBase.

◆ createWithPrefix() [1/2]

template<class Special>
InstrumentUpdate 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 ThreadSafeInstrumentsBase.

◆ createWithPrefix() [2/2]

template<class Special>
SPECIAL_USED_DEFINITION 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.

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 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 ThreadSafeInstrumentsBase.

◆ clear()

template<class Special>
InstrumentUpdate clear ( )
overridevirtual

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

The main instrument ID is reset to "".

Implements ThreadSafeInstrumentsBase.

◆ prepareUpdate()

template<class Special>
InstrumentUpdate 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 ThreadSafeInstrumentsBase.

◆ update()

template<class Special>
InstrumentUpdate 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 ThreadSafeInstrumentsBase.

◆ size()

template<class Special>
int size ( ) const
overridevirtual

Returns the number of instruments.

Implements ThreadSafeInstrumentsBase.

◆ find()

template<class Special>
std::optional< TrackingInstrument > find ( const std::string & id) const
overridevirtual

Finds a specific tracking instrument by ID.

Implements ThreadSafeInstrumentsBase.

◆ modify() [1/3]

template<class Special>
InstrumentUpdate 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);
Class for information of a tracking instrument.
Definition TrackingInstrument.h:91

Implements ThreadSafeInstrumentsBase.

◆ modifyAll() [1/3]

template<class Special>
InstrumentUpdate 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 ThreadSafeInstrumentsBase.

◆ modify() [2/3]

template<class Special>
SPECIAL_USED_DEFINITION 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.

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

Enabled only if Special is not the default SpecialUnused class.

◆ modify() [3/3]

template<class Special>
SPECIAL_USED_DEFINITION 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.

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

Enabled only if Special is not the default SpecialUnused class.

◆ modifyAll() [2/3]

template<class Special>
SPECIAL_USED_DEFINITION void modifyAll ( const std::function< void(const std::string &, Special &)> & fun)

Iterates over all instruments to access the extra data structure Special.

Calls fun(id, extra) for all TrackingInstruments identified by id and their associated Special data structures extra.

Enabled only if Special is not the default SpecialUnused class.

◆ modifyAll() [3/3]

template<class Special>
SPECIAL_USED_DEFINITION 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.

Calls fun(id, ti, extra) for all TrackingInstruments ti identified by id and their associated Special data structures extra.

Enabled only if Special is not the default SpecialUnused class.

◆ setSpecial()

template<class Special>
SPECIAL_USED_DEFINITION void setSpecial ( const std::string & id,
std::unique_ptr< Special > special )

Sets the extra data structure Special associated with a TrackingInstrument.

Enabled only if Special is not the default SpecialUnused class.

◆ getSpecial()

template<class Special>
SPECIAL_CLONABLE_DEFINITION std::unique_ptr< Special > getSpecial ( const std::string & id) const

Returns the Special object associated with the given TrackingInstrument id.

Returns nullptr if id is not found. Enabled only if Special implements the Clonable interface.

◆ getAllSpecials()

template<class Special>
SPECIAL_CLONABLE_DEFINITION std::map< std::string, std::unique_ptr< Special > > getAllSpecials ( ) const

Returns a map with instrument ID keys and the Special objects associated with them.

Enabled only if Special implements the Clonable interface.

◆ getInstrumentsWithSpecial()

template<class Special>
SPECIAL_CLONABLE_DEFINITION std::vector< std::pair< TrackingInstrument, std::unique_ptr< Special > > > getInstrumentsWithSpecial ( ) const

Returns a vector with pairs of TrackingInstrument and the associated Special object.

Enabled only if Special implements the Clonable interface.


The documentation for this class was generated from the following file:
Search Tab / S to search, Esc to close