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)
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)
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)
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)
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)
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) 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).

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:

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:

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:

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.

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.

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
out_future
An optional ArFuture which can be polled.
Returns
AR_SUCCESS or any of:

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.

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 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.

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.

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
out_future
An optional ArFuture which can be polled.
Returns
AR_SUCCESS or any of:

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.

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 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.

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.

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.

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: