Class

ARCoachingOverlayView

A view that presents visual instructions that guide the user.

Declaration

class ARCoachingOverlayView : UIView

Overview

This view offers your users a standardized onboarding routine. You can configure this view to automatically display during session initialization and in limited tracking situations, while giving the user specific instructions that best facilitate ARKit's world tracking.

These illustrations show overlay views with horizontal- and vertical-plane goals, indicating that the user should begin moving the device:

Illustration showing two overlay views. The view at the left shows a horizontal plane, and the view at the right shows a vertical plane. Both views indicate that the user should begin moving the device.

These illustrations show overlay views indicating that the user should continue moving the phone or change the speed with which they move it:

Illustration showing two overlay views. The view at the left indicates that the device is moving and the user should continue moving it. The view at the right indicates that the device is moving too fast and the user should move it more slowly.

When you start your app, the coaching overlay asks the user to move the device in ways that help ARKit establish tracking. When you choose a specific goal like finding a plane, the view tailors its instructions accordingly. After the coaching overlay determines the goal has been met and no further coaching is required, it hides from the user's view.

For an example app that uses the coaching overlay, see Placing Objects and Handling 3D Interaction.

Supporting Automatic Coaching

By default, activatesAutomatically is enabled and therefore you should override coachingOverlayViewWillActivate(_:) to determine whether coaching is in progress. Coordinate your actions to help the user focus on these instructions, for example, by hiding any UI that's not necessary while the session reinitializes.

Relocalizing After an Interruption

If relocalization is enabled (see sessionShouldAttemptRelocalization(_:)), ARKit attempts to restore your session if any interruptions degrade your app's tracking state. In this event, the coaching overlay presents itself and gives the user instructions to assist ARKit with relocalizing.

User instruction to return to the user's previous location so ARKit can restore the session.

During this time, the coaching overlay includes a button that lets the user indicate they'd like to start over rather than restore the session.

Button that enables the user to indicate they'd like to start over rather than restore the session.

ARKit notifies you when the user presses Start Over by calling your delegate's coachingOverlayViewDidRequestSessionReset(_:) function. Implement this callback if your app requires any custom actions to restart the AR experience.

func coachingOverlayViewDidRequestSessionReset(_ coachingOverlayView: ARCoachingOverlayView) {    

    // Reset the session.
    let configuration = ARWorldTrackingConfiguration()
    configuration.planeDetection = [.horizontal, .vertical]
    session.run(configuration, options: [.resetTracking])

    // Custom actions to restart the AR experience. 
    // ...
}

If you do not implement coachingOverlayViewDidRequestSessionReset(_:), the coaching overlay responds to the Start Over button by resetting tracking, which also removes any existing anchors.

For more information about relocalization, see Managing Session Lifecycle and Tracking Quality.

Topics

Delegating Events

var delegate: ARCoachingOverlayViewDelegate?

An object you supply that implements coaching event callbacks.

protocol ARCoachingOverlayViewDelegate

A set of callbacks you implement to be notified of coaching events.

Defining a Goal

var goal: ARCoachingOverlayView.Goal

A field that indicates your app's tracking requirements.

enum ARCoachingOverlayView.Goal

The options that specify your app's tracking requirements.

Activiting the View

var activatesAutomatically: Bool

A flag that indicates whether the coaching view activates automatically, depending on the current session state.

var isActive: Bool

A flag that indicates whether coaching is in progress.

func setActive(Bool, animated: Bool)

Controls whether coaching is in progress.

Providing the Session

var session: ARSession?

The session this view uses to provide coaching.

var sessionProvider: ARSessionProviding?

An object you designate that provides the current session.

See Also

World Tracking

Understanding World Tracking

Discover supporting concepts, features, and best practices for building great AR experiences.

class ARWorldTrackingConfiguration

A configuration that monitors the iOS device's position and orientation while enabling you to augment the environment that's in front of the user.

class ARPlaneAnchor

A 2D surface that ARKit detects in the physical environment.

Tracking and Visualizing Planes

Detect surfaces in the physical environment and visualize their shape and location in 3D space.

Placing Objects and Handling 3D Interaction

Place virtual content on real-world surfaces, and enable the user to interact with virtual content by using gestures.

class ARWorldMap

The space-mapping state and set of anchors from a world-tracking AR session.

Saving and Loading World Data

Serialize a world tracking session to resume it later on.

Ray-Casting and Hit-Testing

Find 3D positions on real-world surfaces given a screen point.