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

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

توافق الجهاز

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

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

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

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

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

صور الثقة

من حيث ثقة الصور التي تعرضها واجهة برمجة التطبيقات 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.
}

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

• تعرَّف على كيفية إنشاء تطبيقك الخاص باستخدام بيانات Raw Depth من خلال الاطّلاع على الدرس التطبيقي حول ترميز Raw Depth.