Guia do desenvolvedor de imagens aumentadas para o Android NDK

Aprenda a usar imagens aumentadas nos seus apps.

Pré-requisitos

Entenda os conceitos básicos de RA e como configurar uma sessão do ARCore antes de continuar.

Criar um banco de dados de imagens

Crie um ArAugmentedImageDatabase para armazenar imagens de referência. Há duas formas:

  • Criar um banco de dados vazio
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);

Os arquivos de banco de dados podem ser criados com a ferramenta de imagem ou chamando ArAugmentedImageDatabase_serialize().

Adicionar imagens ao banco de dados

Esta etapa é opcional se as imagens de referência desejadas já tiverem sido carregadas do arquivo de banco de dados. Para adicionar uma imagem no momento da execução, chame ArAugmentedImageDatabase_addImage(), conforme mostrado abaixo. Consulte o app de exemplo augmented_image_c para conferir funções no namespace 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;

Os valores index e name são usados mais tarde para identificar qual imagem de referência foi detectada.

Ativar o rastreamento de imagens

Configure sua sessão do ARCore para rastrear imagens registrando o banco de dados de imagens:

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

Durante a sessão, o ARCore usa pontos de características da imagem da câmera para corresponder aos do banco de dados de imagens.

Encontrar imagens aumentadas em uma sessão de RA

Para receber as imagens correspondentes, consulte ArAugmentedImages atualizados no loop de atualização de frames.

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

Suporte a diferentes casos de uso

Quando o ARCore detecta uma imagem aumentada, ele cria um Trackable para essa imagem e define ArTrackingState como TRACKING e ArAugmentedImageTrackingMethod como FULL_TRACKING. Quando a imagem rastreada sai da visualização da câmera, o ARCore continua definindo ArTrackingState como TRACKING, mas muda o ArAugmentedImageTrackingMethod para LAST_KNOWN_POSE, continuando a fornecer a orientação e a posição da imagem.

O app precisa usar o estado e o método de rastreamento de maneira diferente, dependendo do caso de uso previsto.

  • Imagens fixas. A maioria dos casos de uso que envolvem imagens fixadas no lugar (ou seja, que não devem se mover) pode simplesmente usar ArTrackingState para determinar se a imagem foi detectada e se o local dela é conhecido. ArAugmentedImageTrackingMethod pode ser ignorado.

  • Mover imagens. Se o app precisar rastrear uma imagem em movimento, use ArTrackingState e ArAugmentedImageTrackingMethod para determinar se a imagem foi detectada e se a posição dela é conhecida.

Caso de uso Imagem fixa Imagem em movimento
Exemplo Um cartaz pendurado na parede Um anúncio na lateral de um ônibus
A pose pode ser
considerada válida quando 		ArTrackingState == TRACKING ArTrackingState == TRACKING
e
ArAugmentedImageTrackingMethod == FULL_TRACKING