Working with AR Foundation

When Do I Need AR Foundation

AR Foundation offers cross platform motion tracking capability. Please read Motion Tracking and EasyAR Features for the relationship between EasyAR and motion tracking, and is AR Foundation needed and when.

If you need to use ARCore on all Xiaomi and Redmi phones that support ARCore, use AR Foundation. Due to bugs in the implementation of Xiaomi manufacturers, the ARCore wrapper of EasyAR has disabled some Xiaomi phones, including the Mi 9, Mi 10, Redmi K20, Redmi K30, Redmi K40 and other series (the list here is incomplete). On these phones, ARCore will not be used by default, and EasyAR motion tracking will be used on phones that support EasyAR motion tracking.

AR Foundation Versions Supported by EasyAR

EasyAR Sense Unity Plugin support AR Foundation 4.1.3 or later.

Attention

AR Foundation support is implemented as EasyAR Sense custom camera. EasyAR Sense will stop responding after a fixed and limited time per run if trial product (personal license, trial XR license, or trial Mega services, etc.) is being used with custom camera or HMD. There is no limitation when using a paid license for EasyAR Sense and paid EasyAR Mega service.

Import AR Foundation Package

Import AR Foundation Unity Package using Unity Package Manager,

../_images/image_g7_1.png

Notice: make sure to import the latest AR Foundation you can get. Unity keeps fixing bugs and sometimes these bugs are critical to basic usages. The above image does not follow AR Foundation updates, please subject to Unity official release version number.

To use AR Foundation on Android or iOS, usually you need to import either ARCore XR Plugin or ARKit XR Plugin Unity package into the project. Follow AR Foundation Introduction to setup necessary packages.

../_images/image_g7_11.png

Notice: make sure the packages are from the same version. AR Foundation and its plugin packages from different versions may not work correctly in some conditions. Unity does not provide a reasonable automatic mechanism to ensure this kind of usage.

Import EasyAR Sense Unity Plugin

Use Unity’s Package Manager window to install the plugin from a local tarball file.

../_images/image_s0_1.png

Choose the com.easyar.sense-*.tgz file in the popup dialogue.

Import EasyAR Sense Unity Plugin AR Foundation Extension

Use Unity’s Package Manager window to install the plugin from a local tarball file.

../_images/image_g7_10.png

Choose the com.easyar.sense.ext.arfoundation-*.tgz file in the popup dialogue.

AR Foundation package will be automatically imported into the project if it is not added before this step. Due to the unperfect Unity package dependency mechanism, it may import an old version of AR Foundation. Please check in the package manager and make sure,

  1. AR Foundation is upgraded to the latest version, if not, please upgrade manually,

../_images/image_g7_12.png

  1. Import ARCore XR Plugin and / or ARKit XR Plugin, and make sure they have the same version with AR Foundation,

../_images/image_g7_11.png

  1. Make sure the imported ARCore XR Plugin or ARKit XR Plugin or other plugins have the same version with AR Foundation, if not, please upgrade manually,

../_images/image_g7_13.png ../_images/image_g7_14.png

Import and Use Samples

Please read How to use Mega Unity development samples (in Chinese) when using EasyAR Mega. The following sample description is for the cases not using Mega.

The samples are distributed within the plugin package. You can import samples into your project using Unity’s Package Manager window.

../_images/image_g7_15.png

To be noteiced, these samples are inside EasyAR Sense Unity Plugin ARFoundation Extension package instead of EasyAR Sense Unity Plugin pacage.

Please make sure to follow AR Foundation documents to config necessary pacakges before use EasyAR samples. Suggest to run Unity official AR Foundation samples to make sure that AR Foundation can work correctly.

The sample usages are the same with other EasyAR samples except above description. You can reference How to Use Samples for details.

Sample Introduction

Please read Mega Unity development samples instruction when using EasyAR Mega.

ARFOnly_SpatialMap_Building sample demonstrates a very simple scenario to make SpatialMap work under AR Foundation.

ARFFirst_MotionTracking_PlaneDetection sample demonstrates an advanced usage, to choose frame source at app start up according to device capability and enables runtime switch of available frame sources. To achieve this kind of usage, you need to deactive AR Foundation GameObjects and set all required values of all frame sources for availability check, and active AR Foundation GameObjects when this frame source is chosen.

../_images/image_g7_9.png

For more descriptions, please read ARFoundationFrameSource.

ARFFirst_ImageTracking_MotionFusion sample demonstrates how to use EasyAR Motion Fusion to enhance image tracking when AR Foundation is used. Meanwhile, it demonstrates how to make apps compatible with devices both support and not support AR Foundation and other motion tracking capabilities.

Add EasyAR Support in AR Foundation Scene

Prepare a Usable AR Foundation Scene

In the next section, a usable AR Foundation scene is required. You can follow AR Foundation Introduction to create a usable scene that can run AR Foundation.

You can create a new Unity project using Unity Hub AR, Core template, it will give you a usable scene,

../_images/image_g7_16.png

A typical AR Foundation scene contains an AR Session and an AR Session Origin.

../_images/image_g7_2.png

NOTE: AR Foundation usually sets its clipping planes to (0.1, 20) , this may clip objects away displayed more than 20 meters from the Camera (the device in real world). Please make sure to change its value for your needs before you use them.

Add EasyAR Components in the Scene

Add EasyAR AR Session in the scene. AR Session can be created from some AR Session presets using EasyAR Sense > Ext: AR Foundation > * GameObject menu.

../_images/image_g7_3.png

You can also assemble AR Session by yourself if necessary. Make sure the assembled AR Session has ARFoundationFrameSource in it.

To use EasyAR with AR Foundation, ARFoundationFrameSource must be selected as frame source in the AR Session after Session start.

This could usually be done by set ARComponentPicker.FrameSource to FirstAvailableActiveChild and make sure ARFoundationFrameSource is the first frame source that can be used in transform order,

../_images/image_g7_5.png

Or set ARComponentPicker.FrameSource to Specify and specify the frame source to ARFoundationFrameSource .

../_images/image_g7_6.png

Then add targets or maps in the scene, for example, if you want to build Sparse SpatialMap, you need to create SparseSpatialMapController by EasyAR Sense > SpatialMap > Map : Sparse SpatialMap

../_images/image_g7_4.png

Finally, a simple scene for sparse spatial map building with AR Foundation could look like this,

../_images/image_g7_8.png

Scenes can be different according to features in use from both AR Foundation and EasyAR Sense Unity Plugin.

Add AR Foundation Support in EasyAR Scene

Prepare a Usable EasyAR Scene

In the next section, a usable EasyAR scene is required. You can reference How to Use Samples to use a sample, or create a new scene reference Start from Zero.

Delete Main Camera

There is already a camera inside AR Foundation objects, so you need to delete camera in the scene in most cases.

../_images/image_g7_17.png

You can also judge if the deletion is needed according to your needs in some advanced usages.

Add EasyAR Components for AR Foundation support in the Scene

Add ARFoundationFrameSource in AR Session. Select AR Session (EasyAR) or Frame Source Group, and add using EasyAR Sense > Ext: AR Foundation > Frame Source : AR Foundation.

../_images/image_g7_7.png

Move ARFoundationFrameSource to be the first,

../_images/image_g7_18.png

In some advanced usages, you can also move it to where you want, or change the order in scripts.

To use EasyAR with AR Foundation, ARFoundationFrameSource must be selected as frame source in the AR Session after Session start.

This could usually be done by set ARComponentPicker.FrameSource to FirstAvailableActiveChild and make sure ARFoundationFrameSource is the first frame source that can be used in transform order,

../_images/image_g7_5.png

Or set ARComponentPicker.FrameSource to Specify and specify the frame source to ARFoundationFrameSource .

../_images/image_g7_6.png

Add AR Foundation Components in the Scene

You can follow AR Foundation Introduction to add AR Foundation components in the scene.

In most of the cases, you need to use menu XR > AR Session and XR > AR Session Origin to add AR Foundation components (follow AR Foundation official instructions if there are any conflicts).

../_images/image_g7_19.png

NOTE: AR Foundation usually sets its clipping planes to (0.1, 20) , this may clip objects away displayed more than 20 meters from the Camera (the device in real world). Please make sure to change its value for your needs before you use them.

Finally, a simple scene for sparse spatial map building with AR Foundation could look like this,

../_images/image_g7_8.png

Scenes can be different according to features in use from both AR Foundation and EasyAR Sense Unity Plugin.

Before run on a device, make sure to read AR Foundation Introduction for how to configure and run a scene containing AR Foundation