Creating an AR Experience

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.

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();

Note

ARDK checks for camera permissions when starting a new session, however it does this differently depending on if you’re running on iOS or Android. On iOS, when you call ARSession.Run() ARDK will ask the user for permission to use the camera. On Android, you must ask the user for permission to use the camera before calling ARSessionFactory.Create(). You can use AndroidPermissionRequester or use Unity’s Android Permission API.

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.

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();

See Also

World Tracking

Tools

AR APIs