Cloud Anchors developer guide for iOS

The ARCore SDK for iOS interfaces with ARKit to provide Cloud Anchor capabilities, letting you share anchors between iOS and Android devices in the same environment.

Learn how to use the ARCore Cloud Anchor API , or ARCore Cloud Anchor service, in your own apps.

Prerequisites

• Xcode version 13.0 or later
• Cocoapods 1.4.0 or later if using Cocoapods
• An ARKit-compatible Apple device running iOS 12.0 or later (deployment target of iOS 12.0 or later required)

If you are new to Cloud Anchors:

• Make sure that you understand the process used to host and resolve a Cloud Anchor .

• Read through the quickstart for system requirements, setup, and installation instructions.

• Check out one of the Cloud Anchor samples

Enable Cloud Anchors in your app

To use the Cloud Anchors API, you have to create a GARSessionConfiguration and set the cloudAnchorMode property for it, as described in Configure an ARCore session in iOS . Use setConfiguration:error: (GARSession) to set the configuration.

You must also enable the ARCore API for your application.

Host and resolve anchors

You can host and resolve cloud anchors with the ARCore Cloud Anchor API. The API includes callback methods for completed operations, as well as Future objects that can be polled.

Host an anchor

Hosting an ARAnchor puts the anchor in a common coordinate system for any given physical space.

A host request sends visual data to a Google server, which maps the ARAnchor ’s position in a coordinate system that represents the current physical space. A successful host request returns a new Cloud Anchor ID, which can be shared and used to resolve the anchor later.

  - 
 ( 
 void 
 ) 
 addAnchorWithTransform: 
 ( 
 matrix_float4x4 
 ) 
 transform 
  
 { 
  
 self 
 . 
 arAnchor 
  
 = 
  
 [[ 
 ARAnchor 
  
 alloc 
 ] 
  
 initWithTransform 
 : 
 transform 
 ]; 
  
 [ 
 self 
 . 
 sceneView 
 . 
 session 
  
 addAnchor 
 : 
 self 
 . 
 arAnchor 
 ]; 
  
 __weak 
  
 ExampleViewController 
  
 * 
 weakSelf 
  
 = 
  
 self 
 ; 
  
 self 
 . 
 hostFuture 
  
 = 
  
 [ 
 self 
 . 
 cloudAnchorManager 
  
 hostCloudAnchor 
 : 
 self 
 . 
 arAnchor 
  
 completion 
 : 
 ^ 
 ( 
 NSString 
  
 * 
 anchorId 
 , 
  
 GARCloudAnchorState 
  
 cloudState 
 ) 
  
 { 
  
 [ 
 weakSelf 
  
 handleHostAnchor 
 : 
 anchorId 
  
 cloudState 
 : 
 cloudState 
 ]; 
  
 } 
  
 error 
 : 
 nil 
 ]; 
  
 [ 
 self 
  
 enterState 
 : 
 HelloARStateHosting 
 ]; 
 } 
 

Resolve an anchor

Resolving an ARAnchor allows Android and iOS devices in a given physical space to add previously hosted anchors to new scenes.

A resolve request sends a Google server a cloud anchor ID along with visual data from the current frame. The server will attempt to match this visual data with the imagery of where currently hosted Cloud Anchors are mapped. When resolving succeeds, a new anchor is added to the session and returned.

  - 
 ( 
 void 
 ) 
 resolveAnchorWithIdentifier: 
 ( 
 NSString 
  
 * 
 ) 
 identifier 
  
 { 
  
 GARResolveCloudAnchorFuture 
  
 * 
 garFuture 
  
 = 
  
 [ 
 self 
 . 
 gSession 
  
 resolveCloudAnchorWithIdentifier 
 : 
 identifier 
  
 completionHandler 
 : 
 completion 
  
 error 
 : 
& error 
 ]; 
 } 
 // Pass the ARFRame to the ARCore session every time there is a frame update. 
 // This returns a GARFrame that contains a list of updated anchors. If your 
 // anchor's pose or tracking state changed, your anchor will be in the list. 
 - 
 ( 
 void 
 ) 
 cloudAnchorManager: 
 ( 
 CloudAnchorManager 
  
 * 
 ) 
 manager 
  
 didUpdateFrame: 
 ( 
 GARFrame 
  
 * 
 ) 
 garFrame 
  
 { 
  
 for 
  
 ( 
 GARAnchor 
  
 * 
 garAnchor 
  
 in 
  
 garFrame 
 . 
 updatedAnchors 
 ) 
  
 { 
  
 if 
  
 ([ 
 garAnchor 
  
 isEqual 
 : 
 self 
 . 
 garAnchor 
 ] 
 && 
 self 
 . 
 resolvedAnchorNode 
 ) 
  
 { 
  
 self 
 . 
 resolvedAnchorNode 
 . 
 simdTransform 
  
 = 
  
 garAnchor 
 . 
 transform 
 ; 
  
 self 
 . 
 resolvedAnchorNode 
 . 
 hidden 
  
 = 
  
 ! 
 garAnchor 
 . 
 hasValidTransform 
 ; 
  
 } 
  
 } 
 } 
 

Optional GARSession polling pattern

If you are using Metal or need a polling option, andyour app runs at a minimum of 30 fps, use the following pattern to pass ARFrame s to the GARSession :

  -( 
 void 
 ) 
 myOwnPersonalUpdateMethod 
  
 { 
  
 ARFrame 
  
 * 
 arFrame 
  
 = 
  
 arSession 
 . 
 currentFrame 
 ; 
  
 NSError 
  
 * 
 error 
  
 = 
  
 nil 
 ; 
  
 GARFrame 
  
 * 
 garFrame 
  
 = 
  
 [ 
 garSession 
  
 update 
 : 
 arFrame 
  
 error 
 : 
& error 
 ]; 
  
 // your update code here 
 } 
 

API quotas

The ARCore API has the following quotas for request bandwidth:

Known issues and workarounds

There are a few known issues when working with the ARCore SDK for iOS.

Default scheme settings cause intermittent app crash

GPU Frame Capture and Metal API Validation scheme settings are enabled by default, which can sometimes cause the app to crash within the SDK.

Diagnose an app crash

Whenever you suspect that a crash has occurred, take a look at your stack trace. If you see MTLDebugComputeCommandEncoder in the stack trace, it is likely due to the default scheme settings.

Workaround

1. Go to Product > Scheme > Edit Scheme… .

2. Open the Run tab.

3. Click Options to view your current settings.

4. Make sure that both GPU Frame Capture and Metal API Validation are disabled.

5. Build and run your app.

See the Cocoapods CHANGELOG for additional known issues.

Limitations

The ARCore SDK for iOS does not support the ARKit setWorldOrigin(relativeTransform:) method call.

Performance considerations

Memory usage increases when you enable the ARCore API. Expect the device’s battery usage to rise due to higher network usage and CPU utilization.

Next steps

• ARCore iOS reference documentation