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.
123456789101112131415Copyvoid 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:
12345678910Copyvoid 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:
1234Copyvoid 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.
1Copy
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:
1234567891011Copyvoid 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.
12345678Copyvoid 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:
12345Copyvoid 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.
1234567891011121314Copyvoid 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:
123Copyvar mImageTarget = VuforiaBehaviour.Instance.ObserverFactory.CreateImageTarget(
"Vuforia/VuforiaMars_Images.xml ",
"Astronaut");
Activate and deactivate a target with true and false:
1CopymImageTarget.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:
123456789101112CopyObserverBehaviour 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:
1CopyVuforiaBehaviour.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.
1Copy
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.
- In a Unity project, create a new script named MyPrefabInstantiator.
- Copy the code below and save the file.
- In the scene, add a Vuforia target GameObject from the menu GameObject -> Vuforia Engine -> <Vuforia Target>.
- Remove the existing DefaultObserverEventHandler component from the GameObject
- Add MyPrefabInstantiator to the target GameObject.
- Create a prefab or use an existing one and submit it to the myModelPrefab field.
- Test your target on your device or in Play Mode.
1234567891011121314151617181920212223242526Copyusing 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:
1234567891011Copyvoid Start()
{
VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}
void OnVuforiaInitialized(VuforiaInitError error)
{
if(error != VuforiaInitError.NONE)
{
// Error handling code
}
}
See Troubleshooting your App for debugging methods.