Guía para desarrolladores de imágenes aumentadas del NDK de Android

Aprende a usar imágenes aumentadas en tus propias apps.

Requisitos previos

Asegúrate de comprender los conceptos fundamentales de RA y cómo configurar una sesión de ARCore antes de continuar.

Crea una base de datos de imágenes

Crea un ArAugmentedImageDatabase para almacenar imágenes de referencia. Existen dos maneras de hacerlo:

  • Crea una base de datos vacía
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);

Los archivos de la base de datos se pueden crear con la Herramienta de imágenes o mediante una llamada a ArAugmentedImageDatabase_serialize().

Agregar imágenes a la base de datos

Este paso es opcional si las imágenes de referencia deseadas ya se cargaron desde el archivo de la base de datos. Para agregar una imagen en el tiempo de ejecución, llama a ArAugmentedImageDatabase_addImage() como se muestra a continuación. Consulta la app de ejemplo augmented_image_c para ver las funciones en el espacio de nombres 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;

Los valores index y name se usarán más adelante para identificar qué imagen de referencia se detectó.

Habilitar el seguimiento de imágenes

Registra la base de datos de imágenes para configurar tu sesión de ARCore a fin de realizar un seguimiento de las imágenes:

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

Durante la sesión, ARCore usa puntos de atributos de la imagen de la cámara para compararlos con los de la base de datos de imágenes.

Encuentra imágenes aumentadas en una sesión de RA

Para obtener las imágenes coincidentes, sondea en busca de ArAugmentedImage actualizadas en el bucle de actualización del marco.

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

Compatibilidad con diferentes casos de uso

Cuando ARCore detecta una imagen aumentada, crea un Trackable para ella y establece ArTrackingState en TRACKING y ArAugmentedImageTrackingMethod en FULL_TRACKING. Cuando la imagen rastreada sale de la vista de cámara, ARCore continúa estableciendo ArTrackingState en TRACKING, pero cambia ArAugmentedImageTrackingMethod a LAST_KNOWN_POSE mientras continúa proporcionando la orientación y la posición de la imagen.

Tu app debe usar el estado y el método de seguimiento de manera diferente según el caso de uso previsto.

  • Imágenes fijas. La mayoría de los casos de uso que involucran imágenes fijas en el lugar (es decir, que no se espera que se muevan) pueden simplemente usar ArTrackingState para determinar si se detectó la imagen y si se conoce su ubicación. Se puede ignorar ArAugmentedImageTrackingMethod.

  • Imágenes en movimiento Si tu app necesita realizar el seguimiento de una imagen en movimiento, usa ArTrackingState y ArAugmentedImageTrackingMethod para determinar si se detectó la imagen y si se conoce su posición.

Caso de uso Imagen fija Moviendo la imagen
Ejemplo Un póster colgado en una pared Un anuncio junto a un autobús
La pose puede
considerarse válida cuando 		ArTrackingState == TRACKING ArTrackingState == TRACKING
y
ArAugmentedImageTrackingMethod == FULL_TRACKING