Creating an AR Session

How to create an AR experience with the ARSession class.

The ARSession class is the top level class in the hierarchy of an AR experience. Use it as a one-stop shop to:

Specify what properties you would like your AR experience to have by running an ARSession with an ARConfiguration object. The ARSession ‘s current configuration is exposed through ARSession ‘s Configuration property.
Access the AR system’s current understanding of the world through ARFrame objects. The frame currently displayed on screen is exposed through ARSession ‘s CurrentFrame property.
Listen for updates to the AR system’s current understanding of the world, like new ARAnchors or ARFrames by subscribing to events.

You can create an ARSession as part of your scene initialization, for example, in the Start() method of a script attached to a game object in your scene.

ARSession Usage

You can create an ARSession using ARSessionFactory:

using Niantic.ARDK.AR;

// This method will create an ARSession that runs on RuntimeEnvironment.LiveDevice
// if called on a mobile device, through Virtual Studio's RemoteConnection
// if called from the Unity Editor with RemoteConnection enabled, or through
// Virtual Studio's Mock mode as the last option.
var session = ARSessionFactory.Create();

Camera Permissions

ARSessions require access to the device’s camera; however, the permission request flow works different depending on if your app is running on iOS or Android.

On iOS, when you call ARSession.Run() the camera permission request will automatically pop up.
On Android, due to the fact that ARCore requires camera permissions in order to create an ARSession, you must ask the user for camera permission before calling ARSessionFactory.Create().

For more details, see Permissions.

Update Events

You can use the ARSession object to subscribe to events that will notify you about changes to anchors and frames in your session:

// Subscribe to events with callbacks defined elsewhere in your code
session.AnchorsAdded += OnAnchorsAdded;
session.AnchorsMerged += OnAnchorsMerged;
session.AnchorsRemoved += OnAnchorsRemoved;
session.FrameUpdated += OnFrameUpdated;

Once you have an ARSession initialized, you need to create an ARConfiguration to run the session with. The ARConfiguration will configure the session’s features. Currently there is only one type of configuration: ARWorldTrackingConfiguration.

using Niantic.ARDK.AR.Configuration;

var configuration = ARWorldTrackingConfigurationFactory.Create();
configuration.WorldAlignment = WorldAlignment.Gravity;
configuration.IsLightEstimationEnabled = true;
configuration.PlaneDetection = PlaneDetection.Horizontal;
configuration.IsAutoFocusEnabled = true;
configuration.IsDepthEnabled = false;
configuration.IsSharedExperienceEnabled = true;

// Now we run the session
session.Run(configuration);

When Pause is called, no AR features (frames, anchors, points, etc.) will be surfaced. The Run method takes in an optional RunOptions argument that can be used to specify the content to carry over into the next session.

AR sessions can be run over and over with different run options and configurations.

Using Managers

To simplify the process of managing an AR session’s lifecycle and/or to configure the session, we provide Managers you can add to your scene.

The API reference and in-code comments/tool tips for ARSessionManager explains how to use it.

Getting the device’s position and orientation in local AR space

The ARFrame object contains a reference to the ARCamera object, which holds data about the device’s camera specs and outputs. The device’s position and orientation in local AR space can be obtained from the camera’s Transform property.

var pos = camera.Transform.ToPosition();
var rot = camera.Transform.ToRotation();

Creating an AR Session

ARSession Usage

Camera Permissions

Update Events

Using Managers

Getting the device’s position and orientation in local AR space

See Also

World Tracking

Tools

AR APIs