استخدام ميزة Raw Depth (العمق الأوّلي) في تطبيق Android

توفّر واجهة برمجة التطبيقات Raw Depth API بيانات عمق لصورة الكاميرا بدقة أعلى من بيانات واجهة برمجة التطبيقات Depth API، ولكنها لا تغطي دائمًا كل وحدة بكسل. يمكن أيضًا إجراء مزيد من المعالجة للصور ذات العمق الأولي والصور المطابِقة لها، ما يسمح للتطبيقات باستخدام بيانات العمق ذات الدقة الكافية لحالة الاستخدام الفردية فقط.

توافق الجهاز

تتوفّر Raw Depth API على جميع الأجهزة التي تتوافق مع Depth API. مثل واجهة برمجة التطبيقات Raw Depth API، مثل واجهة برمجة التطبيقات Full Depth API، لا تتطلّب واجهة برمجة التطبيقات هذه أداة استشعار عمق جهازًا متوافقة، مثل أداة استشعار مدة الرحلة (ToF). ومع ذلك، تستفيد كل من واجهة برمجة التطبيقات Raw Depth API وواجهة برمجة التطبيقات Full Depth API من أي أدوات استشعار متوافقة في الأجهزة والتي قد يحتوي عليها الجهاز.

Raw Depth API مقابل واجهة برمجة التطبيقات Full Depth API

توفّر واجهة برمجة التطبيقات Raw Depth API تقديرات للعمق بدقة أعلى، إلا أنّ صور العمق الأولية قد لا تتضمّن تقديرات عمق لجميع وحدات البكسل في صورة الكاميرا. في المقابل، توفر واجهة برمجة التطبيقات Depth API عمقًا تقديريًا لكل وحدة بكسل، ولكن بيانات العمق لكل بكسل قد تكون أقل دقة بسبب تجانس تقديرات العمق واستكمالها. تنسيق وحجم الصور في العمق متماثلان في كلتا الخدمتين. يختلف المحتوى فقط.

يوضح الجدول التالي الاختلافات بين Raw Depth API وfull Depth API باستخدام صورة كرسي وطاولة في المطبخ.

واجهة برمجة التطبيقات المرتجعات صورة الكاميرا صورة العمق صورة الثقة
واجهة برمجة التطبيقات Raw Depth API
  • صورة بعمق أولي تحتوي على تقدير عمق دقيق جدًا لبعض وحدات البكسل، وليس كلها، في صورة الكاميرا.
  • صورة موثوقة تمنح الثقة لكل بكسل صورة بعمق أوّلي. بيانات بكسل صورة الكاميرا التي لا تحتوي على تقدير للعمق تكون مضبوطة على صفر.
واجهة برمجة تطبيقات العمق الكامل
  • أغنية واحدة "متجانسة" تحتوي على تقدير عمق لكل بكسل.
  • لم يتم تقديم أي صورة ثقة من خلال واجهة برمجة التطبيقات هذه.
 لا ينطبق

صور الثقة

من حيث وضوح الصور التي تعرضها واجهة برمجة التطبيقات Raw Depth API، تكون قيم وحدات البكسل الأفتح ذات قيمة أعلى، وتمثل وحدات البكسل البيضاء الثقة الكاملة وتمثل وحدات البكسل السوداء الثقة بدون أي ثقة. بشكل عام، تكون للمناطق في صورة الكاميرا التي تحتوي على زخرفة أكبر، مثل شجرة، ثقة في عمق العمق بشكل أولي أعلى من المناطق التي ليست كذلك، مثل جدار فارغ. الأسطح التي لا تحتوي على زخرفة عادةً ما تكون نسبة الثقة صفر.

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

احتساب التكلفة

تبلغ التكلفة المحسوبة لواجهة برمجة التطبيقات Raw Depth API حوالي نصف تكلفة الحوسبة لواجهة برمجة التطبيقات Depth API الكاملة.

حالات الاستخدام

باستخدام واجهة برمجة التطبيقات Raw Depth API، يمكنك الحصول على صور بعمق تقدِّم تمثيلاً أكثر تفصيلاً لهندسة العناصر في المشهد. يمكن أن تكون البيانات ذات العمق الأولي مفيدة عند إنشاء تجارب الواقع المعزّز التي تتطلب دقة وتفصيل أكبر لأداء مهام فهم الهندسة. وتشمل بعض حالات الاستخدام ما يلي:

  • إعادة بناء ثلاثية الأبعاد
  • القياس
  • اكتشاف الشكل

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

احرص على فهم مفاهيم الواقع المعزّز الأساسية. وكيفية ضبط جلسة ARCore قبل المتابعة.

تفعيل العمق

في جلسة ARCore جديدة، تحقَّق مما إذا كان جهاز المستخدم يتوافق مع ميزة Depth. لا تتيح بعض الأجهزة المتوافقة مع ARCore استخدام واجهة Depth API بسبب قيود طاقة المعالجة. لحفظ الموارد، يتم إيقاف ميزة "العمق" تلقائيًا على ARCore. عليك تفعيل وضع العمق لكي يستخدم تطبيقك واجهة برمجة التطبيقات Depth API.

Java

Config config = session.getConfig();

// Check whether the user's device supports Depth.
if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)) {
  // Enable depth mode.
  config.setDepthMode(Config.DepthMode.AUTOMATIC);
}
session.configure(config);

Kotlin

if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)) {
  session.configure(session.config.apply { depthMode = Config.DepthMode.AUTOMATIC })
}

الحصول على أحدث الصور الأوّلية للعمق والثقة

يمكنك طلب الرقم frame.acquireRawDepthImage16Bits() للحصول على أحدث صورة أوّلية بعمق أكبر. لا تحتوي بعض وحدات بكسل الصور التي يتم عرضها عبر Raw Depth API على بيانات عمق، ولن تحتوي كل إطارات ARCore على صورة جديدة لعمق العمق. لتحديد ما إذا كانت صورة العمق الأولي للإطار الحالي جديدة، قارن طابعها الزمني بالطابع الزمني للصورة السابقة للعمق الأولي. في حال اختلاف الطوابع الزمنية، تستند صورة العمق الأولية إلى بيانات العمق الجديدة. بخلاف ذلك، فإن صورة العمق هي إعادة إسقاط لبيانات العمق السابقة.

يمكنك طلب الرقم frame.acquireRawDepthConfidenceImage() للحصول على صورة الثقة. ويمكنك استخدام صورة الثقة للتحقق من دقة كل بكسل بعمق خام. يتم عرض صور الثقة بتنسيق Y8. يكون كل بكسل عددًا صحيحًا غير موقَّع بطول 8 بت. تشير القيمة 0 إلى أقل مستوى ثقة، بينما تشير السمة 255 إلى أعلى قيمة.

Java

// Use try-with-resources, so that images are released automatically.
try (
// Depth image is in uint16, at GPU aspect ratio, in native orientation.
Image rawDepth = frame.acquireRawDepthImage16Bits();
    // Confidence image is in uint8, matching the depth image size.
    Image rawDepthConfidence = frame.acquireRawDepthConfidenceImage(); ) {
  // Compare timestamps to determine whether depth is is based on new
  // depth data, or is a reprojection based on device movement.
  boolean thisFrameHasNewDepthData = frame.getTimestamp() == rawDepth.getTimestamp();
  if (thisFrameHasNewDepthData) {
    ByteBuffer depthData = rawDepth.getPlanes()[0].getBuffer();
    ByteBuffer confidenceData = rawDepthConfidence.getPlanes()[0].getBuffer();
    int width = rawDepth.getWidth();
    int height = rawDepth.getHeight();
    someReconstructionPipeline.integrateNewImage(depthData, confidenceData, width, height);
  }
} catch (NotYetAvailableException e) {
  // Depth image is not (yet) available.
}

Kotlin

try {
  // Depth image is in uint16, at GPU aspect ratio, in native orientation.
  frame.acquireRawDepthImage16Bits().use { rawDepth ->
    // Confidence image is in uint8, matching the depth image size.
    frame.acquireRawDepthConfidenceImage().use { rawDepthConfidence ->
      // Compare timestamps to determine whether depth is is based on new
      // depth data, or is a reprojection based on device movement.
      val thisFrameHasNewDepthData = frame.timestamp == rawDepth.timestamp
      if (thisFrameHasNewDepthData) {
        val depthData = rawDepth.planes[0].buffer
        val confidenceData = rawDepthConfidence.planes[0].buffer
        val width = rawDepth.width
        val height = rawDepth.height
        someReconstructionPipeline.integrateNewImage(
          depthData,
          confidenceData,
          width = width,
          height = height
        )
      }
    }
  }
} catch (e: NotYetAvailableException) {
  // Depth image is not (yet) available.
}

الخطوات التالية