C++ Java Unity
Java Reference
DataSet Class Reference

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().

Public Member Functions

boolean equals (Object obj)
 
boolean load (String path, int storageType)
 Load dataset data from storage media. More...
 
int getNumTrackables ()
 Get the total number of Trackable objects using this data set. More...
 
Trackable getTrackable (int idx)
 Get one of the Trackable objects that uses this data set. More...
 
TrackableList getTrackables ()
 Returns a list of trackable objects in this data set. More...
 
Trackable createTrackable (TrackableSource source)
 Create a Trackable from the given TrackableSource and register it with this DataSet. More...
 
MultiTarget createMultiTarget (String name)
 Create a new MultiTarget and register it with this DataSet. More...
 
boolean destroy (Trackable trackable)
 Destroy a Trackable. More...
 
boolean hasReachedTrackableLimit ()
 Check if this DataSet's Trackable capacity is reached. More...
 
boolean isActive ()
 Check if this dataset is active. More...
 

Static Public Member Functions

static boolean exists (String path, int storageType)
 Check if a given data set exists on storage media. More...
 

Member Function Documentation

boolean equals ( Object  obj)
static boolean exists ( String  path,
int  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.
boolean load ( String  path,
int  storageType 
)

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.
int getNumTrackables ( )

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.
Trackable getTrackable ( int  idx)

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.
TrackableList getTrackables ( )

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.

Trackable createTrackable ( TrackableSource  source)

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.
MultiTarget createMultiTarget ( String  name)

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.
boolean destroy ( Trackable  trackable)

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).
boolean hasReachedTrackableLimit ( )

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.
boolean isActive ( )

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.