Guia do desenvolvedor de imagens aumentadas para o Android NDK

Saiba como usar imagens aumentadas nos seus próprios apps.

Pré-requisitos

Verifique se você entendeu os conceitos fundamentais 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

Essa etapa é opcional se as imagens de referência desejadas já tiverem sido carregadas do arquivo do banco de dados. Para adicionar uma imagem durante a execução, chame ArAugmentedImageDatabase_addImage(), conforme mostrado abaixo. Consulte o app de exemplo augmented_image_c (link em inglês) para conferir as 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 posteriormente para identificar qual imagem de referência foi detectada.

Ativar rastreamento de imagem

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 recursos da imagem da câmera para fazer a correspondência com os dados no banco de dados de imagens.

Encontrar imagens aumentadas em uma sessão de RA

Para acessar as imagens correspondentes, procure 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).
  }
}

Compatibilidade com diferentes casos de uso

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

Seu app precisa usar o estado e o método de acompanhamento de maneiras diferentes, dependendo do caso de uso esperado.

  • Imagens corrigidas. A maioria dos casos de uso envolvendo imagens fixas no local, ou seja, que não devem ser movidas, pode simplesmente usar ArTrackingState para determinar se a imagem foi detectada e se a localização dela é conhecida. ArAugmentedImageTrackingMethod pode ser ignorado.

  • Imagens em movimento. Caso o app precise 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 Movendo a imagem
Exemplo Um pôster pendurado na parede Anúncio na lateral de um ônibus
A pose pode ser
considerada válida quando 		ArTrackingState == TRACKING ArTrackingState == TRACKING
e
ArAugmentedImageTrackingMethod == FULL_TRACKING