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

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

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

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

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

เปิดใช้ ARCore API

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

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

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

โฮสต์ Cloud Anchor

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

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

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

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

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

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

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

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

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

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

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

ค่า คำอธิบาย
ErrorResolvingCloudIdNotFound แก้ปัญหาไม่สำเร็จเนื่องจาก ARCore API ไม่พบรหัส Cloud Anchor ที่ระบุ
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 งานการโฮสต์หรือแก้ไขสำหรับ 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 รุ่นเก่าที่เลิกใช้งานแล้ว

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