Table of Contents

Create and configure AR session

To use AR in Unity, you first need to create and configure an AR session in the scene. This article introduces several main methods for creating and configuring an AR session. Generally, after successfully creating a session, you can see the following structure in the Hierarchy view:

alt text

Before you begin

Create a session with default configuration

Right-click on a blank area in the Hierarchy view, and select EasyAR Sense > [AR feature] > AR Session ([feature] Preset) from the menu to create a preconfigured session. The session comes with preconfigured frame source and frame filter components suitable for the feature.

In scripts, you can use ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset, ARSessionFactory.Resources) to create a session.

For example, selecting EasyAR Sense > Image Tracking > AR Session (Image Tracking Preset) from the menu will create a session for image tracking.

alt text

The corresponding script code is as follows:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.ImageTracking);

Note that when using ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder and ARSessionFactory.ARSessionPreset.DenseSpatialMapBuilder presets, you also need to pass in resource parameters. For example, the following code creates a session for sparse spatial mapping and specifies the point cloud material:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder, new ARSessionFactory.Resources { SparseSpatialMapPointCloudMaterial = PointCloudMaterial });

If the script only runs in the editor, you can also use default editor resources:

ARSessionFactory.CreateSession(ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder, ARSessionFactory.Resources.EditorDefault());

The menu EasyAR Sense > AR Session (Preset) > ** lists all available preset sessions for reference.

alt text

Note

Multiple sessions running simultaneously in the same scene will conflict with each other, so only one enabled (GameObject.activeInHierarchy == true) session should be kept in the scene at most.

Add components

The frame source and frame filter components of a session can be added and removed as needed after the session is created.

In the Hierarchy view, select AR Session (EasyAR) and right-click to add the appropriate frame source and frame filter components for the AR feature through the menu EasyAR Sense > [ AR feature ] > **.

In scripts, you can use ARSessionFactory.AddFrameSource<Source>(GameObject, bool) to add a frame source component, or use ARSessionFactory.AddFrameFilter<Filter>(GameObject, ARSessionFactory.Resources) to add a frame filter component.

For example, through the menu EasyAR Sense > Image Tracking > Frame Filter : Image Tracker, you can add a new image tracker to the currently selected session.

alt text

The corresponding script code is as follows:

ARSessionFactory.AddFrameFilter<ImageTrackerFrameFilter>(session);
Caution

Adding components must be completed before assemble. After the session starts executing assemble or completes assemble, any addition or deletion of components will cause the session to enter the Broken state and stop working.

Note that when adding SparseSpatialMapBuilderFrameFilter and DenseSpatialMapBuilderFrameFilter, resource parameters need to be passed in simultaneously. For example, the following code creates a SparseSpatialMapBuilderFrameFilter for sparse spatial mapping and specifies the point cloud material:

ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, new ARSessionFactory.Resources { SparseSpatialMapPointCloudMaterial = PointCloudMaterial })

If the script only runs in the editor, you can also use the default editor resources:

ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, ARSessionFactory.Resources.EditorDefault());

After creating a frame filter, you can use ARSessionFactory.SetupFrameFilters(List<GameObject>, ARSessionFactory.ARSessionPreset) to adjust the frame filter parameters according to the preset configuration.

For example, the following code adds a new image tracker to the session and configures it with the preset parameters of ARSessionFactory.ARSessionPreset.ImageTrackingMotionFusion.

var filter = ARSessionFactory.AddFrameFilter<ImageTrackerFrameFilter>(session);
ARSessionFactory.SetupFrameFilters(new() { filter }, ARSessionFactory.ARSessionPreset.ImageTrackingMotionFusion);

When creating through the menu, it is not possible to adjust parameters according to the preset. You need to configure them according to the specific component instructions after creation.

Remove components

To remove a component from the session, you can select the corresponding component in the Hierarchy view and press the Delete key, or destroy (Destroy) the corresponding object in the script.

Note

Disabling (SetActive(false)) the GameObject of a component has the same effect as removing the component.

For example, to remove an image tracker from the session, select Image Tracker and press the Delete key.

alt text

Caution

Removing components must be completed before assemble. After the session starts executing assemble or completes assemble, any addition or deletion of components will cause the session to enter the Broken state and stop working.

Impact of component ordering

The order of frame filter child nodes in a session has no effect on the execution of the session.

The order of frame source child nodes in a session will affect the selection order of frame sources during the assemble process. Only the first available frame source arranged in transform order will be selected as the actual frame source of the session.

Note

The order of frame source nodes is only effective if modified before assemble. After assemble, adjusting the order will not affect the runtime results.

[Optional] Create a session freely

If the default session configuration does not meet the requirements, you can freely create and configure a session as needed.

You can use the menu EasyAR Sense > AR Session (Preset) > AR Session (Empty) to create an empty session without any frame source or frame filter components.

In scripts, you can use ARSessionFactory.CreateSession() to achieve this.

ARSessionFactory.CreateSession();

Then, add appropriate frame source and frame filter components based on actual needs.

For example, if you need to create a session with sparse spatial mapping and dense spatial mapping capabilities, you can use the following code:

var session = ARSessionFactory.CreateSession();

var group = new GameObject("Frame Source Group");
group.transform.SetParent(session.transform, false);

ARSessionFactory.AddFrameSource<XREALFrameSource>(session);
ARSessionFactory.AddFrameSource<AREngineFrameSource>(session);
ARSessionFactory.AddFrameSource<ARCoreFrameSource>(session);
ARSessionFactory.AddFrameSource<ARCoreARFoundationFrameSource>(session);
ARSessionFactory.AddFrameSource<ARKitFrameSource>(session);
ARSessionFactory.AddFrameSource<ARKitARFoundationFrameSource>(session);
ARSessionFactory.AddFrameSource<VisionOSARKitFrameSource>(session);
ARSessionFactory.AddFrameSource<MotionTrackerFrameSource>(session);

List<GameObject> filters = new();
filters.Add(ARSessionFactory.AddFrameFilter<SparseSpatialMapBuilderFrameFilter>(session, resources));
filters.Add(ARSessionFactory.AddFrameFilter<DenseSpatialMapBuilderFrameFilter>(session, resources));

ARSessionFactory.SetupFrameFilters(filters, ARSessionFactory.ARSessionPreset.SparseSpatialMapBuilder);
ARSessionFactory.SetupFrameFilters(filters, ARSessionFactory.ARSessionPreset.DenseSpatialMapBuilder);

It will create a session structure like this:

alt text

Next steps

Control the runtime

Access components and results

Component reference