Vuforia Engine Lifecycle in Unity

Vuforia Engine provides an API that extends the Unity Editor with Vuforia Engine objects and scripting classes. Most authoring tasks for creating AR experiences with Vuforia Engine can be done with the Vuforia Engine GameObjects directly in the Unity Editor. The scripting API offers extended options and control over your AR application

Introduction

In this guide, we provide a brief introduction and examples on managing the Vuforia Engine lifecycle with VuforiaApplication, configure Vuforia with VuforiaBehaviour, creating Observers, retrieving information on tracked targets, and other common management tasks.

Managing the Vuforia Engine Lifecycle

In Unity, the Vuforia Engine life cycle is managed automatically by default:

  • Vuforia Engine is initialized automatically once when the application is started.
  • It is deinitialized when the application is quit.
  • Loading a Unity scene with any Vuforia Engine game objects, such as target observers or an ARCamera, will start Vuforia Engine, and unloading the scene will stop it again.

This functionality is coupled to the VuforiaBehaviour component on the main camera. If a scene that uses Vuforia game objects does not contain a VuforiaBehaviour, one will automatically be created and attached to the main camera object, starting Vuforia and taking care of camera control and video background rendering.

There are several ways to override this default behavior:

  • Vuforia Engine initialization can be delayed by checking the Delayed Initialization checkbox in the Vuforia Configuration

    This for instance makes sense if there is a special AR mode in your application that is not used by every end user. Other use cases include initializing Vuforia Engine with a custom driver or a specific Fusion Provider.

    In those cases, Vuforia Engine can be initialized manually from scripting API before loading the first scene containing Vuforia Engine functionality: VuforiaApplication.Instance.Initialize();.

  • When loading a scene containing Vuforia Engine game objects, such as Targets or an ARCamera, Vuforia Engine can be prevented from starting by disabling the VuforiaBehaviour component on the ARCamera.

    It can be enabled at a later time from a script to start Vuforia Engine in this scene.

In some cases, it is necessary to execute code at a certain point during the Vuforia Engine life cycle. Some examples include:

  • Checking for initialization errors after Vuforia Engine attempted to initialize.
  • Creating an Observer at runtime to track a target or accessing the properties of an Observer after Vuforia Engine has started.
  • Setting a specific camera focus mode after Vuforia Engine has started.
  • Deleting app-level resources after Vuforia Engine stopped or deinitialized completely.

The VuforiaApplication instance provides callbacks for all these life cycle events. They can be subscribed to from application level scripts:

Vuforia Engine has initialized

Subscribe to VuforiaApplication.Instance.OnVuforiaInitialized to run code that requires Vuforia Engine to be initialized. Events such as setting the file driver, or the fusion provider should be done before Vuforia Engine is started and with Delayed Initialization enabled.

void Awake()
{
    FusionProviderOption fusionProviderOption = FusionProviderOption.PREFER_PLATFORM_FUSION_PROVIDER;
    /* Set VuforiaFusionProvider */
    VuforiaApplication.Instance.Initialize(fusionProviderOption);
    VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}

void OnVuforiaInitialized(VuforiaInitError error)
{
    if (error != VuforiaInitError.NONE)
    {
        // Handle initialization errors
    }
}

Vuforia Engine has started

Subscribe to OnVuforiaStarted to run events after Vuforia was started:

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

void OnVuforiaStarted()
{
    // turn device flashlight on
    VuforiaBehaviour.Instance.CameraDevice.SetFlash(true);
}

Vuforia Engine has stopped

Subscribe to OnVuforiaStopped to run events after Vuforia was stopped:

void Start()
{
     VuforiaApplication.Instance.OnVuforiaStopped += OnVuforiaStopped;
}

Vuforia Engine has paused or resumed

Pause Vuforia Engine and the tracking activities by setting VuforiaBehaviour to disabled and resume to your AR tracking experience by setting it to enabled. OnVuforiaDeinitialized should not be used as this will destroy stored resources including registered targets.

VuforiaBehaviour.Instance.enabled

Subscribe to OnVuforiaPaused to run events after Vuforia paused or resumed, e.g. in order to set a specific focus mode again after the application as paused:

void Start()
{
     VuforiaApplication.Instance.OnVuforiaPaused += OnVuforiaPaused;
}

void OnVuforiaPaused(bool paused)
{
    if (!paused)
        // set focus to infinity:
        VuforiaBehaviour.Instance.CameraDevice.SetFocusMode(FocusMode.FOCUS_MODE_INFINITY);
}

Vuforia Engine has deinitialized

Subscribe to OnVuforiaDeinitialized with a subscriber method to terminate the VuforiaBehaviour and all tracking operations.

void Start()
{
    VuforiaApplication.Instance.OnVuforiaDeinitialized += OnVuforiaDeinitialized;
}
void OnVuforiaDeinitialized()
{
    // Destroy objects, change Vuforia configuration settings
}

VuforiaConfiguration

Other Vuforia Configuration options can be found in the VuforiaConfiguration inspector that is available from the ARCamera GameObject or from Window -> Vuforia Configuration in the Unity (CMD+Shift+V pr Ctrl+Shift+V).

  • Click Add License to navigate to your Licenses tab and generate a new license key for your project.

Editor menu:

Some settings, like the App license key, is used when initializing Vuforia Engine. Set also settings for the camera, error and warning log levels, and if your app should track multiple images simultaneously (Model Targets can only be tracked one at a time, same applies to Area Targets).

Also, in the configuration settings, the ARCore requirement setting under Android Settings, is a build-time setting that is applied when building Unity apps.
Finally, some settings, like tracking the device pose, is evaluated before Vuforia Engine is started in a Unity scene.

These settings can also be accessed at runtime, e.g. to set the license key from some key store or disable device tracking for some scenes. Add the license key before loading your first scene and before starting Vuforia i.e., in the Awake() method:

void Awake() 
{ 
    VuforiaConfiguration.Instance.Vuforia.LicenseKey = "myLicenseKey"; 
    VuforiaConfiguration.Instance.DeviceTracker.AutoInitAndStartTracker = false; 
}

Vuforia Engine State in Unity

In Unity, Vuforia Engine will automatically update the currently observed state for all targets and observers every frame. Changes to the Unity scene, like the positions of targets will be applied automatically. There are therefore no specific API calls necessary to manually retrieve updates.

For some operations, it is important to run your application logic after Vuforia Engine has updated the state in a frame. This includes:

  • Calculating the distance between two targets based on their latest positions.
  • Access Illumination data from VuforiaBehaviour.Instance.World.IlluminationData
  • Access the most up-to-date camera image from VuforiaBehaviour.Instance.CameraDevice.GetCameraImage(…)

>Use OnStateUpdated for these purposes. See also the AmbientLightManager.cs in the Vuforia Core Samples for handling the illumination values or the reference API.

void Start()
{
    VuforiaBehaviour.Instance.World.OnStateUpdated += OnStateUpdated;
}
void OnStateUpdated()
{
    /* Get IlluminationData when ARKit is used by Vuforia Fusion */
    float intensity = VuforiaBehaviour.Instance.World.IlluminationData.AmbientIntensity.Value;
    float temperature = VuforiaBehaviour.Instance.World.IlluminationData.AmbientColorTemperature.Value;

    /* Get IlluminationData when ARCore is used by Vuforia Fusion */
    Vector4 colorCorrection = VuforiaBehaviour.Instance.World.IlluminationData.ColorCorrection.Value;
    float intensityCorrection = VuforiaBehaviour.Instance.World.IlluminationData.IntensityCorrection.Value;
}

Create an Observer

As an alternative to setting up a target using the Vuforia game objects in the Unity Editor, a target can also be loaded and observed at runtime with the ObserverFactory class. Its member functions each take a varying number of overloads to create a target. For example, creating an Image Target from a device database would look like this:

var mImageTarget = VuforiaBehaviour.Instance.ObserverFactory.CreateImageTarget(
            "Vuforia/VuforiaMars_Images.xml ",
            "Astronaut");

Activate and deactivate a target with true and false:

mImageTarget.enabled = true;

Retrieve the Target Status and Status Info

By default, augmentations are rendered when a target is tracked. The DefaultObserverEventHandler is a Vuforia provided component that offers an interface for adding actions to On Target Found and On Target Lost.

You can even implement your own custom event handler script and change these events to implement your custom behavior.

Enable pose smoothing on large pose jumps between EXTENDED_TRACKED and TRACKED on a Vuforia target. Pose jumps are sometimes seen in situations where an extended tracked target has drifted and then snaps back to the target when it’s detected again. Enabling the setting smooths the transition between the positions of the target when its status changes. The VuforiaBehaviour‘s World Center Mode must be set to DEVICE.

Target Status

It is also possible to directly register for an Observer-specific status changed event and evaluate the current status directly:

ObserverBehaviour modelTargetBehaviour;
void Start()
{
    modelTargetBehaviour.OnTargetStatusChanged += OnTargetStatusChanged;
}
void OnTargetStatusChanged(ObserverBehaviour observerbehavour, TargetStatus status)
{
    if (status.Status == Status.TRACKED && status.StatusInfo == StatusInfo.NORMAL)
    {
        // ...
    }
}

Device Tracking Management

The Device Pose Observer is used for tracking the movement of the device in the environment and provide Extended Tracking for observed targets. Enable the device pose tracking in Vuforia Configuration or control it at runtime with enabled and the Reset() function:

VuforiaBehaviour.Instance.DevicePoseBehaviour.enabled = true;

The Device Pose Observer provides additional status information that varies depending on the type of device platform (ARKit, ARCore) and device type (Handheld, Eyewear). For details, see Target Poses and Status Info.

VuforiaBehaviour.Instance.DevicePoseBehaviour.OnTargetStatusChanged += OnTargetStatusChanged;

Attach Content to a Target

With Vuforia Engine started, and a target loaded and observed, content can be added at runtime as a child to the target GameObject. The script below demonstrates a simple method for adding a prefab GameObject to the parent target at runtime on target found by inheriting from the DefaultObserverEventHandler script.

  1. In a Unity project, create a new script named MyPrefabInstantiator.
  2. Copy the code below and save the file.
  3. In the scene, add a Vuforia target GameObject from the menu GameObject -> Vuforia Engine -> <Vuforia Target>.
  4. Remove the existing DefaultObserverEventHandler component from the GameObject
  5. Add MyPrefabInstantiator to the target GameObject.
  6. Create a prefab or use an existing one and submit it to the myModelPrefab field.
  7. Test your target on your device or in Play Mode.
using UnityEngine;
using Vuforia;
 
public class MyPrefabInstantiator : DefaultObserverEventHandler
{
    ImageTargetBehaviour mImageTarget;
    public GameObject myModelPrefab;
 
    protected override void OnTrackingFound()
    {
        InstantiateContent();
    }
 
    void InstantiateContent()
    {
        if (myModelPrefab != null)
        {
            GameObject myModelTrf = Instantiate(myModelPrefab);
            myModelTrf.transform.parent = mImageTarget.transform;
            myModelTrf.transform.localPosition = new Vector3(0f, 0f, 0f);
            myModelTrf.transform.localRotation = Quaternion.identity;
            myModelTrf.transform.localScale = new Vector3(0.1f, 0.1f, 0.1f);
            myModelTrf.transform.gameObject.SetActive(true);
        }
   }
}

Error Handling

Use the VuforiaInitError to ensure Vuforia Engine has initialized properly as demonstrated in the DefaultInitializationHandler script:

void Start()
{
    VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}
void OnVuforiaInitialized(VuforiaInitError error)
{
    if(error != VuforiaInitError.NONE)
    {
        // Error handling code
    }
}

See Troubleshooting your App for debugging methods.

Learn More

Vuforia Engine API

Getting Started with Unity Engine in Unity

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