# ArGeospatialPose
Describes a specific location, elevation, and compass heading relative to Earth ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).
It is comprised of:
- Latitude and longitude are specified in degrees, with positive values being north of the equator and east of the prime meridian as defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System).
- Altitude is specified in meters above the WGS84 ellipsoid, which is roughly equivalent to meters above sea level.
- Orientation approximates the direction the user is facing in the EUS coordinate system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south.
- Accuracy of the latitude, longitude, altitude, and heading are available as numeric confidence intervals where a large value (large interval) means low confidence and small value (small interval) means high confidence.
An `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` can be retrieved from `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getcamerageospatialpose`.
## Summary
| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` | typedef `struct ArGeospatialPose_` Describes a specific location, elevation, and orientation relative to Earth ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |
| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose **out_pose)` | `void` Allocates and initializes a new instance. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_destroy(https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *pose)` | `void` Releases memory used by the given `pose` object. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getaltitude(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_altitude_meters)` | `void` Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` altitude in meters as elevation above the [WGS84 ellipsoid](https://en.wikipedia.org/wiki/World_Geodetic_System). |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, float *out_quaternion_4)` | `void` Extracts the orientation from a Geospatial pose. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getheading(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_heading_degrees)` | `void` **[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** This function has been deprecated in favor of `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`, which provides orientation values in 3D space. To determine a value analogous to the heading value, calculate the yaw, pitch, and roll values from `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`. When the device is pointing downwards, i.e. perpendicular to the ground, heading is analoguous to roll, and when the device is upright in the device's default orientation mode, heading is analogous to yaw. Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` heading. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getheadingaccuracy(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_heading_accuracy_degrees)` | `void` **[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** This function has deprecated in favor of `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getorientationyawaccuracy`, which provides the accuracy analogous to the heading accuracy when the device is held upright in the default orientation mode. Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated heading accuracy. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_gethorizontalaccuracy(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_horizontal_accuracy_meters)` | `void` Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated horizontal accuracy in meters with respect to latitude and longitude. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getlatitudelongitude(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_latitude_degrees, double *out_longitude_degrees)` | `void` Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` latitude and longitude in degrees, with positive values being north of the equator and east of the prime meridian, as defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System). |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getorientationyawaccuracy(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_orientation_yaw_accuracy_degrees)` | `void` Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated orientation yaw angle accuracy. |
| `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getverticalaccuracy(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *geospatial_pose, double *out_vertical_accuracy_meters)` | `void` Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated altitude accuracy. |
## Typedefs
### ArGeospatialPose
```
struct ArGeospatialPose_ ArGeospatialPose
```
Describes a specific location, elevation, and orientation relative to Earth ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).
- Create with: `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_create`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_destroy`
## Functions
### ArGeospatialPose_create
```
void ArGeospatialPose_create(
const ArSession *session,
ArGeospatialPose **out_pose
)
```
Allocates and initializes a new instance.
This function may be used in cases where an instance of this type needs to be created to receive a pose. It must be destroyed with `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_destroy` after use.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | an `https://developers.google.com/ar/reference/c/group/ar-session#arsession` instance. | | `out_pose` | the new pose. | |
### ArGeospatialPose_destroy
```
void ArGeospatialPose_destroy(
ArGeospatialPose *pose
)
```
Releases memory used by the given `pose` object.
| Details ||
|---|---|
| Parameters | |---|---| | `pose` | the pose to destroy. | |
### ArGeospatialPose_getAltitude
```
void ArGeospatialPose_getAltitude(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_altitude_meters
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` altitude in meters as elevation above the [WGS84 ellipsoid](https://en.wikipedia.org/wiki/World_Geodetic_System).
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The Geospatial pose. | | `out_altitude_meters` | The altitude of the pose in meters above the WGS84 ellipsoid. | |
### ArGeospatialPose_getEastUpSouthQuaternion
```
void ArGeospatialPose_getEastUpSouthQuaternion(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
float *out_quaternion_4
)
```
Extracts the orientation from a Geospatial pose.
It represents rotation of the target with respect to the east-up-south coordinates. That is, X+ points east, Y+ points up, and Z+ points south. Right handed coordinate system.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The geospatial pose. | | `out_quaternion_4` | A pointer of 4 float values, which will store the quaternion values as \[x, y, z, w\]. | |
### ArGeospatialPose_getHeading
```
void ArGeospatialPose_getHeading(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_heading_degrees
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` heading.
This function will return valid values for `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` from `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getcamerageospatialpose` and returns 0 for all other `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` objects.
Heading is specified in degrees clockwise from true north and approximates the direction the device is facing. The value returned when facing north is 0°, when facing east is 90°, when facing south is +/-180°, and when facing west is -90°.
The heading approximation is based on the rotation of the device in its current orientation mode (i.e., portrait or landscape) and pitch. For example, when the device is held vertically or upright, the heading is based on the camera optical axis. If the device is held horizontally, looking downwards, the heading is based on the top of the device, with respect to the orientation mode.
Note: Heading is currently only supported in the device's default orientation mode, which is portrait mode for most supported devices.
**[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** This function has been deprecated in favor of `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`, which provides orientation values in 3D space. To determine a value analogous to the heading value, calculate the yaw, pitch, and roll values from `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`. When the device is pointing downwards, i.e. perpendicular to the ground, heading is analoguous to roll, and when the device is upright in the device's default orientation mode, heading is analogous to yaw.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The Geospatial pose. | | `out_heading_degrees` | The heading component of this pose's orientation in \[-180.0, 180.0\] degree range. | |
### ArGeospatialPose_getHeadingAccuracy
```
void ArGeospatialPose_getHeadingAccuracy(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_heading_accuracy_degrees
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated heading accuracy.
This function will return valid values for `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` from `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getcamerageospatialpose` and returns 0 for all other `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` objects.
We define heading accuracy as the estimated radius of the 68th percentile confidence level around `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getheading`. In other words, there is a 68% probability that the true heading is within `out_heading_accuracy_degrees` of this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` heading. Larger numbers indicate lower accuracy.
For example, if the estimated heading is 60°, and `out_heading_accuracy_degrees` is 10°, then there is a 68% probability of the true heading being between 50° and 70°.
**[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** This function has deprecated in favor of `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_getorientationyawaccuracy`, which provides the accuracy analogous to the heading accuracy when the device is held upright in the default orientation mode.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The geospatial pose. | | `out_heading_accuracy_degrees` | The accuracy of the heading confidence in degrees. | |
### ArGeospatialPose_getHorizontalAccuracy
```
void ArGeospatialPose_getHorizontalAccuracy(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_horizontal_accuracy_meters
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated horizontal accuracy in meters with respect to latitude and longitude.
We define horizontal accuracy as the radius of the 68th percentile confidence level around the estimated horizontal location. In other words, if you draw a circle centered at this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` latitude and longitude, and with a radius equal to the horizontal accuracy, then there is a 68% probability that the true location is inside the circle. Larger numbers indicate lower accuracy.
For example, if the latitude is 10, longitude is 10, and `out_horizontal_accuracy_meters` is 15, then there is a 68% probability that the true location is within 15 meters of the (10°, 10°) latitude/longitude coordinate.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The geospatial pose. | | `out_horizontal_accuracy_meters` | The estimated horizontal accuracy of this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose`, radial, in meters. | |
### ArGeospatialPose_getLatitudeLongitude
```
void ArGeospatialPose_getLatitudeLongitude(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_latitude_degrees,
double *out_longitude_degrees
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` latitude and longitude in degrees, with positive values being north of the equator and east of the prime meridian, as defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System).
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The geospatial pose. | | `out_latitude_degrees` | The latitude of the pose in degrees. | | `out_longitude_degrees` | The longitude of the pose in degrees. | |
### ArGeospatialPose_getOrientationYawAccuracy
```
void ArGeospatialPose_getOrientationYawAccuracy(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_orientation_yaw_accuracy_degrees
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated orientation yaw angle accuracy.
Yaw rotation is the angle between the pose's compass direction and north, and can be determined from `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`.
We define yaw accuracy as the estimated radius of the 68th percentile confidence level around yaw angles from `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion`. In other words, there is a 68% probability that the true yaw angle is within `out_orientation_yaw_accuracy_degrees` of this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` rotation. Larger numbers indicate lower accuracy.
For example, if the estimated yaw angle is 60°, and `out_orientation_yaw_accuracy_degrees` is 10°, then there is a 68% probability of the true yaw angle being between 50° and 70°.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The Geospatial pose. | | `out_orientation_yaw_accuracy_degrees` | The accuracy of the orientation confidence in degrees. | |
### ArGeospatialPose_getVerticalAccuracy
```
void ArGeospatialPose_getVerticalAccuracy(
const ArSession *session,
const ArGeospatialPose *geospatial_pose,
double *out_vertical_accuracy_meters
)
```
Gets the `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` estimated altitude accuracy.
We define vertical accuracy as the radius of the 68th percentile confidence level around the estimated altitude. In other words, there is a 68% probability that the true altitude is within `out_vertical_accuracy_meters` of this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` altitude (above or below). Larger numbers indicate lower accuracy.
For example, if this `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose's` altitude is 100 meters, and `out_vertical_accuracy_meters` is 20 meters, there is a 68% chance that the true altitude is within 20 meters of 100 meters.
| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `geospatial_pose` | The Geospatial pose. | | `out_vertical_accuracy_meters` | The estimated vertical accuracy in meters. | |