ทำงานกับท่าทางเชิงพื้นที่โดยใช้ ARCore สำหรับ Jetpack XR

อุปกรณ์ XR ที่รองรับ
คำแนะนำนี้จะช่วยคุณสร้างประสบการณ์การใช้งานสำหรับอุปกรณ์ XR ประเภทต่อไปนี้
แว่นตา AI

Geospatial API ใน ARCore สำหรับ Jetpack XR ช่วยให้แอปของคุณแนบ เนื้อหาจากระยะไกลกับพื้นที่ใดก็ได้ที่ Google Street View ครอบคลุม และสร้างประสบการณ์การใช้งาน AR ในระดับโลกได้ Geospatial API ใช้ข้อมูลเซ็นเซอร์ของอุปกรณ์และ GPS เพื่อตรวจจับสภาพแวดล้อมของอุปกรณ์ จากนั้นจะจับคู่ส่วนที่จดจำได้ของสภาพแวดล้อมนั้นกับโมเดลการแปลที่ให้บริการโดยระบบกำหนดตำแหน่งด้วยภาพ (VPS) ของ Google เพื่อระบุตำแหน่งที่แน่นอนของอุปกรณ์ของผู้ใช้ นอกจากนี้ API ยังจัดการการผสานรวมพิกัดท้องถิ่นของผู้ใช้กับพิกัดทางภูมิศาสตร์จาก VPS เพื่อให้คุณทำงานภายในระบบพิกัดเดียวได้

เปิดใช้ ARCore API

ก่อนที่จะใช้ระบบกำหนดตำแหน่งด้วยภาพ (VPS) ในแอป คุณต้องเปิดใช้ ARCore API ในโปรเจ็กต์ Google Cloud ใหม่หรือที่มีอยู่ก่อน บริการนี้มีหน้าที่โฮสต์ จัดเก็บ และแก้ไข Anchor ทางภูมิศาสตร์

เพิ่มการขึ้นต่อกันของไลบรารีเพิ่มเติม

การใช้ Geospatial API ต้องมีการขึ้นต่อกันของไลบรารีเพิ่มเติม ให้เพิ่มการขึ้นต่อกันเหล่านี้ลงในไฟล์ build.gradle.kts ของแอป

ดึงดูด

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

ขอสิทธิ์ที่จำเป็น

หากต้องการใช้ Geospatial API ใน ARCore กับ Jetpack XR แอปของคุณต้องขอสิทธิ์รันไทม์ต่อไปนี้

ประกาศสิทธิ์ของแอป

คุณต้องประกาศ สิทธิ์เหล่านี้ในไฟล์ Manifest ของแอปก่อนจึงจะขอสิทธิ์เหล่านี้ในรันไทม์ได้

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

ขอสิทธิ์

หลังจากประกาศสิทธิ์ที่จำเป็นแล้ว แอปของคุณต้อง ขอสิทธิ์เหล่านั้นใน รันไทม์ อย่าลืมอธิบายเหตุผลที่แอปของคุณต้องใช้สิทธิ์

Geospatial API จะทำงานไม่ได้หากไม่สามารถระบุตำแหน่งที่แน่นอนของผู้ใช้ ด้วยเหตุนี้ ให้ทำตามคำแนะนำในการขอสิทธิ์เข้าถึงตำแหน่ง ในรันไทม์เพื่อให้แอปของคุณได้รับทั้งสิทธิ์ ACCESS_FINE_LOCATION และ ACCESS_COARSE_LOCATION

เข้าถึงเซสชัน

เข้าถึงข้อมูลทางภูมิศาสตร์ผ่าน Jetpack XR Runtime Session, ซึ่ง แอปของคุณต้องสร้างขึ้น

กำหนดค่าเซสชัน

ระบบไม่ได้เปิดใช้ข้อมูลท่าทางของอุปกรณ์ในเซสชัน XR โดยค่าเริ่มต้น หากต้องการให้แอปดึงข้อมูลท่าทางของอุปกรณ์ได้ ให้กำหนดค่าเซสชันและตั้งค่าโหมด GeospatialMode.VPS_AND_GPS และ 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.
}

โหมด GeospatialMode.VPS_AND_GPS ใช้ประโยชน์จากข้อมูลทั้งระบบกำหนดตำแหน่งด้วยภาพ (VPS) และระบบดาวเทียมนำร่อง (GPS) เพื่อระบุตำแหน่งทางภูมิศาสตร์ของอุปกรณ์ได้อย่างแม่นยำ

อุปกรณ์ XR บางรุ่นไม่รองรับโหมด GeospatialMode.VPS_AND_GPS และ DeviceTrackingMode.LAST_KNOWN หาก Session.configure() สำเร็จ แสดงว่าอุปกรณ์รองรับโหมดเหล่านี้

แจ้งให้ผู้ใช้ยินยอมให้ใช้ข้อมูลอุปกรณ์

แอปที่ใช้ Geospatial API กับ ARCore สำหรับ Jetpack XR ต้องแสดงข้อความแจ้งให้ผู้ใช้รับทราบและยินยอมให้ใช้ข้อมูลจากอุปกรณ์ของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่ข้อกำหนดด้านความเป็นส่วนตัวของผู้ใช้

รับออบเจ็กต์ทางภูมิศาสตร์

เมื่อกำหนดค่าเซสชันแล้ว ให้รับออบเจ็กต์ Geospatial โดยใช้ Geospatial.getInstance(session)

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

ควรใช้ออบเจ็กต์ Geospatial เมื่อสถานะเป็น State.RUNNING เท่านั้น คุณสามารถตรวจสอบสถานะได้โดยใช้ Geospatial.state StateFlow<Geospatial.State>

ตรวจสอบความพร้อมใช้งานของ VPS

เนื่องจาก Geospatial API ใช้ VPS และ GPS ร่วมกันเพื่อกำหนดท่าทางทางภูมิศาสตร์ API จึงพร้อมใช้งานทุกครั้งที่อุปกรณ์ ระบุตำแหน่งได้ ในพื้นที่ที่มีความแม่นยำของ GPS ต่ำ เช่น พื้นที่ในอาคารและสภาพแวดล้อมในเมืองที่มีความหนาแน่นสูง API จะอาศัยความครอบคลุมของ VPS เพื่อสร้างท่าทางที่มีความแม่นยำสูง

ในสภาวะปกติ คุณคาดหวังได้ว่า VPS จะให้ความแม่นยำของตำแหน่งประมาณ 5 เมตรและความแม่นยำในการหมุน 5 องศา คุณสามารถตรวจสอบว่าตำแหน่งมีความครอบคลุมของ VPS หรือไม่โดยใช้ฟังก์ชันระงับ Geospatial.checkVpsAvailability(latitude, longitude) การเรียกนี้เป็นการดำเนินการแบบไม่พร้อมกันและไม่จำเป็นต้องกำหนดค่าเซสชันด้วยโหมด GeospatialMode.VPS_AND_GPS

โค้ดต่อไปนี้แสดงวิธีตรวจสอบความพร้อมใช้งานของ VPS จากละติจูดและลองจิจูดที่ระบุ

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

แอปของคุณต้องตั้งค่าอย่างถูกต้องเพื่อสื่อสารกับ ARCore API ใน Google Cloud มิเช่นนั้นแอปจะได้รับผลลัพธ์ VpsAvailabilityNotAuthorized

แปลงท่าทางของอุปกรณ์เป็นท่าทางทางภูมิศาสตร์

คุณสามารถแปลงท่าทางของอุปกรณ์เป็นท่าทางทางภูมิศาสตร์เพื่อให้แว่นตา AI โต้ตอบและสร้างข้อมูลที่คำนึงถึงตำแหน่งได้ ไปป์ไลน์นี้จะแปลตำแหน่งและการวางแนวปัจจุบันของอุปกรณ์ในระบบพิกัดท้องถิ่น (ท่าทางของอุปกรณ์) เป็นพิกัดที่ได้รับการยอมรับทั่วโลก

ซึ่งจะช่วยคุณในเรื่องต่อไปนี้

  • สร้างเนื้อหา AR แบบถาวร โดยที่ออบเจ็กต์เสมือนที่ผู้ใช้วางไว้จะยึดกับตำแหน่งทั่วโลกอย่างแม่นยำเพื่อให้ดึงข้อมูลได้ในภายหลัง
  • ทริกเกอร์ประสบการณ์การใช้งานตามตำแหน่งโดยการอัปเดตตำแหน่งของผู้ใช้บนแผนที่อย่างต่อเนื่องเพื่อเปิดใช้การนำทางแบบเรียลไทม์หรือเกมเพลย์ที่มีการกำหนดเขตพื้นที่เสมือน
  • ระบุบริบทที่แน่นอนในโลกจริงของผู้ใช้เพื่อกระตุ้นตรรกะของแอปพลิเคชันที่เกี่ยวข้องกับตำแหน่ง

วิธีแปลงท่าทางของอุปกรณ์เป็นท่าทางทางภูมิศาสตร์โดยใช้ 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.
    }
}

แปลงท่าทางทางภูมิศาสตร์เป็นท่าทางของอุปกรณ์

คุณสามารถแปลงท่าทางทางภูมิศาสตร์เป็นท่าทางของอุปกรณ์เพื่อช่วยมอบประสบการณ์การใช้งานที่คำนึงถึงตำแหน่งและบริบทบนแว่นตา AI การแปลงนี้จะใช้ข้อมูลที่กำหนดโดยพิกัดในโลกจริง เช่น ตำแหน่งของจุดสังเกต เส้นทางการนำทาง หรือเนื้อหา AR แบบถาวร แล้วแปลงเป็นพื้นที่ภาพที่แน่นอนของแว่นตาของผู้ใช้

วิธีแปลงท่าทางทางภูมิศาสตร์เป็นท่าทางของอุปกรณ์โดยใช้ 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.
    }
}