This article introduces you to the steps for creating a basic Vuforia Engine Cloud Recognition app in Unity. Use Cloud Recognition in your application to recognize and track millions of Image Targets.
To learn more about the benefits, licensing, and use cases of Cloud Recognition, please refer to the Cloud Recognition article.
Accessing Sample Code
A great way to start is to see the Cloud Recognition feature in action. It is available in Unity as a part of the Vuforia Core Samples. The sample scene demonstrates how the OnNewSearchResult
method retrieves a CloudRecoSearchResult
from which the metadata is available in the CloudRecoEventHandler.cs script.
Unity Setup
The following steps explain how to create a cloud recognition app in Unity. The app reacts to a cloud target detection event, retrieves the metadata associated with the target, and displays the metadata text.
Prerequisites
- A Supported Unity version with the latest Vuforia SDK Package. See Supported Versions and Getting Started with Vuforia Engine in Unity for a setup guide.
- Your preferred code editor (Visual Studio, Mono Develop, Xcode, etc.).
- A Vuforia Engine Developer Account.
Instructions
- Create a new project in Unity.
- Create a license key for your project.
- Add the license key to your Vuforia Engine app.
- In the Hierarchy window, delete the Main Camera object.
- In the GameObject menu, select and add Vuforia Engine -> AR Camera.
- In the GameObject menu, select Vuforia Engine -> Cloud Recognition -> Cloud Recognition. A new Cloud Recognition object is created.
- In the Inspector window of your Cloud Recognition GameObject, enter your cloud database client keys in the client keys in the Access Key and Secret Key fields. For information about creating a cloud database, refer to the Cloud Databases article.
- Create a C# script named SimpleCloudRecoEventHandler.cs
- Attach the SimpleCloudRecoEventHandler script to the Cloud Recognition GameObject.
- Implement the SimpleCloudRecoEventHandler script by referencing the following code samples:
- Implement the
RegisterEventHandlers
interface and register it with the CloudRecoBehaviour:
123456789101112131415161718192021222324252627282930Copyusing UnityEngine;
using Vuforia;
public class SimpleCloudRecoEventHandler : MonoBehaviour
{
CloudRecoBehaviour mCloudRecoBehaviour;
bool mIsScanning = false;
string mTargetMetadata = "";
public ImageTargetBehaviour ImageTargetTemplate;
// Register cloud reco callbacks
void Awake()
{
mCloudRecoBehaviour = GetComponent<CloudRecoBehaviour>();
mCloudRecoBehaviour.RegisterOnInitializedEventHandler(OnInitialized);
mCloudRecoBehaviour.RegisterOnInitErrorEventHandler(OnInitError);
mCloudRecoBehaviour.RegisterOnUpdateErrorEventHandler(OnUpdateError);
mCloudRecoBehaviour.RegisterOnStateChangedEventHandler(OnStateChanged);
mCloudRecoBehaviour.RegisterOnNewSearchResultEventHandler(OnNewSearchResult);
}
//Unregister cloud reco callbacks when the handler is destroyed
void OnDestroy()
{
mCloudRecoBehaviour.UnregisterOnInitializedEventHandler(OnInitialized);
mCloudRecoBehaviour.UnregisterOnInitErrorEventHandler(OnInitError);
mCloudRecoBehaviour.UnregisterOnUpdateErrorEventHandler(OnUpdateError);
mCloudRecoBehaviour.UnregisterOnStateChangedEventHandler(OnStateChanged);
mCloudRecoBehaviour.UnregisterOnNewSearchResultEventHandler(OnNewSearchResult);
}
- Implementing the
OnInitialized()
,OnInitError()
andOnUpdateError()
methods are optional. These methods provide useful log data in case an error occurs:
123456789101112131415Copy public void OnInitialized(CloudRecoBehaviour cloudRecoBehaviour)
{
Debug.Log("Cloud Reco initialized");
}
public void OnInitError(CloudRecoBehaviour.InitError initError)
{
Debug.Log("Cloud Reco init error " + initError.ToString());
}
public void OnUpdateError(CloudRecoBehaviour.QueryError updateError)
{
Debug.Log("Cloud Reco update error " + updateError.ToString());
}
- Implement the
OnStateChanged()
method of the interface to determine whether Vuforia Engine is currently performing a Cloud Reco scan:
123456789Copy public void OnStateChanged(bool scanning)
{
mIsScanning = scanning;
if (scanning)
{
// Clear all known targets
}
}
- Implement the
OnNewSearchResult()
method. This code only processes a cloud recognition event without displaying a 3D augmentation for the target. See Add a Cloud Image Target below.
123456789Copy // Here we handle a cloud target recognition event
public void OnNewSearchResult(CloudRecoBehaviour.CloudRecoSearchResult cloudRecoSearchResult )
{
// Store the target metadata
mTargetMetadata = cloudRecoSearchResult.MetaData;
// Stop the scanning by disabling the behaviour
mCloudRecoBehaviour.enabled = false;
}
- Implement the
OnGUI()
method to display the current scanning state and the metadata of the last cloud target detected:
12345678910111213141516Copy void OnGUI() {
// Display current 'scanning' status
GUI.Box (new Rect(100,100,200,50), mIsScanning ? "Scanning" : "Not scanning");
// Display metadata of latest detected cloud-target
GUI.Box (new Rect(100,200,200,50), "Metadata: " + mTargetMetadata);
// If not scanning, show button
// so that user can restart cloud scanning
if (!mIsScanning) {
if (GUI.Button(new Rect(100,300,200,50), "Restart Scanning")) {
// Reset Behaviour
mCloudRecoBehaviour.enabled = true;
mTargetMetadata="";
}
}
}
- Save the current scene.
Add a Cloud Image Target
Perform the following steps to add a 3D augmentation object on top of your Cloud Image Target upon detection:
- In the GameObject menu, select Vuforia Engine -> Cloud Image -> Cloud Image Target to add a new Image Target object.
- Right-click ImageTarget and select 3D Object -> Cube to create a simple cube object.
- Center and scale the cube object appropriately so that it fits nicely on top of the Image Target plane in the scene.
- Optionally, add directional lighting to the scene so that any augmentation appears shaded.
- Add the SimpleCloudRecoEventHandler.cs script as a component to the Cloud Image Target GameObject.
- Modify the SimpleCloudRecoEventHandler.cs script by adding the following code to the
OnNewSearchResult()
method. This code programmatically instantiates an Image Target that corresponds to the one detected by the Cloud Recognition engine:
123456Copy// Build augmentation based on target
if (ImageTargetTemplate)
{
/* Enable the new result with the same ImageTargetBehaviour: */
mCloudRecoBehaviour.EnableObservers(cloudRecoSearchResult, ImageTargetTemplate.gameObject);
}
- Select the CloudRecognition object in the scene.
The Inspector should display the Image Target Template field in the Simple Cloud Reco Event Handler component. - In the Hierarchy window, drag the ImageTarget into the Image Target Template field in the Inspector window.
- Save the current scene.
- Build and run your project or test it with Vuforia Play Mode.