Geospatial quickstart for iOS

This quickstart for the ARCore Geospatial API shows you how to run a sample app in Xcode that demonstrates the Geospatial API.

For a guide to developing your own app with the Geospatial API, see the Geospatial developer guide for iOS.

See the Introduction to the ARCore Geospatial API for more information about the Geospatial API.

If you're new to developing with ARCore, see Getting started.

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)

Set up the sample app

The GeospatialExample project included with the ARCore SDK for iOS describes code that calls the Geospatial API.

  1. Clone or download the ARCore SDK for iOS from GitHub to obtain the sample app code.

  2. Open a Terminal or Finder window and navigate to the folder where you cloned or downloaded the SDK.

  3. Navigate to the arcore-ios-sdk-master/Examples folder.

  4. Open the Examples folder, select the GeospatialExample folder, and click Open.

Set up a Google Cloud Project

Before using the Visual Positioning System (VPS) in your app, you must first enable the ARCore API in a new or existing Google Cloud project. Though the Geospatial API works with both Keyless and API Key authorization, For this quickstart guide, use the API Key method.

Set up authorization

To make Geospatial API calls to the VPS, the sample app needs authorization, and may use an unrestricted API key. If you use a restricted API key, you must also provide a bundle ID to associate with the API key.

  1. In XCode, in the GeospatialExample sample app, open the ViewController.m file and search for your-api-key.

  2. Add your API key to the GARSession: paste the API key you copied from a previous step over the text, your-api-key (leave the quotes), as shown:

    self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];

Set up the ARCore SDK

The GeospatialExample app ships with a Podfile preconfigured with the ARCore SDK and iOS versions that you need. To install these dependencies, open a Terminal window and run pod install from the folder where the Xcode project exists.

This generates an .xcworkspace file that you'll use later to build and run the app.

Build and run the sample app

  1. In Xcode, select the GeospatialExample workspace file, and click Signing & Capabilities.

  2. Check the box, Automatically manage signing.

  3. In the Team field, enter a team name.

    You may use the default Bundle Identifier to run the app from Xcode, but you must change it if you use the GeospatialExample as a stub for your own app in production.

  4. Connect your device to run the sample app.

  5. Build and run the GeospatialExample app from the .xcworkspace file to launch it on your device.

    To avoid build errors, make sure you are building from the .xcworkspace file and not the .xcodeproj file.

You should be able to see a camera view, along with debug information describing the current Geospatial transform of your device. As you scan the environment around you, notice the positioning accuracy confidence values may change as you move around, if you're in an area supported by VPS localisation.

When ARCore is confident in your device's location and heading, you can place an Anchor at your current location using the Geospatial transform.

The positioning accuracy may be too low if VPS information is unavailable. The app must be connected to the internet, and the location must be known to the VPS. For best results, run the sample app outside (not indoors) during daylight hours.

Also, if you are in an area that does not support VPS, or if GPS signals aren't sufficient, you may need to adjust the confidence thresholds in the app in order to place an anchor.

To adjust the thresholds:

  1. In Xcode, open the ViewController.m file and browse to the following section:

    // Thresholds for 'good enough' accuracy. These can be tuned for the
// application. We use both 'low'
// and 'high' values here to avoid flickering state changes.
static const CLLocationAccuracy kHorizontalAccuracyLowThreshold = 10;
static const CLLocationAccuracy kHorizontalAccuracyHighThreshold = 20;
static const CLLocationDirectionAccuracy kHeadingAccuracyLowThreshold = 15;
static const CLLocationDirectionAccuracy kHeadingAccuracyHighThreshold = 25;

  2. Adjust these values as needed. The higher the value, the lower the accuracy.

    Lowering the accuracy allows the app greater latitude in placing an anchor. See Adjust for transform accuracy for more information.

Next steps

Review the Geospatial developer guide for iOS and get started building with the Geospatial API.