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

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

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

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

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

يمكن أن تخزِّن كل قاعدة بيانات صور معلومات عن 1,000 صورة كحد أقصى.

هناك طريقتان لإنشاء AugmentedImageDatabase:

  • تحميل قاعدة بيانات صور محفوظة بعد ذلك، يمكنك إضافة المزيد من الصور المرجعية بشكل اختياري.
  • أنشئ قاعدة بيانات فارغة جديدة. بعد ذلك، أضِف الصور المرجعية واحدة تلو الأخرى.

تحميل قاعدة بيانات صور محفوظة

استخدِم AugmentedImageDatabase.deserialize() لتحميل قاعدة بيانات صور حالية:

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

يمكن إنشاء قواعد بيانات الصور باستخدام أداة سطر الأوامر arcoreimg أثناء التطوير، أو من خلال استدعاء AugmentedImageDatabase.serialize() على قاعدة بيانات تحتوي على ملفّ يتم تحميله في الذاكرة.

إنشاء قاعدة بيانات فارغة جديدة

لإنشاء قاعدة بيانات صور فارغة أثناء التشغيل، استخدِم AugmentedImageDatabase المنشئ:

JavaKotlin
AugmentedImageDatabase imageDatabase = new AugmentedImageDatabase(session);
 
val imageDatabase = AugmentedImageDatabase(session)

إضافة صور إلى قاعدة بيانات حالية

أضِف صورًا إلى قاعدة بيانات الصور من خلال استدعاء AugmentedImageDatabase.addImage() لكل صورة، مع تحديد widthInMeters اختياري.

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)

يمكن استخدام الفهارس المعروضة لاحقًا لتحديد الصورة المرجعية التي تم اكتشافها.

تفعيل ميزة تتبُّع الصور

اضبط جلسة ARCore لبدء تتبُّع الصور من خلال ضبط session config على جلسة تم ضبطها باستخدام قاعدة بيانات الصور المطلوبة:

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

أثناء الجلسة، تبحث أداة ARCore عن الصور من خلال مطابقة نقاط العناصر من صورة الكاميرا مع تلك النقاط في قاعدة بيانات الصور.

للحصول على الصور المطابقة، يمكنك إجراء استطلاع للاطّلاع على AugmentedImage المعدَّلة في حلقة تعديل اللقطات.

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

إتاحة حالات استخدام مختلفة

عندما ترصد منصة ARCore صورة مزوّدة بتكنولوجيا الواقع المعزّز، تنشئ Trackable لهذه الصورة المزوّدة بتكنولوجيا الواقع المعزّز وتضبط TrackingState على TRACKING وTrackingMethod على FULL_TRACKING. عندما تخرج الصورة التي يتم تتبُّعها من نطاق رؤية الكاميرا، يغيّر ARCoreTrackingMethod الرمز إلى LAST_KNOWN_POSE مع مواصلة توفير اتجاه الصورة وموقعها.

يجب أن يستخدم تطبيقك هذه التصنيفات بشكلٍ مختلف حسب حالة الاستخدام المقصودة.

  • الصور الثابتة: في معظم حالات الاستخدام التي تتضمّن صورًا ثابتة في مكانها (أي لا يُتوقّع أن تتحرّك)، يمكن استخدام TrackingState ببساطة لتحديد ما إذا تم رصد الصورة وما إذا كان موقعها الجغرافي معروفًا. يمكن تجاهل TrackingMethod.

  • الصور المتحركة إذا كان تطبيقك يحتاج إلى تتبُّع صورة متحركة، استخدِم كلًا من TrackingState وTrackingMethod لتحديد ما إذا تم رصد الصورة وما إذا كان موقعها معروفًا.

حالة الاستخدام صورة ثابتة صورة متحرّكة
مثال ملصق معلق على الحائط إعلان على جانب حافلة
يمكن
اعتبار الوضعية صالحة في الحالات التالية: 		TrackingState == TRACKING TrackingState == TRACKING
و
TrackingMethod == FULL_TRACKING

انظر أيضًا