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(double latitude, double longitude, double altitude, float[] rotation)` Creates a new `Anchor` at the specified geodetic location and orientation relative to the Earth.
`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 qx, float qy, float qz, float qw)` Creates a new `Anchor` at the specified geodetic 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 geodetic positioning of the device.
`Earth.EarthState`	`getEarthState()` Gets the current `Earth.EarthState` of the `Earth`.
`TrackingState`	`getTrackingState()` Gets the `TrackingState` of the Earth object as of the last frame.
`int`	`hashCode()` Returns a hash code value for the object.

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 at the given pose in the world coordinate space that is attached to this trackable.
`abstract Collection<Anchor>`	`getAnchors()` Gets the Anchors attached to this trackable.
`abstract TrackingState`	`getTrackingState()` Gets the TrackingState of this Trackable.

Public Methods

createAnchor

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

Creates a new Anchor at the specified geodetic 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.

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.

To create an anchor that has the +Z axis pointing in the same direction as heading obtained from a GeospatialPose, use the following formula: {qx, qy, qz, qw} = {0, sin((pi - Math.toRadians(pose.getHeading())) / 2), 0, cos((pi - Math.toRadians(pose.getHeading())) / 2)}.

An anchor's tracking state will be TrackingState.PAUSED while getTrackingState() is TrackingState.PAUSED. The tracking state will permanently become TrackingState.STOPPED if the Session.configure(Config) is set 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 WGS-84 ellipsoid.
`longitude`	The longitude of the anchor relative to the WGS-84 ellipsoid.
`altitude`	The altitude of the anchor relative to the WGS-84 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.

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

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

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

Details

Parameters

`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`	The altitude of the anchor relative to the WGS-84 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.

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.

getCameraGeospatialPose

public GeospatialPose getCameraGeospatialPose()

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

The heading of the returned GeospatialPose approximates the direction the user is facing, specifically:

When the display is perpendicular to the ground, the back of the device points in the heading direction.
When the display is parallel to the ground and facing upward, heading is along the logical display's up direction, taking into account display rotation.
When the display is parallel to the ground and facing downward, heading is along the logical display's down direction.
In intermediate positions, the heading blends smoothly between the above behaviors.

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.

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.

getTrackingState

public TrackingState getTrackingState()

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

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

Earth

Nested Classes

Public Methods

Inherited Methods

Public Methods

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

createAnchor

public Anchor createAnchor (Pose pose)

createAnchor

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

createAnchor

public boolean equals (Object obj)

equals

public Collection<Anchor> getAnchors ()

getAnchors

public GeospatialPose getCameraGeospatialPose ()

getCameraGeospatialPose

public Earth.EarthState getEarthState ()

getEarthState

public TrackingState getTrackingState ()

getTrackingState

public int hashCode ()

hashCode