Class

ARWorldMap

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

Declaration

class ARWorldMap : NSObject

Overview

The session state in a world map includes ARKit's awareness of the physical space the user moves the device in (which ARKit uses to determine the device's position and orientation), as well as any ARAnchor objects added to the session (which can represent detected real-world features or virtual content placed by your app).

Serialize and Deserialize a World Map

When your app is quitting, you can save the current world map (acquired using getCurrentWorldMap(completionHandler:)). Because ARWorldMap conforms to NSSecureCoding, you serialize it using NSKeyedArchiver.

func writeWorldMap(_ worldMap: ARWorldMap, to url: URL) throws {
    let data = try NSKeyedArchiver.archivedData(withRootObject: worldMap, requiringSecureCoding: true)
    try data.write(to: url)
}

To restore the world map the next time your app launches, use NSKeyedUnarchiver.

func loadWorldMap(from url: URL) throws -> ARWorldMap {
    let mapData = try Data(contentsOf: url)
    guard let worldMap = try NSKeyedUnarchiver.unarchivedObject(ofClass: ARWorldMap.self, from: mapData)
        else { throw ARError(.invalidWorldMap) }
    return worldMap
}

You can use anchors from a resumed world map to place the same virtual content at the same positions from the saved session, if the app is launched in the same physical environment.

For more information, see Saving and Loading World Data.

Share a Saved World Map

With two devices tracking the same world map, you can build a networked experience where both users can see and interact with the same virtual content. To send an ARWorldMap to another device, creating a shared frame of reference for multiuser AR experiences:

  1. On one device, use NSKeyedArchiver as in to convert the world map to a data object. (You don't need to write the data to a file to send it over the network.)

  2. Use the networking technology of your choice to send the resulting data to another device. (For example, in a MultipeerConnectivity session, call send(_:toPeers:with:) to send data, and implement MCSessionDelegate methods on the other device to receive data.)

  3. On the receiving device, use NSKeyedUnarchiver as in to instantiate an ARWorldMap from the data.

For more information, see Creating a Multiuser AR Experience.

Run a Deserialized World Map

To begin a new session from an existing ARWorldMap, set a world tracking configuration's initialWorldMap property and use run(_:options:). This starts a new session using the same spatial awareness and anchors loaded from the saved world map.

Topics

Examining a World Map

var anchors: [ARAnchor]

The set of anchors recorded in the world map.

var center: simd_float3

The center point of the world map's space-mapping data, relative to the world coordinate origin of the session the map was recorded in.

var extent: simd_float3

The size of the world map's space-mapping data, relative to the world coordinate origin of the session the map was recorded in.

Debugging a World Map

var rawFeaturePoints: ARPointCloud

A coarse representation of the space-mapping data recorded in the world map.

Relationships

Inherits From

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.

class ARCoachingOverlayView

A view that presents visual instructions that guide the user during session initialization and in limited tracking situations.

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.

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.