Obtain the device camera's Geospatial pose

Stay organized with collections Save and categorize content based on your preferences.

Once you have configured your app's settings to use the Geospatial API, you can obtain the device camera's GeospatialPose. This pose, managed in an Earth object, contains the following information:

  • Location, expressed in latitude and longitude. An estimate of the location accuracy is also supplied.
  • Altitude, and an estimate of the altitude's accuracy.
  • Heading, an approximation of the direction the device is facing, and an estimate of the accuracy of the heading.

To obtain the GeospatialPose, request the camera's pose relative to Earth while the Earth object is tracking:

Java

if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  GeospatialPose cameraGeospatialPose = earth.getCameraGeospatialPose();
  // cameraGeospatialPose contains geodetic location, rotation, and confidences values.
}

Kotlin

if (earth.trackingState == TrackingState.TRACKING) {
  val cameraGeospatialPose = earth.cameraGeospatialPose
  // cameraGeospatialPose contains geodetic location, rotation, and confidences values.
}

Check the tracking state of the Earth object

Geospatial values are only valid while Earth.TrackingState is TrackingState.TRACKING. Otherwise, TrackingState may be PAUSED or STOPPED. Always wrap your Geospatial API calls in a TrackingState control block, as shown below.

Java

Earth earth = session.getEarth();
if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  // Values obtained by the Geospatial API are valid as long as the Earth object has
  // TrackingState Tracking.
  // TODO: use Geospatial APIs in this block.
}

Kotlin

val earth = session.earth ?: return
if (earth.trackingState == TrackingState.TRACKING) {
  // Values obtained by the Geospatial API are valid as long as the Earth object has
  // TrackingState Tracking.
  // TODO: use Geospatial APIs in this block.
}

See also, Earth.Earthstate for other error states and conditions that may prevail. When Earth.getTrackingState() does not become TrackingState.TRACKING, Earth.EarthState may contain the cause of this failure.

Adjust for pose accuracy

As noted in the quickstart, the accuracy of the pose from the VPS may vary, due to the availability of VPS data for the location, or due to temporal conditions at the location. Your app may have to make adjustments for the accuracy of the pose, as determined by the Geospatial API.

The Geospatial API provides an estimate for the accuracy of the latitude/longitude, altitude, and heading values returned from the VPS.

For example, if the heading value returned from GeospatialPose.getHeading() is 60 degrees, and the value from GeospatialPose.getHeadingAccuracy() is 10, there is a 68% probability that the VPS heading is within 10 degrees of the observed heading, as illustrated in the diagram on the left.

Heading accuracy

If the value from GeospatialPose.getHeadingAccuracy() is 15, there is a 68% chance that the true heading is within 15 degrees of 60 degrees, as shown in the diagram on the right. Note that the higher the value returned from GeospatialPose.getHeadingAccuracy(), the lower the accuracy of the heading value from GeospatialPose.getHeading().

Similarly, GeospatialPose.getHorizontalAccuracy() reports the number of meters within which the true latitude/longitude value has a 68% probability of being within the given distance, and GeospatialPose.getVerticalAccuracy() reports the number of meters within which the true altitude value has a 68% probability of being within the given distance.

What's next