Guia do desenvolvedor sobre imagens aumentadas para Android

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

Cada banco de dados de imagens pode armazenar informações de até 1.000 imagens.

Há duas maneiras de criar um AugmentedImageDatabase:

• Carregar um banco de dados de imagens salvo. Em seguida, adicione mais imagens de referência, se quiser.
• Crie um novo banco de dados vazio. Em seguida, adicione as imagens de referência uma por vez.

Carregar um banco de dados de imagens salvo

Use AugmentedImageDatabase.deserialize() para carregar um banco de dados de imagens:

Java

AugmentedImageDatabase imageDatabase;
try (InputStream inputStream = this.getAssets().open("example.imgdb")) {
  imageDatabase = AugmentedImageDatabase.deserialize(session, inputStream);
} catch (IOException e) {
  // The Augmented Image database could not be deserialized; handle this error appropriately.
}

Kotlin

val imageDatabase = this.assets.open("example.imgdb").use {
  AugmentedImageDatabase.deserialize(session, it)
}

Os bancos de dados de imagens podem ser criados usando a ferramenta de linha de comando arcoreimg durante o desenvolvimento ou chamando AugmentedImageDatabase.serialize() em um banco de dados que contém o que é carregado na memória.

Criar um novo banco de dados vazio

Para criar um banco de dados de imagens vazio no momento da execução, use o construtor AugmentedImageDatabase:

Java

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

Kotlin

val imageDatabase = AugmentedImageDatabase(session)

Adicionar imagens a um banco de dados

Adicione imagens ao seu banco de dados chamando AugmentedImageDatabase.addImage() para cada imagem, especificando um widthInMeters opcional.

Java

Bitmap bitmap;
try (InputStream bitmapString = getAssets().open("dog.jpg")) {
  bitmap = BitmapFactory.decodeStream(bitmapString);
} catch (IOException e) {
  // The bitmap could not be found in assets; handle this error appropriately.
  throw new AssertionError("The bitmap could not be found in assets.", e);
}

// If the physical size of the image is not known, use addImage(String, Bitmap) instead, at the
// expense of an increased image detection time.
float imageWidthInMeters = 0.10f; // 10 cm
int dogIndex = imageDatabase.addImage("dog", bitmap, imageWidthInMeters);

Kotlin

val bitmap = assets.open("dog.jpg").use { BitmapFactory.decodeStream(it) }
// If the physical size of the image is not known, use addImage(String, Bitmap) instead, at the
// expense of an increased image detection time.
val imageWidthInMeters = 0.10f // 10 cm
val dogIndex = imageDatabase.addImage("dog", bitmap, imageWidthInMeters)

Os índices retornados podem ser usados mais tarde para identificar qual imagem de referência foi detectada.

Ativar o rastreamento de imagens

Configure sua sessão do ARCore para começar a rastrear imagens definindo a configuração da sessão como uma que está configurada com o banco de dados de imagens desejado:

Java

Config config = new Config(session);
config.setAugmentedImageDatabase(imageDatabase);
session.configure(config);

Kotlin

val config = Config(session)
config.augmentedImageDatabase = imageDatabase
session.configure(config)

Durante a sessão, o ARCore procura imagens comparando os pontos de recurso da imagem da câmera com os do banco de dados de imagens.

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

Java

Collection<AugmentedImage> updatedAugmentedImages =
    frame.getUpdatedTrackables(AugmentedImage.class);
for (AugmentedImage img : updatedAugmentedImages) {
  if (img.getTrackingState() == TrackingState.TRACKING) {
    // Use getTrackingMethod() to determine whether the image is currently
    // being tracked by the camera.
    switch (img.getTrackingMethod()) {
      case LAST_KNOWN_POSE:
        // The planar target is currently being tracked based on its last
        // known pose.
        break;
      case FULL_TRACKING:
        // The planar target is being tracked using the current camera image.
        break;
      case NOT_TRACKING:
        // The planar target isn't been tracked.
        break;
    }

    // You can also check which image this is based on img.getName().
    if (img.getIndex() == dogIndex) {
      // TODO: Render a 3D version of a dog in front of img.getCenterPose().
    } else if (img.getIndex() == catIndex) {
      // TODO: Render a 3D version of a cat in front of img.getCenterPose().
    }
  }
}

Kotlin

val updatedAugmentedImages = frame.getUpdatedTrackables(AugmentedImage::class.java)

for (img in updatedAugmentedImages) {
  if (img.trackingState == TrackingState.TRACKING) {
    // Use getTrackingMethod() to determine whether the image is currently
    // being tracked by the camera.
    when (img.trackingMethod) {
      AugmentedImage.TrackingMethod.LAST_KNOWN_POSE -> {
        // The planar target is currently being tracked based on its last known pose.
      }
      AugmentedImage.TrackingMethod.FULL_TRACKING -> {
        // The planar target is being tracked using the current camera image.
      }
      AugmentedImage.TrackingMethod.NOT_TRACKING -> {
        // The planar target isn't been tracked.
      }
    }

    // You can also check which image this is based on AugmentedImage.getName().
    when (img.index) {
      dogIndex -> TODO("Render a 3D version of a dog at img.getCenterPose()")
      catIndex -> TODO("Render a 3D version of a cat at img.getCenterPose()")
    }
  }
}

Suporte a diferentes casos de uso

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

O app precisa usar essas enumerações 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 TrackingState para determinar se a imagem foi detectada e se o local dela é conhecido. TrackingMethod pode ser ignorado.

• Mover imagens. Se o app precisar rastrear uma imagem em movimento, use TrackingState e TrackingMethod 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	TrackingState == TRACKING	TrackingState == TRACKING e TrackingMethod == FULL_TRACKING

Observação: se uma imagem na visualização da câmera mudar muito rapidamente para uma segunda imagem com aproximadamente o mesmo tamanho e posição, o ARCore pode definir erroneamente o TrackingMethod como FULL_TRACKING para ambas as imagens e também atualizar a âncora da primeira imagem aumentada para a posição da nova imagem. Por exemplo, isso poderia acontecer se você estivesse apontando a câmera para uma imagem em um navegador da Web e mudasse para outra guia do navegador contendo uma segunda imagem de tamanho e posição semelhantes.

Consulte também

• Os projetos de amostra de imagens aumentadas no SDK do ARCore.

• O codelab de imagens aumentadas do ARCore.