คู่มือนักพัฒนาซอฟต์แวร์ Cloud Anchor สำหรับ Android (Kotlin/Java)

ดูวิธีใช้ Cloud Anchor ในแอปของคุณเอง

ข้อกำหนดเบื้องต้น

ตรวจสอบว่าคุณเข้าใจแนวคิด AR พื้นฐาน และวิธีกําหนดค่าเซสชัน ARCore ก่อนดำเนินการต่อ

หากคุณเพิ่งเริ่มใช้ Cloud Anchor ให้ทำดังนี้

เปิดใช้ ARCore API

ก่อนที่จะใช้ Cloud Anchor ในแอป คุณต้องเปิดใช้ ARCore API ในแอปพลิเคชันก่อน

เปิดใช้ความสามารถของ Cloud Anchor ในการกำหนดค่าเซสชัน

เมื่อเปิดใช้ฟังก์ชันการทำงานของ Cloud Anchor ในแอปแล้ว ให้เปิดใช้ความสามารถของ Cloud Anchor ในการกำหนดค่าเซสชัน AR ของแอป เพื่อให้สื่อสารกับ ARCore API ได้

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

โฮสต์ Cloud Anchor

โฮสติ้งเริ่มต้นด้วยการโทรหา hostCloudAnchorAsync() ARCore จะอัปโหลดข้อมูลภาพ ท่าทางของอุปกรณ์ และตำแหน่ง Anchor ไปยัง ARCore API จากนั้น API จะประมวลผลข้อมูลนี้เพื่อสร้างแผนที่ฟีเจอร์ 3 มิติ ซึ่งในท้ายที่สุดแล้วจะส่งคืน Cloud Anchor ID ที่ไม่ซ้ำกันของ Anchor ไปยังอุปกรณ์

คุณยังยืดอายุการใช้งานของ Anchor ที่โฮสต์ไว้ได้โดยใช้ ARCore Cloud Anchor Management API

แอปของคุณควรทำตามขั้นตอนต่อไปนี้เพื่อโฮสต์ Cloud Anchor ให้เสร็จสมบูรณ์

  1. โทร hostCloudAnchorAsync()
  2. รอให้ระบบติดต่อกลับ หรือตรวจสอบสถานะในอนาคตอย่างต่อเนื่องจนกว่าการดำเนินการจะเสร็จสิ้น
  3. ตรวจสอบสถานะผลลัพธ์ เพื่อดูว่าดำเนินการสำเร็จหรือไม่ หรือตีความรหัสข้อผิดพลาดหากดำเนินการไม่สำเร็จ
  4. แชร์ผลลัพธ์รหัส Cloud Anchor กับไคลเอ็นต์อื่นๆ และใช้รหัสดังกล่าวเพื่อแก้ไข Cloud Anchor ด้วย resolveCloudAnchorAsync()

ตรวจสอบคุณภาพการแมปของจุดองค์ประกอบ

Session.FeatureMapQuality แสดงคุณภาพของจุดโฟกัสที่ ARCore เห็นในช่วง 2-3 วินาทีก่อนหน้าจากท่าทางของกล้อง โดยทั่วไปแล้ว Cloud Anchor ที่โฮสต์โดยใช้ฟีเจอร์คุณภาพสูงกว่าจะได้รับการแก้ไขอย่างถูกต้องมากกว่า ใช้ Session.estimateFeatureMapQualityForHosting() เพื่อรับค่าประมาณคุณภาพของแผนที่ฟีเจอร์สำหรับท่าทางของกล้องหนึ่งๆ

ค่า คำอธิบาย
INSUFFICIENT จุดของจุดสนใจที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้าอยู่ในระดับต่ำ สถานะนี้บ่งบอกว่า ARCore มักจะแก้ปัญหา Cloud Anchor ได้ยาก แนะนำให้ผู้ใช้ย้ายอุปกรณ์เพื่อให้มองเห็นตำแหน่ง Cloud Anchor ที่ต้องการโฮสต์ได้จากมุมต่างๆ
SUFFICIENT คุณภาพของจุดของฟีเจอร์ที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้านั้นน่าจะเพียงพอสำหรับ ARCore ที่จะแก้ไข Cloud Anchor ได้สำเร็จ อย่างไรก็ตาม ความถูกต้องของท่าทางที่แก้ไขแล้วจะลดลง แนะนำให้ผู้ใช้ย้ายอุปกรณ์เพื่อให้มองเห็นตำแหน่ง Cloud Anchor ที่ต้องการโฮสต์ได้จากมุมต่างๆ
GOOD คุณภาพของจุดของฟีเจอร์ที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้านั้นน่าจะเพียงพอสำหรับ ARCore ที่จะแก้ไข Cloud Anchor ด้วยความแม่นยำสูงได้สำเร็จ

แก้ไขแท็ก Anchor ที่โฮสต์ไว้ก่อนหน้านี้

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

คุณเริ่มการแก้ไขสำหรับ Cloud Anchor หลายรายการตามลำดับได้ มีการดำเนินการ Cloud Anchor พร้อมกันได้สูงสุด 40 รายการต่อครั้ง

ยกเลิกการดำเนินการหรือนำ Cloud Anchor ออก

เรียกใช้ cancel() เพื่อยกเลิกการดำเนินการ Cloud Anchor ที่รอดำเนินการ เรียกใช้ detach() เพื่อนำ Cloud Anchor ที่แก้ไขแล้วออกจากแอป

ตรวจสอบสถานะผลลัพธ์ของการดำเนินการ Cloud Anchor

ใช้ Anchor.CloudAnchorState เพื่อตรวจสอบสถานะผลลัพธ์ของการดำเนินการโฮสติ้งหรือการแก้ไข รวมถึงข้อผิดพลาด

ค่า คำอธิบาย
ERROR_CLOUD_ID_NOT_FOUND แก้ปัญหาไม่สำเร็จเนื่องจาก ARCore API ไม่พบรหัส Cloud Anchor ที่ระบุ
ERROR_HOSTING_DATASET_PROCESSING_FAILED โฮสติ้งล้มเหลวเนื่องจากเซิร์ฟเวอร์ประมวลผลชุดข้อมูลสำหรับ Anchor ที่ระบุไม่สำเร็จ โปรดลองอีกครั้งหลังจากที่อุปกรณ์รวบรวมข้อมูลเพิ่มเติมจากสภาพแวดล้อมแล้ว
ERROR_HOSTING_SERVICE_UNAVAILABLE เข้าถึง ARCore API ไม่ได้ ซึ่งอาจเกิดขึ้นได้จากสาเหตุหลายประการ อุปกรณ์อาจอยู่ในโหมดบนเครื่องบินหรืออาจไม่ได้เชื่อมต่ออินเทอร์เน็ต คำขอที่ส่งไปยังเซิร์ฟเวอร์อาจหมดเวลาโดยไม่ตอบกลับ อาจมีการเชื่อมต่อเครือข่ายที่ไม่ดี, การไม่พร้อมใช้งาน DNS, ปัญหาเกี่ยวกับไฟร์วอลล์ หรือสิ่งอื่นใดที่อาจส่งผลต่อความสามารถของอุปกรณ์ในการเชื่อมต่อกับ ARCore API
ERROR_INTERNAL งานโฮสติ้งหรือแก้ไขสำหรับ Anchor นี้เสร็จสิ้นโดยมีข้อผิดพลาดภายใน แอปไม่ควรพยายามกู้คืนจากข้อผิดพลาดนี้
ERROR_NOT_AUTHORIZED การให้สิทธิ์จากใบสมัครไม่ถูกต้อง โปรดดูการแก้ปัญหาเกี่ยวกับการให้สิทธิ์ ARCore API
ERROR_RESOLVING_SDK_VERSION_TOO_NEW แก้ไขปัญหา Cloud Anchor ไม่ได้เนื่องจากเวอร์ชัน SDK ที่ใช้แก้ไข Anchor ใหม่กว่าและเข้ากันไม่ได้กับเวอร์ชันที่ใช้โฮสต์
ERROR_RESOLVING_SDK_VERSION_TOO_OLD แก้ไข Cloud Anchor ไม่ได้เนื่องจากเวอร์ชัน SDK ที่ใช้แก้ไข Anchor เก่ากว่า และไม่สามารถใช้ร่วมกับเวอร์ชันที่ใช้โฮสต์ได้
ERROR_RESOURCE_EXHAUSTED แอปพลิเคชันใช้โควต้าคำขอที่จัดสรรให้กับโปรเจ็กต์ Google Cloud ที่ระบุหมดแล้ว คุณควรขอโควต้าเพิ่มเติมสำหรับ ARCore API สำหรับโปรเจ็กต์ของคุณจาก Google Developers Console
SUCCESS งานการโฮสต์หรือแก้ไขสำหรับ Anchor นี้เสร็จสมบูรณ์

โควต้า API สำหรับคำขอโฮสต์และแก้ปัญหา

ARCore API มีโควต้าต่อไปนี้สำหรับแบนด์วิดท์คำขอ

ประเภทโควต้า สูงสุด ระยะเวลา ใช้กับ
จำนวน Anchor ไม่จำกัด ไม่มี โปรเจ็กต์
คำขอสำหรับโฮสต์ Anchor 30 นาที ที่อยู่ IP และโปรเจ็กต์
คำขอ Anchor แก้ปัญหา 300 นาที ที่อยู่ IP และโปรเจ็กต์

แนวทางปฏิบัติแนะนำเพื่อประสบการณ์ที่ดีของผู้ใช้

แนะนำให้ผู้ใช้ทำตามขั้นตอนต่อไปนี้เพื่อให้แอปได้รับประสบการณ์ที่ดี

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

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

  • ตรวจสอบว่ามีแสงสว่างเพียงพอในสภาพแวดล้อมในชีวิตจริงขณะโฮสต์และแก้ไข Cloud Anchor

นโยบายการเลิกใช้งาน

  • แอปที่สร้างด้วย ARCore SDK 1.12.0 ขึ้นไปจะอยู่ภายใต้นโยบายการเลิกใช้งาน Cloud Anchor API
  • แอปที่สร้างด้วย ARCore SDK 1.11.0 หรือต่ำกว่าจะโฮสต์หรือแก้ปัญหา Cloud Anchor ไม่ได้ เนื่องจาก SDK ใช้ ARCore API รุ่นเก่าที่เลิกใช้งานแล้ว

สิ่งที่จะเกิดขึ้นหลังจากนี้