Logo of the VisionLib Documentation Pages
› Go to visionlib.com

documentation
AR Foundation Support (Beta)

Level: Advanced

This tutorial explains how to set up VisionLib object tracking when using AR Foundation in a Unity scene. You should already be familiar with setting up VisionLib in a Unity scene without AR Foundation, as described in the UnitySDK Quick Start.

Note: The provided code for using AR Foundation (version 2.x) together with VisionLib was developed for Unity 2019.4 LTS. Using VisionLib together with AR Foundation (version 4.x) in Unity 2020 is possible, but requires some additional configuration.

Note: The ARFoundation support requires a license file containing the AllowInjectingImage feature.

Example Scene

  • Use the Unity Package Manager (Window > Package Manager) to install the VisionLib SDK and the VisionLib SDK - ARFoundation package (from the Extensions folder) that we provide as a tarball.
  • Import the VisionLib.SDK.ARFoundation.Examples-Unity.unitypackage file that is contained in the same download.
  • Copy your license file to StreamingAssets/VisionLib/ reference it in the TrackingConfiguration component of the VLTracking GameObject.
  • The example scene for AR Foundation support can be found in the folder Assets/VisionLib ARFoundation Examples/Scenes/
  • This scene already contains all necessary elements from both ARFoundation and VisionLib, to track the VisionLib paper car. Details on how to setup the tracking for your own models can be found at the bottom of this page.

Using Unity 2020

Importing the VisionLib SDK - ARFoundation package in Unity 2020 will automatically install the AR Foundation version (2.1.18) which is verified for Unity 2019 LTS via its package dependency. As that version is not compatible with Unity 2020, a bunch of compiler errors will appear. To fix this, follow these additional steps:

  • Via the Unity Package Manager, manually update the version of the AR Foundation package to 4.1.7 (verified version)

Note: When using Android, make sure to use the ARCore package version 4.0.12. Do not use version 4.1.x or higher as this will currently cause a black screen when deployed. This behaviour might change in future versions.

  • Under Project Settings > Player > Other Settings > Script Compilation > Scripting Define Symbols add the entry ENABLE_ARFOUNDATION_4 to the text field and press Apply

Requirements

AR Foundation is currently only supported on Android and iOS. Our implementation has been tested on Android 10, Android 11, iOS 13 and iOS 14.

It is not possible to test scenes in the editor when using AR Foundation. Please deploy them to a device in order to test them.

Build Settings

  • At File > Build Settings select iOS or Android and click on Switch Platform if it is not already selected.
  • Under Project Settings > XR Plugin Management, install the XR Plugin Management.

Note: When the XR Plugin Manager causes errors, try restarting the Unity Editor.

In the following sections, Player Settings will refer to Edit > Project Settings > Player > Settings For (Android / iOS).

iOS

  • If you want to deploy to iOS, you have to install the ARKit XR Plugin by checking the ARKit toggle in the XR Plugin Management.

Note: There are implicit dependencies between the ARKit XR Plugin version and the specific version of the Unity Editor.

  • For us the verified version of ARKit XR Plugin (2.1.18) worked with the current LTS version of Unity (2019.4.20)
  • Using Unity version 2019.4.13 we could not use the current version and had to use ARKit XR Plugin version 2.1.9.
  • At Player Settings > Other Settings
    • Set Camera Usage Description* to any value, e.G. Augmented Reality
    • Set Target minimum iOS version to at least 11.0
    • Set Architecture to ARM64

Android

  • If you want to deploy to Android, install the ARCore XR Plugin by checking the ARCore toggle in the XR Plugin Management.

Note: There are implicit dependencies between the ARCore XR Plugin version and the specific version of the Unity Editor.

  • For us the verified version of ARCore XR Plugin (2.1.18) worked with the current LTS version of Unity (2019.4.20)
  • Using Unity version 2019.4.13 we could not use the current version and had to use ARCore XR Plugin version 2.1.8.

At Player Settings > Other Settings

  • Make sure that your Minimum API Level is at least set to Android 7.0 Nougat (API level 24). Otherwise you will get the following error message:
    BuildFailedException: ARCore Required apps require a minimum SDK version of 24. Currently set to AndroidApiLevel21
  • Enable Auto Graphics API. If you want to disable Auto Graphics API, make sure Vulkan graphics API is not on top of the list of Graphic APIs. Otherwise you will get the following error message when trying to build:
    BuildFailedException: You have enabled the Vulkan graphics API, which is not supported by ARCore.
  • As of now, Vulkan is not supported by ARCore.

At Player Settings > XR Settings, make sure that ARCore Supported and Virtual Reality Supported are unchecked. Otherwise you will get the following error message:

  • At XR > ARCore, create the configuration asset for AR Core by clicking Create and store it in the Assets directory of your project. (Unity will suggest to store it there).
    • After creating that file, you have to set the requirement mode of ARCore to Optional.
    • Otherwise you will get the following error message:
  • At this point the example scene can be deployed and tested.

Custom Tracking Configuration

In the AR Foundation Example, we use the tracking configuration in StreamingAssets/VisionLib/Examples/ARFoundation/ModelTracking/ARFoundationModelTrackingConfiguration.vl. You can use that as a starting point for your own configuration file as described in the UnitySDK Quick Start. Please copy the file instead of modifying the existing file to prevent issues when updating to new versions of VisionLib.

The VLTracking GameObject itself contains the Tracking Configuration component, where you can set the path to your tracking configuration file.

Since Unity sets the position of the AR Foundation camera in meters, your model also has to be scaled accordingly. Please also set the metric to "m" in your tracking configuration file.

VisionLib XR Tracking Settings

The components that connect AR Foundation with VisionLib are placed on the GameObject called VLXRTracker.

The parameters have the following effects:

  • If you want to reduce the workload that is created by VisionLib object tracking, you can set the Max Tracking FPS to a lower value - or increase it to trigger object tracking more frequently.
  • If you select Use Pose From Tracking Config, the initial position will be read from the tracking configuration file instead of the VLInitCamera.
  • If you deselect Keep Upright, the initial position of the tracking content will not be geared to the world up vector.
  • The value in Smooth Time is the time in seconds that the tracking content will take to go to the position of the object tracking result. Higher values will make the transitions smoother but the updates will be less immediate.

Add VL Tracking to an existing AR Foundation Scene

To enable VisionLib object tracking in an existing AR Foundation scene, select Game Object > VisionLib > Add XR Tracking. This will add all necessary GameObjects and Components under a parent object called VLTracking to your scene. It will also try to connect them automatically to the AR Foundation GameObjects.

Once the VLTracking GameObject is created, set your tracking configuration in the public parameter of the object's Tracking Configuration component.

Adjust the Transform of the VLInitCamera, so that the camera is pointing to the tracking target from the point that should be used to start tracking from.

Finally, you have to set the Content property of the XR Tracker component of the VLXRTracker to the GameObject that should be placed as an augmentation on the tracked object. The example uses the Scene Content GameObject for that purpose.