Cloud 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 reco 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 Recognition is handled by the Engine via the Cloud Image Target Observer. Configure the Cloud 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 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.

123456789101112131415161718192021
Copy
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.

Starting and stopping a Cloud Recognition search

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.

12
Copy
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 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.

12345678910111213141516171819202122232425262728293031323334
Copy
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 Recognition search results, please see Counting Cloud 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:

123456789101112131415
Copy
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

Can this page be better?
Share your feedback via our issue tracker