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

*** ** * ** ***


```
class Geospatial
```

<br />

*** ** * ** ***

Localization ability in Earth-relative coordinates.

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

Not all devices support `https://developer.android.com/reference/kotlin/androidx/xr/runtime/GeospatialMode#SPATIAL()`, use `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/arcore/Geospatial.State#geospatialTrackingState()` is `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.GeospatialTrackingState#RUNNING()`, and otherwise should not be used. Use `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#state()` to obtain the current `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.State`.

## Summary

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

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#getInstance(androidx.xr.runtime.Session)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session)` Returns the Geospatial object for the given `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session`. |

| ### Public functions |
|---|---|
| `suspend https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)(latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html)` Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createAnchor(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion)( latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, altitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, eastUpSouthQuaternion: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Quaternion )` Creates a new `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` at the specified geospatial location and orientation relative to the Earth. |
| `suspend https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createAnchorOnSurface(kotlin.Double,kotlin.Double,kotlin.Double,androidx.xr.runtime.math.Quaternion,androidx.xr.arcore.GeospatialSurface)( latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, altitudeAboveSurface: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html, eastUpSouthQuaternion: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Quaternion, surface: https://developer.android.com/reference/kotlin/androidx/xr/arcore/GeospatialSurface )` Creates a new `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` at a specified geospatial location. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)(pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose)` Converts the input `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` to a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/GeospatialPose` in the same position as the original pose. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)(geospatialPose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/GeospatialPose)` Converts a geospatial location and orientation relative to the Earth to a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` in the same position. |
| `open operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#equals(kotlin.Any)(other: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#hashCode()()` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#toString()()` Returns a string representation of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial` for debugging. |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.State>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#state()` the current `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.State` of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial` |

## Public companion functions

### getInstance

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

```
fun getInstance(session: Session): Geospatial
```

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

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

## Public functions

### checkVpsAvailability

```
suspend fun checkVpsAvailability(latitude: Double, longitude: Double): VpsAvailabilityResult
```

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/kotlin/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 |
|---|---|
| `latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the latitude in degrees |
| `longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the longitude in degrees |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/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)

```
fun createAnchor(
    latitude: Double,
    longitude: Double,
    altitude: Double,
    eastUpSouthQuaternion: Quaternion
): AnchorResult
```

Creates a new `https://developer.android.com/reference/kotlin/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/kotlin/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/kotlin/androidx/xr/arcore/Anchor` will permanently become `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TrackingState#STOPPED()` if the `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the latitude of the anchor |
| `longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the longitude of the anchor |
| `altitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the altitude of the anchor |
| `eastUpSouthQuaternion: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Quaternion` | the rotation quaternion of the anchor |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | an `https://developer.android.com/reference/kotlin/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

```
suspend fun createAnchorOnSurface(
    latitude: Double,
    longitude: Double,
    altitudeAboveSurface: Double,
    eastUpSouthQuaternion: Quaternion,
    surface: GeospatialSurface
): AnchorResult
```

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

The specified `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/arcore/GeospatialSurface#TERRAIN()` refers to the Earth's terrain (or floor) and `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/arcore/AnchorCreateResourcesExhausted` result.

Creating a Terrain anchor requires an active Earth which is `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.GeospatialTrackingState#RUNNING()`. If it is not, then this function returns an `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/arcore/TrackingState#PAUSED()` if the Earth is not actively tracking. Its tracking state will permanently become `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TrackingState#STOPPED()` if `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `latitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the latitude of the anchor |
| `longitude: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the longitude of the anchor |
| `altitudeAboveSurface: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html` | the altitude of the anchor above the given surface |
| `eastUpSouthQuaternion: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Quaternion` | the rotation quaternion of the anchor |
| `surface: https://developer.android.com/reference/kotlin/androidx/xr/arcore/GeospatialSurface` | the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/GeospatialSurface` on which to create the anchor |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | an `https://developer.android.com/reference/kotlin/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)

```
fun createGeospatialPoseFromPose(pose: Pose): CreateGeospatialPoseFromPoseResult
```

Converts the input `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` to a `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` to be converted into a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/GeospatialPose` |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` | a `https://developer.android.com/reference/kotlin/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)

```
fun createPoseFromGeospatialPose(geospatialPose: GeospatialPose): CreatePoseFromGeospatialPoseResult
```

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

This method may return a `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `geospatialPose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/GeospatialPose` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/GeospatialPose` to be converted into a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose` |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` | a `https://developer.android.com/reference/kotlin/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

```
open operator fun equals(other: Any?): Boolean
```

### hashCode

```
open fun hashCode(): Int
```

### toString

```
open fun toString(): String
```

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

Note: Not intended for production use.

## Public properties

### state

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

```
val state: StateFlow<Geospatial.State>
```

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