Contents

Configuration Objects

Configure your augmented reality session to detect and track specific types of content.

Overview

Configuration objects define how ARKit sets up and runs your augmented reality session. Although ARWorldTrackingConfiguration provides the widest range of features in a rear-camera experience, each feature consumes device energy and compute cycles. So to maximize device uptime and performance, enable additional options sparingly.

If another AR configuration fulfills your requirements with a more concise feature set, use that configuration instead. For example, use ARBodyTrackingConfiguration instead of a world-tracking configuration for 3D motion-capture if you don’t need user face-tracking, collaboration, or scene reconstruction.

Select frame features

Some configurations support subfeatures that relate to a session’s frame. Enable these features by setting the following flags in the configuration’s frameSemantics:

bodyDetection

Enables 2D human body tracking.

personSegmentation

Enables people occlusion.

personSegmentationWithDepth

Enables people occlusion based on whether the people in the camera feed are closer to the camera than the virtual content.

Use supportsFrameSemantics(_:) to verify whether the iOS device supports the ARConfiguration.FrameSemantics you desire before setting frameSemantics.

Switch configurations at runtime

To toggle features like plane detection, frame semantics, and environment texturing, you switch your configuration at runtime by calling runWithConfiguration: on your existing session. Where possible, ARKit maintains all the information collected during the session under the prior configuration, such as information about the physical environment and anchors.

If your session switches between face- and world-tracking configurations, the session doesn’t maintain state.

Enable high-quality video and custom capture settings

In iOS 16, you can enable a 4K and high dynamic range (HDR) video format. In addition, you can customize your session’s video settings through the underlying AV capture device.

To determine whether your session supports 4K, call recommendedVideoFormatFor4KResolution.

guard let hiResFormat = ARWorldTrackingConfiguration.recommendedVideoFormatFor4KResolution else {
   print("4K video format not supported."); return }

Then, create a configuration with the format. You can also indicate the intent to enable HDR by setting videoHDRAllowed to true.

var config = ARWorldTrackingConfiguration()
config.videoFormat = hiResFormat
config.videoHDRAllowed = true
session.run(config)

If the device supports a configurable capture session, the configurableCaptureDeviceForPrimaryCamera provides the underlying capture device that you can adjust as needed.

if let device = ARWorldTrackingConfiguration.configurableCaptureDeviceForPrimaryCamera {
   do { try device.lockForConfiguration()
      // Configure capture settings here.
      device.unlockForConfiguration()
   } catch { /* Error handling. */ }
}

Capture high-resolution still frames

In iOS 16, you can enable high-resolution frame capture by calling recommendedVideoFormatForHighResolutionFrameCapturing on your configuration. If the device supports high-resolution stills, the function returns a video format you can use to start a session:

guard let hiResFormat = type(of: config).recommendedVideoFormatForHighResolutionFrameCapturing else {
    fatalError("The device doesn't support high-resolution stills.") }
config.videoFormat = hiResFormat
arSession.run(config)

During the session, capture a high-resolution still frame at any time by calling captureHighResolutionFrame(completion:):

arSession.captureHighResolutionFrame { (frame, error) in
    if let frame = frame {
        saveHiResFrame(frame)
    } else { /* Error handling. */ }

Topics

Common Configuration Details

Spatial Tracking

Body and Face Tracking

Image Recognition

Object Detection

See Also

Setup