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{
|
enum Describes the current state of ArEarth . |
Typedefs |
|
---|---|
ArEarth
|
typedefstruct 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
|
Check |
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 The given |
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.
|
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 |
|
||||||||||||||
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 |
|
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 |
|
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 |
|
||||||||
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 |
|
||||||||||||||
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 |
|
||||||||||||||||||
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 |
|
||||||||||||||||||
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 |
|
||||||||||||||
Returns |
AR_SUCCESS or any of:
|