دليل المطوِّرين حول الصور المعزّزة لنظام التشغيل Android

تعرَّف على كيفية استخدام ميزة "الصور المعزَّزة" في تطبيقاتك.

المتطلبات الأساسية

قبل المتابعة، تأكد من فهم مفاهيم الواقع المعزّز الأساسية وكيفية ضبط جلسة ARCore.

إنشاء قاعدة بيانات للصور

يمكن لكل قاعدة بيانات صور تخزين معلومات لما يصل إلى 1000 صورة.

هناك طريقتان لإنشاء 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 أثناء تطويرها، أو من خلال طلب الوصول إلى 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

يمكن أيضًا مراجعة