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 CameraGeospatialPose. This pose, managed in an AREarthManager 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 CameraGeospatialPose, request the camera's pose relative to Earth while the TrackingState is Tracking

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
  // camera_geospatial_pose contains geodetic location, rotation, and
  // confidences values.
  var cameraGeospatialPose = EarthManager.CameraGeospatialPose;
}

Check the tracking state of the AREarthManager object

Geospatial values are only valid while TrackingState.EarthTrackingState is TrackingState.Tracking. Otherwise, TrackingState may be Limited or None. Always wrap your Geospatial API calls in a TrackingState control block, as shown below.

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
     // Values obtained by the Geospatial API are valid as long as
     // earthTrackingState is TrackingState.Tracking.
     // Use Geospatial APIs in this block.
}

See also, AREarthManager.EarthState for other error states and conditions that may prevail. When TrackingState is Limited or None, AREarthManager.EarthState may describe the cause of this failure.

Adjust for pose accuracy

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.Heading is 60 degrees, and the value from GeospatialPose.HeadingAccuracy 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.HeadingAccuracy 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.HeadingAccuracy, the lower the accuracy of the heading value from GeospatialPose.Heading.

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

What's next