Với Geospatial API trong ARCore cho Jetpack XR, ứng dụng của bạn có thể đính kèm nội dung từ xa vào bất kỳ khu vực nào mà Chế độ xem đường phố của Google hỗ trợ và tạo trải nghiệm thực tế tăng cường trên quy mô toàn cầu. Geospatial API sử dụng dữ liệu GPS và cảm biến trên thiết bị để phát hiện môi trường của thiết bị, sau đó so khớp các phần có thể nhận dạng của môi trường đó với một mô hình bản địa hoá do Hệ thống định vị bằng hình ảnh (VPS) của Google cung cấp để xác định vị trí chính xác của thiết bị người dùng. API này cũng đảm nhiệm việc hợp nhất toạ độ cục bộ của người dùng với toạ độ địa lý từ VPS để bạn có thể làm việc trong một hệ thống toạ độ duy nhất.
Bật ARCore API
Trước khi sử dụng Hệ thống định vị trực quan (VPS) trong ứng dụng, trước tiên, bạn phải bật ARCore API trong một dự án mới hoặc hiện có trên Google Cloud. Dịch vụ này chịu trách nhiệm lưu trữ, lưu và phân giải các neo không gian địa lý.
Thêm các phần phụ thuộc thư viện bổ sung
Để sử dụng Geospatial API, bạn cần có một số phần phụ thuộc bổ sung của thư viện. Thêm các phần phụ thuộc này vào tệp build.gradle.kts của ứng dụng:
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") }
Yêu cầu cấp các quyền bắt buộc
Để sử dụng Geospatial API trong ARCore với Jetpack XR, ứng dụng của bạn cần yêu cầu các quyền sau đây trong thời gian chạy:
ACCESS_INTERNET: Bắt buộc để liên hệ với dịch vụ đám mây ARCore Geospatial API.ACCESS_COARSE_LOCATION: Bắt buộc để xác định vị trí ước chừng của người dùng.ACCESS_FINE_LOCATION: Bắt buộc để xác định vị trí chính xác của người dùng.
Khai báo quyền cho ứng dụng
Trước khi có thể yêu cầu các quyền này trong thời gian chạy, bạn cần khai báo các quyền đó trong tệp kê khai của ứng dụng:
<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>
Yêu cầu cấp quyền
Sau khi khai báo các quyền bắt buộc, ứng dụng của bạn phải yêu cầu các quyền đó tại thời gian chạy. Nhớ giải thích lý do ứng dụng của bạn cần các quyền này.
Geospatial API không thể hoạt động nếu không xác định được vị trí chính xác của người dùng. Do đó, hãy làm theo hướng dẫn về yêu cầu quyền truy cập thông tin vị trí khi bắt đầu chạy để ứng dụng của bạn có thể được cấp cả quyền ACCESS_FINE_LOCATION và ACCESS_COARSE_LOCATION.
Truy cập vào một phiên
Truy cập vào thông tin không gian địa lý thông qua Jetpack XR Runtime Session mà ứng dụng của bạn phải tạo.
Định cấu hình phiên
Theo mặc định, thông tin về tư thế của thiết bị không được bật trên các phiên XR. Để cho phép ứng dụng của bạn truy xuất thông tin về tư thế của thiết bị, hãy định cấu hình phiên và đặt cả chế độ GeospatialMode.VPS_AND_GPS và DeviceTrackingMode.LAST_KNOWN:
// Define the configuration object to enable Geospatial features.
val newConfig = session.config.copy(
// Set the GeospatialMode to VPS_AND_GPS.
geospatial = Config.GeospatialMode.VPS_AND_GPS
// Set the DeviceTrackingMode to LAST_KNOWN.
deviceTracking = Config.DeviceTrackingMode.LAST_KNOWN
)
// Apply the configuration to the session.
try {
when (val configResult = session.configure(newConfig)) {
is SessionConfigureGooglePlayServicesLocationLibraryNotLinked -> {
// This case generally indicates a missing library dependency.
}
is SessionConfigureSuccess -> {
// The session is now configured to use the Geospatial API.
}
else -> {
// Catch-all for other configuration errors returned using the result class.
}
}
} catch (e: UnsupportedOperationException) {
// Handle configuration failure. For example, if the specific mode is not supported on the current device or API version.
}
Chế độ GeospatialMode.VPS_AND_GPS tận dụng cả dữ liệu Hệ thống định vị trực quan (VPS) và Hệ thống định vị toàn cầu (GPS) để xác định chính xác vị trí không gian địa lý của thiết bị.
Không phải thiết bị thực tế mở rộng (XR) nào cũng hỗ trợ chế độ GeospatialMode.VPS_AND_GPS và DeviceTrackingMode.LAST_KNOWN. Nếu Session.configure() thành công, tức là thiết bị hỗ trợ các chế độ này.
Nhắc người dùng cho phép sử dụng dữ liệu trên thiết bị
Những ứng dụng sử dụng Geospatial API với ARCore cho Jetpack XR phải đưa ra lời nhắc để người dùng xác nhận và cho phép sử dụng dữ liệu trên thiết bị của họ. Hãy xem các yêu cầu về quyền riêng tư của người dùng để biết thêm thông tin.
Lấy đối tượng Không gian địa lý
Sau khi phiên được định cấu hình, hãy lấy đối tượng Geospatial bằng cách sử dụng Geospatial.getInstance(session):
// Get the Geospatial instance
var geospatial = Geospatial.getInstance(session)
Bạn chỉ nên sử dụng đối tượng Geospatial khi trạng thái của đối tượng này là State.RUNNING. Bạn có thể theo dõi trạng thái bằng Geospatial.state StateFlow<Geospatial.State>.
Kiểm tra tình trạng còn hàng của VPS
Vì Geospatial API sử dụng kết hợp VPS và GPS để xác định tư thế không gian địa lý, nên bạn có thể sử dụng API này miễn là thiết bị có thể xác định vị trí của mình. Ở những khu vực có độ chính xác GPS thấp, chẳng hạn như không gian trong nhà và môi trường đô thị dày đặc, API này dựa vào phạm vi phủ sóng VPS để tạo ra các tư thế có độ chính xác cao.
Trong điều kiện thông thường, bạn có thể kỳ vọng VPS cung cấp độ chính xác về vị trí khoảng 5 mét và độ chính xác về hướng xoay là 5 độ. Bạn có thể kiểm tra xem một vị trí có phạm vi phủ sóng VPS hay không bằng cách sử dụng hàm tạm ngưng Geospatial.checkVpsAvailability(latitude, longitude). Lệnh gọi này là một thao tác không đồng bộ và không yêu cầu phiên được định cấu hình ở chế độ GeospatialMode.VPS_AND_GPS.
Đoạn mã sau đây minh hoạ cách kiểm tra trạng thái sẵn có của VPS theo một vĩ độ và kinh độ cụ thể:
// You can query the GPS to get the current device's location and check if it has VPS
val latitude = getLatitudeFromGPS()
val longitude = getLongitudeFromGPS()
// Must be called from a coroutine.
val result = geospatial.checkVpsAvailability(latitude, longitude)
if (result is VpsAvailabilityAvailable) {
// VPS is available
} else if (result is VpsAvailabilityUnavailable) {
// VPS is not available
}
Ứng dụng của bạn phải được thiết lập đúng cách để giao tiếp với ARCore API trên Google Cloud; nếu không, ứng dụng của bạn sẽ nhận được kết quả VpsAvailabilityNotAuthorized.
Chuyển đổi tư thế của thiết bị thành tư thế không gian địa lý
Bạn có thể chuyển đổi tư thế của thiết bị thành tư thế không gian địa lý để cho phép kính AI tương tác và tạo dữ liệu nhận biết vị trí. Quy trình này chuyển đổi vị trí và hướng hiện tại của thiết bị trong hệ toạ độ cục bộ (tư thế thiết bị) thành các toạ độ được nhận dạng trên toàn cầu.
Điều này có thể giúp bạn:
- Tạo nội dung AR ổn định, trong đó đối tượng ảo mà người dùng đặt được neo chính xác vào một vị trí toàn cầu để truy xuất sau này.
- Kích hoạt trải nghiệm dựa trên vị trí bằng cách liên tục cập nhật vị trí của người dùng trên bản đồ để bật tính năng chỉ đường theo thời gian thực hoặc lối chơi có hàng rào địa lý.
- Xác định bối cảnh chính xác của người dùng trong thế giới thực để kích hoạt logic ứng dụng liên quan đến vị trí.
Để chuyển đổi tư thế thiết bị thành tư thế không gian địa lý bằng cách sử dụng Geospatial.createGeospatialPoseFromPose():
// Get the current device Pose from the AR Session's state
// This is the device's position and orientation relative to the AR tracking origin.
val devicePose = ArDevice.getInstance(session).state.value.devicePose
// Convert the device Pose into a GeospatialPose
when (val geospatialPoseResult = geospatial.createGeospatialPoseFromPose(devicePose)) {
is CreateGeospatialPoseFromPoseSuccess -> {
val currentGeospatialPose = geospatialPoseResult.pose
val horizontalAccuracy = geospatialPoseResult.horizontalAccuracy
// ... use pose and accuracy
val latitude = currentGeospatialPose.latitude
val longitude = currentGeospatialPose.longitude
// The orientation is stored as a Quaternion in the EUS (East-Up-South) system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south. True North is aligned with the -Z axis.
val eusQuaternion = currentGeospatialPose.eastUpSouthQuaternion
}
is CreateGeospatialPoseFromPoseNotTracking -> {
// Geospatial is not currently tracking
}
}
Chuyển đổi tư thế không gian địa lý thành tư thế thiết bị
Bạn có thể chuyển đổi tư thế không gian địa lý thành tư thế thiết bị để giúp mang lại trải nghiệm theo ngữ cảnh, nhận biết vị trí trên kính AI. Quá trình chuyển đổi này lấy thông tin được xác định bằng toạ độ trong thế giới thực (chẳng hạn như vị trí của một địa danh, đường dẫn điều hướng hoặc nội dung thực tế tăng cường cố định) và chuyển đổi thông tin đó thành không gian hình ảnh chính xác của kính người dùng.
Cách chuyển đổi tư thế không gian địa lý thành tư thế thiết bị bằng Geospatial.createPoseFromGeospatialPose():
when (val poseResult = geospatial.createPoseFromGeospatialPose(geospatialPose)) {
is CreatePoseFromGeospatialPoseSuccess -> {
val devicePose = poseResult.pose
// devicePose is now ready to be used
}
is CreatePoseFromGeospatialPoseNotTracking -> {
// Geospatial is not currently tracking
}
}