Guida per gli sviluppatori sulle immagini aumentate per Android NDK

Scopri come utilizzare le immagini aumentate nelle tue app.

Prerequisiti

Prima di procedere, assicurati di conoscere i concetti fondamentali dell'AR e come configurare una sessione ARCore.

Crea un database di immagini

Crea un ArAugmentedImageDatabase per archiviare le immagini di riferimento. Esistono due modi:

  • Crea un database vuoto
ArAugmentedImageDatabase* ar_augmented_image_database = NULL;
ArAugmentedImageDatabase_create(ar_session, &ar_augmented_image_database);
 
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);

I file di database possono essere creati con lo strumento Immagine o chiamando ArAugmentedImageDatabase_serialize().

Aggiungere immagini al database

Questo passaggio è facoltativo se le immagini di riferimento che ti interessano sono già state caricate dal file del database. Per aggiungere un'immagine in fase di esecuzione, chiama ArAugmentedImageDatabase_addImage() come mostrato di seguito. Consulta l'app di esempio augmented_image_c per le funzioni nello spazio dei nomi util.

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;

I valori index e name vengono utilizzati in un secondo momento per identificare l'immagine di riferimento rilevata.

Attivare il monitoraggio delle immagini

Configura la sessione ARCore per monitorare le immagini registrando il database delle immagini:

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

Durante la sessione, ARCore utilizza i punti di riferimento dell'immagine della fotocamera per confrontarli con quelli nel database delle immagini.

Trovare le immagini aumentate in una sessione AR

Per ottenere le immagini corrispondenti, esegui il polling per gli ArAugmentedImage aggiornati nel loop di aggiornamento dei frame.

// 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).
  }
}

Supporto di diversi casi d'uso

Quando ARCore rileva un'immagine aumentata, crea un Trackable per quell'immagine aumentata e imposta ArTrackingState su TRACKING e ArAugmentedImageTrackingMethod su FULL_TRACKING. Quando l'immagine monitorata esce dal campo visivo della fotocamera, ARCore continua a impostare ArTrackingState su TRACKING, ma modifica ArAugmentedImageTrackingMethod in LAST_KNOWN_POSE continuando a fornire l'orientamento e la posizione dell'immagine.

L'app deve utilizzare lo stato e il metodo di monitoraggio in modo diverso a seconda del caso d'uso previsto.

  • Immagini fisse. La maggior parte dei casi d'uso che coinvolgono immagini fisse (ovvero non previste per essere spostate) può semplicemente utilizzare ArTrackingState per determinare se l'immagine è stata rilevata e se la sua posizione è nota. ArAugmentedImageTrackingMethod può essere ignorato.

  • Immagini in movimento. Se la tua app deve monitorare un'immagine in movimento, utilizza sia ArTrackingState sia ArAugmentedImageTrackingMethod per determinare se l'immagine è stata rilevata e se la sua posizione è nota.

Caso d'uso Immagine fissa Immagine in movimento
Esempio Un poster appeso a una parete Un annuncio sulla fiancata di un autobus
La posa può essere
considerata valida quando 		ArTrackingState == TRACKING ArTrackingState == TRACKING
e
ArAugmentedImageTrackingMethod == FULL_TRACKING