מדריך למפתחים בנושא תמונות מורחבות ב-Android

איך משתמשים בתמונות משופרות באפליקציות שלכם

דרישות מוקדמות

לפני שממשיכים, חשוב להבין את המושגים הבסיסיים של AR ואת האופן שבו מגדירים סשן ARCore.

יצירת מסד נתונים של תמונות

כל מסד נתונים של תמונות יכול לאחסן מידע לגבי עד 1,000 תמונות.

יש שתי דרכים ליצור AugmentedImageDatabase:

  • טוענים מסד נתונים שמור של תמונות. אם רוצים, אפשר להוסיף עוד תמונות עזר.
  • יוצרים מסד נתונים ריק חדש. לאחר מכן מוסיפים תמונות עזר, אחת בכל פעם.

טעינה של מסד נתונים שמור של תמונות

משתמשים ב-AugmentedImageDatabase.deserialize() כדי לטעון מסד נתונים קיים של תמונות:

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

אפשר ליצור מסדי נתונים של תמונות באמצעות arcoreimg בכלי שורת הפקודה (CLI) במהלך הפיתוח, או באמצעות קריאה AugmentedImageDatabase.serialize() במסד נתונים שמכיל את הטעינה בזיכרון.

יצירת מסד נתונים ריק חדש

כדי ליצור מסד נתונים ריק של תמונות בזמן ריצה, צריך להשתמש בבנאי של AugmentedImageDatabase:

Java

AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);

Kotlin

val imageDatabase = AugmentedImageDatabase(session)

הוספת תמונות למסד נתונים קיים

כדי להוסיף תמונות למסד הנתונים של התמונות, צריך להפעיל את AugmentedImageDatabase.addImage() לכל תמונה, ולציין widthInMeters אופציונלי.

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)

ניתן להשתמש באינדקסים שהוחזרו מאוחר יותר כדי לזהות איזו תמונת עזר זוהה.

הפעלת מעקב אחר תמונות

כדי להגדיר את סשן ARCore כך שיתחיל לעקוב אחרי תמונות, מגדירים את הגדרת הסשן כך שתכלול את מסד הנתונים הרצוי של התמונות:

Java

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

Kotlin

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

במהלך הסשן, ARCore מחפש תמונות לפי התאמת נקודות של מאפיינים. של המצלמה אל התמונות שבמסד הנתונים של התמונות.

כדי לקבל את התמונות התואמות, אפשר לבצע דגימה של AugmentedImage התמונה המעודכנת בלולאת עדכון הפריים.

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

תמיכה בתרחישים שונים לדוגמה

כש-ARCore מזהה תמונה מורחבת, היא יוצרת Trackable לאותה תמונה מורחבת ומגדירה את TrackingState לערך TRACKING ואת TrackingMethod לערך FULL_TRACKING. כשהתמונה שבמעקב יוצאת מהטווח של המצלמה, ARCore משנה את TrackingMethod ל-LAST_KNOWN_POSE תוך המשך מתן המידע על הכיוון והמיקום של התמונה.

האפליקציה צריכה להשתמש ברשימה הזו באופן שונה בהתאם לתרחיש השימוש המיועד.

  • תמונות קבועות. רוב התרחישים לדוגמה שקשורים לתמונות שקבועות במקום (כלומר, לא צפוי לעבור) יכולים פשוט להשתמש ב-TrackingState כדי לקבוע האם התמונה זוהתה ואם המיקום שלה ידוע. אפשר להתעלם מ-TrackingMethod.

  • תמונות זזות. אם האפליקציה שלכם צריכה לעקוב אחרי תמונה בתנועה, צריך להשתמש גם ב-TrackingState וגם ב-TrackingMethod כדי לקבוע אם התמונה זוהתה ואם המיקום שלה ידוע.

תרחיש לדוגמה תמונה קבועה תמונה נעה
דוגמה פוסטר שתלוי על קיר פרסומת בצד האוטובוס
אפשר
להתייחס לתנוחה כתקפה אם 		TrackingState == TRACKING TrackingState == TRACKING
וגם
TrackingMethod == FULL_TRACKING

ראה גם