/*=============================================================================== Copyright (c) 2015-2018 PTC Inc. All Rights Reserved. Copyright (c) 2010-2014 Qualcomm Connected Experiences, Inc. All Rights Reserved. Vuforia is a trademark of PTC Inc., registered in the United States and other countries. \file DataSet.h \brief Header file for DataSet class. ===============================================================================*/ #ifndef _VUFORIA_DATASET_H_ #define _VUFORIA_DATASET_H_ // Include files #include #include #include #include namespace Vuforia { // Forward declarations class Trackable; class MultiTarget; class TrackableSource; /// 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(). * * \anchor DataSetActive * 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: * -# Call ObjectTracker::deactivateDataSet() to deactivate the %DataSet. * -# Make the desired changes to the %DataSet and/or any of its Trackables. * -# 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(). */ class VUFORIA_API DataSet : private NonCopyable { public: /// 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. * * \param path Path and filename of the .xml file. Path handling is controlled * by storageType. * \param storageType Controls 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. */ static bool exists(const char* path, STORAGE_TYPE 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. * * \param path Path and filename of the .xml file. Path handling is * controlled by storageType. * \param storageType Controls how the path to the .xml file should be handled. * \returns true if the data was loaded successfully, otherwise false. */ virtual bool load(const char* path, STORAGE_TYPE storageType) = 0; /// 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 int getNumTrackables() const = 0; /// 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 Trackable* getTrackable(int idx) = 0; /// 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 List getTrackables() = 0; /// 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. * * \param source The 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 Trackable* createTrackable(const TrackableSource* source) = 0; /// 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. * * \param name A name for the new MultiTarget * \returns A new MultiTarget, or NULL if this DataSet is currently active. */ virtual MultiTarget* createMultiTarget(const char* name) = 0; /// 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 destroy(Trackable* trackable) = 0; /// 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 hasReachedTrackableLimit() = 0; /// 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. */ virtual bool isActive() const = 0; virtual ~DataSet() {} }; } // namespace Vuforia #endif //_VUFORIA_DATASET_H_