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 ArGeospatialPose. This pose, managed in an ArEarth 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 ArGeospatialPose, request the camera's pose relative to Earth while the ArEarth object is tracking:

if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArGeospatialPose* camera_geospatial_pose = NULL;
    ArGeospatialPose_create(ar_session, &camera_geospatial_pose);
    ArEarth_getCameraGeospatialPose(ar_session, ar_earth,
                                    camera_geospatial_pose);
    // camera_geospatial_pose contains geodetic location, rotation, and
    // confidences values.
    ArGeospatialPose_destroy(camera_geospatial_pose);
  }
}

Check the tracking state of the ArEarth object

Geospatial values are only valid while ArEarthState is AR_EARTH_STATE_ENABLED, and ArTrackingState is AR_TRACKING_STATE_TRACKING. Otherwise, ArTrackingState may be AR_TRACKING_STATE_PAUSED or AR_TRACKING_STATE_STOPPED. Always wrap your Geospatial API calls in an ArTrackingState control block, as shown below.

ArEarth* ar_earth = NULL;
ArSession_acquireEarth(ar_session, &ar_earth);
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    // Values obtained by the Geospatial API are valid as long as ArEarth
    // has AR_TRACKING_STATE_TRACKING.
    // TODO: use Geospatial APIs in this block.
  }
}

Note that when ArTrackable_getTrackingState does not become AR_TRACKING_STATE_TRACKING, ArEarthState 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 ArGeospatialPose_getHeading() is 60 degrees, and the value from ArGeospatialPose_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 ArGeospatialPose_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 ArGeospatialPose_getHeadingAccuracy(), the lower the accuracy of the heading value from ArGeospatialPose_getHeading().

Similarly, ArGeospatialPose_getHorizontalAccuracy() reports the number of meters within which the true latitude/longitude value has a 68% probability of being within the given distance, and ArGeospatialPose_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