C++ Java Unity
C++ Reference
TargetFinder Class Referenceabstract

Detailed Description

Efficiently recognizes particular targets in the camera feed.

A TargetFinder identifies Image Targets in the camera feed. It can perform detection and recognition, but is not able to track targets, nor provide any kind of pose.

A TargetFinder allows your application to support the detection and tracking of a dramatically increased number of targets, by acting as a sort of filter mechanism on the tracking environment. Based on the results of a TargetFinder search, your application can selectively enable tracking for individual targets only when those targets are actually present - avoiding expensive and redundant tracking attempts for targets which are not present.

A TargetFinder should be considered to operate asynchronously, offering discrete results outside of the typical State lifecycle:

  • TargetFinder results are not stored in the State.
  • TargetFinder results may take several frames (or longer) to compute (notably when using cloud-based image recognition) and may be delivered asynchronously.
  • TargetFinder results are delivered on-demand and must be explicitly requested.

Obtain a TargetFinder instance from the ObjectTracker by calling ObjectTracker::getTargetFinder().

Inheritance diagram for TargetFinder:

Public Types

enum  {
 Status codes returned by getInitState() More...
enum  {
 Status codes returned from updateQueryResults() More...
enum  {
 Filter modes for updateQueryResults() More...

Public Member Functions

virtual bool startInit (const char *userAuth, const char *secretAuth)=0
 Start initialization of the cloud-based recognition system. More...
virtual int getInitState () const =0
 Get the current state of the initialization process. More...
virtual void waitUntilInitFinished ()=0
 Block the current thread until initialization is completed. More...
virtual bool deinit ()=0
 Deinitializes the cloud-based recognition system. More...
virtual bool startRecognition ()=0
 Start visual recognition. More...
virtual bool stop ()=0
 Stop visual recognition. More...
virtual bool isRequesting () const =0
 Get whether the TargetFinder is currently awaiting the results of a query. More...
virtual TargetFinderQueryResult updateQueryResults (int filter=FILTER_CURRENTLY_TRACKED)=0
 Updates and returns visual search results. More...
virtual ObjectTargetenableTracking (const TargetSearchResult &result)=0
 Enable tracking for a particular search result. More...
virtual void clearTrackables ()=0
 Disable tracking on all previously-enabled search results. More...
virtual List< ObjectTargetgetObjectTargets ()=0
 Returns a list of ObjectTargets currently enabled for tracking. More...

Member Enumeration Documentation

anonymous enum

Status codes returned by getInitState()


Initialization has not started.


Initialization is running.


Initialization completed successfully.


No network connection.


Service is not available.

anonymous enum

Status codes returned from updateQueryResults()


No matches since the last update.


No recognition request since the last update.


New search results have been found.


Credentials are wrong or outdated.


The specified project was suspended.


Device has no network connection.


Server not found, down or overloaded.


Low frame quality has been continuously observed.


SDK Version outdated.


Client/Server clocks too far away.


No response to network request after timeout.

anonymous enum

Filter modes for updateQueryResults()


No results are filtered, all successful queries are returned.


Filter out targets that are currently being tracked (Most Common)

Member Function Documentation

virtual bool startInit ( const char *  userAuth,
const char *  secretAuth 
pure virtual

Start initialization of the cloud-based recognition system.

Initialize this TargetFinder to recognize Image Targets using cloud-based recognition. Initialization requires a network connection and runs asynchronously. Use getInitState() to query the progress and final result of initialization.

After initialization completes, call startRecognition() to begin continuous recognition of Image Targets in the camera feed. Calls to updateQueryResults() will return search results representing known Image Targets that the cloud-based image recognition system has detected in the camera feed (if any).

userAuthUser name for logging in to the visual search server
secretAuthUser secret for logging in to the visual search server
virtual int getInitState ( ) const
pure virtual

Get the current state of the initialization process.

one of the INIT_* values from the enum above.
virtual void waitUntilInitFinished ( )
pure virtual

Block the current thread until initialization is completed.

virtual bool deinit ( )
pure virtual

Deinitializes the cloud-based recognition system.

virtual bool startRecognition ( )
pure virtual

Start visual recognition.

Starts continuous recognition of Targets in the camera feed.

Use updateQueryResults() to retrieve search matches.

virtual bool stop ( )
pure virtual

Stop visual recognition.

virtual bool isRequesting ( ) const
pure virtual

Get whether the TargetFinder is currently awaiting the results of a query.

virtual TargetFinderQueryResult updateQueryResults ( int  filter = FILTER_CURRENTLY_TRACKED)
pure virtual

Updates and returns visual search results.

Get an updated list of visual search results. Results represent Image Targets. You may want to cast the results to CloudRecoSearchResult for more details.

The visual search process runs asynchronously, and only when recognition is running (i.e. after you call startRecognition()). A call to updateQueryResults() returns the latest available results, which may be several frames out of date with respect to the current camera frame. They should therefore be treated as an indication as to which targets are present in the scene in general, with the understanding that those same targets may not necessarily be visible in the current camera frame.

To enable full tracking on one the targets, pass the matching TargetSearchResult instance to enableTracking().

TargetSearchResult instances are owned by the TargetFinder. Each call to updateQueryResults() invalidates all previously obtained results.

By default, targets that are already enabled for tracking are not included in the returned list, unless the target or its associated metadata has been updated since they were last enabled for tracking. If you want to override this and include all results, pass FILTER_NONE for the filter argument.
filterFilter to apply to the search results. If you pass FILTER_CURRENTLY_TRACKED, only search results that are not currently being tracked (i.e. targets that have NOT been enabled for tracking via enableTracking()) will be returned. Pass FILTER_NONE to return all results regardless of current tracking state.
a TargetFinderQueryResult representing the latest-available visual search results.
virtual ObjectTarget* enableTracking ( const TargetSearchResult result)
pure virtual

Enable tracking for a particular search result.

Creates an ObjectTarget for local detection and tracking of a detected target. The pose of this target will be included in State::getTrackableResults().

If this TargetFinder is performing cloud-based image recognition (i.e. if it was initialized via startInit(const char*, const char*), then the returned object will be an instance of ImageTarget.

For performance and/or memory management reasons, calling this function may result in the disabling and destruction of a previously created ObjectTarget. For this reason you should only hold on to the returned ObjectTarget pointer at most until the next call to enableTracking().
resultThe search result that you want to start tracking.
A newly created ObjectTarget representing the requested search result, or NULL if the target could not be enabled for tracking (check application logs for failure details).
virtual void clearTrackables ( )
pure virtual

Disable tracking on all previously-enabled search results.

Disable and destroy all of the ObjectTargets created via enableTracking().

virtual List<ObjectTarget> getObjectTargets ( )
pure virtual

Returns a list of ObjectTargets currently enabled for tracking.