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.
123456789101112131415161718192021CopyVuObserver *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.
12CopyMyClientData 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
.
12345678910111213141516171819202122232425262728293031323334Copyvoid 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:
123456789101112131415Copyvoid 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 |