Geospatial anchors

A Geospatial anchor is a type of anchor that allows you to place 3D content at any given latitude, longitude, and altitude. It relies on a pose, or a position and orientation, to be placed in the real world. The position consists of a latitude, longitude, and altitude, which are specified in the WGS84 coordinate system. The orientation consists of a quaternion rotation.

Altitude is reported in meters above the reference WGS84 ellipsoid such that ground level is not at zero. Your app is responsible for providing these coordinates for each created anchor.

Prerequisites

Make sure that you enable the Geospatial API before proceeding.

Determine the latitude and longitude of a location

There are three ways you can calculate a location’s latitude and longitude:

  • Use Google Maps
  • Use Google Earth. Note that obtaining these coordinates using Google Earth, as opposed to Google Maps, will give you an error margin of up to several meters.
  • Go to the physical location

Use Google Maps

To get the latitude and longitude of a location using Google Maps:

  1. Go to Google Maps on your desktop computer.

  2. Navigate to Layers > More.

  3. Change the Map Type to Satellite and clear the Globe View checkbox at the bottom left corner of the screen.

    This will force a 2D perspective and eliminate possible errors that could come from an angled 3D view.

  4. On the map, right-click on the location and select the longitude/latitude to copy it to your clipboard.

Use Google Earth

You can calculate a location’s latitude and longitude from Google Earth by clicking a location in the UI and reading the data from placemark details.

To get the latitude and longitude of a location using Google Earth:

  1. Go to Google Earth on your desktop computer.
  2. Navigate to the hamburger menu and select Map Style.

  3. Toggle off the 3D Buildings switch.

  4. Once the 3D Buildings switch has been toggled off, click the pin icon to add a placemark at the selected location.

  5. Specify a project to contain your placemark and click Save.

  6. In the Title field for the placemark, enter a name for the placemark.

  7. Click the back arrow in the project pane and select the More Actions menu.

  8. Choose Export as KML file from the menu.

The KLM file reports the latitude, longitude, and altitude for a placemark in the <coordinates> tag separated by commas, as follows:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

Do not use the latitude and longitude from the <LookAt> tags, which specify the camera position, not the location.

Go to the physical location

You can calculate a location’s altitude by going there physically and doing a local observation.

Determine the altitude of a location

There are a few ways to determine a location’s altitude for placing anchors:

  • If the anchor's location is physically near the user, you can use an altitude that's similar to the altitude of the user’s device.
  • Once you have the latitude and longitude, use the Elevation API to get an elevation based on the EGM96 specification. You must convert the Maps API EGM96 elevation to WGS84 for comparison against the GeospatialPose altitude. See the GeoidEval that has both a command line and an HTML interface. The Maps API reports latitude and longitude according to the WGS84 specification out of the box.
  • You can obtain a location’s latitude, longitude, and altitude from Google Earth. This will give you an error margin of up to several meters. Use the latitude, longitude, and altitude from the <coordinates> tags, not the <LookAt> tags, in the KML file.
  • If an existing anchor is close by and if you are not on a steep incline, you may be able to use the altitude from the camera’s GeospatialPose without using another source, such as the Maps API.

Get the rotation quaternion

GeospatialPose.getEastUpSouthQuaternion() extracts the orientation from a Geospatial pose and outputs a quaternion that represents the rotation matrix transforming a vector from the target to the east-up-south (EUS) coordinate system. X+ points east, Y+ points up, and Z+ points south. Values are written in the order {x, y, z, w}.

Place a Geospatial anchor in the real world

Once you have the latitude, longitude, altitude, and rotation quaternion, use Earth.createAnchor() to anchor content to geographical coordinates that you specify.

Java

if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  Anchor anchor =
      earth.createAnchor(
          /* Locational values */
          latitude,
          longitude,
          altitude,
          /* Rotational pose values */
          qx,
          qy,
          qz,
          qw);
  // TODO: Attach content to the anchor specified by geodetic location and pose.
}

Kotlin

if (earth.trackingState == TrackingState.TRACKING) {
  val anchor =
    earth.createAnchor(
      /* Locational values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw
    )
  // TODO: Attach content to the anchor specified by geodetic location and pose.
}

Get a Geospatial pose from an AR pose

Earth.getGeospatialPose() provides an additional way to determine the latitude and longitude by converting an AR pose to a Geospatial pose.

Get an AR pose from a Geospatial pose

Earth.getPose() converts an Earth-specified horizontal position, altitude, and quaternion rotation with respect to an east-up-south coordinate frame to an AR pose with respect to the GL world coordinate.

What's next

  • Check out Terrain anchors, a type of Geospatial anchor that can be placed using only latitude and longitude coordinates.