Guida per gli sviluppatori sulle immagini aumentate per Android

Scopri come utilizzare le immagini aumentate nelle tue app.

Prerequisiti

Assicurati di aver compreso i concetti fondamentali di AR e di configurare una sessione ARCore prima di procedere.

Crea un database di immagini

Ogni database di immagini può archiviare informazioni per un massimo di 1000 immagini.

Esistono due modi per creare una AugmentedImageDatabase:

  • Carica un database di immagini salvate. Poi, facoltativamente, 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 che contiene contenuti caricati in memoria.

Crea un nuovo database vuoto

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

Java

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

Kotlin

val imageDatabase = AugmentedImageDatabase(session)

Aggiungere immagini a un database esistente

Aggiungi immagini al tuo database di immagini chiamando AugmentedImageDatabase.addImage() per ogni immagine e specificando un valore 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 seguito per identificare quale immagine di riferimento è stata rilevata.

Attiva il monitoraggio delle immagini

Configura la tua sessione ARCore per iniziare a monitorare le immagini impostando la configurazione sessione su una configurazione 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 caratteristica dell'immagine della videocamera a quelli nel database delle immagini.

Per ottenere le immagini corrispondenti, esegui il sondaggio per verificare la presenza di AugmentedImage aggiornate nel loop di aggiornamento del 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()")
    }
  }
}

Supportare diversi casi d'uso

Quando ARCore rileva un'immagine aumentata, crea un elemento Trackable per questa immagine e imposta TrackingState su TRACKING e TrackingMethod su FULL_TRACKING. Quando l'immagine tracciata esce dalla visualizzazione della fotocamera, ARCore modifica il valore TrackingMethod in LAST_KNOWN_POSE, continuando a fornire l'orientamento e la posizione dell'immagine.

L'app deve utilizzare queste enumerazioni in modo diverso a seconda del caso d'uso previsto.

  • Immagini fisse. Nella maggior parte dei casi d'uso relativi a immagini fisse in posizione (ovvero che non sono previste per essere spostate) possono 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, usa sia TrackingState sia TrackingMethod per determinare se l'immagine è stata rilevata e se la sua posizione è nota.

Caso d'uso Immagine corretta Spostamento immagine in corso...
Esempio Un poster appeso a una parete Un annuncio sulla fiancata di un autobus
La posa può essere
considerata valida quando 		TrackingState == TRACKING TrackingState == TRACKING
e
TrackingMethod == FULL_TRACKING

Vedi anche