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 ArTrackingState AR_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:
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: