Praca z pozycjami geoprzestrzennymi za pomocą ARCore w Jetpack XR

Odpowiednie urządzenia XR
Ten przewodnik pomoże Ci tworzyć rozwiązania na te typy urządzeń XR.
Więcej informacji o typach urządzeń z XR →
Okulary AI
Więcej informacji o typach urządzeń z XR →

Dzięki interfejsowi Geospatial API w ARCore dla Jetpack XR Twoja aplikacja może zdalnie dołączać treści do dowolnego obszaru objętego usługą Google Street View i tworzyć rozwiązania AR na skalę globalną. Interfejs Geospatial API wykorzystuje dane z czujników urządzenia i GPS do wykrywania otoczenia urządzenia, a następnie dopasowuje rozpoznawalne części tego otoczenia do modelu lokalizacji dostarczonego przez system pozycjonowania wizualnego (VPS) Google, aby określić dokładną lokalizację urządzenia użytkownika. Interfejs API dba też o łączenie lokalnych współrzędnych użytkownika ze współrzędnymi geograficznymi z VPS, dzięki czemu możesz pracować w jednym systemie współrzędnych.

Włączanie interfejsu ARCore API

Zanim zaczniesz korzystać z systemu pozycjonowania wizualnego (VPS) w swojej aplikacji, musisz najpierw włączyć interfejs ARCore API w nowym lub dotychczasowym projekcie Google Cloud. Ta usługa odpowiada za hostowanie, przechowywanie i rozwiązywanie kotwic geoprzestrzennych.

Dodawanie dodatkowych zależności biblioteki

Korzystanie z interfejsu Geospatial API wymaga dodatkowych zależności biblioteki. Dodaj je do pliku build.gradle.kts aplikacji:

Dynamiczny

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")
}

Wysyłanie prośby o wymagane uprawnienia

Aby korzystać z interfejsu Geospatial API w ARCore z Jetpack XR, Twoja aplikacja musi poprosić o te uprawnienia w czasie działania:

Deklarowanie uprawnień aplikacji

Zanim poprosisz o te uprawnienia w czasie działania, musisz je zadeklarować w pliku manifestu aplikacji:

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

Wysyłanie prośby o uprawnienia

Po zadeklarowaniu wymaganych uprawnień Twoja aplikacja musi poprosić o nie w czasie działania. Wyjaśnij, dlaczego Twoja aplikacja potrzebuje tych uprawnień.

Interfejs Geospatial API nie może działać, jeśli nie może określić dokładnej lokalizacji użytkownika. Dlatego postępuj zgodnie z instrukcjami dotyczącymi wysyłania prośby o lokalizację uprawnienia w czasie działania, aby Twoja aplikacja mogła uzyskać uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION.

Dostęp do sesji

Dostęp do informacji geoprzestrzennych uzyskasz za pomocą sesji Jetpack XR Runtime Session, którą musi utworzyć Twoja aplikacja.

Konfigurowanie sesji

Informacje o pozycji urządzenia nie są domyślnie włączone w sesjach XR. Aby umożliwić aplikacji pobieranie informacji o pozycji urządzenia, skonfiguruj sesję i ustaw tryby GeospatialMode.VPS_AND_GPS i DeviceTrackingMode.LAST_KNOWN:

// 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

Tryb GeospatialMode.VPS_AND_GPS wykorzystuje dane z systemu pozycjonowania wizualnego (VPS) i globalnego systemu pozycjonowania (GPS), aby dokładnie określić pozycję geoprzestrzenną urządzenia.

Nie wszystkie urządzenia XR obsługują tryby GeospatialMode.VPS_AND_GPS i DeviceTrackingMode.LAST_KNOWN. Jeśli Session.configure() zakończy się powodzeniem, urządzenie obsługuje te tryby.

Prośba o zgodę użytkownika na korzystanie z danych na urządzeniu

Aplikacje, które korzystają z interfejsu Geospatial API w ARCore dla Jetpack XR, muszą wyświetlać użytkownikowi prośbę o potwierdzenie i zezwolenie na korzystanie z danych z jego urządzenia. Więcej informacji znajdziesz w wymaganiach dotyczących ochrony prywatności użytkowników.

Pobieranie obiektu Geospatial

Po skonfigurowaniu sesji pobierz obiekt Geospatial za pomocą Geospatial.getInstance(session):

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

Obiekt Geospatial powinien być używany tylko wtedy, gdy jego stan to State.RUNNING. Stan możesz monitorować za pomocą Geospatial.state StateFlow<Geospatial.State>.

Sprawdzanie dostępności VPS

Ponieważ interfejs Geospatial API używa kombinacji VPS i GPS do określania pozycji geoprzestrzennej, jest on dostępny zawsze, gdy urządzenie może określić swoją lokalizację. Na obszarach o niskiej dokładności GPS, takich jak przestrzenie wewnętrzne i gęsto zabudowane środowiska miejskie, interfejs API polega na zasięgu VPS, aby generować pozycje o wysokiej dokładności.

W typowych warunkach możesz oczekiwać, że VPS zapewni dokładność pozycji wynoszącą około 5 metrów i dokładność obrotu wynoszącą 5 stopni. Możesz sprawdzić, czy dana lokalizacja ma zasięg VPS, za pomocą funkcji zawieszenia Geospatial.checkVpsAvailability(latitude, longitude). To wywołanie jest operacją asynchroniczną i nie wymaga skonfigurowania sesji w trybie GeospatialMode.VPS_AND_GPS.

Poniższy kod pokazuje, jak sprawdzić dostępność VPS na podstawie określonej szerokości i długości geograficznej:

// 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

Twoja aplikacja musi być prawidłowo skonfigurowana do komunikacji z interfejsem ARCore API w Google Cloud. W przeciwnym razie aplikacja otrzyma wynik VpsAvailabilityNotAuthorized.

Konwertowanie pozycji urządzenia na pozycję geoprzestrzenną

Możesz przekonwertować pozycję urządzenia na pozycję geoprzestrzenną, aby umożliwić okularom z AI interakcję z danymi uwzględniającymi lokalizację i ich generowanie. Ten potok tłumaczy bieżącą pozycję i orientację urządzenia w jego lokalnym systemie współrzędnych (pozycja urządzenia) na współrzędne rozpoznawane globalnie.

Może to pomóc w:

  • Tworzeniu trwałych treści AR, w których umieszczony przez użytkownika wirtualny obiekt jest dokładnie zakotwiczony w lokalizacji globalnej, aby można go było później pobrać.
  • Wywoływaniu rozwiązań opartych na lokalizacji przez ciągłe aktualizowanie pozycji użytkownika na mapie, aby umożliwić nawigację w czasie rzeczywistym lub rozgrywkę w obrębie geofence.
  • Określaniu dokładnego kontekstu rzeczywistego użytkownika w celu wywoływania logiki aplikacji związanej z lokalizacją.

Aby przekonwertować pozycję urządzenia na pozycję geoprzestrzenną za pomocą Geospatial.createGeospatialPoseFromPose():

// 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

Konwertowanie pozycji geoprzestrzennej na pozycję urządzenia

Możesz przekonwertować pozycję geoprzestrzenną na pozycję urządzenia, aby dostarczać kontekstowe rozwiązania uwzględniające lokalizację na okularach z AI. Ta transformacja pobiera informacje zdefiniowane przez współrzędne rzeczywiste – takie jak lokalizacja punktu orientacyjnego, ścieżka nawigacji lub trwałe treści AR – i przekształca je w dokładną przestrzeń wizualną okularów użytkownika.

Aby przekonwertować pozycję geoprzestrzenną na pozycję urządzenia za pomocą Geospatial.createPoseFromGeospatialPose():

// 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