How To Migrate Native Projects to Vuforia Engine 7.2

Introduction

This document highlights significant changes made to Vuforia Engine 7.2 that will impact native developers migrating projects from Vuforia Engine 6.5 through 7.1. Unity developers looking to upgrade to 7.2 should refer to the How to Migrate a Unity Project document.

The World Origin

With all previous versions of the Vuforia Engine, the center of the world (origin) would be defined by the Camera. Starting with Vuforia Engine 7.2, the world has it's own origin independent of the camera and ,in most cases' independent of any target. Furthermore, we are also updating the coordinate systems throughout the Vuforia Engine for consistency. These updates have some implication to developers looking to migrate to Vuforia 7.2.

New Coordinate System

  • The World - The world coordinate system uses a right-handed coordinate system (similar to OpenGL) with the Y axis being "Up".
  • The Camera - The camera coordinate system is changing to also use the same right-handed coordinate system. The camera pose is reported relative to the world-origin using the world's coordinate system.
  • The Objects - Image Targets, Cylinder Targets, Multi Targets, Object Targets, Model Targets, User Defined Targets, and VuMark all report their poses relative to the world-origin using the world's coordinate system.
Vuforia Image

Coordinate Systems in Vuforia Engine 7.1

Vuforia Image

Coordinate Systems in Vuforia Engine 7.2

DeviceTracker

The Device Tracker is a feature that allows developers to access pose information about the device. The Device Tracker supports both Rotational (introduced in Vuforia Engine 5.5) and Positional (introduced in Vuforia 6.5) modes.

Starting Vuforia 7.0, the Vuforia Fusion feature started to leverage platform capabilities. In Vuforia 7.0 six-degree-of-freedom device tracking in combination with GroundPlane was introduced on calibrated devices and ARKit-based iOS devices. In Vuforia 7.2, for the Positional Device Tracker can now be driven by ARKit, ARCore or Vuforia Engine's VIO technology.

For more information on using the Positional Device Tracker, please refer to Using Device Tracker document.

Extended Tracking

One of the benefits we gain from the increased support for Device Tracking is that we now can use the device pose for a better quality extended tracking. Extended Tracking is the concept that a target's pose information will be available even when the object is not in the field of view of the camera or cannot directly be tracked for other reasons. When the Device Tracker is turned on using Positional mode, all targets behave as they are Extended Tracked targets. In other words, these changes also mean that the Extended Tracking functionality is now a global setting and it applies to all of the active targets.

Due to this, the previous APIs for Extended Tracking are being deprecated. The APIs remain in the Vuforia Engine but will be removed in the near future. It is NOT recommended to run the deprecated Extended Tracking APIs alongside Device Tracking as it may have severe performance implications for your application.

Developers migrating applications which use Image Targets, Multi-Targets, Cylinder Targets, Object Targets, User-Defined Targets, or VuMarks, and are looking for equivalent Extended Tracking functionality as per 7.2, should use the FUSION_PROVIDER_OPTIMIZE_IMAGE_TARGETS_AND_VUMARKS parameter on Vuforia::setAllowedFusionProviders. This must be done before any trackers are initialized, but can happen after Vuforia Engine initialization, as long as the FUSION_PROVIDER_PLATFORM_SENSOR_FUSION bitwise value is not modified.

  • In cases where the parameter flag does not modify the FUSION_PROVIDER_PLATFORM_SENSOR_FUSION bitwise value, the setAllowedFusionProvider can be set after Vuforia Engine initializes but before any Trackers are initialized. 
  • In cases where the parameter flag does modify FUSION_PROVIDER_PLATFORM_SENSOR_FUSION, the setAllowedFusionProvider must be modified before Vuforia initializes.

When the Positional Device Tracker is enabled and the target is visible in the camera's field-of-view, then the target will report back as TRACKED. Once the target is out of the camera's field-of-view, the target will report back as EXTENDED_TRACKED.

The notion of Persistent Extended Tracking has also been removed. When Vuforia is leveraging ARKit or ARCore, any maps are managed by the respective platform. If the device does not support ARKit or ARCore, then any maps used are managed by the Vuforia Engine internally. The default behaviour is persistent by default when the active Fusion Provider reports FUSION_PROVIDER_VUFORIA_VISION_ONLY or FUSION_PROVIDER_PLATFORM_SENSOR_FUSION. There is no persistent behaviour when the active Fusion Provider reports FUSION_PROVIDER_VUFORIA_SENSOR_FUSION.

It is important to note that due to these changes along with the broadening of Vuforia Fusion, extended tracking may behave differently than it did as of Vuforia 7.1 and earlier. Please refer to the Vuforia Fusion section below for more informaiton. 

Vuforia Fusion

Also part of Vuforia Engine 7.2, we are updating the Device Tracker to leverage Vuforia Fusion. Vuforia Fusion refers to the internal techniques used by the Vuforia Engine to take advantage of the best platform enablers (such as ARCore and ARKit) while still providing developers with the broadest reach of devices.

Vuforia Fusion works by choosing the best technology for Device Tracking. Please refer to the following list for default priority:

Vuforia Fusion Default Priority:

  1. Platform Enablers (ARKit/ARCore)
  2. Vuforia VIO
  3. Vuforia SLAM
Due to addition of support for platform enablers, it is important that AR content, targets, and physical objects all have their coordinate scale in meters. Objects that do not have their scale set appropriately may not track well.
 
For more information about Vuforia Fusion, please refer to the Vuforia Fusion documentation.

ARCore

Vuforia Engine 7.2 includes support for ARCore. To add support to ARCore, please refer to Using ARCore with Vuforia document.

Front Facing Camera

Front-facing camera support has been deprecated in Vuforia 7.2

Vuforia Engine Initialization

Vuforia Engine 7.2 has made some changes to the initialization process that may impact the flow of your application. The default initialization behavior of Vuforia Engine 7.2 is to download the latest device profile in order to deliver the best experience on the device.  Depending on the speed of the user's internet, this could add several seconds to application load. This only occurs the very first time the user launches the app and will not impact application loading in future launches of the app.

It is strongly recommended to allow the Vuforia Engine to fetch the latest device profile. Developers looking to disable this behavior should set the following hint before initializing Vuforia: Vuforia::setHint(Vuforia::HINT_ASYNC_FETCH_OF_LATEST_CALIBRATION, 0);

Building in Xcode

Vuforia Engine 7.2 introduced a new way of linking Vuforia Engine library files in iOS. Apps should use the dynamically-linked Vuforia.framework instead of the traditional static library (libVuforia.a) & headers.

The framework is called "Vuforia.framework" which is a directory containing the Vuforia binary (run-time linked Mach-O object) and the corresponding headers.  Once you tell Xcode to use the framework, it will automatically find the library and headers.  Therefore the include path information in a traditional Vuforia project is redundant and should be removed.

In addition to linking, the framework must also be embedded into the application package so that the dynamic library is available at runtime.  The framework has to be codesigned with the same credentials as the app.  Xcode handles that automatically; you will see two separate codesign steps in the build log.

Native Apps

To adapt an existing application that used the static library, you will need to edit your Xcode project.

  • In the project structure pane: 
    • Delete the reference to libVuforia.a
  • In the General tab, “Embedded Binaries” section:
    • Press “+” and navigate to & select Vuforia.framework.  (Note – it should then show up both in this list, and the list of linked frameworks below – you shouldn’t need to add it to both)
  • In the Build Settings tab: 
    • Remove the old header file location from "Header search paths"
    • Remove the old static library location from "Library search paths"
    • Add the directory that contains Vuforia.framework to "Framework search paths"  - this will be “../../build” if your app is in the “samples” directory.
    • Verify that "Runpath search paths" contains the string "@executable_path/Frameworks" (it should have been added automatically when you added the framework to the embedded binaries).   Without this the app will crash very early in startup, before entering main.

Unity Apps

No manual intervention needed for Unity apps; the Unity build process should handle it all automatically.

API Changes to note

New API available starting with Vuforia SDK 7.2:

  • Vuforia::setAllowedFusionProviders(), new API to control Vuforia Fusion providers.
  • Vuforia::getActiveProvider(), new API to determine which Fusion provider is active.
  • PositionalDeviceTracker::reset(), new API to reset PositionalDeviceTracker.

The following functions have been deprecated:

  • Trackable::startExtendedTracking() and Trackable::stopExtendedTracking(), use PositionalDeviceTracker() for Extended Tracking use-case.
  • ObjectTracker::persistentExtendedTracking(), now Extended Tracking assumed persistent as available provided by Vuforia Fusion.
  • ObjectTracker::resetExtendedTracking(), use PositionalDeviceTracker::reset() instead.
  • VideoBackgroundConfiguration mEnabled, deprecated with no furhter behavior impact.
  • Vuforia::TrackableResult::getCoordinateSystem(), deprecated with no furhter behavior impact.
  • CameraDevice::getCameraCalibration(), use State::getCameraCalibration() to access calibration information.
  • Renderer::begin(), use Renderer::begin(state) in combination with StateUpdater::updateState().
  • The COORDINATE_SYSTEM_TYPE parameter is no longer available in the RenderingPrimitive::getProjectionMatrix(), getVideoProjectionMatrix(), getViewPortCentreToEyeAxis() functions.