C++ Java Unity
C++ Reference
DataSet Class Referenceabstract

Detailed Description

A container of data for one or more Trackable instances.

A DataSet stores data for one or more ObjectTarget-derived Trackables (for a full list of applicable types, refer to the inheritance tree diagram for ObjectTarget).

Typically, you obtain an empty DataSet instance from ObjectTracker::createDataSet(). Populate the returned DataSet either using load() with data prepared offline (pairs of .xml and .dat files), or using createTrackable() with data provided at runtime (for example from a camera frame). Once populated, activate the DataSet using ObjectTracker::activateDataSet().

It is not possible to modify a DataSet, nor any of the Trackables which rely on it, while the DataSet is active.

To modify an active DataSet (e.g. via calls to load(), createTrackable(), destroy()) or to make changes to a Trackable which uses it, you need to do the following:

  1. Call ObjectTracker::deactivateDataSet() to deactivate the DataSet.
  2. Make the desired changes to the DataSet and/or any of its Trackables.
  3. Call ObjectTracker::activateDataSet() to activate the DataSet, which will resume tracking with the new data.

To destroy the DataSet once it is no longer needed, call ObjectTracker::deactivateDataSet() followed by ObjectTracker::destroyDataSet().

Inheritance diagram for DataSet:
NonCopyable

Public Member Functions

virtual bool load (const char *path, STORAGE_TYPE storageType)=0
 Load dataset data from storage media. More...
 
virtual int getNumTrackables () const =0
 
virtual TrackablegetTrackable (int idx)=0
 Get one of the Trackable objects that uses this data set. (DEPRECATED) More...
 
virtual List< TrackablegetTrackables ()=0
 Returns a list of trackable objects in this data set. More...
 
virtual TrackablecreateTrackable (const TrackableSource *source)=0
 Create a Trackable from the given TrackableSource and register it with this DataSet. More...
 
virtual MultiTargetcreateMultiTarget (const char *name)=0
 Create a new MultiTarget and register it with this DataSet. More...
 
virtual bool destroy (Trackable *trackable)=0
 Destroy a Trackable. More...
 
virtual bool hasReachedTrackableLimit ()=0
 Check if this DataSet's Trackable capacity is reached. More...
 
virtual bool isActive () const =0
 Check if this dataset is active. More...
 
virtual ~DataSet ()
 

Static Public Member Functions

static bool exists (const char *path, STORAGE_TYPE storageType)
 Check if a given data set exists on storage media. More...
 

Constructor & Destructor Documentation

virtual ~DataSet ( )
inlinevirtual

Member Function Documentation

static bool exists ( const char *  path,
STORAGE_TYPE  storageType 
)
static

Check if a given data set exists on storage media.

A data set on permanent storage media consists of an .xml file and a .dat file, sharing the same file name, in the same folder. This function checks for the existence of a data set that matches this pattern, given an .xml file and a path type.

Parameters
pathPath and filename of the .xml file. Path handling is controlled by storageType.
storageTypeControls how path to the .xml file should be handled.
Returns
true if the specified .xml file and a matching .dat file both exist, otherwise false.
virtual bool load ( const char *  path,
STORAGE_TYPE  storageType 
)
pure virtual

Load dataset data from storage media.

During a successful load, one or more Trackable objects will be created from the loaded data. These Trackables can be accessed via getTrackables().

Note that loading of data sets may take a significant amount of time, and it is therefore recommended to do this on a background thread.

This method cannot be used while the DataSet is active.

load() can only be called once on a DataSet. Subsequent calls to load() will remove any existing data and replace it with the newly-loaded data.

Parameters
pathPath and filename of the .xml file. Path handling is controlled by storageType.
storageTypeControls how the path to the .xml file should be handled.
Returns
true if the data was loaded successfully, otherwise false.
virtual int getNumTrackables ( ) const
pure virtual

Get the total number of Trackable objects using this data set. (DEPRECATED) Trackable instances that are themselves part of other Trackable instances (e.g. an ImageTarget that is part of a MultiTarget) are not counted here.

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackables() API instead.
virtual Trackable* getTrackable ( int  idx)
pure virtual

Get one of the Trackable objects that uses this data set. (DEPRECATED)

Trackable instances that are themselves a part of other Trackable instances (e.g. an ImageTarget that is part of a MultiTarget) are not returned here. To access such instances, use MultiTarget::getPart() instead.

Deprecated:
This API has been deprecated. It will be removed in an upcoming Vuforia release. Use the getTrackables() API instead.
virtual List<Trackable> getTrackables ( )
pure virtual

Returns a list of trackable objects in this data set.

Trackables that are part of other trackables (e.g. an ImageTarget that is part of a MultiTarget) are not delivered by this method. Such trackables can be accesses via the trackable they are part of. E.g. use MultiTarget::getParts() to access the respective ImageTargets.

virtual Trackable* createTrackable ( const TrackableSource source)
pure virtual

Create a Trackable from the given TrackableSource and register it with this DataSet.

This method can be used to create a new Trackable based on source data acquired at runtime, such as a camera frame (see ImageTargetBuilder for more information.)

The returned Trackable will also be included in future calls getTrackables() (unless it is made part of MultiTarget), until either it is destroyed by a call to Destroy(), or the DataSet itself is destroyed via ObjectTracker::destroyDataSet().

This method cannot be used while the DataSet is active.

Parameters
sourceThe TrackableSource to use when creating the new Trackable.
Returns
A new Trackable based on the given TrackableSource, or NULL if this DataSet is currently active.
virtual MultiTarget* createMultiTarget ( const char *  name)
pure virtual

Create a new MultiTarget and register it with this DataSet.

The returned MultiTarget is owned by this DataSet. It will be included in future calls to getNumTrackables() and getTrackable(), until either it is destroyed by a call to Destroy(), or the DataSet itself is destroyed via ObjectTracker::destroyDataSet().

This method cannot be used while the DataSet is active.

Parameters
nameA name for the new MultiTarget
Returns
A new MultiTarget, or NULL if this DataSet is currently active.
virtual bool destroy ( Trackable trackable)
pure virtual

Destroy a Trackable.

This method cannot be used while the DataSet is active.

Returns
true on success, or false on failure (check application logs for failure details).
virtual bool hasReachedTrackableLimit ( )
pure virtual

Check if this DataSet's Trackable capacity is reached.

Each DataSet has a limited number for Trackable instances that it can hold. Use this method to check if this DataSet's capacity has been reached.

For example, if you are creating ImageTargets based on camera frames captured at runtime, you can check this method before calling createTrackable(). If it returns true, you might want to destroy the oldest ImageTarget first, or ask the user what to do.

Returns
true if the number of Trackables in this DataSet is at maximum capacity, otherwise false.
virtual bool isActive ( ) const
pure virtual

Check if this dataset is active.

A DataSet is only usable by a Tracker when it is active, but an active DataSet cannot be modified.

To activate a DataSet, call ObjectTracker::activateDataSet(). To deactivate a DataSet, call ObjectTracker::deactivateDataSet().

Returns
true if this DataSet is currently active.