Guida per gli sviluppatori sulle immagini aumentate per Android

Scopri come utilizzare le immagini aumentate nelle tue app.

Prerequisiti

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

Crea un database di immagini

Ogni database di immagini può memorizzare informazioni su un massimo di 1000 immagini.

Esistono due modi per creare un AugmentedImageDatabase:

  • Carica un database di immagini salvato. Poi, se vuoi, aggiungi altre immagini di riferimento.
  • Crea un nuovo database vuoto. quindi aggiungi le immagini di riferimento una alla volta.

Carica un database di immagini salvato

Utilizza AugmentedImageDatabase.deserialize() per caricare un database di immagini esistente:

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

I database di immagini possono essere creati utilizzando lo strumento a riga di comando arcoreimg durante lo sviluppo o chiamando AugmentedImageDatabase.serialize() su un database contenente le immagini caricate in memoria.

Crea un nuovo database vuoto

Per creare un database di immagini vuoto in fase di esecuzione, utilizza il costruttore AugmentedImageDatabase:

Java

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

Kotlin

val imageDatabase = AugmentedImageDatabase(session)

Aggiungi immagini a un database esistente

Aggiungi immagini al database di immagini chiamando AugmentedImageDatabase.addImage() per ogni immagine, specificando un widthInMeters facoltativo.

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)

Gli indici restituiti possono essere utilizzati in un secondo momento per identificare l'immagine di riferimento rilevato.

Attiva il monitoraggio delle immagini

Configura la sessione ARCore per iniziare a monitorare le immagini impostando la configurazione della sessione su una configurata con il database di immagini desiderato:

Java

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

Kotlin

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

Durante la sessione, ARCore cerca le immagini abbinando i punti di riferimento dell'immagine della fotocamera a quelli nel database delle immagini.

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

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()")
    }
  }
}

Supporto di diversi casi d'uso

Quando ARCore rileva un'immagine aumentata, crea un elemento Trackable per quella immagine Set e immagini aumentate TrackingState a TRACKING e TrackingMethod a FULL_TRACKING. Quando l'immagine monitorata esce dal campo visivo della fotocamera, ARCore cambia TrackingMethod in LAST_KNOWN_POSE continuando a fornire l'orientamento e la posizione dell'immagine.

La tua app dovrebbe utilizzare queste enumerazioni in modo diverso a seconda dell'uso previsto per verificare se è così.

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

  • Immagini in movimento. Se la tua app deve monitorare un'immagine in movimento, utilizza sia TrackingState sia TrackingMethod 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 un muro Un annuncio sulla fiancata di un autobus
La posa può essere
considerata valida quando
TrackingState == TRACKING TrackingState == TRACKING
e
TrackingMethod == FULL_TRACKING

Vedi anche