Cloud Recognition

The Vuforia Cloud Recognition Service is an enterprise class Image Recognition solution that enables developers to host and manage Image Targets online. Cloud Recognition is available with the Development, Cloud, Pro, and Enterprise licenses. Usage is determined by the total number of image recognitions, or “recos”, per month that your app performs and is counted when a target is matched.

The result of a Image Recognition query is determine by the API used to execute the query.
 
Query APIResult
TargetFinder API (SDK)Image Target Trackable
Cloud Recognition Web APIList of target IDs
Note: The query result returned to the Cloud Recognition Web API is a list of matching targets by ID, ranked by recognition confidence. This API does not receive a trackable target result.

Use Cases

The Vuforia Cloud Recognition service is ideally suited for apps that use many targets, or targets that need to be updated frequently. Customers using the service can leverage the following benefits:
  • Scale: More than one million targets can be used in an app.
  • Flexibility: Integrate with existing content management systems.
  • Time to Market: Deliver real-time, dynamically changing content and accelerate time to market
For
  • Publications – Catalogs, Magazines, Newspapers
  • Retailers – Product visualization, in-store traffic generation, etc.
  • Advertisers – Multi-branded content, coupons, promotions, etc.
  • Product Recognition – Wine labels/bottles, Cereal boxes, etc.
See:
Comparison of Device and Cloud Databases

Working with Cloud Recognition

Cloud Recognitions supports two workflows for uploading and managing targets in Cloud Databases, using either the Vuforia Target Manager or the Vuforia Web Services API.

SDK Workflow

Cloud Recognition apps utilize the same APIs for handling Image Targets that apps using Device Databases do. The significant difference between Cloud and Device Database apps is that Cloud Recognition apps utilize the TargetFinder class which manages the execution of queries and handling of query results. 

See:
How To Create a Simple Cloud Recognition App in Unity
How To Implement Cloud Recognition using the Native SDKs
How To Add Your Own Cloud Database to the Cloud Reco Sample

 


Cloud Recognition Service

How many cloud targets can I host with a Cloud Plan?

Development licenses support up to 1000 recos per month on up to 1000 images
Cloud licenses support up to 10,000 recos per month on up to 100,000 images
Pro licenses support more than 10,000 recos per month on more than 100,000 images

How many VWS API calls do I receive with my Cloud or Pro plan?

10,000 VWS API calls per day are allowed.

If you expect to exceed this allowance, or if you receive an error message indicating that you have exceeded the allowed number of calls, please contact us.

Can my app use multiple cloud databases?

No. You may only associate one cloud database per app

 


How To Determine Cloud Usage

The License Manager provides a report on your app's user activity that indicates how many Cloud recos have been executed as a proportion the app's monthly reco limit.

The app usage bar is color coded to indicate when you are approaching the maximum monthly usage for the plan associated with your app. If the bar is orange or red, your usage is approaching the maximum and you should determine whether you will need to move to a plan that supports greater usage for the remainder of the month.
 

 


Cloud Recognition Error Codes

The follow error codes may be returned by the Target Finder and Cloud Recognition service. This table lists the codes alongside their meanings.
 
CodeMeaning
INIT_ERROR_NO_NETWORK_CONNECTIONNo network connection
INIT_ERROR_SERVICE_NOT_AVAILABLEService is not available
UPDATE_ERROR_AUTHORIZATION_FAILEDCredentials are wrong or outdated
UPDATE_ERROR_PROJECT_SUSPENDEDThe specified project was suspended
UPDATE_ERROR_NO_NETWORK_CONNECTIONDevice has no network connection
UPDATE_ERROR_SERVICE_NOT_AVAILABLEServer not found, down or overloaded
UPDATE_ERROR_BAD_FRAME_QUALITYLow frame quality has been continuously observed
UPDATE_ERROR_UPDATE_SDKSDK Version outdated
UPDATE_ERROR_TIMESTAMP_OUT_OF_RANGEClient/Server clocks too far away
UPDATE_ERROR_REQUEST_TIMEOUTNo response to network request after timeout
You can also find the definitions of these codes in the header file for the TargetFinder class.
From Vuforia::TargetFinder
 
 
    /// Status codes returned by the init() function
    enum
    {
        INIT_DEFAULT = 0,                        ///< Initialization has not started
        INIT_RUNNING = 1,                        ///< Initialization is running
        INIT_SUCCESS = 2,                        ///< Initialization completed successfully
        INIT_ERROR_NO_NETWORK_CONNECTION = -1,   ///< No network connection
        INIT_ERROR_SERVICE_NOT_AVAILABLE = -2    ///< Service is not available
    };
 
    /// Status codes returned by the updateSearchResults() function
    enum
    {
        UPDATE_NO_MATCH = 0,                     ///< No matches since the last update
        UPDATE_NO_REQUEST = 1,                   ///< No recognition request since the last update
        UPDATE_RESULTS_AVAILABLE = 2,            ///< New search results have been found
        UPDATE_ERROR_AUTHORIZATION_FAILED = -1,  ///< Credentials are wrong or outdated
        UPDATE_ERROR_PROJECT_SUSPENDED = -2,     ///< The specified project was suspended.
        UPDATE_ERROR_NO_NETWORK_CONNECTION = -3, ///< Device has no network connection
        UPDATE_ERROR_SERVICE_NOT_AVAILABLE = -4, ///< Server not found, down or overloaded.
        UPDATE_ERROR_BAD_FRAME_QUALITY = -5,     ///< Low frame quality has been continuously observed
        UPDATE_ERROR_UPDATE_SDK = -6,            ///< SDK Version outdated.
        UPDATE_ERROR_TIMESTAMP_OUT_OF_RANGE = -7,///< Client/Server clocks too far away.
        UPDATE_ERROR_REQUEST_TIMEOUT = -8        ///< No response to network request after timeout.
    };
 

 


How To Use Cloud Recognition Metadata

The Vuforia Cloud Recognition Service enables new types of applications in retail and publishing. An application that uses Cloud Recognition can query a Cloud Database with camera images, and then can handle the matching results returned from the cloud to perform local detection and tracking.

Every Cloud Image Target can optionally have an associated metadata. A target’s metadata is user-defined data that can be associated with a target and is filled with custom information, up to the allowed limits (up to 1 MB per target).

You can use the metadata to store additional content. This additional content relates to a specific target that your application can process using some custom logic.

Data stored in metadata

For example, your application may use the metadata to store the following items:

  • A simple text message for your app to display on the screen of the device when the target is detected. For example: “Hello, I am your cloud image target XYZ, you have detected me :-)!”
  • A simple URL string, for instance http://my_server/my_3d_models/my_model_01.obj. The URL should point to a custom network location where some other content is stored, such as a 3D model, a video, an image, or any other custom data. For each different image target, your application would use such a URL to download the specific content.
  • Some custom text that your application can process and use to perform specific actions. Your metadata could contain some text to represent an object in JSON format, for example:
    {
    "Name": "John",
    "Age" : "35",
    "Address": "10, Vuforia Avenue"
    }
  • A full 3D model, not just the URL pointing to a model on a server, but the model itself. For example, the metadata itself could embed an .OBJ 3D model, provided that the size does not exceed the limits allowed, of up to 1 MB.

Common use metadata examples

Video URLs

  • For each target, you store metadata containing the URL of a video associated to the specific target
  • Your application reads the metadata of a target, when such target is recognized by Vuforia
  • Your application uses the URL in the metadata to connect to a server, to download, and to play the video (for example, http://my_server/my_videos/my_video_001.mp4)

3D models

  • For each target, you can store metadata containing the URL of a 3D model to associate with the specific target
  • Your application reads the metadata of a target, when such target is recognized by Vuforia
  • Your application uses the URL in the metadata  to connect to a server and to download the 3D model (for example, http://my_server/my_3d_models/my_model_001.obj)
  • Your application renders the 3D model on the detected target

Unity Asset Bundles (Unity only)

  • For each target, you can store metadata containing the URL of a Unity Asset Bundle to associate with the specific target (for instance, representing a 3D model or other Unity asset)
  • Your application reads the metadata of a target, when such target is recognized by Vuforia
  • Your application uses the URL in the metadata to connect to a server, to download the Asset Bundle, and to integrate it into the Unity scene at run time (for example, http://my_server/my_asset_bundles/my_asset_001.unity3d)
  • See also: How To Use AssetBundles to Package Augmentations

How to create and store metadata for a Cloud target

  • Metadata can be uploaded with an image target at the time you create the target in your Cloud Database.
  • You can update the metadata of an existing target, at a later time.
  • In either case, you can use the online Target Manager
  • OR you can proceed programmatically using the VWS API, as explained here: Vuforia Web Services

How to get the metadata of a Cloud target when it is recognized

The Vuforia SDK offers a dedicated API to retrieve the metadata of a target in your mobile application. When a cloud target is detected (recognized), a new TargetSearchResult is reported to the application, and the metadata is obtained using one of the following methods:

  • Vuforia Native SDK - C++ API: TargetSearchResult::getMetaData() - const char*
  • Vuforia Native SDK - Java API: TargetSearchResult.getMetaData() - String
  • Vuforia Unity Extension - C# API: TargetSearchResult.Metadata - string

Using C++ API

So, using the C++ API, you can get the metadata with the QCAR_onUpdate() method, as show in the following code example:
virtual void QCAR_OnUpdate(QCAR::State & state)
{
    QCAR::TrackerManager &tm = QCAR::TrackerManager::getInstance();
    QCAR::ImageTracker *tracker = tm.getTracker(QCAR::ImageTracker::getClassType());
    QCAR::TargetFinder *finder = tracker->getTargetFinder();
    // Check if there are new results available:
    if (finder->updateSearchResults() == QCAR::TargetFinder::UPDATE_RESULTS_AVAILABLE)
    {
        // Iterate through the new results:
        if (finder->getResultCount() > 0)
        {
            const QCAR::TargetSearchResult* result = finder->getResult(0);
            const char *metadata = result->getMetaData();
        }
    }
}

Using Java API

Similarly, using the Java API, you can get the metadata with the onQCARUpdate() method, as shown in the following example:
public void onQCARUpdate(State state)
{
    // Get the image tracker:
    TrackerManager tm = TrackerManager.getInstance();
    ImageTracker tracker = (ImageTracker) tm.getTracker(ImageTracker.getClassType());
    TargetFinder finder = tracker.getTargetFinder();
    // Check if there are new results available:
    final int statusCode = finder.updateSearchResults();
    if (statusCode == TargetFinder.UPDATE_RESULTS_AVAILABLE)
    {
        if (finder.getResultCount() > 0)
        {
            TargetSearchResult result = finder.getResult(0);
            String metadata = result.getMetaData();
            ...
        }
    }
    ...
}

In Unity

In Unity, the TargetSearchResult is reported in the OnNewSearchResult callback method of the ICloudRecoEventHandler interface. So the metadata can be retrieved as shown in the following example:
public void OnNewSearchResult(TargetFinder.TargetSearchResult targetSearchResult)
{
    string metadata = targetSearchResult.MetaData;
    Debug.Log("We got a target metadata: " + metadata);
}

Sample code

  • For a reference sample code in native Android, see the code in the Books.java in the Books-2-x-y sample project.
  • For a reference sample code in native iOS, see the code in the BooksEAGLView.mm file in the Books-2-x-y sample project.
  • For a reference sample code in Unity, see the CloudRecoEventHandler.cs script (attached to theCloudRecognition prefab) in the Books sample. In particular, the OnNewSearchResult method shows how to get a targetSearchResult object, from which you can then get the metadata, as shown in the example code.