Sample Code

Building Your First AR Experience

Create an app that runs an AR session and uses plane detection to place 3D content using SceneKit.

Download

Overview

This sample app runs an ARKit world tracking session with content displayed in a SceneKit view. To demonstrate plane detection, the app simply places an SCNPlane object to visualize each detected ARPlaneAnchor object.

Configure and Run the AR Session

The ARSCNView class is a SceneKit view that includes an ARSession object that manages the motion tracking and image processing required to create an augmented reality (AR) experience. However, to run a session you must provide a session configuration.

The ARWorldTrackingConfiguration class provides high-precision motion tracking and enables features to help you place virtual content in relation to real-world surfaces. To start an AR session, create a session configuration object with the options you want (such as plane detection), then call the run(_:options:) method on the session object of your ARSCNView instance:

let configuration = ARWorldTrackingConfiguration()
configuration.planeDetection = .horizontal
sceneView.session.run(configuration)

Run your session only when the view that will display it is onscreen.

Important: If your app requires ARKit for its core functionality, use the arkit key in the UIRequiredDeviceCapabilities section of your app’s Info.plist file to make your app available only on devices that support ARKit. If AR is a secondary feature of your app, use the isSupported property to determine whether to offer AR-based features.

Place 3D Content for Detected Planes

After you’ve set up your AR session, you can use SceneKit to place virtual content in the view.

When plane detection is enabled, ARKit adds and updates anchors for each detected plane. By default, the ARSCNView class adds an SCNNode object to the SceneKit scene for each anchor. Your view’s delegate can implement the renderer(_:didAdd:for:) method to add content to the scene.

func renderer(_ renderer: SCNSceneRenderer, didAdd node: SCNNode, for anchor: ARAnchor) {
       // Place content only for anchors found by plane detection.
       guard let planeAnchor = anchor as? ARPlaneAnchor else { return }

       // Create a SceneKit plane to visualize the plane anchor using its position and extent.
       let plane = SCNPlane(width: CGFloat(planeAnchor.extent.x), height: CGFloat(planeAnchor.extent.z))
       let planeNode = SCNNode(geometry: plane)
       planeNode.simdPosition = float3(planeAnchor.center.x, 0, planeAnchor.center.z)
       
       /*
        `SCNPlane` is vertically oriented in its local coordinate space, so
        rotate the plane to match the horizontal orientation of `ARPlaneAnchor`.
       */
       planeNode.eulerAngles.x = -.pi / 2
       
       // Make the plane visualization semitransparent to clearly show real-world placement.
       planeNode.opacity = 0.25
       
       /*
        Add the plane visualization to the ARKit-managed node so that it tracks
        changes in the plane anchor as plane estimation continues.
       */
       node.addChildNode(planeNode)
}

If you add content as a child of the node corresponding to the anchor, the ARSCNView class automatically moves that content as ARKit refines its estimate of the plane’s position and extent. To show the full extent of the estimated plane, this sample app also implements the renderer(_:didUpdate:for:) method, updating the SCNPlane object’s size to reflect the esitmate provided by ARKit.

func renderer(_ renderer: SCNSceneRenderer, didUpdate node: SCNNode, for anchor: ARAnchor) {
    // Update content only for plane anchors and nodes matching the setup created in `renderer(_:didAdd:for:)`.
    guard let planeAnchor = anchor as?  ARPlaneAnchor,
        let planeNode = node.childNodes.first,
        let plane = planeNode.geometry as? SCNPlane
        else { return }
    
    // Plane estimation may shift the center of a plane relative to its anchor's transform.
    planeNode.simdPosition = float3(planeAnchor.center.x, 0, planeAnchor.center.z)
    
    /*
     Plane estimation may extend the size of the plane, or combine previously detected
     planes into a larger one. In the latter case, `ARSCNView` automatically deletes the
     corresponding node for one plane, then calls this method to update the size of
     the remaining plane.
    */
    plane.width = CGFloat(planeAnchor.extent.x)
    plane.height = CGFloat(planeAnchor.extent.z)
}

See Also

World-Based AR Experiences

Handling 3D Interaction and UI Controls in Augmented Reality

Follow best practices for visual feedback, gesture interactions, and realistic rendering in AR experiences.

class ARWorldTrackingConfiguration

A configuration that uses the rear-facing camera, tracks a device's orientation and position, and detects real-world flat surfaces.

class AROrientationTrackingConfiguration

A configuration that uses the rear-facing camera and tracks only a device's orientation.

class ARPlaneAnchor

Information about the position and orientation of a real-world flat surface detected in a world-tracking AR session.