Obtain the device camera's Geospatial pose

Once you have configured your app's settings to use the Geospatial API, you can call ArEarth_getCameraGeospatialPose to obtain a ArGeospatialPose that describes the device’s Geospatial positioning for the camera in the latest frame. This pose, managed in an ArEarth object, contains the following information:

  • Location, expressed in latitude and longitude
  • Altitude
  • An orientation approximating the direction the user is facing in the EUS coordinate system with X+ pointing east, Y+ pointing up, and Z+ pointing south

Check the tracking state

Geospatial values are only valid while ArEarth.ArTrackingState is ArTrackingState.AR_TRACKING_STATE_TRACKING and ArEarth.ArEarthState is AR_EARTH_STATE_ENABLED. Make sure to wrap all Geospatial API calls in a ArEarth.ArTrackingState control block.

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);
  }
}

If ArEarth.ArTrackingState does not become ArTrackingState.AR_TRACKING_STATE_TRACKING, ArEarth.ArTrackingState may be AR_TRACKING_STATE_PAUSED or AR_TRACKING_STATE_STOPPED. If neither of these conditions are true, check ArEarth.ArEarthState, which shows other error states that may keep the ArEarth object from tracking.

Adjust the pose for accuracy

When the device is upright in the default orientation, the pitch (X+) and roll (Z+) angles tend to be precise due to a natural alignment with AR tracking. However, the yaw (Y+) angles can vary depending on VPS data availability and temporal conditions at the location. Your app may have to make adjustments for accuracy.

ArGeospatialPose_getOrientationYawAccuracy() provides an accuracy estimate for the yaw (Y+) angles for a certain ArGeospatialPose. The orientation yaw accuracy is a number that describes the radius, in degrees, of the 68th percentile confidence level around the yaw angles returned from ArGeospatialPose_getEastUpSouthQuaternion(). In other words, there is a 68% chance that the ArGeospatialPose’s true yaw angle is accurate.

Larger values indicate lower accuracy. For example, if the estimated yaw angle is 60 degrees and the yaw accuracy is 10 degrees, then there is a 68% probability that the true yaw angle is between 50 and 70 degrees.

What's next