Class

ARSession

The main object you use to control an AR experience.

Declaration

class ARSession : NSObject

Overview

An ARSession object coordinates the major processes that ARKit performs on your behalf to create an augmented reality experience. These processes include reading data from the device's motion sensing hardware, controlling the device's built-in camera, and performing image analysis on captured camera images. The session synthesizes all of these results to establish a correspondence between the real-world space the device inhabits and a virtual space where you model AR content.

Create a Session

Every AR experience requires an ARSession. If you implement a custom renderer, you instantiate the session yourself.

let session = ARSession()
session.delegate = self

If you use one of the standard renderers (like ARView, ARSCNView, or ARSKView), the renderer creates a session object for you. When you want to interact with your app's session, you access it on your app's renderer.

let session = myView.session

Run a Session

Running a session requires a configuration. Subclasses of ARConfiguration determine how ARKit tracks a device's position and motion relative to the real world, and thus it determines the kinds of AR experiences you create. For example, ARWorldTrackingConfiguration enables you to augment the user's view of the world around them though the device's back camera.

Topics

Configuring and Running a Session

func run(ARConfiguration, options: ARSession.RunOptions)

Starts AR processing for the session with the specified configuration and options.

var identifier: UUID

A unique identifier of the running session.

struct ARSession.RunOptions

Options affecting how to transition an AR session's current state when you change its configuration.

var configuration: ARConfiguration?

An object that defines motion and scene tracking behaviors for the session.

func pause()

Pauses processing in the session.

Responding to Events

var delegate: ARSessionDelegate?

An object you provide to receive captured video images and tracking information, or to respond to changes in session status.

var delegateQueue: DispatchQueue?

The dispatch queue through which the session calls your delegate methods.

protocol ARSessionDelegate

Methods you can implement to receive captured video frame images and tracking state from an AR session.

protocol ARSessionObserver

Methods you can implement to respond to changes in the state of an AR session.

Accessing the Camera Frame

var currentFrame: ARFrame?

The most recent still frame captured by the active camera feed, including ARKit's interpretation of it.

Managing Anchors

func add(anchor: ARAnchor)

Adds the specified anchor to be tracked by the session.

func remove(anchor: ARAnchor)

Removes the specified anchor from tracking by the session.

Saving or Sharing State

func getCurrentWorldMap(completionHandler: (ARWorldMap?, Error?) -> Void)

Returns an object encapsulating the world-tracking session's space-mapping state and set of anchors.

Scanning 3D Objects

func createReferenceObject(transform: simd_float4x4, center: simd_float3, extent: simd_float3, completionHandler: (ARReferenceObject?, Error?) -> Void)

Creates a reference object (for 3D object detection) from the specified region of the session’s world space.

Updating the World Origin

func setWorldOrigin(relativeTransform: simd_float4x4)

Changes the basis for the AR world coordinate space using the specified transform.

Finding Real-World Surfaces

Cast a ray from a point on the screen to find intersections with real-world surfaces.

func raycast(ARRaycastQuery) -> [ARRaycastResult]

Checks once for intersections between a ray and real-world surfaces.

func trackedRaycast(ARRaycastQuery, updateHandler: ([ARRaycastResult]) -> Void) -> ARTrackedRaycast?

Repeats a ray-cast query over time to notify you of updated surfaces in the physical environment.

Managing Collaboration

func update(with: ARSession.CollaborationData)

Updates your session with information about the physical environment that is collected by another user.

class ARSession.CollaborationData

An object that holds information that a user has collected about the physical environment.

Providing a Session

protocol ARSessionProviding

An object that provides a session.

Relationships

Inherits From

Conforms To

See Also

Essentials

Choosing Which Camera Feed to Augment

Augment the user's environment through either the front or back camera.

Verifying Device Support and User Permission

Check whether your app can use ARKit and respect user privacy at runtime.

Managing Session Lifecycle and Tracking Quality

Keep the user informed on the current session state and recover from interruptions.

class ARConfiguration

An object that defines the particular ARKit features you enable in your session at a given time.

class ARAnchor

A position and orientation of something of interest in the physical environment.