Cloud Recognition

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

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, Basic + Cloud and Pro 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.

• Cloud Recognition Service
• How to Determine Cloud Usage
• Cloud Recognition Error Codes
• How to Use Cloud Recognition Metadata

The result of an Image Recognition query is determined by the API used to execute the query.

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 Recognition supports two workflows for uploading and managing targets in Cloud Databases, using either the Vuforia Target Manager or the Vuforia Web Services (VWS) 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

Supported Targets

The Target Manager and the VWS API both support planar, 2D Image Targets with Cloud Recognition. Images used for Cloud Recognition must be either 8-bit or 24-bit PNG or JPG formatted files. JPG files must be RGB or greyscale. Images with the alpha (transparent) channel are not accepted. The maximum image file size is 2.25 MB.

  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
      INIT_ERROR_DEVICE_DATABASE_ERROR = -3          ///< Error loading the device database
    };
  
  /// Status codes found on the status property of the TargetFinderQueryResults
  /// instance returned by updateQueryResults() 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.
  };

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 2 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 Engine
• 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 Engine
• 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 Engine
• 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 later
• 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

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

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

For details, please refer to How to Use Cloud Recognition.

Sample code

• For a reference sample code in Unity, see the CloudRecoEventHandler.cs script (attached to theCloudRecognition prefab) in the Books sample. The OnNewSearchResult method shows how to get a targetSearchResult object, from which you can then get the metadata, as shown in the example code

Further Reading

How to Use Cloud Recognition

How to Use Rendering Primitives

Comparison of Device and Cloud Databases

How to Perform an Image Recognition Query