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

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

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

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

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

เปิดใช้ ARCore API

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

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

แก้ปัญหาเกี่ยวกับหมุดที่โฮสต์ไว้ก่อนหน้านี้

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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