فهم بيئة المستخدم على حزمة تطوير البرامج (SDK) لنظام التشغيل Android (Kotlin/Java)

تعرَّف على كيفية استخدام Scene Semantics API في تطبيقاتك.

تتيح واجهة برمجة التطبيقات Scene Semantics API للمطوّرين فهم المشهد المحيط بالمستخدم من خلال توفير معلومات دلالية مستندة إلى نموذج تعلُّم الآلة في الوقت الفعلي. بالنظر إلى صورة لمشهد في الهواء الطلق، تعرض واجهة برمجة التطبيقات تصنيفًا لكل وحدة بكسل عبر مجموعة من الفئات الدلالية المفيدة، مثل السماء أو المبنى أو الشجرة أو الطريق أو الرصيف أو المركبة أو شخص أو غير ذلك. بالإضافة إلى تصنيفات البكسل، توفّر واجهة برمجة التطبيقات Scene Semantics API أيضًا قيم ثقة لكل تصنيف من وحدات البكسل وطريقة سهلة الاستخدام للاستعلام عن مدى انتشار تصنيف معيّن في المشهد الخارجي.

من اليمين إلى اليسار، أمثلة على صورة تم إدخالها والصورة الدلالية لتصنيفات وحدات البكسل وصورة الثقة المقابلة:

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

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

تفعيل دلالات المشهد

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

لتوفير الموارد، تكون ميزة "دلالات المشهد" غير مفعّلة تلقائيًا في ARCore. فعِّل الوضع الدلالي ليتمكّن تطبيقك من استخدام واجهة برمجة التطبيقات Scene Semantics API.

Java

Config config = session.getConfig();

// Check whether the user's device supports the Scene Semantics API.
boolean isSceneSemanticsSupported =
    session.isSemanticModeSupported(Config.SemanticMode.ENABLED);
if (isSceneSemanticsSupported) {
  config.setSemanticMode(Config.SemanticMode.ENABLED);
}
session.configure(config);

Kotlin

val config = session.config

// Check whether the user's device supports the Scene Semantics API.
val isSceneSemanticsSupported = session.isSemanticModeSupported(Config.SemanticMode.ENABLED)
if (isSceneSemanticsSupported) {
  config.semanticMode = Config.SemanticMode.ENABLED
}
session.configure(config)

الحصول على الصورة الدلالية

بعد تفعيل ميزة "دلالات المشهد"، يمكن استرداد الصورة الدلالية. الصورة الدلالية هي صورة ImageFormat.Y8، حيث يتوافق كل بكسل مع تصنيف دلالي يحدّده SemanticLabel.

استخدِم Frame.acquireSemanticImage() للحصول على الصورة الدلالية:

Java

// Retrieve the semantic image for the current frame, if available.
try (Image semanticImage = frame.acquireSemanticImage()) {
  // Use the semantic image here.
} catch (NotYetAvailableException e) {
  // No semantic image retrieved for this frame.
  // The output image may be missing for the first couple frames before the model has had a
  // chance to run yet.
}

Kotlin

// Retrieve the semantic image for the current frame, if available.
try {
  frame.acquireSemanticImage().use { semanticImage ->
    // Use the semantic image here.
  }
} catch (e: NotYetAvailableException) {
  // No semantic image retrieved for this frame.
}

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

الحصول على صورة الثقة

بالإضافة إلى الصورة الدلالية التي توفّر تصنيفًا لكل وحدة بكسل، توفّر واجهة برمجة التطبيقات أيضًا صورة ثقة لقيم الثقة المقابلة بالبكسل. صورة الثقة هي صورة ImageFormat.Y8، حيث يقابل كل بكسل قيمة في النطاق [0, 255]، ما يتوافق مع الاحتمالية المرتبطة بالعلامة الدلالية لكل بكسل.

استخدِم Frame.acquireSemanticConfidenceImage() للحصول على صورة الثقة الدلالية:

Java

// Retrieve the semantic confidence image for the current frame, if available.
try (Image semanticImage = frame.acquireSemanticConfidenceImage()) {
  // Use the semantic confidence image here.
} catch (NotYetAvailableException e) {
  // No semantic confidence image retrieved for this frame.
  // The output image may be missing for the first couple frames before the model has had a
  // chance to run yet.
}

Kotlin

// Retrieve the semantic confidence image for the current frame, if available.
try {
  frame.acquireSemanticConfidenceImage().use { semanticConfidenceImage ->
    // Use the semantic confidence image here.
  }
} catch (e: NotYetAvailableException) {
  // No semantic confidence image retrieved for this frame.
}

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

طلب نسبة البكسلات لتصنيف دلالي

يمكنك أيضًا الاستعلام عن نسبة البكسلات في اللقطة الحالية التي تنتمي إلى فئة معيّنة، مثل السماء. وهذا الطلب أكثر فعالية من عرض الصورة الدلالية وإجراء بحث بكسل تلو الآخر عن تصنيف معيّن. الكسر الذي يتم عرضه هو قيمة عائمة في النطاق [0.0, 1.0].

استخدام Frame.getSemanticLabelFraction() للحصول على الكسر لتصنيف معيّن:

Java

// Retrieve the fraction of pixels for the semantic label sky in the current frame.
try {
  float outFraction = frame.getSemanticLabelFraction(SemanticLabel.SKY);
  // Use the semantic label fraction here.
} catch (NotYetAvailableException e) {
  // No fraction of semantic labels was retrieved for this frame.
}

Kotlin

// Retrieve the fraction of pixels for the semantic label sky in the current frame.
try {
  val fraction = frame.getSemanticLabelFraction(SemanticLabel.SKY)
  // Use the semantic label fraction here.
} catch (e: NotYetAvailableException) {
  // No fraction of semantic labels was retrieved for this frame.
}