Area Targets in Unity¶

This guide will take you through the process of importing and working with Area Targets in Unity. By importing the Unity package that is created from the Area Target Generator (ATG) or using the Vuforia Creator app (VCA) you will be able to design and develop environment-based AR experiences for Unity's supported platforms.

Get started with Area Targets using the Vuforia Core Samples that includes an Area Target scene. Or, create your own Area Target following the guides on the Best Practices for Preparing and Scanning an Environment and How to create an Area Target and import it into Unity for authoring.

NOTE: Area Targets are only supported on ARKit or ARCore enabled devices and selected eyewear devices. VISLAM enabled devices are not supported. See Supported Versions.

Import your Area Target in an Empty Unity Project¶

If you have your own Area Target ready as a *.unitypackage you can begin with the following steps.

Start by creating and opening a new project in Unity. For supported Unity Editor versions, see Supported Versions.
Set up your project with Vuforia Engine by adding the Vuforia Engine Unity package. See here on how to do this.
Remove the default Main Camera from the scene. Replace it with an ARCamera by going to the GameObject menu -> Vuforia Engine -> AR Camera.
Obtain a license key for your project. Please refer to Licenses on how to obtain a license key.
1. Place your license key in the associated field in Vuforia Configuration (CmD+Shift+V for macOS, Ctrl+Shift+V for Windows)
If it isn't already, enable the Track Device Pose at the same time. Enabling Device Tracking is required for tracking Area Targets.

Scene set-up with Area Targets¶
Create an AreaTarget GameObject from GameObject->Vuforia Engine->Area Target->Area Target.
Import the Area Target database .unitypackage that was generated from the Area Target Generator by selecting Assets -> Import Package -> Custom Package (or double click the .unitypackage).
Select the imported Database and Area Target from the AreaTarget GameObject via the dropdown menu.

Warning

NOTE: Coexisting Area Targets from before and after Vuforia Engine SDK 10.4 are not supported in a Unity project.

Configure the Area Target¶

The Area Target database contains additional assets of the scanned area including textures, materials, and a prefab model or mesh. After importing the package, from the Project window, locate these files in the folder Assets/Editor/Vuforia/<dataset name> folder.

The preview mesh of a scanned area is automatically added to the AreaTarget GameObject whilst a prefab model from Matterport™ generated Area Targets is available and can be placed in the scene if you wish to modify certain captured elements of the area.

NOTE: Changing the size of the AreaTarget GameObject is not supported, it is always in 'meters'. It guarantees that your scanned environment retains its original scale throughout the entire development workflow. If you need to use a different scene scale in your project, please review the Virtual Scene Scale Factor in Unity article.

Location Prior¶

Large Area Targets require an external location prior to locate the user within the space of the Area Target. Trying to use a large Area Target without the Requires External Position enabled will throw an error. All Area Targets can be set with a Requires External Position in their Area Target Behaviour component in the Inspector.

Smaller Area Targets can still be created without setting an external position, but if you wish to activate the Area Targets, they must have the same setting as the first and currently activated Area Target: Requires External Position as enabled or disabled. For more details about the Location Prior, please see Location Prior for Large Area Targets.

NOTE: If a scene contains multiple Area Targets with inconsistent Requires External Position, a message will appear to apply the setting to all Area Targets. Dissimilar settings from the first activated Area Target prevents the Area Targets from being activated.

Clipping Height¶

Use the Clipping Height (%) slider to hide ceiling and details that obstruct your view of the Area Target preview mesh in your Unity Scene. The complete Area Target will still track as a whole.

Runtime Mesh¶

You can enable runtime occlusion in your real environment by adding a runtime mesh representation.

By setting the Runtime Occlusion Mesh, other GameObjects will be visually obstructed by the environment's walls and objects. If you wish to test your Area Target while being able to see all your content, you can keep the box unticked.
Set the Runtime Mesh Collider to add a mesh collider to the runtime mesh representation of your Area Target. it will allow you to ray-cast against the mesh representation of your environment or include the environment into collision and physics simulations

The button Add Runtime Mesh creates a new GameObject as child of the Area Target. It has the Runtime Mesh Rendering Behaviour component which instantiates the Area Target's mesh at runtime and keeps the geometry accessible for updates and changes. With the mesh available directly from the Area Target, you don't need to include the model mesh when building application.

It requires a Display Material for rendering the mesh of the tracked Area Target. The component can be used on other GameObjects, but then you need to supply a Source Behaviour as well.

Use the CreateRuntimeMeshRenderingBehaviour to create the mesh representation of an Area Target at runtime. This is especially useful in cases where the Area Target was also created at runtime, for example with the Area Target Capture API.

NOTE: There aren't any prefab models for point clouds as it is the case with Area Targets generated from meshes. But the runtime mesh is supported.

Point Cloud Area Targets only support colliders for the closest surroundings during runtime.

NOTE: When you create a prefab out of an Area Target GameObject, and wish to build to a device and load it at runtime, you will need to add the Area Target's _occlusion.3dt file to the Assets/StreamingAssets/Vuforia/ folder. Otherwise, the Occlusion or Collider feature will not work.

Add content¶

Add your augmentation content as a child to the AreaTarget GameObject. Add for example a 3D Cube or your own content to the scene and position it in relation to the preview model, matching the scale of the environment.

Development ideas¶

Here are some suggestions for additional configurations of the Area Target GameObject:

Use the freely available assets from the Vuforia Core Samples to quickly add responsive UI and billboards to your own Area Target.
Add other Vuforia targets to your project such as a Model Target to improve tracking around an object that is central for the user experience in the AR scene.
Add a custom occlusion shader on the preview model to selectively hide content behind walls or doors.
Use raycasting with a mesh collider to let users place augmented content at runtime.
Add a navigation mesh to your scene to guide users around. See NavMesh in Unity on how to do this.
Combine multiple Area Targets in a single scene for seamless transition and tracking into new areas.
Use the AreaTargetBehaviour to provide access to Area Target functionality at runtime. In most cases, you call methods using the AreaTargetBehaviour class with BoundingBox() for the target's bounding box in 3D scene units, and Size() to get the dimensions of the physical target.

Working with Cloud Area Targets in Unity¶

Access a Cloud Area Target at runtime to asynchronously download it and start tracking without requiring the whole dataset.

This section shows the steps to create a Unity scene with a simple Cloud Area Target experience.

Right-click in the Hierarchy and select Vuforia Engine -> Area Target -> Cloud Area Target.
Fill out the Cloud Area Target Behaviour fields to associate it with your Cloud Area Target:
TargetID – as returned in the ‘id’ field after successful upload from Cloud Area Targets Web API.
Client ID and Client Secret – as returned in the clientId and clientSecret fields after your successful credentials generation. See Authentication.

Note

A preview of the Area Target will not yet show in the scene.

To visualize the Cloud Area Target during authoring, download the Cloud Area Target’s Unity Package using the web API described in Cloud Area Targets Web API and import the authoring assets into the scene.

The Unity package does not include the tracking dataset files. These are retrieved via the Cloud Area Target Behaviour at the application's runtime.

Cloud Area Target Behaviour

Cloud Area Target Behaviour runtime creation¶

Use the ObserverFactory to create Cloud Area Targets at runtime using CreateCloudAreaTarget() or CreateCloudAreaTargetAsync(). The creation methods lets you set whether the Cloud Area Target Behaviour should include a collider, use occlusion for authored content, and if the target should be initialized with an external prior.

var target = VuforiaBehaviour.Instance.ObserverFactory.CreateCloudAreaTarget(string
userAuth, string secretAuth, string targetID);

Use an external prior in combination with Cloud Area Targets to stream data in portions rather than downloading the whole dataset before initialization. If you don’t explicitly set this option and provide a prior, Area Targets that don’t require a prior will be fully downloaded at the beginning of your session and cached locally for further use on the device.

Include Mesh Observer¶

The following creates an Area Target Behaviour with a Mesh Observer for occlusion rendering:

var target = VuforiaBehaviour.Instance.ObserverFactory.CreateCloudAreaTarget(
    userAuth,
    secretAuth,
    targetID,
    hasOcclusion = true);

Note that the occlusion mesh is always streamed, updates to the mesh are made as data is retrieved from the cloud. Other than that, at runtime, the Area Target will behave like a locally loaded Area Target.

Runtime Status of Cloud Area Targets¶

The status and status info of Cloud Area Targets are the same as local Area Targets, but with one additional status info:

MISSING_DATA

Occurs when asynchronous loading of the tracking data failed. Tracking quality might therefore decrease or the tracking might be lost entirely.

Example Implementation¶

The below script creates and initializes the Cloud Area Target Behavior. An empty Unity project was created from scratch, an ARCamera was added, and the script was attached to a single GameObject. Add OAuth2 credentials with your own (userAuth, secretAuth) and a targetId to the below script.

CloutAT.cs
using System.Collections.Generic;
using UnityEngine;
using Vuforia;

public class CloudAT : MonoBehaviour
{
    public string ClientId = "";
    public string ClientSecret = "";
    public string TargetId = "";

    void Awake()
    {
        VuforiaApplication.Instance.OnVuforiaStarted += OnVuforiaStarted;
    }

    void OnDestroy()
    {
        VuforiaApplication.Instance.OnVuforiaStarted -= OnVuforiaStarted;
    }

    void OnVuforiaStarted()
    {
        // Create and Area Target Behaviour for a specific Cloud Area Target, including occlusion support.
        // Adjust with correct OAuth2 credentials and Cloud Area Target ID
        var target = VuforiaBehaviour.Instance.ObserverFactory.CreateCloudAreaTarget(
        ClientId, //userAuth
        ClientSecret, //userSecret
        TargetId, //Cloud Area Target ID
        true, //hasOcclusion
        false, //hasCollision
        false); //requiresExternalPosition

        Debug.Log("Cloud AT Created");

        // Register an event handler to log changes of the Cloud Area Target's tracking status.
        // If status switches to EXTENDED_TRACKED, then the target has been detected
        // and we start tracking it.
        target.OnTargetStatusChanged += OnStatusChanged;
        }

    void OnStatusChanged(ObserverBehaviour cloudAtBehviour, TargetStatus targetStatus)
    {
        Debug.LogFormat("Cloud AT Status Changed {0} {1}", targetStatus.Status, targetStatus.StatusInfo);
    }
}

Cloud Area Target cache management¶

Cloud Area Target Observers cache downloaded data persistently inside the app’s storage. That means, data once downloaded will remain in local storage, and reduce the network expenses. It further allows for a snappier experience when the Cloud Area Target is used subsequently.

Naturally, if several large Cloud Area Targets are used by the app, a significant amount of data will accumulate on the local storage. Thus, we support clearing all cached data from the local storage.

Clear cache with the following:

VuforiaBehaviour.Instance.ClearAreaTargetObserverCloudCache();

NOTE: The above method is only successful in case no Area Target Behaviours exist at the time of the call. ClearAreaTargetObserverCloudCache() logs an error if it fails.

The following function can be called from e.g., a button-press to clear the cache. It checks for Cloud Area Targets, disables them, and clears the cache.

public void ClearCache()
{
    var cloudAreaTargets = FindObjectsOfType<CloudAreaTargetBehaviour>();
    foreach (var cloudAreaTargetBehaviour in cloudAreaTargets)
    {
        Debug.LogFormat("Deactivating CloudAreaTargetObserver: {0}", cloudAreaTargetBehaviour.name);

        cloudAreaTargetBehaviour.enabled = false;
    }

    // This method must be called before Vuforia has started and without any CloudAreaTargets
    // in the scene. Cloud Area Targets cache all downloaded data in the app’s storage. Said
    // caching mechanism allows for shorter startup times on subsequent executions of the app,
    // and makes sure to provide an as-smooth-as-possible experience. Naturally, over time quite
    // some data may accumulate, especially in case multiple large Cloud Area Targets have been
    // employed on the device. Thus, to free up app storage, it is possible to remove all cached
    // Cloud Area Target data from storage via the following call: 
    // VuforiaBehaviourExtensionMethods.ClearAreaTargetObserverCloudCache(VuforiaBehaviour.Instance);
    VuforiaBehaviour.Instance.ClearAreaTargetObserverCloudCache();
    Debug.Log("Cloud AT Cache cleared");
}

Test your Area Targets in Unity's Play Mode¶

Test the Area Target in the Unity Editor with Play Mode. It is recommended to use a recorded sequence with the Record and Playback functionality.

Select the Play Mode Recording or Simulator mode in Vuforia Configuration under Play Mode and press Play.

Note

Using the Simulator Play Mode for Cloud Area Targets requires you to download the authoring assets of the Cloud Area Target and add them to the scene.

You can read more about different Unity Play Modes here.

Build your Unity Project¶

When ready, you can build your Unity Project to your ARCore or ARKit enabled device or to a Microsoft HoloLens 2. A Vuforia project is built in the same way as other Unity apps for Android, iOS, and UWP platforms.