Praca z pozycjami geoprzestrzennymi za pomocą ARCore w Jetpack XR

Odpowiednie urządzenia XR
Te wskazówki pomogą Ci tworzyć aplikacje na te typy urządzeń XR.
Więcej informacji o typach urządzeń XR
Okulary AI
Więcej informacji o typach urządzeń XR

Dzięki interfejsowi Geospatial API w ARCore dla Jetpacka XR aplikacja może zdalnie dołączać treści do dowolnego obszaru objętego Street View w Google i tworzyć doświadczenia AR na skalę globalną. Interfejs Geospatial API wykorzystuje dane z czujników urządzenia i GPS, aby wykrywać otoczenie urządzenia, a następnie dopasowywać rozpoznawalne części tego otoczenia do modelu lokalizacji dostarczanego przez system pozycjonowania wizualnego (VPS) Google, aby określić dokładną lokalizację urządzenia użytkownika. Interfejs API zajmuje się też łączeniem 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 używać w aplikacji systemu pozycjonowania wizualnego (VPS), musisz najpierw włączyć interfejs ARCore API w nowym lub istniejącym projekcie Google Cloud. Ta usługa odpowiada za hostowanie, przechowywanie i rozwiązywanie kotwic przestrzennych.

Dodawanie dodatkowych zależności dotyczących bibliotek

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

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

Poproś o wymagane uprawnienia

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

Deklarowanie uprawnień aplikacji

Zanim poprosisz o te uprawnienia w czasie działania aplikacji, musisz zadeklarować je 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>

Prośba o uprawnienia

Po zadeklarowaniu wymaganych uprawnień 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 wytycznymi dotyczącymi prośby o uprawnienia do lokalizacji w czasie działania, aby aplikacja mogła uzyskać uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION.

Dostęp do sesji

Dostęp do informacji geoprzestrzennych uzyskasz za pomocą środowiska wykonawczego Jetpack XR Session, które 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 wizualnego systemu pozycjonowania (VPS) i globalnego systemu pozycjonowania (GPS), aby dokładnie określić położenie geoprzestrzenne urządzenia.

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

Prośba użytkownika o zezwolenie na korzystanie z danych urządzenia

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

Pobieranie obiektu Geospatial

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

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

Obiektu Geospatial należy używać tylko wtedy, gdy jego stan to State.RUNNING. Stan możesz monitorować za pomocą funkcji Geospatial.state StateFlow<Geospatial.State>.

Sprawdzanie dostępności VPS

Interfejs Geospatial API korzysta z kombinacji VPS i GPS do określania pozycji geoprzestrzennej, dlatego jest dostępny zawsze, gdy urządzenie może określić swoją lokalizację. Na obszarach o niskiej dokładności GPS, takich jak przestrzenie wewnątrz budynków i gęsto zabudowane obszary miejskie, interfejs API korzysta z zasięgu VPS, aby generować pozy o wysokiej dokładności.

W typowych warunkach VPS zapewnia dokładność pozycji wynoszącą około 5 metrów i dokładność obrotu wynoszącą 5 stopni. Możesz sprawdzić, czy dana lokalizacja jest objęta zasięgiem VPS, korzystając z funkcji zawieszaniaGeospatial.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

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

Konwertowanie pozycji urządzenia na pozycję geoprzestrzenną

Możesz przekształcić pozycję urządzenia w pozycję geoprzestrzenną, aby umożliwić okularom z AI interakcję z danymi zależnymi od lokalizacji i ich generowanie. Ten potok przekształca bieżące położenie i orientację urządzenia w lokalnym układzie współrzędnych (pozycja urządzenia) na współrzędne rozpoznawane globalnie.

Może Ci to pomóc:

  • Tworzenie 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 odzyskać.
  • Wywoływanie funkcji opartych na lokalizacji przez ciągłe aktualizowanie pozycji użytkownika na mapie, aby umożliwić nawigację w czasie rzeczywistym lub rozgrywkę w ramach geofencingu.
  • Określanie dokładnego kontekstu użytkownika w rzeczywistym świecie 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 przekształcić pozę geoprzestrzenną w pozę urządzenia, aby dostarczać kontekstowe, oparte na lokalizacji treści na okularach z AI. Ta transformacja przekształca informacje zdefiniowane przez współrzędne świata rzeczywistego, takie jak lokalizacja punktu orientacyjnego, ścieżka nawigacji lub trwałe treści AR, na precyzyjną przestrzeń wizualną okularów użytkownika.

Aby przekonwertować pozę geoprzestrzenną na pozę urządzenia za pomocą funkcji 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