Hướng dẫn dành cho nhà phát triển Cloud Anchors cho Android NDK (C)

Tìm hiểu cách sử dụng Cloud Anchors trong ứng dụng của riêng bạn.

Điều kiện tiên quyết

Hãy đảm bảo bạn hiểu rõ các khái niệm cơ bản về AR và cách định cấu hình một phiên ARCore trước khi tiếp tục.

Nếu bạn mới sử dụng Neo trên đám mây, hãy đảm bảo rằng bạn hiểu rõ cách hoạt động của máng liên kết và Neo trên đám mây.

Bật API ARCore

Trước khi sử dụng Cloud Anchors trong ứng dụng, trước tiên, bạn phải bật API ARCore trong ứng dụng của mình.

Bật các chức năng của Cloud Anchor trong cấu hình phiên

Sau khi bạn bật chức năng Cloud Anchors trong ứng dụng, hãy bật các chức năng của Cloud Anchors trong phần cấu hình phiên thực tế tăng cường của ứng dụng để có thể giao tiếp với API ARCore:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Lưu trữ Cloud Anchor

Khi tổ chức, bạn sẽ bắt đầu cuộc gọi đến số ArSession_hostCloudAnchorAsync(). ARCore sẽ tải dữ liệu hình ảnh, tư thế thiết bị và tư thế neo lên API ARCore. Sau đó, API sẽ xử lý thông tin này để xây dựng bản đồ tính năng 3D, cuối cùng sẽ trả về một mã nhận dạng neo duy nhất trên đám mây cho thiết bị liên kết.

Bạn cũng có thể kéo dài thời gian tồn tại của quảng cáo cố định được lưu trữ bằng cách sử dụng API Quản lý neo trên đám mây ARCore.

Ứng dụng của bạn nên làm theo các bước sau để hoàn tất việc lưu trữ Cloud Anchor:

  1. Gọi ArSession_hostCloudAnchorAsync().
  2. Chờ lệnh gọi lại hoặc liên tục kiểm tra trạng thái Tương lai cho đến khi thực hiện xong.
  3. Kiểm tra trạng thái kết quả để xác định xem thao tác có thành công hay không hoặc diễn giải mã lỗi nếu thao tác đó không thành công.
  4. Chia sẻ kết quả nhận dạng Cloud Anchor ID với các ứng dụng khác và sử dụng mã này để phân giải Cloud Anchor bằng cách sử dụng ArSession_resolveCloudAnchorAsync().

Kiểm tra chất lượng liên kết của các điểm đối tượng

ArFeatureMapQuality cho biết chất lượng của các điểm nổi bật mà ARCore nhìn thấy trong vài giây trước đó từ một tư thế máy ảnh nhất định. Những quảng cáo cố định trên đám mây được lưu trữ bằng các tính năng chất lượng cao thường được giải quyết chính xác hơn. Sử dụng ArSession_estimateFeatureMapQualityForHosting() để nhận thông tin ước tính về chất lượng bản đồ đối tượng cho một tư thế máy ảnh cụ thể.

Giá trị Nội dung mô tả
INSUFFICIENT Chất lượng của các điểm nổi bật được xác định từ tư thế trong vài giây trước ở mức thấp. Trạng thái này cho biết rằng ARCore có thể sẽ gặp nhiều khó khăn hơn khi phân giải Cloud Anchor. Hãy khuyến khích người dùng di chuyển thiết bị để có thể nhìn thấy vị trí mong muốn của Neo trên đám mây mà họ muốn lưu trữ từ nhiều góc độ.
SUFFICIENT Chất lượng của các điểm đặc trưng được xác định từ tư thế trong vài giây trước có thể đủ để ARCore phân giải thành công Cloud Anchor, mặc dù độ chính xác của tư thế đã giải quyết có thể sẽ giảm. Hãy khuyến khích người dùng di chuyển thiết bị để có thể nhìn thấy vị trí mong muốn của Neo trên đám mây mà họ muốn lưu trữ từ nhiều góc độ.
GOOD Chất lượng của các điểm tính năng được xác định từ tư thế trong vài giây trước có thể đủ để ARCore phân giải thành công Cloud Anchor với độ chính xác cao.

Xử lý quảng cáo cố định cuối màn hình được lưu trữ trước đó

Gọi ArSession_resolveCloudAnchorAsync() để phân giải một Cloud Anchor được lưu trữ. API ARCore định kỳ so sánh các tính năng hình ảnh từ cảnh với bản đồ tính năng 3D của liên kết để xác định vị trí và hướng của người dùng so với neo. Khi tìm thấy kết quả trùng khớp, API sẽ trả về tư thế của Cloud Anchor được lưu trữ.

Bạn có thể bắt đầu phân giải cho nhiều Cloud Anchors theo trình tự. Tối đa 40 hoạt động Cloud Anchor đồng thời có thể tồn tại cùng lúc.

Huỷ thao tác hoặc xoá Cloud Anchor

Gọi ArFuture_cancel() để huỷ thao tác Cloud Anchor đang chờ xử lý. Gọi ArAnchor_detach() để ngừng theo dõi và quên Cloud Anchor đã được giải quyết. Các tham chiếu đến quảng cáo cố định phải được huỷ bỏ riêng biệt bằng cách gọi ArAnchor_release().

Kiểm tra trạng thái kết quả của thao tác Cloud Anchor

Hãy dùng ArCloudAnchorState để kiểm tra trạng thái kết quả của hoạt động lưu trữ hoặc giải quyết, bao gồm cả các lỗi.

Giá trị Nội dung mô tả
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Không phân giải được do API ARCore không tìm thấy mã nhận dạng neo được cung cấp cho đám mây.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Không lưu trữ được vì máy chủ không thể xử lý thành công tập dữ liệu cho điểm neo đã cho. Hãy thử lại sau khi thiết bị đã thu thập thêm dữ liệu từ môi trường.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE Không thể truy cập API ARCore. Lỗi này có thể xảy ra do một số lý do. Thiết bị này có thể đang ở chế độ trên máy bay hoặc có thể không có kết nối Internet hoạt động. Yêu cầu được gửi đến máy chủ có thể đã hết thời gian chờ mà không có phản hồi. Có thể có kết nối mạng kém, không sử dụng được DNS, vấn đề với tường lửa hoặc bất cứ vấn đề nào khác có thể ảnh hưởng đến khả năng kết nối của thiết bị với API ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Một tác vụ lưu trữ hoặc phân giải cho liên kết này đã kết thúc gặp lỗi nội bộ. Ứng dụng không được tìm cách khôi phục lỗi này.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Xem phần Khắc phục sự cố về việc uỷ quyền API ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Không phân giải được Cloud Anchor vì phiên bản SDK dùng để phân giải quảng cáo cố định cuối màn hình mới hơn và không tương thích với phiên bản dùng để lưu trữ quảng cáo cố định cuối màn hình.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Không phân giải được Cloud Anchor vì phiên bản SDK dùng để phân giải quảng cáo cố định đã cũ hơn và không tương thích với phiên bản dùng để lưu trữ quảng cáo cố định.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED Ứng dụng đã dùng hết hạn mức yêu cầu được phân bổ cho dự án được nêu trên Google Cloud. Bạn nên yêu cầu hạn mức bổ sung cho API ARCore cho dự án của mình từ Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS Đã hoàn tất thành công tác vụ lưu trữ hoặc phân giải cho liên kết này.

Hạn mức API cho các yêu cầu lưu trữ và giải quyết

API ARCore có các hạn mức sau cho băng thông yêu cầu:

Loại hạn mức Tối đa Thời lượng Áp dụng cho
Số lượng neo không giới hạn Không áp dụng dự án
Yêu cầu liên kết máy chủ 30 phút Dự án và địa chỉ IP
Yêu cầu resolve liên kết 300 phút Dự án và địa chỉ IP

Các phương pháp hay nhất để mang lại trải nghiệm tốt cho người dùng

Hãy hướng dẫn người dùng thực hiện những việc sau để đảm bảo mang lại trải nghiệm tốt cho người dùng trên ứng dụng của bạn:

  • Đợi vài giây sau khi phiên bắt đầu trước khi cố gắng lưu trữ một điểm neo (bằng cách đặt một đối tượng, v.v.). Việc này giúp quá trình theo dõi có một khoảng thời gian ổn định.
  • Khi chọn một vị trí để đặt quảng cáo cố định, hãy cố gắng tìm một khu vực có các đặc điểm trực quan dễ dàng phân biệt với nhau. Để có kết quả tốt nhất, hãy tránh các bề mặt phản chiếu hoặc bề mặt thiếu đặc điểm trực quan, chẳng hạn như tường trắng trống.

  • Giúp máy ảnh được huấn luyện ở trung tâm yêu thích và di chuyển thiết bị xung quanh trung tâm yêu thích để lập bản đồ môi trường từ các góc khác nhau, duy trì khoảng cách vật lý gần bằng như khi bạn chụp. Điều này sẽ giúp thu thập nhiều dữ liệu trực quan hơn và tăng cường độ phân giải.

  • Đảm bảo có đủ ánh sáng trong môi trường thực tế khi lưu trữ và phân giải các phương thức neo của đám mây.

Chính sách về việc ngừng cung cấp

  • Các ứng dụng được xây dựng bằng SDK ARCore 1.12.0 trở lên thuộc phạm vi điều chỉnh của chính sách về việc ngừng sử dụng Cloud Anchor API.
  • Các ứng dụng được xây dựng bằng ARCore SDK 1.11.0 trở xuống không thể lưu trữ hoặc phân giải Cloud Anchors do sử dụng API ARCore cũ và không dùng nữa.

Các bước tiếp theo