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

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

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

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

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

أنشئ ArAugmentedImageDatabase لتخزين الصور المرجعية. هناك طريقتان:

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

ArAugmentedImageDatabase* ar_augmented_image_database = NULL;
ArAugmentedImageDatabase_create(ar_session, &ar_augmented_image_database);

• القراءة من ملف قاعدة بيانات الصور يُرجى الرجوع إلى [AugmentedImage C sample app] util::LoadFileFromAssetManager.

std::string database_buffer;
util::LoadFileFromAssetManager(asset_manager_, "sample_database.imgdb",
                               &database_buffer);
uint8_t* raw_buffer = reinterpret_cast<uint8_t*>(&database_buffer.front());

ArAugmentedImageDatabase* ar_augmented_image_database = NULL;
const ArStatus status = ArAugmentedImageDatabase_deserialize(
    ar_session, raw_buffer, database_buffer.size(),
    &ar_augmented_image_database);

يمكن إنشاء ملفات قاعدة البيانات باستخدام أداة الصور أو من خلال استدعاء ArAugmentedImageDatabase_serialize().

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

هذه الخطوة اختيارية إذا سبق أن تم تحميل الصور المرجعية المطلوبة من ملف قاعدة البيانات. لإضافة صورة أثناء التشغيل، استخدِم العنصر ArAugmentedImageDatabase_addImage() كما هو موضّح أدناه. راجِع نموذج تطبيق augmented_image_c للاطّلاع على الدوالّ في مساحة الاسم util.

int32_t width, height, stride, index;
uint8_t* image_pixel_buffer = nullptr;
constexpr const char kSampleImageName[] = "default.jpg";
bool load_image_result = util::LoadImageFromAssetManager(
    kSampleImageName, &width, &height, &stride, &image_pixel_buffer);

uint8_t* grayscale_buffer = nullptr;
util::ConvertRgbaToGrayscale(image_pixel_buffer, width, height, stride,
                             &grayscale_buffer);

int32_t grayscale_stride = stride / 4;
const ArStatus status = ArAugmentedImageDatabase_addImage(
    ar_session_, ar_augmented_image_database, kSampleImageName,
    grayscale_buffer, width, height, grayscale_stride, &index);

// If the physical size of the image is known, you can instead use
//     ArStatus ArAugmentedImageDatabase_addImageWithPhysicalSize
// This will improve the initial detection speed. ARCore will still actively
// estimate the physical size of the image as it is viewed from multiple
// viewpoints.

delete[] image_pixel_buffer;
delete[] grayscale_buffer;

تُستخدَم قيمتَي index وname لاحقًا لتحديد الصورة المرجعية التي تم رصدها.

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

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

ArConfig_setAugmentedImageDatabase(ar_session_, ar_config,
                                   ar_augmented_image_database);
const ArStatus status = ArSession_configure(ar_session_, ar_config);

خلال الجلسة، يستخدم ARCore نقاط تمييز من صورة الكاميرا لمطابقتها مع النقاط الواردة في قاعدة بيانات الصور.

العثور على صور مُعزَّزة في جلسة واقع مُعزَّز

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

// Update loop, in onDrawFrame
ArTrackableList* updated_image_list = nullptr;
ArTrackableList_create(ar_session_, &updated_image_list);
ArFrame_getUpdatedTrackables(
    ar_session_, ar_frame_, AR_TRACKABLE_AUGMENTED_IMAGE, updated_image_list);

int32_t image_list_size;
ArTrackableList_getSize(ar_session_, updated_image_list, &image_list_size);

for (int i = 0; i < image_list_size; ++i) {
  ArTrackable* ar_trackable = nullptr;
  ArTrackableList_acquireItem(ar_session_, updated_image_list, i,
                              &ar_trackable);
  ArAugmentedImage* image = ArAsAugmentedImage(ar_trackable);

  ArTrackingState tracking_state;
  ArTrackable_getTrackingState(ar_session_, ar_trackable, &tracking_state);

  int image_index;
  ArAugmentedImage_getIndex(ar_session_, image, &image_index);

  if (tracking_state == AR_TRACKING_STATE_TRACKING) {
    util::ScopedArPose scopedArPose(ar_session_);
    ArAugmentedImage_getCenterPose(ar_session_, image,
                                   scopedArPose.GetArPose());

    ArAnchor* image_anchor = nullptr;
    const ArStatus status = ArTrackable_acquireNewAnchor(
        ar_session_, ar_trackable, scopedArPose.GetArPose(), &image_anchor);

    // For example, you can now render content at the image anchor, choosing
    // content based on the image index (or name).
  }
}

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

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

يجب أن يستخدم تطبيقك حالة التتبّع وطريقة التتبّع بشكلٍ مختلف استنادًا إلى حالة الاستخدام المقصودة.

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

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

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

ملاحظة: إذا تغيّرت صورة في عرض الكاميرا بسرعة كبيرة إلى صورة ثانية لها الحجم والموقع نفسهما تقريبًا، قد يضبط ARCoreArAugmentedImageTrackingMethod على FULL_TRACKING لكلتا الصور عن طريق الخطأ، كما قد يعدّل عنصر الربط للصورة المعزّزة الأولى إلى موضع الصورة الجديدة. على سبيل المثال، قد يحدث ذلك إذا كنت توجّه الكاميرا إلى صورة في متصفّح ويب، ثم غيّرت إلى علامة تبويب أخرى في المتصفّح تحتوي على صورة ثانية مماثلة في الحجم والموقع.