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

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

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

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

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

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

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

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

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

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

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

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