Guide du développeur Augmented Images pour Android

Découvrez comment utiliser les images augmentées dans vos propres applications.

Prérequis

Avant de continuer, assurez-vous de bien comprendre les concepts fondamentaux de la RA et de savoir configurer une session ARCore.

Créer une base de données d'images

Chaque base de données d'images peut stocker des informations sur jusqu'à 1 000 images.

Il existe deux façons de créer un AugmentedImageDatabase:

• Chargez une base de données d'images enregistrée. Vous pouvez ensuite ajouter d'autres images de référence.
• Créez une base de données vide. Ajoutez ensuite les images de référence une par une.

Charger une base de données d'images enregistrée

Utilisez AugmentedImageDatabase.deserialize() pour charger une base de données d'images existante:

JavaKotlin

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

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

Vous pouvez créer des bases de données d'images à l'aide de l'outil de ligne de commande arcoreimg pendant le développement ou en appelant AugmentedImageDatabase.serialize() sur une base de données qui contient des images chargées en mémoire.

Créer une base de données vide

Pour créer une base de données d'images vide au moment de l'exécution, utilisez le constructeur AugmentedImageDatabase:

JavaKotlin

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

val imageDatabase = AugmentedImageDatabase(session)

Ajouter des images à une base de données existante

Ajoutez des images à votre base de données d'images en appelant AugmentedImageDatabase.addImage() pour chaque image, en spécifiant un widthInMeters facultatif.

JavaKotlin

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

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)

Les indices renvoyés peuvent ensuite être utilisés pour identifier l'image de référence détectée.

Activer le suivi des images

Configurez votre session ARCore pour commencer à suivre les images en définissant la configuration de la session sur celle qui est configurée avec la base de données d'images souhaitée:

JavaKotlin

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

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

Pendant la session, ARCore recherche des images en faisant correspondre les points de caractéristiques de l'image de l'appareil photo à ceux de la base de données d'images.

Pour obtenir les images correspondantes, interrogez les AugmentedImage mis à jour dans votre boucle de mise à jour de frame.

JavaKotlin

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

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

Prise en charge de différents cas d'utilisation

Lorsque ARCore détecte une image étendue, il crée un Trackable pour cette image étendue et définit TrackingState sur TRACKING et TrackingMethod sur FULL_TRACKING. Lorsque l'image suivie sort du champ de vision de la caméra, ARCore remplace TrackingMethod par LAST_KNOWN_POSE tout en continuant à fournir l'orientation et la position de l'image.

Votre application doit utiliser ces énumérations différemment en fonction du cas d'utilisation prévu.

• Images fixes La plupart des cas d'utilisation impliquant des images fixes (c'est-à-dire qui ne doivent pas bouger) peuvent simplement utiliser TrackingState pour déterminer si l'image a été détectée et si son emplacement est connu. TrackingMethod peut être ignoré.

• Déplacer des images Si votre application doit suivre une image en mouvement, utilisez à la fois TrackingState et TrackingMethod pour déterminer si l'image a été détectée et si sa position est connue.

Cas d'utilisation	Image fixe	Image animée
Exemple	Un poster accroché au mur	Annonce sur le flanc d'un bus
La pose peut être considérée comme valide lorsque :	TrackingState == TRACKING	TrackingState == TRACKING et TrackingMethod == FULL_TRACKING

Remarque :Si une image dans la vue de la caméra passe très rapidement à une deuxième image ayant à peu près la même taille et la même position, ARCore peut définir par erreur TrackingMethod sur FULL_TRACKING pour les deux images, et mettre à jour l'ancrage de la première image agrandie à la position de la nouvelle image. Par exemple, cela peut se produire si vous pointez la caméra vers une image dans un navigateur Web, puis que vous passez à un autre onglet du navigateur contenant une deuxième image de taille et de position similaires.

Voir aussi

• Exemples de projets Augmented Images dans le SDK ARCore

• Atelier de programmation sur Augmented Images avec ARCore