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

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

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

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

หากคุณเพิ่งเริ่มใช้ Cloud Anchor:

  • ตรวจสอบว่าคุณเข้าใจวิธีการทำงานของ Anchor และ Cloud Anchor แล้ว
  • อ่าน quickstart ของ 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 ที่ไม่ซ้ำกันสำหรับ 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 แก้ไข Anchor ของ Cloud ได้สำเร็จ แม้ว่าความแม่นยำของท่าทางที่แก้ไขแล้วจะลดลง กระตุ้นให้ผู้ใช้ย้ายอุปกรณ์เพื่อให้ดูตำแหน่งที่ต้องการของ 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 30 นาที ที่อยู่ IP และโปรเจ็กต์
คำขอ Anchor resolve 300 นาที ที่อยู่ IP และโปรเจ็กต์

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

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

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

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

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

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

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

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