This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
In this article, we present the practice of implementing app behavior that counts successful Cloud Recognition matches. To get the accurate number of recos (recognitions), it is important to first understand the functionality of Cloud Recognition and the API tools at your disposal.
Engine SDK Cloud Reco functionality
When the Cloud Recognition SDK is used, an Image Recognition Query is deployed to find a matching ID within the Cloud database server. If a query result registers a match, it is counted as a reco.
More information can be found on How to Perform an Image Recognition Query.
In detail, during the runtime of your app, while the Cloud Reco service is running and the Device Camera is enabled, each camera frame is analyzed for two properties:
- A "scene change", which determines if what is in the camera's field of view has changed,
- Frame quality, which determines if an incoming camera frame is in-focus, exhibits no blurring and has sufficient lighting for recognition.
If both conditions are met, then the SDK service will trigger a query to the Cloud database server. The server determines if there are elements in that query's camera frame that matches a target in the Cloud database. If there is, then this is triggered as a reco, which in-turn increments the reco count.
NOTE: Unsuccessful queries are not counted against the quota!
Exposing when Cloud Reco Queries are Counted
There are two ways to get the reco count for a cloud database:
- Through the Target Manager on the Vuforia Engine Developer Portal. Cloud Reco counts are displayed with the list of targets in your Cloud Database, providing a discrete count for each target.
- Through the Vuforia Web Services API, you can set up a HTTPS GET to return a list of the target IDs in a cloud database. See How to Get a Target List a Cloud Database for more information and setup. Use the data returned to summate the total recos of your Cloud database.
Cloud Recognition Filter Mode
To get the number of recos in your app you can use the filter mode. Modifying the filter applied to Cloud Recognition search results is intended for diagnostic purposes only, and it is not recommended for use in production apps.
The updateQueryResults() method accepts a filter setting value of either
- FILTER_NONE (disable filtering)
- FILTER_CURRENTLY_TRACKED (enable filtering for targets being tracked).
The latter is the default behavior of the TargetFinder.
Filter Mode values:
/// Filter modes to be passed into updateQueryResults() function
enum
{
FILTER_NONE = 0,///< No results are filtered, all successful queries are returned
FILTER_CURRENTLY_TRACKED = 1 ///< Filter out targets that are currently being tracked (Most Common)
};
By default, Cloud Recognition query results are not returned for targets that are currently being tracked. If the FILTER_NONE argument is used, results will be returned regardless of whether the same target has already been enabled for tracking. You can remove this filter for troubleshooting or to determine if recognition events are unexpectedly occurring on the same target due to user behavior. For example, it could be due to a scene change occurring from excessive camera movement or network delays.
Make sure that you do not re-enable the target for tracking as this will interrupt the tracking process!
Update visual search results with a filter value
/**
* Clears and rebuilds the list of updateQueryResults with results found
* since the last call to updateQueryResults (). Returns the status code
* UPDATE_RESULTS_AVAILABLE if new search results have been found.
* By default, targets that are already enabled for tracking are not included
* in the list of updateQueryResults unless the target or its associated
* meta data has been updated since they were last enabled for tracking.
*/
virtual int updateQueryResults (int filter = FILTER_CURRENTLY_TRACKED) = 0;
Simplified Cloud Reco Filtering Chart
Troubleshooting discrepant Reco Counts
Network Latency
Inherent network latency can introduce race conditions in which more than one Cloud Recognition event would be logged at the portal. The following is one possible scenario of such an occurrence:
- A user points their camera at a target that is present in the Cloud database. Once requirements are met for scene change and frame quality, a query is sent to the Cloud Reco service.
- Before the first query response is received by the client, the user moves the device slightly (with the same target still in the camera’s view), and triggers a second query being sent to the Cloud Reco service due to a “scene change”.
- The initial query is processed by the Cloud Reco service, and the service returns a successful reco result. The client handles this query response before the second response is received.
- The second query response arrives at the client, but the first query has already been processed for this target. Thus, the client discards the second result as a duplicate response.
In the above example, both queries will be counted as successful recos towards the Cloud Database’s quota.
To limit such duplicities, the SDK Cloud Reco service should be stopped after a successful reco response is received by the client (See the section on Continuous Queries). This will help to better control when queries are triggered. A UX element can also be introduced at application level if it is desired to allow the user to manually trigger another query.
To start and stop the Cloud Recognition Search, see How to Use Cloud Recognition in Native
Continuous Queries
Another likely cause of different counts between app and the server may be due to a continuously running TargetFinder. Stop the TargetFinder when TargetSearchResult is reported by the Vuforia API callbacks.
Use TargetFinder.Stop(); once the cloud target has been recognized to prevent further cloud queries on a target that is already being tracked. Calling Stop() will not affect the tracking of a target that is enabled and tracked. That target is also cached locally and moving off the target and coming back to it will work without an additional cloud query as long as ClearTrackables() isn't called when tracking is lost.
NOTE: Our CloudReco sample app for Unity, demonstrates best practices for querying and stopping the TargetFinder
Learn more
Cloud Recognition
How to Use Cloud Recognition in Native
How to Use Cloud Recognition in Unity