คู่มือนักพัฒนาซอฟต์แวร์ Cloud Anchor สำหรับ Unity (AR Foundation)

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

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

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

หากคุณเพิ่งเริ่มใช้ Cloud Anchor โปรดทำความเข้าใจวิธีการทำงานของหมุดและ Cloud Anchor

เปิดใช้ ARCore API

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

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

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

โฮสต์ Cloud Anchor

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

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

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

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

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

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

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

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

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

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

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

ระบบจะเรียก ARCloudAnchor.OnDestroy() โดยอัตโนมัติเมื่อนำคอมโพเนนต์ ARCloudAnchor ออกจากออบเจ็กต์เกมที่มีคอมโพเนนต์ดังกล่าว ซึ่งจะเป็นการแยกออกและปล่อยออบเจ็กต์ Cloud Anchor เดิม

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

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

ค่า คำอธิบาย
ErrorResolvingCloudIdNotFound การแก้ไขไม่สำเร็จเนื่องจาก ARCore API ไม่พบรหัสหมุดบนระบบคลาวด์ที่ระบุ
ErrorHostingDatasetProcessingFailed โฮสติ้งล้มเหลวเนื่องจากเซิร์ฟเวอร์ประมวลผลชุดข้อมูลสำหรับ Anchor ที่ระบุไม่สำเร็จ ลองอีกครั้งหลังจากที่อุปกรณ์รวบรวมข้อมูลเพิ่มเติมจากสภาพแวดล้อมแล้ว
ErrorHostingServiceUnavailable เข้าถึง ARCore API ไม่ได้ ซึ่งอาจเกิดขึ้นได้จากสาเหตุหลายประการ อุปกรณ์อาจอยู่ในโหมดบนเครื่องบินหรืออาจไม่มีการเชื่อมต่ออินเทอร์เน็ต คำขอที่ส่งไปยังเซิร์ฟเวอร์อาจหมดเวลาโดยไม่ได้รับการตอบกลับ อาจเป็นเพราะการเชื่อมต่อเครือข่ายไม่ดี, DNS ไม่พร้อมใช้งาน, ปัญหาไฟร์วอลล์ หรือสิ่งอื่นๆ ที่อาจส่งผลต่อความสามารถของอุปกรณ์ในการเชื่อมต่อกับ ARCore API
ErrorInternal งานโฮสติ้งหรือแก้ไขสำหรับ Anchor นี้เสร็จสิ้นโดยมีข้อผิดพลาดภายใน แอปไม่ควรพยายามกู้คืนจากข้อผิดพลาดนี้
ErrorNotAuthorized แอปสื่อสารกับ ARCore API ไม่ได้เนื่องจากการให้สิทธิ์ไม่ถูกต้อง ตรวจสอบการตั้งค่าโปรเจ็กต์ > XR > ส่วนขยาย ARCore เพื่อดูกลยุทธ์การให้สิทธิ์ที่ถูกต้อง
ErrorResolvingPackageTooNew ไม่สามารถแก้ไข Cloud Anchor ได้เนื่องจากแพ็กเกจส่วนขยาย ARCore ที่ใช้แก้ไข Cloud Anchor เป็นเวอร์ชันใหม่กว่าและไม่เข้ากันได้กับเวอร์ชันที่ใช้โฮสต์
ErrorResolvingPackageTooOld แก้ไข Cloud Anchor ไม่ได้เนื่องจากแพ็กเกจส่วนขยาย ARCore ที่ใช้เพื่อแก้ไข Cloud Anchor เป็นเวอร์ชันเก่า และไม่สามารถใช้ร่วมกับเวอร์ชันที่ใช้โฮสต์ได้
ErrorResourceExhausted แอปพลิเคชันใช้โควต้าคำขอที่จัดสรรให้กับโปรเจ็กต์ Google Cloud หนึ่งๆ จนหมดแล้ว คุณควรขอโควต้าเพิ่มเติมสำหรับ ARCore API สำหรับโปรเจ็กต์ของคุณจาก Google Developers Console
Success งานโฮสติ้งหรือการแก้ไขสำหรับหมุดนี้เสร็จสมบูรณ์แล้ว

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

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

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

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

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

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

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

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

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

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

ขั้นตอนถัดไป