ArEarth

A ArTrackable implementation representing the Earth.

Provides localization ability in geospatial coordinates.

To access ArEarth, configure the session with an appropriate ArGeospatialMode and use ArSession_acquireEarth.

Not all devices support AR_GEOSPATIAL_MODE_ENABLED, use ArSession_isGeospatialModeSupported to check if the current device and selected camera support enabling this mode.

ArEarth should only be used when its ArTrackingState is AR_TRACKING_STATE_TRACKING, and otherwise should not be used. Use ArTrackable_getTrackingState to obtain the current ArTrackingState. If the ArTrackingState does not become AR_TRACKING_STATE_TRACKING, then ArEarth_getEarthState may contain more information as ArEarthState.

Use ArEarth_getCameraGeospatialPose to obtain the Earth-relative virtual camera pose for the latest frame.

Use ArEarth_acquireNewAnchor to attach anchors to Earth. Calling ArTrackable_acquireNewAnchor with an ArEarth instance will fail to create a new anchor and will return the AR_ERROR_INVALID_ARGUMENT error code.

ArEarth does not support hit testing. Because ArEarth is a type of ArTrackable, the singleton ArEarth instance may also be returned by ArSession_getAllTrackables when enabled.

Summary

Enumerations
`ArEarthState{ AR_EARTH_STATE_ENABLED = 0, AR_EARTH_STATE_ERROR_INTERNAL = -1, AR_EARTH_STATE_ERROR_GEOSPATIAL_MODE_DISABLED = -2, AR_EARTH_STATE_ERROR_NOT_AUTHORIZED = -3, AR_EARTH_STATE_ERROR_RESOURCE_EXHAUSTED = -4, AR_EARTH_STATE_ERROR_APK_VERSION_TOO_OLD = -5 }`	enum Describes the current state of `ArEarth`.

Typedefs
`ArEarth`	typedef `struct ArEarth_` The Earth trackable (reference type, long-lived).

Functions
`ArEarth_acquireNewAnchor(ArSession session, ArEarth earth, double latitude, double longitude, double altitude, const float eus_quaternion_4, ArAnchor *out_anchor)`	`ArStatus` Creates a new `ArAnchor` at the specified geodetic location and orientation relative to the Earth.
`ArEarth_getCameraGeospatialPose(const ArSession session, const ArEarth earth, ArGeospatialPose *out_camera_geospatial_pose)`	`void` Returns the Earth-relative camera pose for the latest frame.
`ArEarth_getEarthState(const ArSession session, const ArEarth earth, ArEarthState *out_state)`	`void` Gets the current `ArEarthState` of the `ArEarth`.
`ArEarth_getGeospatialPose(const ArSession session, const ArEarth earth, const ArPose pose, ArGeospatialPose out_geospatial_pose)`	`ArStatus` Converts the provided `pose` to a `ArGeospatialPose` with respect to the Earth.
`ArEarth_getPose(const ArSession session, const ArEarth earth, double latitude, double longitude, double altitude, const float eus_quaternion_4, ArPose out_pose)`	`ArStatus` Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a pose with respect to GL world coordinates.
`ArEarth_resolveAnchorOnRooftopAsync(ArSession session, ArEarth earth, double latitude, double longitude, double altitude_above_rooftop, const float eus_quaternion_4, void context, ArResolveAnchorOnRooftopCallback callback, ArResolveAnchorOnRooftopFuture **out_future)`	`ArStatus` Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s rooftop.
`ArEarth_resolveAnchorOnTerrainAsync(ArSession session, ArEarth earth, double latitude, double longitude, double altitude_above_terrain, const float eus_quaternion_4, void context, ArResolveAnchorOnTerrainCallback callback, ArResolveAnchorOnTerrainFuture **out_future)`	`ArStatus` Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s terrain.
`ArEarth_resolveAndAcquireNewAnchorOnTerrain(ArSession session, ArEarth earth, double latitude, double longitude, double altitude_above_terrain, const float eus_quaternion_4, ArAnchor *out_anchor)`	`ArStatus` Deprecated. Use `ArEarth_resolveAnchorOnTerrainAsync` instead. Creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s terrain.

Enumerations

ArEarthState

 ArEarthState

Describes the current state of ArEarth.

When ArTrackable_getTrackingState does not become AR_TRACKING_STATE_TRACKING, ArEarthState may contain the cause of this failure.

Obtain using ArEarth_getEarthState.

Properties
`AR_EARTH_STATE_ENABLED`	`ArEarth` is enabled, and has not encountered any problems. Check `ArTrackable_getTrackingState` to determine if it can be used.
`AR_EARTH_STATE_ERROR_APK_VERSION_TOO_OLD`	The APK is older than the supported version.
`AR_EARTH_STATE_ERROR_GEOSPATIAL_MODE_DISABLED`	The given `ArEarth` is no longer valid and has `ArTrackingStateAR_TRACKING_STATE_STOPPED` due to `AR_GEOSPATIAL_MODE_DISABLED` being set on the `ArSession`. The given `ArEarth` object should be released by calling `ArTrackable_release`.
`AR_EARTH_STATE_ERROR_INTERNAL`	Earth localization has encountered an internal error. The app should not attempt to recover from this error. Please see the Android logs for additional information.
`AR_EARTH_STATE_ERROR_NOT_AUTHORIZED`	The authorization provided by the application is not valid. The Google Cloud project may not have enabled the ARCore API. When using API key authentication, this will happen if the API key in the manifest is invalid or unauthorized. It may also fail if the API key is restricted to a set of apps not including the current one. When using keyless authentication, this may happen when no OAuth client has been created, or when the signing key and package name combination does not match the values used in the Google Cloud project. It may also fail if Google Play Services isn't installed, is too old, or is malfunctioning for some reason (e.g. killed due to memory pressure).
`AR_EARTH_STATE_ERROR_RESOURCE_EXHAUSTED`	The application has exhausted the quota allotted to the given Google Cloud project. The developer should request additional quota for the ARCore API for their project from the Google Cloud Console.

Typedefs

ArEarth

struct ArEarth_ ArEarth

The Earth trackable (reference type, long-lived).

Trackable type: AR_TRACKABLE_EARTH
Acquire with: ArSession_acquireEarth
Release with: ArTrackable_release

Functions

ArEarth_acquireNewAnchor

ArStatus ArEarth_acquireNewAnchor(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude,
  const float *eus_quaternion_4,
  ArAnchor **out_anchor
)

Creates a new ArAnchor at the specified geodetic location and orientation relative to the Earth.

Latitude and longitude are defined by the WGS84 specification, and altitude values are defined as the elevation above the WGS84 ellipsoid in meters.

The rotation provided by eus_quaternion_4 is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

An anchor's ArTrackingState will be AR_TRACKING_STATE_PAUSED while ArEarth is AR_TRACKING_STATE_PAUSED. The tracking state will permanently become AR_TRACKING_STATE_STOPPED if the ArSession configuration is set to AR_GEOSPATIAL_MODE_DISABLED.

Creating anchors near the north pole or south pole is not supported. If the latitude is within 0.1 degrees of the north pole or south pole (90 degrees or -90 degrees), this function will return AR_ERROR_INVALID_ARGUMENT and the anchor will fail to be created.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`latitude`	The latitude of the anchor relative to the WGS84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS84 ellipsoid.
`altitude`	The altitude of the anchor relative to the WGS84 ellipsoid, in meters.
`eus_quaternion_4`	The rotation quaternion as {qx, qy, qx, qw}.
`out_anchor`	The newly-created `ArAnchor`. This will be set to `NULL` if no anchor was created.

Returns

AR_SUCCESS or any of:

AR_ERROR_ILLEGAL_STATE if earth is AR_TRACKING_STATE_STOPPED due to AR_GEOSPATIAL_MODE_DISABLED configured on the ArSession. Reacquire ArEarth if earth mode was reenabled.
AR_ERROR_INVALID_ARGUMENT if latitude is outside the allowable range, or if either session, earth, or eus_quaternion_4 is NULL.

ArEarth_getCameraGeospatialPose

void ArEarth_getCameraGeospatialPose(
  const ArSession *session,
  const ArEarth *earth,
  ArGeospatialPose *out_camera_geospatial_pose
)

Returns the Earth-relative camera pose for the latest frame.

The orientation of the obtained ArGeospatialPose 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.

Note: This pose is only valid when ArTrackable_getTrackingState is AR_TRACKING_STATE_TRACKING. Otherwise, the resulting ArGeospatialPose will contain default values.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` object.
`out_camera_geospatial_pose`	Pointer to a `ArGeospatialPose` to receive the Geospatial pose.

ArEarth_getEarthState

void ArEarth_getEarthState(
  const ArSession *session,
  const ArEarth *earth,
  ArEarthState *out_state
)

Gets the current ArEarthState of the ArEarth.

This state is guaranteed not to change until ArSession_update is called.

Details

Parameters

`session`	The ARCore session.
`earth`	The earth object.
`out_state`	The current state of `ArEarth`.

ArEarth_getGeospatialPose

ArStatus ArEarth_getGeospatialPose(
  const ArSession *session,
  const ArEarth *earth,
  const ArPose *pose,
  ArGeospatialPose *out_geospatial_pose
)

Converts the provided pose to a ArGeospatialPose with respect to the Earth.

The out_geospatial_pose's rotation quaternion is a rotation with respect to an East-Up-South coordinate frame. An identity quaternion will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

The heading value for a ArGeospatialPose obtained by this function will be 0. See ArGeospatialPose_getEastUpSouthQuaternion for an orientation in 3D space.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`pose`	The local pose to translate to an Earth pose.
`out_geospatial_pose`	Pointer to a `ArGeospatialPose` that receives the Geospatial pose.

Returns

AR_SUCCESS, or any of:

AR_ERROR_NOT_TRACKING if the Earth's tracking state is not AR_TRACKING_STATE_TRACKING.
AR_ERROR_INVALID_ARGUMENT if any of the parameters are null.

ArEarth_getPose

ArStatus ArEarth_getPose(
  const ArSession *session,
  const ArEarth *earth,
  double latitude,
  double longitude,
  double altitude,
  const float *eus_quaternion_4,
  ArPose *out_pose
)

Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a pose with respect to GL world coordinates.

Position near the north pole or south pole is not supported. If the latitude is within 0.1 degrees of the north pole or south pole (90 degrees or -90 degrees), this function will return AR_ERROR_INVALID_ARGUMENT.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`latitude`	The latitude of the anchor relative to the WGS84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS84 ellipsoid.
`altitude`	The altitude of the anchor relative to the WGS84 ellipsoid, in meters.
`eus_quaternion_4`	The rotation quaternion as {qx, qy, qx, qw}.
`out_pose`	A pointer to `ArPose` of the local pose with the latest frame.

Returns

AR_SUCCESS, or any of:

AR_ERROR_NOT_TRACKING if the Earth's tracking state is not AR_TRACKING_STATE_TRACKING.
AR_ERROR_INVALID_ARGUMENT, if any of the parameters are null or latitude is outside the allowable range.

ArEarth_resolveAnchorOnRooftopAsync

ArStatus ArEarth_resolveAnchorOnRooftopAsync(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_rooftop,
  const float *eus_quaternion_4,
  void *context,
  ArResolveAnchorOnRooftopCallback callback,
  ArResolveAnchorOnRooftopFuture **out_future
)

Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s rooftop.

See the Rooftop anchors developer guide for more information.

The specified altitude_above_rooftop is interpreted to be relative to the top of a building at the given horizontal location, rather than relative to the WGS84 ellipsoid. If there is no building at the given location, then the altitude is interpreted to be relative to the terrain instead. Specifying an altitude of 0 will position the anchor directly on the rooftop whereas specifying a positive altitude will position the anchor above the rooftop, against the direction of gravity.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See ArFuture for information on obtaining results and cancelling the operation.

You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain and Rooftop anchors at time. Attempting to resolve more than 100 Terrain or Rooftop anchors will result in resolve calls returning status AR_ERROR_RESOURCE_EXHAUSTED.

Creating a Rooftop anchor requires an active ArEarth for which the ArEarthState is AR_EARTH_STATE_ENABLED and ArTrackingState is AR_TRACKING_STATE_TRACKING. If it is not, then this function returns AR_ERROR_ILLEGAL_STATE. This call also requires a working internet connection to communicate with the ARCore API on Google Cloud. ARCore will continue to retry if it is unable to establish a connection to the ARCore service.

Latitude and longitude are defined by the WGS84 specification.

To create an anchor that has the +Z axis pointing in the same direction as heading obtained from ArGeospatialPose, use the following formula:

{qx, qy, qz, qw} = {0, sin((pi - heading * M_PI / 180.0) / 2), 0, cos((pi -
heading * M_PI / 180.0) / 2)}}.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`latitude`	The latitude of the anchor relative to the WGS-84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS-84 ellipsoid.
`altitude_above_rooftop`	The altitude of the anchor above the Earth's rooftop.
`eus_quaternion_4`	The rotation quaternion as {qx, qy, qx, qw}.
`context`	An optional void pointer passed when using a callback.
`callback`	A callback function.
`out_future`	An optional `ArFuture` which can be polled.

Returns

AR_SUCCESS or any of:

AR_ERROR_ILLEGAL_STATE if earth is AR_TRACKING_STATE_STOPPED and ArEarthState is not AR_EARTH_STATE_ENABLED due to AR_GEOSPATIAL_MODE_DISABLED configured on the ArSession. Reacquire ArEarth if geospatial mode was reenabled.
AR_ERROR_INVALID_ARGUMENT if latitude is outside the allowable range, or if either session, earth, or eus_quaternion_4 is NULL, or both callback and out_future are null.
AR_ERROR_RESOURCE_EXHAUSTED if too many Rooftop and Terrain anchors are currently held.

ArEarth_resolveAnchorOnTerrainAsync

ArStatus ArEarth_resolveAnchorOnTerrainAsync(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_terrain,
  const float *eus_quaternion_4,
  void *context,
  ArResolveAnchorOnTerrainCallback callback,
  ArResolveAnchorOnTerrainFuture **out_future
)

Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s terrain.

See the Terrain anchors developer guide for more information.

The specified altitude is interpreted to be relative to the Earth's terrain (or floor) at the specified latitude/longitude geodetic coordinates, rather than relative to the WGS-84 ellipsoid. Specifying an altitude of 0 will position the anchor directly on the terrain (or floor) whereas specifying a positive altitude will position the anchor above the terrain (or floor), against the direction of gravity.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See ArFuture for information on obtaining results and cancelling the operation.

Creating a terrain anchor requires an active ArEarth for which the ArEarthState is AR_EARTH_STATE_ENABLED and ArTrackingState is AR_TRACKING_STATE_TRACKING. If it is not, then this function returns AR_ERROR_ILLEGAL_STATE. This call also requires a working internet connection to communicate with the ARCore API on Google Cloud. ARCore will continue to retry if it is unable to establish a connection to the ARCore service.

Latitude and longitude are defined by the WGS84 specification.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`latitude`	The latitude of the anchor relative to the WGS-84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS-84 ellipsoid.
`altitude_above_terrain`	The altitude of the anchor above the Earth's terrain (or floor).
`eus_quaternion_4`	The rotation quaternion as {qx, qy, qx, qw}.
`context`	An optional void pointer passed when using a callback.
`callback`	A callback function.
`out_future`	An optional `ArFuture` which can be polled.

Returns

AR_SUCCESS or any of:

AR_ERROR_ILLEGAL_STATE if ArEarthState is not AR_EARTH_STATE_ENABLED.
AR_ERROR_INVALID_ARGUMENT if latitude is outside the allowable range, or if either session, earth, or eus_quaternion_4 is NULL, or both callback and out_future are NULL.
AR_ERROR_RESOURCE_EXHAUSTED if too many anchors (counting both Terrain and Rooftop anchors) are currently held or are being resolved.

ArEarth_resolveAndAcquireNewAnchorOnTerrain

ArStatus ArEarth_resolveAndAcquireNewAnchorOnTerrain(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_terrain,
  const float *eus_quaternion_4,
  ArAnchor **out_anchor
)

Creates an anchor at a specified horizontal position and altitude relative to the horizontal position’s terrain.

Terrain means the ground, or ground floor inside a building with VPS coverage. For areas not covered by VPS, consider using ArEarth_acquireNewAnchor to attach anchors to Earth.

This creates a new ArAnchor and schedules a task to resolve the anchor's pose using the given parameters. You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain anchors at time. Attempting to resolve more than 100 Terrain anchors will result in resolve calls returning status AR_ERROR_RESOURCE_EXHAUSTED.

If this function returns AR_SUCCESS, the terrain anchor state of out_terrain_anchor will be AR_TERRAIN_ANCHOR_STATE_TASK_IN_PROGRESS, and its tracking state will be AR_TRACKING_STATE_PAUSED. This anchor remains in this state until its pose has been successfully resolved. If the resolving task results in an error, the tracking state will be set to AR_TRACKING_STATE_STOPPED. If the return value is not AR_SUCCESS, then out_cloud_anchor will be set to NULL.

Latitude and longitude are defined by the WGS84 specification.

Deprecated. Use ArEarth_resolveAnchorOnTerrainAsync instead.

Details

Parameters

`session`	The ARCore session.
`earth`	The `ArEarth` handle.
`latitude`	The latitude of the anchor relative to the WGS-84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS-84 ellipsoid.
`altitude_above_terrain`	The altitude of the anchor above the Earth's terrain (or floor).
`eus_quaternion_4`	The rotation quaternion as {qx, qy, qx, qw}.
`out_anchor`	The newly-created anchor.

Returns

AR_SUCCESS or any of:

AR_ERROR_ILLEGAL_STATE if ArEarthState is not AR_EARTH_STATE_ENABLED.
AR_ERROR_INVALID_ARGUMENT if latitude is outside the allowable range, or if either session, earth, or eus_quaternion_4 is NULL.
AR_ERROR_RESOURCE_EXHAUSTED if too many terrain anchors are currently held.