# Geospatial

Artifact: [androidx.xr.arcore:arcore](https://developer.android.com/jetpack/androidx/releases/xr-arcore) [View Source](https://cs.android.com/search?q=file:androidx/xr/arcore/Geospatial.kt+class:androidx.xr.arcore.Geospatial) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

*** ** * ** ***


```
public final class Geospatial
```

<br />

*** ** * ** ***

Localization ability in Earth-relative coordinates.

To use the Geospatial object, configure the session with `https://developer.android.com/reference/androidx/xr/runtime/GeospatialMode#SPATIAL()`.

Not all devices support `https://developer.android.com/reference/androidx/xr/runtime/GeospatialMode#SPATIAL()`, use `https://developer.android.com/reference/androidx/xr/runtime/XrDevice#isGeospatialModeSupported(androidx.xr.runtime.GeospatialMode)` to check if the current device supports enabling this mode.

The Geospatial object should only be used when its `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State#geospatialTrackingState()` is `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.GeospatialTrackingState#RUNNING()`, and otherwise should not be used. Use `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#state()` to obtain the current `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State`.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/xr/arcore/Geospatial.GeospatialTrackingState` Describes the state of Geospatial. |
| `public final class https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State` State of Geospatial at a specific point in time. |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/VpsAvailabilityResult` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)(double latitude, double longitude)` Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createAnchor(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion)( double latitude, double longitude, double altitude, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Quaternion eastUpSouthQuaternion )` Creates a new `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at the specified geospatial location and orientation relative to the Earth. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createAnchorOnSurface(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion,androidx.xr.arcore.GeospatialSurface)( double latitude, double longitude, double altitudeAboveSurface, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Quaternion eastUpSouthQuaternion, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/GeospatialSurface surface )` Creates a new `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at a specified geospatial location. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose)` Converts the input `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` to a `https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose` in the same position as the original pose. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose geospatialPose)` Converts a geospatial location and orientation relative to the Earth to a `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` in the same position. |
| `boolean` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#equals(kotlin.Any)(https://developer.android.com/reference/java/lang/Object.html other)` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/Geospatial` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#getInstance(androidx.xr.runtime.Session)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session)` Returns the Geospatial object for the given `https://developer.android.com/reference/androidx/xr/runtime/Session`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State>` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#getState()()` the current `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State` of `https://developer.android.com/reference/androidx/xr/arcore/Geospatial` |
| `int` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#hashCode()()` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#toString()()` Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/Geospatial` for debugging. |

## Public methods

### checkVpsAvailability

```
public final @NonNull VpsAvailabilityResult checkVpsAvailability(double latitude, double longitude)
```

Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.

The Visual Positioning System (VPS) provides highly accurate global localization by matching features from the device's camera against Google's global database of 3D imagery. The availability of VPS in a given location helps to improve the quality of Geospatial localization and tracking accuracy.

This launches an asynchronous operation used to query the Google Cloud ARCore API. It may be called without calling `https://developer.android.com/reference/androidx/xr/runtime/Session#configure(androidx.xr.runtime.Config)`.

Your app must be properly set up to communicate with the Google Cloud ARCore API in order to obtain a result from this call, otherwise the result will be .

| Parameters |
|---|---|
| `double latitude` | the latitude in degrees |
| `double longitude` | the longitude in degrees |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/VpsAvailabilityResult` | the result of the VPS availability check |

### createAnchor

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
public final @NonNull AnchorResult createAnchor(
    double latitude,
    double longitude,
    double altitude,
    @NonNull Quaternion eastUpSouthQuaternion
)
```

Creates a new `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at the specified geospatial location and orientation relative to the Earth.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System), 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 `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createAnchorOnSurface(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion,androidx.xr.arcore.GeospatialSurface)`.

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.

The tracking state of an `https://developer.android.com/reference/androidx/xr/arcore/Anchor` will permanently become `https://developer.android.com/reference/androidx/xr/arcore/TrackingState#STOPPED()` if the `https://developer.android.com/reference/androidx/xr/runtime/GeospatialMode` is disabled, or if another full-space app uses Geospatial.

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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

| Parameters |
|---|---|
| `double latitude` | the latitude of the anchor |
| `double longitude` | the longitude of the anchor |
| `double altitude` | the altitude of the anchor |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Quaternion eastUpSouthQuaternion` | the rotation quaternion of the anchor |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | an `https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` with the result of the anchor creation |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the latitude is outside the allowable range |

### createAnchorOnSurface

```
public final @NonNull AnchorResult createAnchorOnSurface(
    double latitude,
    double longitude,
    double altitudeAboveSurface,
    @NonNull Quaternion eastUpSouthQuaternion,
    @NonNull GeospatialSurface surface
)
```

Creates a new `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at a specified geospatial location.

The specified `https://developer.android.com/reference/androidx/xr/arcore/Geospatial#createAnchorOnSurface(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion,androidx.xr.arcore.GeospatialSurface)` is interpreted to be relative to the given surface 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 surface whereas specifying a positive altitude will position the anchor above the surface, against the direction of gravity.

`https://developer.android.com/reference/androidx/xr/arcore/GeospatialSurface#TERRAIN()` refers to the Earth's terrain (or floor) and `https://developer.android.com/reference/androidx/xr/arcore/GeospatialSurface#ROOFTOP()` refers to the top of a building at the given horizontal location. If there is no building at the given location, then the rooftop surface is interpreted to be the terrain instead.

You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 surface anchors at time. Attempting to resolve more than 100 surface anchors will return an `https://developer.android.com/reference/androidx/xr/arcore/AnchorCreateResourcesExhausted` result.

Creating a Terrain anchor requires an active Earth which is `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.GeospatialTrackingState#RUNNING()`. If it is not, then this function returns an `https://developer.android.com/reference/androidx/xr/arcore/AnchorCreateTrackingUnavailable` result. 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 `https://developer.android.com/reference/androidx/xr/arcore/TrackingState#PAUSED()` if the Earth is not actively tracking. Its tracking state will permanently become `https://developer.android.com/reference/androidx/xr/arcore/TrackingState#STOPPED()` if `https://developer.android.com/reference/androidx/xr/runtime/GeospatialMode` is disabled, or if another full-space app uses Geospatial.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System), and the altitude value is defined by the elevation above the Earth's terrain (or floor) 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.

| Parameters |
|---|---|
| `double latitude` | the latitude of the anchor |
| `double longitude` | the longitude of the anchor |
| `double altitudeAboveSurface` | the altitude of the anchor above the given surface |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Quaternion eastUpSouthQuaternion` | the rotation quaternion of the anchor |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/GeospatialSurface surface` | the `https://developer.android.com/reference/androidx/xr/arcore/GeospatialSurface` on which to create the anchor |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | an `https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` with the result of the anchor creation |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the latitude is outside the allowable range |
| `AnchorUnsupportedLocationException` | if there is no information at the provided location |

### createGeospatialPoseFromPose

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
public final @NonNull CreateGeospatialPoseFromPoseResult createGeospatialPoseFromPose(@NonNull Pose pose)
```

Converts the input `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` to a `https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose` in the same position as the original pose.

This method may return a result if Geospatial is not currently tracking.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose` | the `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` to be converted into a `https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` | a `https://developer.android.com/reference/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` with the result of the conversion |

### createPoseFromGeospatialPose

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
public final @NonNull CreatePoseFromGeospatialPoseResult createPoseFromGeospatialPose(@NonNull GeospatialPose geospatialPose)
```

Converts a geospatial location and orientation relative to the Earth to a `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` in the same position.

This method may return a `https://developer.android.com/reference/androidx/xr/arcore/CreatePoseFromGeospatialPoseNotTracking` result if Geospatial is not currently tracking.

Positions 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 an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose geospatialPose` | the `https://developer.android.com/reference/androidx/xr/runtime/math/GeospatialPose` to be converted into a `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` | a `https://developer.android.com/reference/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` with the result of the conversion |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the latitude is within 0.1 degrees of the north pole or south pole (90 degrees or -90 degrees) |

### equals

```
public boolean equals(Object other)
```

### getInstance

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
public static final @NonNull Geospatial getInstance(@NonNull Session session)
```

Returns the Geospatial object for the given `https://developer.android.com/reference/androidx/xr/runtime/Session`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the `https://developer.android.com/reference/androidx/xr/runtime/Session` to get the `https://developer.android.com/reference/androidx/xr/arcore/Geospatial` object from |

### getState

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
public final @NonNull StateFlow<@NonNull Geospatial.State> getState()
```

the current `https://developer.android.com/reference/androidx/xr/arcore/Geospatial.State` of `https://developer.android.com/reference/androidx/xr/arcore/Geospatial`

### hashCode

```
public int hashCode()
```

### toString

```
public @NonNull String toString()
```

Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/Geospatial` for debugging.

Note: Not intended for production use.