Entwicklerleitfaden für erweiterte Bilder für Android

Informationen zur Verwendung von Augmented Reality-Bildern in Ihren eigenen Apps

Vorbereitung

Machen Sie sich mit den grundlegenden AR-Konzepten und der Konfiguration einer ARCore-Sitzung vertraut, bevor Sie fortfahren.

Bilddatenbank erstellen

Jede Bilddatenbank kann Informationen für bis zu 1.000 Bilder speichern.

Es gibt zwei Möglichkeiten, eine AugmentedImageDatabase zu erstellen:

• Laden Sie eine gespeicherte Bilddatenbank. Optional können Sie weitere Referenzbilder hinzufügen.
• Erstellen Sie eine neue leere Datenbank. Fügen Sie dann nacheinander Referenzbilder hinzu.

Gespeicherte Bilddatenbank laden

Verwenden Sie AugmentedImageDatabase.deserialize(), um eine vorhandene Bilddatenbank zu laden:

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

Bilddatenbanken können während der Entwicklung mit dem Befehlszeilentool arcoreimg erstellt oder durch Aufrufen von AugmentedImageDatabase.serialize() auf eine Datenbank mit Bildern erstellt werden, die in den Arbeitsspeicher geladen werden.

Neue leere Datenbank erstellen

Verwenden Sie den Konstruktor AugmentedImageDatabase, um eine leere Bilddatenbank zur Laufzeit zu erstellen:

Java

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

Kotlin

val imageDatabase = AugmentedImageDatabase(session)

Einer vorhandenen Datenbank Bilder hinzufügen

Fügen Sie Ihrer Bilddatenbank Bilder hinzu, indem Sie für jedes Bild AugmentedImageDatabase.addImage() aufrufen und optional widthInMeters angeben.

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)

Anhand der zurückgegebenen Indizes kann später ermittelt werden, welches Referenzbild erkannt wurde.

Bild-Tracking aktivieren

Konfigurieren Sie Ihre ARCore-Sitzung so, dass Bilder erfasst werden. Legen Sie dazu die Sitzungskonfiguration auf eine Konfiguration fest, die mit der gewünschten Bilddatenbank konfiguriert ist:

Java

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

Kotlin

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

Während der Sitzung sucht ARCore nach Bildern, indem es die Merkmals- und Positionsdaten aus dem Kamerabild mit denen in der Bilddatenbank abgleicht.

Um die übereinstimmenden Bilder abzurufen, frage in der Frame-Update-Schleife nach aktualisierten AugmentedImages.

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

Unterstützung verschiedener Anwendungsfälle

Wenn ARCore ein Augmented Image erkennt, wird ein Trackable für dieses Augmented Image erstellt und TrackingState auf TRACKING und TrackingMethod auf FULL_TRACKING gesetzt. Wenn sich das getrackte Bild aus dem Kamerabild bewegt, ändert ARCore das TrackingMethod in LAST_KNOWN_POSE, während die Ausrichtung und Position des Bildes weiterhin angegeben wird.

Diese Aufzählungen sollten in Ihrer App je nach Verwendungszweck unterschiedlich verwendet werden.

• Statische Bilder Bei den meisten Anwendungsfällen mit Bildern, die an Ort und Stelle bleiben (d. h. sich nicht bewegen sollen), kann mit TrackingState einfach ermittelt werden, ob das Bild erkannt wurde und ob sein Standort bekannt ist. TrackingMethod kann ignoriert werden.

• Bewegte Bilder Wenn Ihre App ein sich bewegendes Bild verfolgen muss, verwenden Sie sowohl TrackingState als auch TrackingMethod, um festzustellen, ob das Bild erkannt wurde und ob seine Position bekannt ist.

Anwendungsfall	Fixiertes Bild	Bewegtes Bild
Beispiel	Ein an einer Wand hängendes Poster	Eine Anzeige auf der Seite eines Busses
Die Pose kann als gültig betrachtet werden, wenn	TrackingState == TRACKING	TrackingState == TRACKING und TrackingMethod == FULL_TRACKING

Hinweis: Wenn sich ein Bild in der Kameraansicht sehr schnell in ein zweites Bild mit ungefähr derselben Größe und Position ändert, setzt ARCore möglicherweise fälschlicherweise TrackingMethod für beide Bilder auf FULL_TRACKING und aktualisiert auch den Anker des ersten AR-Bilds auf die Position des neuen Bilds. Das kann beispielsweise passieren, wenn Sie die Kamera auf ein Bild in einem Webbrowser richten und dann zu einem anderen Browsertab wechseln, der ein zweites Bild mit ähnlicher Größe und Position enthält.

Weitere Informationen

• Die Beispielprojekte für Augmented Images im ARCore SDK

• ARCore-Codelab für Augmented Reality-Bilder