Skip to content

Cloud Image Recognition API Overview

Use a cloud database to detect and track amongst millions of Cloud Image Targets. This article presents the general steps to implement Cloud Image Recognition in native.

A Cloud Image Target is an Image Target stored in the Vuforia Servers. This allows you to store, detect, and track between millions of Image Targets from a single Cloud Database. Upload your Cloud Image Targets using the Target Manager. See also Cloud Targets Web API.

General Setup

Please see the Vuforia Engine Lifecycle for a general introduction to the Vuforia Engine lifecycle. The Engine is required for creating and using Observers.

Create a Cloud Image Target Observer

Cloud Image Recognition is handled by the Engine via the Cloud Image Target Observer. Configure the Cloud Image Recognition with VuCloudImageTargetConfig and detect recognition events with VuCloudImageTargetObservationTargetInfo.

Differently from other tracking API in the SDK, where you get continuous tracking updates via pull mechanisms from the State, Cloud Image Recognition does not necessarily get continuous information; you need to register a handler for getting updates. Do this with the vuCloudImageTargetObserverRegisterHandlers. Once the Observer is created and activated, search results will be reported via the registered callback function VuCloudImageTargetObservationsHandler.

Create Observer from VuCloudImageTargetConfig

To use Cloud Recognition, you first need to initialize the system and set the credentials for your cloud database. The creation process requires an active network connection and runs asynchronously.

The following creates the Cloud Image Target Observer. It is activated by default.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
VuObserver *observer = nullptr;

VuCloudImageTargetConfig cloudImageTargetConfig = vuCloudImageTargetConfigDefault();
cloudImageTargetConfig.userAuth = "<your credentials>";
cloudImageTargetConfig.secretAuth = "<your credentials>";

VuCloudImageTargetCreationError creationError;
if (vuEngineCreateCloudImageTargetObserver(engine, &observer, &cloudImageTargetConfig, &creationError) != VU_SUCCESS)
{
    // handle observer creation errors
    switch (creationError)
    {
    case VU_CLOUD_IMAGE_TARGET_CREATION_ERROR_NO_NETWORK_CONNECTION:
        // handle the "NO NETWORK" error
        break;

        // handle other VU_CLOUD_IMAGE_TARGET_CREATION_ERROR... errors
    }

    return;
}

NOTE: Find your authentication keys in the Cloud Database's details in the Target Manager.

Register handlers for Cloud Image Targets with VuCloudImageTargetObservationsHandler. This observation handler is triggered whenever a new Cloud Image Target is detected. You can then choose to create an Image Target Observer with vuEngineCreateImageTargetObserverFromCloudObservation() to start tracking the image.

1
2
MyClientData clientData; /* placeholder for an app-specific data structure */
vuCloudImageTargetObserverRegisterHandlers(observer, &recoEventHandler, &queryErrorHandler, &clientData);

Handling Search Results

At runtime, you need to handle new Cloud Image Recognition search results and, if desired, create the Image Target Observer for tracking.

Below is a sample code snippet that inspects information about the detected targets via vuCloudImageTargetObservationGetTargetInfo. Target info includes name, unique id, metadata, and tracking rating.

From the observations, the sample then creates an Image Target Observer with vuEngineCreateImageTargetObserverFromCloudObservation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
void VU_API_CALL
recoEventHandler(const VuObservationList *observations, void *clientData)
{
    MyClientData *myClientData = static_cast<MyClientData *>(clientData);

    int32_t numObservations = 0;
    vuObservationListGetSize(observations, &numObservations);

    // iterate through all Cloud Image Target observations received via reco event
    for (int i = 0; i < numObservations; i++)
    {
        VuObservation *observation = nullptr;
        vuObservationListGetElement(observations, i, &observation);

        // read Cloud Image Target information
        VuCloudImageTargetObservationTargetInfo cloudImageTargetInfo;
        vuCloudImageTargetObservationGetTargetInfo(observation, &cloudImageTargetInfo);
        // print("Cloud Image Target '%s' recognized", cloudImageTargetInfo.name);

        // create Image Target observer using Cloud Image Target observation
        VuImageTargetCloudObservationConfig cloudObservationConfig = vuImageTargetCloudObservationConfigDefault();
        cloudObservationConfig.observation = observation;
        cloudObservationConfig.activate = VU_TRUE; // automatically activate if engine is running

        VuObserver *targetObserver = nullptr;
        VuImageTargetCloudObservationCreationError creationError;
        if (vuEngineCreateImageTargetObserverFromCloudObservation(engine, &targetObserver, &cloudObservationConfig,
                                                                  &creationError) != VU_SUCCESS)
        {
            // error handling
            continue;
        }
    }
}

For more information on counting and handling the Cloud Image Recognition search results, please see Counting Cloud Image Recognition Events.

Error Messages

Errors that are detected asynchronously after the Observer is created are reported via the error handler callback. Here is an example of how to write such a handler:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
void VU_API_CALL
queryErrorHandler(VuCloudImageTargetQueryError queryError, void *clientData)
{
    MyClientData *myClientData = static_cast<MyClientData *>(clientData);

    // handle query-related errors
    switch (queryError)
    {
    case VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_AUTHORIZATION_FAILED:
        // handle "authorization failed" errors
        break;

        // handle other VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_... errors
    }
}

The following error codes may be returned by the VuCloudImageTargetQueryError. This table lists the codes alongside their meanings.

Code Meaning
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_NO_NETWORK_CONNECTION No network connection
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_SERVICE_NOT_AVAILABLE Server not found, down, or overloaded
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_AUTHORIZATION_FAILED Credentials are wrong or outdated
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_PROJECT_SUSPENDED The specified project was suspended
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_BAD_FRAME_QUALITY Low frame quality has been continuously observed
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_UPDATE_SDK SDK version outdated
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_TIMESTAMP_OUT_OF_RANGE Client/Server clocks too far apart
VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_REQUEST_TIMEOUT No response to network request after timeout

Learn More

How to Perform an Image Recognition Query

Rendering in Native

Counting Cloud Image Recognition Events