Mit raumbezogenen Posen in ARCore für Jetpack XR arbeiten

XR‑Geräte, für die der Leitfaden gilt
Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.
Informationen zu XR-Gerätetypen →
AI Glasses
Informationen zu XR-Gerätetypen →

Mit der Geospatial API in ARCore für Jetpack XR kann Ihre App Inhalte remote an jeden Bereich anhängen, der von Google Street View abgedeckt wird, und AR-Erlebnisse weltweit erstellen. Die Geospatial API verwendet Geräte- und GPS-Sensordaten, um die Umgebung des Geräts zu erkennen. Anschließend werden die erkennbaren Teile dieser Umgebung mit einem von Googles Visual Positioning System (VPS) bereitgestellten Lokalisierungsmodell abgeglichen, um den genauen Standort des Geräts eines Nutzers zu bestimmen. Die API führt auch die lokalen Koordinaten des Nutzers mit den geografischen Koordinaten aus VPS zusammen, sodass Sie in einem einzigen Koordinatensystem arbeiten können.

ARCore API aktivieren

Bevor Sie das Visual Positioning System (VPS) in Ihrer App verwenden können, müssen Sie zuerst die ARCore API in einem neuen oder vorhandenen Google Cloud-Projekt aktivieren. Dieser Dienst ist für das Hosten, Speichern und Auflösen von geografischen Ankern zuständig.

Zusätzliche Bibliotheksabhängigkeiten hinzufügen

Für die Verwendung der Geospatial API sind einige zusätzliche Bibliotheksabhängigkeiten erforderlich. Fügen Sie diese der Datei build.gradle.kts Ihrer App hinzu:

Groovy

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation "com.google.android.gms:play-services-location:21.3.0"
}

Kotlin

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation("com.google.android.gms:play-services-location:21.3.0")
}

Erforderliche Berechtigungen anfordern

Wenn Sie die Geospatial API in ARCore mit Jetpack XR verwenden möchten, muss Ihre App die folgenden Laufzeitberechtigungen anfordern:

App-Berechtigungen deklarieren

Bevor Sie diese Berechtigungen zur Laufzeit anfordern können, müssen Sie sie im Manifest Ihrer App deklarieren:

<manifest ... >
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

Berechtigungen anfordern

Nachdem Sie die erforderlichen Berechtigungen deklariert haben, muss Ihre App sie zur Laufzeit anfordern. Erläutern Sie, warum Ihre App die Berechtigungen benötigt.

Die Geospatial API kann nur funktionieren, wenn der genaue Standort des Nutzers ermittelt werden kann. Folgen Sie daher der Anleitung zum Anfordern von Standortberechtigungen zur Laufzeit, damit Ihrer App sowohl die Berechtigung ACCESS_FINE_LOCATION als auch die Berechtigung ACCESS_COARSE_LOCATION erteilt werden kann.

Auf eine Sitzung zugreifen

Über eine Jetpack XR-Laufzeit Session auf raumbezogene Informationen zugreifen, die von Ihrer App erstellt werden müssen.

Sitzung konfigurieren

Informationen zur Geräteposition sind bei XR-Sitzungen nicht standardmäßig aktiviert. Damit Ihre App Informationen zur Geräteposition abrufen kann, müssen Sie die Sitzung konfigurieren und sowohl den Modus GeospatialMode.VPS_AND_GPS als auch den Modus DeviceTrackingMode.LAST_KNOWN festlegen:

// Define the configuration object to enable Geospatial features.
val newConfig = Config(
    // Set the GeospatialMode to VPS_AND_GPS.
    geospatial = GeospatialMode.VPS_AND_GPS,
    // Set the DeviceTrackingMode to LAST_KNOWN.
    deviceTracking = DeviceTrackingMode.LAST_KNOWN
)
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }
        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Geospatial.kt

Im GeospatialMode.VPS_AND_GPS-Modus werden sowohl VPS- als auch GPS-Daten verwendet, um die geografische Position des Geräts genau zu bestimmen.

Nicht alle XR-Geräte unterstützen die Modi GeospatialMode.VPS_AND_GPS und DeviceTrackingMode.LAST_KNOWN. Wenn Session.configure() erfolgreich ist, unterstützt das Gerät diese Modi.

Nutzer auffordern, die Verwendung von Gerätedaten zu erlauben

Apps, die die Geospatial API mit ARCore für Jetpack XR verwenden, müssen dem Nutzer eine Aufforderung präsentieren, in der er die Verwendung von Daten von seinem Gerät bestätigen und zulassen muss. Weitere Informationen finden Sie unter Anforderungen an den Datenschutz.

Geospatial-Objekt abrufen

Sobald die Sitzung konfiguriert ist, rufen Sie das Objekt Geospatial mit Geospatial.getInstance(session) ab:

// Get the Geospatial instance for the current session.
val geospatial = Geospatial.getInstance(session)
Geospatial.kt

Das Geospatial-Objekt sollte nur verwendet werden, wenn sein Status State.RUNNING ist. Sie können den Status mit dem Geospatial.state-StateFlow<Geospatial.State> überwachen.

Verfügbarkeit von VPS prüfen

Da die Geospatial API eine Kombination aus VPS und GPS verwendet, um eine Geospatial-Pose zu bestimmen, ist die API immer verfügbar, wenn das Gerät seinen Standort bestimmen kann. In Gebieten mit geringer GPS-Genauigkeit, z. B. in Innenräumen und in dicht besiedelten städtischen Umgebungen, stützt sich die API auf die VPS-Abdeckung, um Posen mit hoher Genauigkeit zu generieren.

Unter normalen Bedingungen können Sie davon ausgehen, dass VPS eine Positionsgenauigkeit von etwa 5 Metern und eine Rotationsgenauigkeit von 5 Grad bietet. Mit der Funktion Geospatial.checkVpsAvailability(latitude, longitude) können Sie prüfen, ob ein Standort VPS-Abdeckung hat. Dieser Aufruf ist ein asynchroner Vorgang und erfordert nicht, dass die Sitzung im Modus GeospatialMode.VPS_AND_GPS konfiguriert ist.

Im folgenden Code wird gezeigt, wie Sie die VPS-Verfügbarkeit anhand eines bestimmten Breiten- und Längengrads prüfen:

// You can query the GPS to get the current device's location.
val latitude = 37.422
val longitude = -122.084

// Use the geospatial instance to check VPS availability for a specific location.
val result = geospatial.checkVpsAvailability(latitude, longitude)
when (result) {
    is VpsAvailabilityAvailable -> {
        // VPS is available at this location.
    }
    is VpsAvailabilityErrorInternal -> {
        // VPS availability check failed with an internal error.
    }
    is VpsAvailabilityNetworkError -> {
        // VPS availability check failed due to a network error.
    }
    is VpsAvailabilityNotAuthorized -> {
        // VPS availability check failed due to an authorization error.
    }
    is VpsAvailabilityResourceExhausted -> {
        // VPS availability check failed due to resource exhaustion.
    }
    is VpsAvailabilityUnavailable -> {
        // VPS is not available at this location.
    }
}
Geospatial.kt

Ihre App muss richtig eingerichtet sein, um mit der ARCore API in Google Cloud zu kommunizieren. Andernfalls erhält sie das Ergebnis VpsAvailabilityNotAuthorized.

Geräteposition in eine raumbezogene Position umwandeln

Sie können die Geräteposition in eine raumbezogene Position umwandeln, damit KI-Brillen mit standortbezogenen Daten interagieren und solche Daten generieren können. In dieser Pipeline wird die aktuelle Position und Ausrichtung des Geräts in seinem lokalen Koordinatensystem (Geräte-Pose) in global anerkannte Koordinaten übersetzt.

Das kann Ihnen helfen:

  • Erstellen Sie persistenten AR-Content, bei dem das von einem Nutzer platzierte virtuelle Objekt präzise an einem globalen Standort verankert wird, damit es später abgerufen werden kann.
  • Standortbasierte Funktionen auslösen, indem die Position des Nutzers auf einer Karte kontinuierlich aktualisiert wird, um Echtzeitnavigation oder Geo-Fencing-Gameplay zu ermöglichen.
  • Den genauen realen Kontext des Nutzers ermitteln, um standortbezogene Anwendungslogik auszulösen.

So konvertieren Sie eine Geräte-Pose mithilfe von Geospatial.createGeospatialPoseFromPose() in eine georäumliche Pose:

// Get the current device Pose from the AR Session's state.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose.
when (val result = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val geoPose = result.pose
        val lat = geoPose.latitude
        val lon = geoPose.longitude
        val alt = geoPose.altitude
        // Orientation is in the EUS (East-Up-South) coordinate system.
        val orientation = geoPose.eastUpSouthQuaternion
    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt

Geospatial Pose in Device Pose umwandeln

Sie können eine geospatiale Position in eine Geräteposition umwandeln, um kontextbezogene, standortbezogene Funktionen auf KI-Brillen bereitzustellen. Bei dieser Transformation werden Informationen, die durch reale Koordinaten definiert sind, z. B. die Position eines Orientierungspunkts, ein Navigationspfad oder persistenter AR-Inhalt, in den präzisen visuellen Raum der Brille des Nutzers umgewandelt.

So konvertieren Sie eine raumbezogene Position mithilfe von Geospatial.createPoseFromGeospatialPose() in eine Geräteposition:

// Convert a GeospatialPose (lat/long/alt) back to a device-space Pose.
when (val result = geospatial.createPoseFromGeospatialPose(geoPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose: Pose = result.pose
        // devicePose is now ready to be used relative to the tracking origin.
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt