Jetpack XR için ARCore'u kullanarak coğrafi uzamsal pozlarla çalışma

Uygun XR cihazlar
Bu kılavuz, bu tür XR cihazlar için deneyimler oluşturmanıza yardımcı olur.
XR cihaz türleri hakkında bilgi edinin →
Yapay Zeka Gözlükleri
XR cihaz türleri hakkında bilgi edinin →

Jetpack XR için ARCore'daki Geospatial API ile uygulamanız, Google Street View'un kapsadığı herhangi bir alana içeriği uzaktan ekleyebilir ve küresel ölçekte AR deneyimleri oluşturabilir. Geospatial API, cihazın ortamını algılamak için cihaz sensörü ve GPS verilerini kullanır. Ardından, kullanıcının cihazının tam konumunu belirlemek için bu ortamın tanınabilir kısımlarını Google'ın Görsel Konumlandırma Sistemi (VPS) tarafından sağlanan bir yerelleştirme modeliyle eşleştirir. API, kullanıcının yerel koordinatlarını VPS'den alınan coğrafi koordinatlarla birleştirerek tek bir koordinat sistemi içinde çalışmanızı sağlar.

ARCore API'yi etkinleştirme

Uygulamanızda Görsel Konumlandırma Sistemi'ni (VPS) kullanmadan önce yeni veya mevcut bir Google Cloud projesinde ARCore API'yi etkinleştirmeniz gerekir. Bu hizmet, coğrafi uzamsal bağlantıların barındırılması, depolanması ve çözümlenmesinden sorumludur.

Ek kitaplık bağımlılıkları ekleme

Geospatial API'yi kullanmak için bazı ek kitaplık bağımlılıkları gerekir. Uygulamanızın build.gradle.kts dosyasına şunları ekleyin:

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

Gerekli izinleri isteme

ARCore'da Jetpack XR ile Geospatial API'yi kullanmak için uygulamanızın aşağıdaki çalışma zamanı izinlerini istemesi gerekir:

Uygulama izinlerini beyan etme

Bu izinleri çalışma zamanında isteyebilmeniz için önce uygulamanızın manifest dosyasında bildirmeniz gerekir:

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

İzin iste

Gerekli izinleri bildirdikten sonra uygulamanızın çalışma zamanında bu izinleri istemesi gerekir. Uygulamanızın neden izinlere ihtiyacı olduğunu açıkladığınızdan emin olun.

Geospatial API, kullanıcının tam konumunu belirleyemediği sürece çalışamaz. Bu nedenle, uygulamanıza hem ACCESS_FINE_LOCATION hem de ACCESS_COARSE_LOCATION izinlerinin verilebilmesi için çalışma zamanında konum izni isteme ile ilgili yönergeleri uygulayın.

Bir oturuma erişme

Session Jetpack XR Runtime aracılığıyla coğrafi bilgiye erişin. Uygulamanızın bu bilgiyi oluşturması gerekir.

Oturumu yapılandırma

Cihaz duruşu bilgileri, XR oturumlarında varsayılan olarak etkin değildir. Uygulamanızın cihaz duruşu bilgilerini almasını sağlamak için oturumu yapılandırın ve hem GeospatialMode.VPS_AND_GPS hem de DeviceTrackingMode.LAST_KNOWN modlarını ayarlayın:

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

GeospatialMode.VPS_AND_GPS modu, cihazın coğrafi konumunu doğru bir şekilde belirlemek için hem Görsel Konumlandırma Sistemi (VPS) hem de Küresel Konumlandırma Sistemi (GPS) verilerinden yararlanır.

GeospatialMode.VPS_AND_GPS ve DeviceTrackingMode.LAST_KNOWN modları tüm XR cihazlarda desteklenmez. Session.configure() başarılı olursa cihaz bu modları destekler.

Kullanıcıdan cihaz verilerinin kullanımına izin vermesini isteme

Jetpack XR için ARCore ile Geospatial API'yi kullanan uygulamalar, kullanıcıya cihazındaki verilerin kullanımını onaylaması ve izin vermesi için bir istem göstermelidir. Daha fazla bilgi için kullanıcı gizliliği şartlarına göz atın.

Geospatial nesnesini edinme

Oturum yapılandırıldıktan sonra Geospatial nesnesini Geospatial.getInstance(session) kullanarak alın:

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

Geospatial nesnesi yalnızca durumu State.RUNNING olduğunda kullanılmalıdır. Durumu Geospatial.state StateFlow<Geospatial.State> ile izleyebilirsiniz.

VPS'nin kullanılabilirliğini kontrol etme

Geospatial API, Geospatial duruşunu belirlemek için VPS ve GPS'i birlikte kullandığından API, cihaz konumunu belirleyebildiği her zaman kullanılabilir. Kapalı alanlar ve yoğun şehir ortamları gibi GPS doğruluğunun düşük olduğu yerlerde API, yüksek doğrulukta pozlar oluşturmak için VPS kapsamına bağlıdır.

Normal koşullarda, VPS'nin yaklaşık 5 metre konum doğruluğu ve 5 derece dönme doğruluğu sağlaması beklenir. Askıya alma işlevini Geospatial.checkVpsAvailability(latitude, longitude) kullanarak bir konumda VPS kapsamı olup olmadığını kontrol edebilirsiniz. Bu çağrı, eşzamansız bir işlemdir ve oturumun GeospatialMode.VPS_AND_GPS moduyla yapılandırılması gerekmez.

Aşağıdaki kod, belirli bir enlem ve boylamdan VPS kullanılabilirliğini nasıl kontrol edeceğinizi gösterir:

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

Uygulamanızın Google Cloud'daki ARCore API ile iletişim kuracak şekilde doğru ayarlanması gerekir. Aksi takdirde uygulamanız VpsAvailabilityNotAuthorized sonucu alır.

Cihaz pozunu coğrafi uzamsal poza dönüştürme

Yapay zeka gözlüklerinin konum bilgisine duyarlı verilerle etkileşime girmesini ve bu verileri oluşturmasını sağlamak için cihaz pozunu coğrafi uzamsal poza dönüştürebilirsiniz. Bu işlem hattı, cihazın yerel koordinat sistemindeki mevcut konumunu ve yönünü (cihaz duruşu) dünya genelinde tanınan koordinatlara çevirir.

Bu sayede aşağıdaki işlemleri yapabilirsiniz:

  • Kullanıcının yerleştirdiği sanal nesnenin daha sonra alınabilmesi için global bir konuma doğru şekilde sabitlendiği kalıcı artırılmış gerçeklik içerikleri oluşturun.
  • Gerçek zamanlı navigasyon veya coğrafi sınırlı oyun deneyimlerini etkinleştirmek için kullanıcının haritadaki konumunu sürekli olarak güncelleyerek konuma dayalı deneyimleri tetikleyin.
  • Konumla alakalı uygulama mantığını tetiklemek için kullanıcının gerçek dünyadaki tam bağlamını belirleyin.

Geospatial.createGeospatialPoseFromPose() kullanarak cihaz pozunu coğrafi uzamsal poza dönüştürmek için:

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

Coğrafi uzamsal duruşu cihaz duruşuna dönüştürme

Yapay zeka gözlüklerde bağlama uygun ve konuma duyarlı deneyimler sunmak için coğrafi uzamsal duruşu cihaz duruşuna dönüştürebilirsiniz. Bu dönüştürme işlemi, gerçek dünya koordinatlarıyla tanımlanan bilgileri (ör. bir simge yapının, navigasyon yolunun veya kalıcı AR içeriğinin konumu) alıp kullanıcının gözlüğünün tam görsel alanına dönüştürür.

Geospatial.createPoseFromGeospatialPose() kullanarak coğrafi uzamsal duruşu cihaz duruşuna dönüştürmek için:

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