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

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

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

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 ARCore API trong ứng dụng của mình.

Bật các chức năng Cloud Anchor định cấu hình phiên

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

// 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

Quá trình lưu trữ bắt đầu bằng lệnh gọi đến 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ã Cloud Anchor ID duy nhất cho điểm neo cho thiết bị.

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

Ứng dụng của bạn phải 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 lệnh gọi lại hoàn tất.
  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ả Cloud Anchor ID với các ứng dụng khác và dùng mã đó để phân giải Cloud Anchor bằng ArSession_resolveCloudAnchorAsync().

Kiểm tra chất lượng lập bản đồ của các điểm đối tượng

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

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

Giải quyết quảng cáo cố định được lưu trữ trước đây

Gọi ArSession_resolveCloudAnchorAsync() để phân giải một Cloud Anchor được lưu trữ. ARCore API định kỳ so sánh các đặc điểm trực quan của cảnh với bản đồ tính năng 3D của neo để xác định vị trí và hướng của người dùng tương ứng với neo. Khi tìm thấy kết quả trùng khớp, API sẽ trả về vị trí 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ự. Có thể tồn tại tối đa 40 hoạt động Cloud Anchor đồng thời cùng một lúc.

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

Gọi ArFuture_cancel() để huỷ một thao tác Cloud Anchor đang chờ xử lý. Gọi ArAnchor_detach() để ngừng theo dõi và quên một Cloud Anchor đã được phân giải. Các tệp tham chiếu đến văn bản liên kết phải được giải phóng một cách riêng biệt bằng cách gọi ArAnchor_release().

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

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ị Mô tả
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Không giải quyết được do ARCore API không tìm thấy mã Cloud Anchor được cung cấp.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Không lưu trữ được do máy chủ không xử lý được tập dữ liệu cho quảng cáo cố định đã 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 truy cập được API ARCore. Lỗi này có thể xảy ra do một số lý do. Thiết bị có thể đang ở chế độ trên máy bay hoặc không có kết nối Internet. 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, sự cố tường lửa hoặc bất kỳ điều gì 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 giải quyết cho quảng cáo cố định này đã kết thúc với một lỗi nội bộ. Ứng dụng không được tìm cách khôi phục từ lỗi này.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Hãy xem bài viết 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 thể phân giải Cloud Anchor vì phiên bản SDK dùng để phân giải quảng cáo cố định này mới hơn và không tương thích với phiên bản dùng để lưu trữ phiên bản đó.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Không thể phân giải Cloud Anchor vì phiên bản SDK dùng để phân giải neo này đã cũ hơn và không tương thích với phiên bản dùng để lưu trữ URL đó.
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 Google Cloud cụ thể. 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 một tác vụ lưu trữ hoặc giải quyết cho quảng cáo cố định này.

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

API ARCore có các hạn mức sau đây 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 quảng cáo cố định không giới hạn Không áp dụng dự án
Yêu cầu máy chủ cố định 30 phút Địa chỉ IP và dự án
Yêu cầu giải quyết cố định 300 phút Địa chỉ IP và dự án

Các phương pháp hay nhất để tạo 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:

  • Hãy chờ vài giây sau khi phiên bắt đầu, trước khi cố gắng lưu trữ quảng cáo cố định (bằng cách đặt một đối tượng, v.v.). Việc này sẽ giúp quá trình theo dõi có thời gian ổn định.
  • Khi chọn một vị trí để lưu trữ 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ễ 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ư những bức tường trắng trống.

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

  • Đảm bảo rằng có đủ ánh sáng trong môi trường thực tế khi lưu trữ và phân giải Cloud Anchors.

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

  • Các ứng dụng được xây dựng bằng ARCore SDK 1.12.0 trở lên phải tuân thủ 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 SDK sử dụng API ARCore cũ hơn và không còn dùng nữa.

Các bước tiếp theo