本頁面由 Cloud Translation API 翻譯而成。

Android NDK 適用的擴增圖片開發人員指南

瞭解如何在自家應用程式中使用擴增圖片。

必要條件

請務必先瞭解基本 AR 概念，並瞭解如何設定 ARCore 工作階段，再繼續操作。

建立圖片資料庫

建立 ArAugmentedImageDatabase 以儲存參考圖片。有兩種方法：

建立空白資料庫

ArAugmentedImageDatabase* ar_augmented_image_database = NULL;
ArAugmentedImageDatabase_create(ar_session, &ar_augmented_image_database);

從圖片資料庫檔案讀取。如要瞭解 util::LoadFileFromAssetManager，請參閱 [AugmentedImage C 範例應用程式]。

std::string database_buffer;
util::LoadFileFromAssetManager(asset_manager_, "sample_database.imgdb",
                               &database_buffer);
uint8_t* raw_buffer = reinterpret_cast<uint8_t*>(&database_buffer.front());

ArAugmentedImageDatabase* ar_augmented_image_database = NULL;
const ArStatus status = ArAugmentedImageDatabase_deserialize(
    ar_session, raw_buffer, database_buffer.size(),
    &ar_augmented_image_database);

您可以使用圖片工具或呼叫 ArAugmentedImageDatabase_serialize() 建立資料庫檔案。

將圖片新增至資料庫

如果您已從資料庫檔案載入所需的參考圖片，則可略過這個步驟。如要在執行階段新增圖片，請呼叫 ArAugmentedImageDatabase_addImage()，如下所示。如要瞭解 util 命名空間中的函式，請參閱 augmented_image_c 範例應用程式。

int32_t width, height, stride, index;
uint8_t* image_pixel_buffer = nullptr;
constexpr const char kSampleImageName[] = "default.jpg";
bool load_image_result = util::LoadImageFromAssetManager(
    kSampleImageName, &width, &height, &stride, &image_pixel_buffer);

uint8_t* grayscale_buffer = nullptr;
util::ConvertRgbaToGrayscale(image_pixel_buffer, width, height, stride,
                             &grayscale_buffer);

int32_t grayscale_stride = stride / 4;
const ArStatus status = ArAugmentedImageDatabase_addImage(
    ar_session_, ar_augmented_image_database, kSampleImageName,
    grayscale_buffer, width, height, grayscale_stride, &index);

// If the physical size of the image is known, you can instead use
//     ArStatus ArAugmentedImageDatabase_addImageWithPhysicalSize
// This will improve the initial detection speed. ARCore will still actively
// estimate the physical size of the image as it is viewed from multiple
// viewpoints.

delete[] image_pixel_buffer;
delete[] grayscale_buffer;

系統稍後會使用 index 和 name 值，識別系統偵測到的參考圖片。

啟用圖片追蹤

如要設定 ARCore 工作階段，以便追蹤圖片，請註冊圖片資料庫：

ArConfig_setAugmentedImageDatabase(ar_session_, ar_config,
                                   ar_augmented_image_database);
const ArStatus status = ArSession_configure(ar_session_, ar_config);

在工作階段期間，ARCore 會使用攝影機圖像中的特徵點，比對圖像資料庫中的特徵點。

在 AR 工作階段中尋找擴增圖片

如要取得相符的圖片，請在影格更新迴圈中輪詢更新的 ArAugmentedImage。

// Update loop, in onDrawFrame
ArTrackableList* updated_image_list = nullptr;
ArTrackableList_create(ar_session_, &updated_image_list);
ArFrame_getUpdatedTrackables(
    ar_session_, ar_frame_, AR_TRACKABLE_AUGMENTED_IMAGE, updated_image_list);

int32_t image_list_size;
ArTrackableList_getSize(ar_session_, updated_image_list, &image_list_size);

for (int i = 0; i < image_list_size; ++i) {
  ArTrackable* ar_trackable = nullptr;
  ArTrackableList_acquireItem(ar_session_, updated_image_list, i,
                              &ar_trackable);
  ArAugmentedImage* image = ArAsAugmentedImage(ar_trackable);

  ArTrackingState tracking_state;
  ArTrackable_getTrackingState(ar_session_, ar_trackable, &tracking_state);

  int image_index;
  ArAugmentedImage_getIndex(ar_session_, image, &image_index);

  if (tracking_state == AR_TRACKING_STATE_TRACKING) {
    util::ScopedArPose scopedArPose(ar_session_);
    ArAugmentedImage_getCenterPose(ar_session_, image,
                                   scopedArPose.GetArPose());

    ArAnchor* image_anchor = nullptr;
    const ArStatus status = ArTrackable_acquireNewAnchor(
        ar_session_, ar_trackable, scopedArPose.GetArPose(), &image_anchor);

    // For example, you can now render content at the image anchor, choosing
    // content based on the image index (or name).
  }
}

支援不同用途

ARCore 偵測到擴增圖片時，會為該擴增圖片建立 Trackable，並將 ArTrackingState 設為 TRACKING，將 ArAugmentedImageTrackingMethod 設為 FULL_TRACKING。當追蹤的圖片移出相機視野時，ARCore 會繼續將 ArTrackingState 設為 TRACKING，但會將 ArAugmentedImageTrackingMethod 變更為 LAST_KNOWN_POSE，同時繼續提供圖片的方向和位置。

應用程式應根據預期用途，以不同的方式使用追蹤狀態和追蹤方法。

修正圖片。大多數涉及固定圖片 (也就是不會移動的圖片) 的用途，只要使用 ArTrackingState 即可判斷是否已偵測到圖片，以及是否已知圖片的位置。ArAugmentedImageTrackingMethod 可忽略。
動態圖片：如果應用程式需要追蹤移動中的圖片，請同時使用 ArTrackingState 和 ArAugmentedImageTrackingMethod，判斷是否已偵測到圖片，以及是否已知圖片的位置。

用途	已修正的圖片	動態圖片
範例	牆上掛著海報	公車車身廣告
當姿勢符合下列條件時，系統會將其視為有效：	`ArTrackingState == TRACKING`	`ArTrackingState == TRACKING` 和 `ArAugmentedImageTrackingMethod == FULL_TRACKING`