Thanks for tuning in to Google I/O! Watch AR content on-demand.

Earth


          public     class
          Earth

A Trackable implementation representing the Earth. Provides localization ability in Earth-relative coordinates.

To access Earth, configure the session with an appropriate Config.GeospatialMode and use Session.getEarth().

Not all devices support Config.GeospatialMode.ENABLED, use Session.isGeospatialModeSupported(Config.GeospatialMode) to check if the current device and selected camera support enabling this mode.

The Earth object should only be used when its TrackingState is TrackingState.TRACKING, and otherwise should not be used. Use getTrackingState() to obtain the current TrackingState. If the TrackingState does not become TrackingState.TRACKING, then getEarthState() may contain more information in a Earth.EarthState.

Use getCameraGeospatialPose() to obtain the Earth-relative virtual camera pose for the latest frame.

Use createAnchor(double, double, double, float, float, float, float) to attach anchors to Earth. Calling createAnchor(Pose) on Earth will fail to create a new anchor and will throw IllegalArgumentException.

Earth does not support hit testing and will never be a result from Frame.hitTest(MotionEvent). Because Earth is a type of Trackable, the singleton Earth instance may also be returned by Session.getAllTrackables(Class) when enabled.

Nested Classes

enum Earth.EarthState Describes the current state of Earth.

Public Methods

`Anchor`	`createAnchor(Pose pose)` This method is deprecated. use `createAnchor(double, double, double, float, float, float, float)` instead.
`Anchor`	`createAnchor(double latitude, double longitude, double altitude, float[] rotation)` Creates a new `Anchor` at the specified geospatial location and orientation relative to the Earth.
`Anchor`	`createAnchor(double latitude, double longitude, double altitude, float qx, float qy, float qz, float qw)` Creates a new `Anchor` at the specified geospatial location and orientation relative to the Earth.
`boolean`	`equals(Object obj)` Indicates whether some other object is a `Trackable` referencing the same logical trackable as this one.
`Collection<Anchor>`	`getAnchors()` Gets the Anchors attached to this trackable.
`GeospatialPose`	`getCameraGeospatialPose()` Returns the `GeospatialPose` for the camera in the latest frame, describing the geospatial positioning of the device.
`Earth.EarthState`	`getEarthState()` Gets the current `Earth.EarthState` of the `Earth`.
`GeospatialPose`	`getGeospatialPose(Pose pose)` Converts the input pose to a `GeospatialPose` in the same position as the original `Pose`.
`Pose`	`getPose(double latitude, double longitude, double altitude, float qx, float qy, float qz, float qw)` Converts the input geospatial location and orientation relative to the Earth to a `Pose` in the same position.
`TrackingState`	`getTrackingState()` Gets the `TrackingState` of the Earth object as of the last frame.
`int`	`hashCode()` Returns a hash code value for the object.
`ResolveAnchorOnRooftopFuture`	`resolveAnchorOnRooftopAsync(double latitude, double longitude, double altitudeAboveRooftop, float qx, float qy, float qz, float qw, BiConsumer<Anchor, Anchor.RooftopAnchorState> callback)` Creates an anchor at a specified horizontal position and altitude relative to the horizontal position's rooftop.
`Anchor`	`resolveAnchorOnTerrain(double latitude, double longitude, double altitudeAboveTerrain, float qx, float qy, float qz, float qw)` This method is deprecated. Use `resolveAnchorOnTerrainAsync(double, double, double, float, float, float, float, BiConsumer)` instead.
`ResolveAnchorOnTerrainFuture`	`resolveAnchorOnTerrainAsync(double latitude, double longitude, double altitudeAboveTerrain, float qx, float qy, float qz, float qw, BiConsumer<Anchor, Anchor.TerrainAnchorState> callback)` Asynchronously creates a new `Anchor` at a specified horizontal position and altitude relative to the horizontal position's terrain.

Inherited Methods

From

class
            java.lang.Object

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

From

interface
            com.google.ar.core.Trackable

`abstract Anchor`	`createAnchor(Pose pose)` Creates an anchor that is attached to this trackable, using the given initial pose in the world coordinate space.
`abstract Collection<Anchor>`	`getAnchors()` Gets the Anchors attached to this trackable.
`abstract TrackingState`	`getTrackingState()` Gets the TrackingState of this Trackable.

Public Methods

public Anchor createAnchor (Pose pose)

createAnchor

public Anchor createAnchor(
  Pose pose
)

This method was deprecated.
use createAnchor(double, double, double, float, float, float, float) instead.

Earth does not support creating an Anchor using a Pose. Use createAnchor(double, double, double, float, float, float, float) instead.

Details

Parameters

pose

public Anchor createAnchor (double latitude, double longitude, double altitude, float[] rotation)

createAnchor

public Anchor createAnchor(
  double latitude,
  double longitude,
  double altitude,
  float[] rotation
)

Creates a new Anchor at the specified geospatial location and orientation relative to the Earth.

Latitude and longitude are defined by the WGS84 specification, and the altitude value is defined by the elevation above the WGS84 ellipsoid in meters. To create an anchor using an altitude relative to the Earth's terrain instead of altitude above the WGS84 ellipsoid, use resolveAnchorOnTerrainAsync(double, double, double, float, float, float, float, BiConsumer).

The rotation quaternion provided is 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 tracking state will be TrackingState.PAUSED while Earth's getTrackingState() is TrackingState.PAUSED. Its tracking state will permanently become TrackingState.STOPPED if Session.configure(Config) sets the Geospatial mode to Config.GeospatialMode.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 throw IllegalArgumentException.

Details

Parameters

`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.
`rotation`	EUS (east-up-south) rotation quaternion in the order {x, y, z, w}.

Returns the anchor if successful; otherwise throws an exception.

Throws

`IllegalStateException`	if `Earth` is `TrackingState.STOPPED` due to `Config.GeospatialMode.DISABLED` configured on the `Session`. Reacquire `Earth` if geospatial mode was reenabled.
`IllegalArgumentException`	if `latitude` is outside the allowable range.
`NotTrackingException`	when localisation is not yet available.

public Anchor createAnchor (double latitude, double longitude, double altitude, float qx, float qy, float qz, float qw)

createAnchor

public Anchor createAnchor(
  double latitude,
  double longitude,
  double altitude,
  float qx,
  float qy,
  float qz,
  float qw
)

Creates a new Anchor at the specified geospatial location and orientation relative to the Earth.

An anchor's TrackingState will be TrackingState.PAUSED while getTrackingState() is TrackingState.PAUSED. Its tracking state will permanently become TrackingState.STOPPED if Session.configure(Config) sets the Geospatial mode to Config.GeospatialMode.DISABLED.

Details

Parameters

`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.
`qx`	The x component of the EUS (east-up-south) rotation quaternion.
`qy`	The y component of the EUS (east-up-south) rotation quaternion.
`qz`	The z component of the EUS (east-up-south) rotation quaternion.
`qw`	The w component of the EUS (east-up-south) rotation quaternion.

Returns the anchor if successful; otherwise throws an exception.

Throws

`IllegalStateException`	if `Earth` is `TrackingState.STOPPED` due to `Config.GeospatialMode.DISABLED` configured on the `Session`. Reacquire `Earth` if geospatial mode was reenabled.
`IllegalArgumentException`	if `latitude` is outside the allowable range.

public boolean equals (Object obj)

equals

public boolean equals(
  Object obj
)

Indicates whether some other object is a Trackable referencing the same logical trackable as this one.

Details

Parameters

obj the reference object with which to compare.

Returns true if this object is the same as the obj argument; false otherwise.

getAnchors

public Collection<Anchor> getAnchors()

Gets the Anchors attached to this trackable.

public GeospatialPose getCameraGeospatialPose ()

getCameraGeospatialPose

public GeospatialPose getCameraGeospatialPose()

Returns the GeospatialPose for the camera in the latest frame, describing the geospatial positioning of the device.

The orientation of the obtained GeospatialPose 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 getTrackingState() returns TrackingState.TRACKING, otherwise, the resulting GeospatialPose will contain invalid values.

Details

Throws

`IllegalStateException`	when `Session.getConfig()` does not have `Config.GeospatialMode.ENABLED` set.
`NotTrackingException`	when localisation is not yet available.

public Earth.EarthState getEarthState ()

getEarthState

public Earth.EarthState getEarthState()

Gets the current Earth.EarthState of the Earth.

This state is guaranteed not to change until Session.update() is called.

public GeospatialPose getGeospatialPose (Pose pose)

getGeospatialPose

public GeospatialPose getGeospatialPose(
  Pose pose
)

Converts the input pose to a GeospatialPose in the same position as the original Pose.

Earth's current tracking state must be TrackingState.TRACKING in order to obtain a value from this function Otherwise, a NotTrackingException may be thrown.

The returned GeospatialPose does not contain a valid heading value. See GeospatialPose.getEastUpSouthQuaternion() to obtain an orientation in 3D space.

Details

Parameters

pose the Pose to be converted into a GeospatialPose.

Returns the GeospatialPose in the same position.

Throws

NotTrackingException when Earth's current tracking state is not TrackingState.TRACKING.

public Pose getPose (double latitude, double longitude, double altitude, float qx, float qy, float qz, float qw)

getPose

public Pose getPose(
  double latitude,
  double longitude,
  double altitude,
  float qx,
  float qy,
  float qz,
  float qw
)

Converts the input geospatial location and orientation relative to the Earth to a Pose in the same position.

Earth's current tracking state must be TrackingState.TRACKING in order to obtain a value from this function. Otherwise, a NotTrackingException may be thrown.

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

Details

Parameters

`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.
`qx`	The x component of the EUS (east-up-south) rotation quaternion.
`qy`	The y component of the EUS (east-up-south) rotation quaternion.
`qz`	The z component of the EUS (east-up-south) rotation quaternion.
`qw`	The w component of the EUS (east-up-south) rotation quaternion.

Returns the Pose in the same position in gl world coordinate.

Throws

`NotTrackingException`	when `Earth's` current `tracking state` is not `TrackingState.TRACKING`.
`IllegalArgumentException`	if `latitude` is outside the allowable range.

public TrackingState getTrackingState ()

getTrackingState

public TrackingState getTrackingState()

Gets the TrackingState of the Earth object as of the last frame.

public int hashCode ()

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

Details
Returns	a hash code value for this object.
See Also	`equals(Object)`

public ResolveAnchorOnRooftopFuture resolveAnchorOnRooftopAsync (double latitude, double longitude, double altitudeAboveRooftop, float qx, float qy, float qz, float qw, BiConsumer<Anchor, Anchor.RooftopAnchorState> callback)

resolveAnchorOnRooftopAsync

public ResolveAnchorOnRooftopFuture resolveAnchorOnRooftopAsync(
  double latitude,
  double longitude,
  double altitudeAboveRooftop,
  float qx,
  float qy,
  float qz,
  float qw,
  BiConsumer<Anchor, Anchor.RooftopAnchorState> callback
)

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 altitudeAboveRooftop 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 Future 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 throw ResourceExhaustedException.

Creating a Rooftop anchor requires an active Earth which is Earth.EarthState.ENABLED. If it is not, then this function throws IllegalStateException. 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.

A Rooftop anchor's tracking state will be TrackingState.PAUSED while Earth's getTrackingState() is TrackingState.PAUSED. Its tracking state will permanently become TrackingState.STOPPED if Session.configure(Config) is used to set Config.GeospatialMode.DISABLED.

Latitude and longitude are defined by the WGS84 specification.

Details

Parameters

`latitude`	The latitude of the anchor relative to the WGS84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS84 ellipsoid.
`altitudeAboveRooftop`	The altitude of the anchor above the Earth's rooftop.
`qx`	The x component of the EUS (east-up-south) rotation quaternion.
`qy`	The y component of the EUS (east-up-south) rotation quaternion.
`qz`	The z component of the EUS (east-up-south) rotation quaternion.
`qw`	The w component of the EUS (east-up-south) rotation quaternion.
`callback`	An optional callback, called when the operation is finished, unless the future is cancelled. May be null.

Returns A handler that can be polled or cancelled.

Throws

`IllegalStateException`	if `Earth` is `TrackingState.STOPPED` due to `Config.GeospatialMode.DISABLED` configured on the `Session`. Reacquire `Earth` if the Geospatial mode was re-enabled.
`IllegalArgumentException`	if `latitude` is outside the allowable range.
`NotTrackingException`	when localisation is not yet available.
`ResourceExhaustedException`	if too many Terrain and Rooftop anchors have already been held.

public Anchor resolveAnchorOnTerrain (double latitude, double longitude, double altitudeAboveTerrain, float qx, float qy, float qz, float qw)

resolveAnchorOnTerrain

public Anchor resolveAnchorOnTerrain(
  double latitude,
  double longitude,
  double altitudeAboveTerrain,
  float qx,
  float qy,
  float qz,
  float qw
)

This method was deprecated.
Use resolveAnchorOnTerrainAsync(double, double, double, float, float, float, float, BiConsumer) instead.

Creates a new 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. If the altitude relative to the WGS84 ellipsoid is known, use createAnchor(Pose) instead.

The specified altitudeAboveTerrain is interpreted to be relative to the Earth's terrain (or floor) at the specified latitude/longitude geospatial coordinates, rather than relative to the WGS84 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 Anchor 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 throw ResourceExhaustedException.

The returned Anchor will have its Anchor.TerrainAnchorState set to Anchor.TerrainAnchorState.TASK_IN_PROGRESS, and its TrackingState will be TrackingState.PAUSED. The anchor will remain in this state until its pose has been successfully resolved. If the resolving task results in an error, the anchor's TrackingState will be permanently set to TrackingState.STOPPED, and Anchor.getTerrainAnchorState() will contain a Anchor.TerrainAnchorState detailing error information.

Creating a Terrain anchor requires an active Earth which is Earth.EarthState.ENABLED. If it is not, then this function throws IllegalStateException. 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.

A Terrain anchor's tracking state will be TrackingState.PAUSED while Earth's getTrackingState() is TrackingState.PAUSED. Its tracking state will permanently become TrackingState.STOPPED if Session.configure(Config) is used to set Config.GeospatialMode.DISABLED.

Latitude and longitude are defined by the WGS84 specification.

Details

Parameters

`latitude`	The latitude of the anchor relative to the WGS84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS84 ellipsoid.
`altitudeAboveTerrain`	The altitude of the anchor above the Earth's terrain (or floor).
`qx`	The x component of the EUS (east-up-south) rotation quaternion.
`qy`	The y component of the EUS (east-up-south) rotation quaternion.
`qz`	The z component of the EUS (east-up-south) rotation quaternion.
`qw`	The w component of the EUS (east-up-south) rotation quaternion.

Returns the anchor if successful; otherwise throws an exception.

Throws

`IllegalStateException`	if `Earth` is `TrackingState.STOPPED` due to `Config.GeospatialMode.DISABLED` configured on the `Session`. Reacquire `Earth` if geospatial mode was reenabled.
`IllegalArgumentException`	if `latitude` is outside the allowable range.
`NotTrackingException`	when localisation is not yet available.
`ResourceExhaustedException`	if too many terrain anchors have already been held.

public ResolveAnchorOnTerrainFuture resolveAnchorOnTerrainAsync (double latitude, double longitude, double altitudeAboveTerrain, float qx, float qy, float qz, float qw, BiConsumer<Anchor, Anchor.TerrainAnchorState> callback)

resolveAnchorOnTerrainAsync

public ResolveAnchorOnTerrainFuture resolveAnchorOnTerrainAsync(
  double latitude,
  double longitude,
  double altitudeAboveTerrain,
  float qx,
  float qy,
  float qz,
  float qw,
  BiConsumer<Anchor, Anchor.TerrainAnchorState> callback
)

Asynchronously creates a new Anchor at a specified horizontal position and altitude relative to the horizontal position's terrain. See the Terrain anchors developer guide for more information.

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

Latitude and longitude are defined by the WGS84 specification.

Details

Parameters

`latitude`	The latitude of the anchor relative to the WGS84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS84 ellipsoid.
`altitudeAboveTerrain`	The altitude of the anchor above the Earth's terrain (or floor).
`qx`	The x component of the EUS (east-up-south) rotation quaternion.
`qy`	The y component of the EUS (east-up-south) rotation quaternion.
`qz`	The z component of the EUS (east-up-south) rotation quaternion.
`qw`	The w component of the EUS (east-up-south) rotation quaternion.
`callback`	The callback to invoke on the Main thread, if any.

Returns A handle to the async operation.

Throws

`IllegalStateException`	if `Earth` is `TrackingState.STOPPED` due to `Config.GeospatialMode.DISABLED` configured on the `Session`. Reacquire `Earth` if geospatial mode was reenabled.
`IllegalArgumentException`	if `latitude` is outside the allowable range.
`ResourceExhaustedException`	if too many anchors (counting both Terrain and Rooftop anchors) have already been held or are being resolved.