XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

744

المراجعة

1

حالة التصديق

تمت المصادقة عليه

الاعتماد على الإضافات والإصدارات

XR_EXT_spatial_entity

المساهمون

رون بيسمز، Meta
نيهاف جاين، Google
ناتالي فلوري، Meta
يويتشي تاغوتشي، Meta
يين لي، Microsoft
جيمي ألامبارامبيل، ByteDance
تشيبينغ ليو، ByteDance
جون يان، ByteDance

نظرة عامة

تستند هذه الإضافة إلى XR_EXT_spatial_entity وتسمح للتطبيقات برصد العلامات وتتبُّعها في بيئتها. العلامات هي رموز ثنائية الأبعاد قد تشمل رموز الاستجابة السريعة أو رموز الاستجابة السريعة المصغّرة أو علامات ArUco أو علامات AprilTags.

يتم تمثيل العلامة التي يتم تتبّعها ككيان مكاني يتضمّن المكوّنات التالية:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

دعم وقت التشغيل

يجب أن يعلن وقت التشغيل عن دعمه لإمكانات تتبُّع العلامات المختلفة باستخدام xrEnumerateSpatialCapabilitiesEXT من خلال إدراج أيّ من الإمكانات التالية:

  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

الإعداد

لتفعيل رصد نوع علامة، يجب أن يمرّر التطبيق بنية الإعدادات المقابلة إلى xrCreateSpatialContextAsyncEXT .

إعدادات أنواع العلامات

رموز الاستجابة السريعة

يتم تعريف بنية XrSpatialCapabilityConfigurationQrCodeEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationQrCodeEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • capability must be XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
  • ‫enabledComponentCount هو uint32_t يتضمّن عدد العناصر في enabledComponents .
  • ‫enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الوظيفة.

إذا كانت رموز الاستجابة السريعة متاحة، يجب أن تفعّل بيئة التشغيل ميزة تتبُّع رموز الاستجابة السريعة عند تمرير بنية XrSpatialCapabilityConfigurationQrCodeEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT من خلال xrEnumerateSpatialCapabilitiesEXT .

الاستخدام الصالح (ضمني)

رموز الاستجابة السريعة المصغّرة

يتم تحديد بنية XrSpatialCapabilityConfigurationMicroQrCodeEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationMicroQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationMicroQrCodeEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • capability must be XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
  • ‫enabledComponentCount هو uint32_t يتضمّن عدد العناصر في enabledComponents .
  • ‫enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الوظيفة.

إذا كانت رموز Micro QR مدعومة، يجب أن يتيح وقت التشغيل تتبُّع رمز الاستجابة السريعة المصغّر عندما يتم تمرير بنية XrSpatialCapabilityConfigurationMicroQrCodeEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند طلب xrCreateSpatialContextAsyncEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT من خلال xrEnumerateSpatialCapabilitiesEXT .

الاستخدام الصالح (ضمني)

علامات ArUco

يتم تحديد بنية XrSpatialCapabilityConfigurationArucoMarkerEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationArucoMarkerEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerArucoDictEXT         arUcoDict;
} XrSpatialCapabilityConfigurationArucoMarkerEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • capability must be XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
  • ‫enabledComponentCount هو uint32_t يتضمّن عدد العناصر في enabledComponents .
  • ‫enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الوظيفة.
  • ‫arUcoDict هو قاموس العلامات المطلوب رصدها.

إذا كانت علامات ArUco متوافقة، يجب أن يفعّل وقت التشغيل تتبُّع علامات ArUco عند تمرير بنية XrSpatialCapabilityConfigurationArucoMarkerEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT .

يجب أن تعرض بيئة التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT من xrCreateSpatialContextAsyncEXT إذا كانت بنية XrSpatialCapabilityConfigurationArucoMarkerEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs ولكن لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

الاستخدام الصالح (ضمني)

يتم تعريف التعداد XrSpatialMarkerArucoDictEXT على النحو التالي:

typedef enum XrSpatialMarkerArucoDictEXT {
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT = 1,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT = 2,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT = 3,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT = 4,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT = 5,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT = 6,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT = 7,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT = 8,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT = 9,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT = 10,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT = 11,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT = 12,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT = 13,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT = 14,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT = 15,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT = 16,
    XR_SPATIAL_MARKER_ARUCO_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerArucoDictEXT;

قاموس ArUco المحدّد مسبقًا والمتوافق:

أوصاف التعداد

  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT: قاموس علامات Aruco بدقة 4×4 بكسل مع 50 معرّفًا
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT — قاموس علامات Aruco بدقة 4×4 بكسل مع 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT: قاموس علامات Aruco بدقة 4×4 بكسل مع 250 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT: قاموس علامات Aruco بدقة 4×4 بكسل مع 1000 معرّف
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT: قاموس علامات Aruco بحجم 5×5 بكسل مع 50 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT: قاموس علامات Aruco بحجم 5×5 بكسل مع 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT: قاموس علامات Aruco بحجم 5×5 بكسل مع 250 معرّفًا
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT — قاموس علامات Aruco بحجم 5×5 بكسل مع 1000 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT: قاموس علامات Aruco بحجم 6×6 بكسل مع 50 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT: قاموس علامات Aruco بحجم 6×6 بكسل مع 100 رقم تعريف
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT: قاموس علامات Aruco بحجم 6×6 بكسل مع 250 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT: قاموس علامات Aruco بحجم 6×6 بكسل مع 1000 معرّف
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT: قاموس علامات Aruco بحجم 7×7 بكسل مع 50 معرّفًا
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — قاموس علامات Aruco بدقة 7×7 بكسل مع 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT: قاموس علامات Aruco بحجم 7×7 بكسل مع 250 معرّفًا.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — قاموس علامات Aruco بدقة 7×7 بكسل مع 1000 معرّف.
علامات AprilTags

يتم تعريف بنية XrSpatialCapabilityConfigurationAprilTagEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationAprilTagEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerAprilTagDictEXT      aprilDict;
} XrSpatialCapabilityConfigurationAprilTagEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • capability must be XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
  • ‫enabledComponentCount هو uint32_t يتضمّن عدد العناصر في enabledComponents .
  • ‫enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الوظيفة.
  • ‫aprilDict هو قاموس العلامات المطلوب رصدها.

إذا كانت علامات AprilTags متاحة، يجب أن تفعّل بيئة التشغيل ميزة تتبُّع علامات AprilTag عند تمرير بنية XrSpatialCapabilityConfigurationAprilTagEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT من xrCreateSpatialContextAsyncEXT إذا كانت بنية XrSpatialCapabilityConfigurationAprilTagEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs ولكن لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

الاستخدام الصالح (ضمني)

يتم تعريف التعداد XrSpatialMarkerAprilTagDictEXT على النحو التالي:

typedef enum XrSpatialMarkerAprilTagDictEXT {
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT = 1,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT = 2,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT = 3,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT = 4,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerAprilTagDictEXT;

قاموس AprilTag المحدّد مسبقًا والمتوافق:

أوصاف التعداد

  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT: 4 في 4 بت، الحد الأدنى لمسافة هامينغ بين أي رمزَين = 5، 30 رمزًا.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT — 5 في 5 بت، الحد الأدنى لمسافة هامينغ بين أي رمزين = 9، 35 رمزًا.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT: 6 × 6 بت، والحد الأدنى لمسافة هامينغ بين أي رمزين = 10، وعدد الرموز 2320.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT — 6 × 6 بت، الحد الأدنى لمسافة هامينغ بين أي رمزين = 11، 587 رمزًا.

إعدادات العلامات الاختيارية

يجب أن تستدعي التطبيقات xrEnumerateSpatialCapabilityFeaturesEXT للحصول على قائمة بالميزات الاختيارية المتوافقة.

يُرجى الاطّلاع على XrSpatialCapabilityFeatureEXT للحصول على قائمة كاملة بجميع ميزات الإمكانات المكانية التي تتيحها أي إضافة.

حجم العلامة

يتم تحديد بنية XrSpatialMarkerSizeEXT على النحو التالي:

typedef struct XrSpatialMarkerSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              markerSideLength;
} XrSpatialMarkerSizeEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫markerSideLength هو حجم جميع العلامات بالأمتار.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإمكانية معيّنة، وإذا كان التطبيق يربط XrSpatialMarkerSizeEXT ببنية الإعدادات المقابلة لتلك الإمكانية، يجب أن يفترض وقت التشغيل أنّ جميع العلامات التي تم رصدها لها عرض وارتفاع يبلغان markerSideLength . يؤدي توفير هذه المعلومات إلى وقت التشغيل إلى السماح لوقت التشغيل بإرجاع وضع وحجم أكثر دقة. يجب ربط هذه البنية بسلسلة next من XrSpatialCapabilityConfigurationQrCodeEXT أو XrSpatialCapabilityConfigurationMicroQrCodeEXT أو XrSpatialCapabilityConfigurationArucoMarkerEXT أو XrSpatialCapabilityConfigurationAprilTagEXT .

الاستخدام الصالح (ضمني)

تحسين العلامات الثابتة

يتم تعريف بنية XrSpatialMarkerStaticOptimizationEXT على النحو التالي:

typedef struct XrSpatialMarkerStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticMarker;
} XrSpatialMarkerStaticOptimizationEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • يشير الرمز optimizeForStaticMarker إلى ما إذا كان من المتوقّع عدم تحريك جميع العلامات في المساحة.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإمكانية معيّنة، وإذا ربط التطبيق XrSpatialMarkerStaticOptimizationEXT ببنية الإعدادات المقابلة لتلك الإمكانية، يجب أن يفترض وقت التشغيل أنّ جميع العلامات التي تم رصدها ثابتة إذا تم ضبط optimizeForStaticMarker على XR_TRUE . يتيح ذلك لبيئة التشغيل إنشاء وضعية وحجم أكثر دقة. يجب ربط هذه البنية بسلسلة next من XrSpatialCapabilityConfigurationQrCodeEXT أو XrSpatialCapabilityConfigurationMicroQrCodeEXT أو XrSpatialCapabilityConfigurationArucoMarkerEXT أو XrSpatialCapabilityConfigurationAprilTagEXT .

الاستخدام الصالح (ضمني)

المكوّنات المضمونة

يجب أن توفّر بيئة التشغيل التي تتيح استخدام XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT المكوّنات المكانية التالية كمكوّنات مضمونة لجميع العناصر التي تكتشفها هذه الإمكانات، ويجب تعدادها في xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

مكوّن العلامة

بيانات المكوّنات

يتم تعريف بنية XrSpatialMarkerDataEXT على النحو التالي:

typedef struct XrSpatialMarkerDataEXT {
    XrSpatialCapabilityEXT    capability;
    uint32_t                  markerId;
    XrSpatialBufferEXT        data;
} XrSpatialMarkerDataEXT;

أوصاف الأعضاء

  • ‫capability هي السمة XrSpatialCapabilityEXT التي رصدت العلامة.
  • ‫markerId هو المعرّف المرمّز من العلامة. بالنسبة إلى علامات ArUco وAprilTag، يجب أن يكون هذا الحقل صالحًا وأن تتم تعبئته بالمعرّف المرمّز. بالنسبة إلى رموز الاستجابة السريعة، يجب أن يكون هذا الحقل صفرًا.
  • ‫data هو معرّف المخزن المؤقت ونوع المعلومات الإضافية المضمّنة في العلامة.

يتيح XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT وXR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT استخدام بيانات إضافية. إذا كان "capability" من بين هذه الأجهزة:

  • إذا نجحت بيئة التشغيل في فك ترميز بيانات العلامة، يجب ضبط نوع المخزن المؤقت data على XR_SPATIAL_BUFFER_TYPE_UINT8_EXT أو XR_SPATIAL_BUFFER_TYPE_STRING_EXT، حسب البيانات في العلامة. يجب أيضًا أن يضبط وقت التشغيل رقم تعريف صالحًا للمخزن المؤقت في data يمكن للتطبيق استخدامه مع دالة xrGetSpatialBuffer* المناسبة للحصول على البيانات.
  • إذا لم يفكّ وقت التشغيل ترميز بيانات العلامة بعد، يجب ضبط معرّف المخزن المؤقت data على XR_NULL_SPATIAL_BUFFER_ID_EXT ونوع المخزن المؤقت على XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT .

لا يتيح XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT وXR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT استخدام بيانات إضافية، ويجب أن يضبط وقت التشغيل معرّف المخزن المؤقت لـ data على XR_NULL_SPATIAL_BUFFER_ID_EXT .

الاستخدام الصالح (ضمني)

بنية قائمة المكوّنات لطلب البيانات

يتم تحديد بنية XrSpatialComponentMarkerListEXT على النحو التالي:

typedef struct XrSpatialComponentMarkerListEXT {
    XrStructureType            type;
    void*                      next;
    uint32_t                   markerCount;
    XrSpatialMarkerDataEXT*    markers;
} XrSpatialComponentMarkerListEXT;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫markerCount هو عدد العناصر في العضو markers.
  • ‫markers هي مصفوفة من XrSpatialMarkerDataEXT .

يمكن للتطبيق الاستعلام عن مكوّن العلامة للكيانات المكانية في XrSpatialSnapshotEXT من خلال إضافة XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes وإضافة XrSpatialComponentMarkerListEXT إلى سلسلة المؤشرات التالية لـ XrSpatialComponentDataQueryResultEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentMarkerListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن لم يتم تضمين XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان markerCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

الاستخدام الصالح (ضمني)

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialCapabilityComponentTypesEXT :: componentTypes لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين التعداد في قائمة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents للبنية المشتقة من XrSpatialCapabilityConfigurationBaseHeaderEXT للإمكانية التي تتيح هذا المكوّن.

لا يتطلّب هذا المكوّن أي إعدادات خاصة ليتم تضمينه في سلسلة XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

مكوّن ثنائي الأبعاد مقيّد

يوفّر المكوّن الثنائي الأبعاد المحدود مركز العلامة ونطاقاتها التي يمثّلها الكيان الذي تظهر عليه. يُرجى الاطّلاع على Bounded 2D لمزيد من التفاصيل حول مكوّن Bounded 2D.

يجب أن يشير XrSpatialBounded2DDataEXT :: center إلى مركز العلامة. عند النظر إلى الوجه الأمامي للعلامة، يجب أن يشير المحور X إلى اليمين، ويجب أن يشير المحور Y إلى أعلى العلامة. يجب أن يتّبع وقت التشغيل نظام الإحداثيات اليميني، وبالتالي يخرج المحور Z من الوجه الأمامي للعلامة. وهذا يعني أنّ العلامة التي يكون موضعها {0, 0, 0} ودورانها {0, 0, 0, 1} (بدون دوران) وامتدادها {1, 1} تشير إلى علامة بمقاس متر واحد × متر واحد تتوسّطها {0, 0, 0} مع توجيه المتجه العمودي للوجه الأمامي نحو الاتجاه +Z في مساحة المكوّن.

يتم عرض تمثيل لاتجاه العلامة أدناه.

xr ml marker understanding axis

الشكل 25: علامة رمز الاستجابة السريعة مع المحور

رموز الاختبار

يجب أن يكون مستوى X-Y للرموز التالية داخل المستند وأن يشير المحور Z إلى المُشاهد. يجب أن يظهر أصل المحور في وسط كل علامة. يجب أن يشير المحور X إلى اليمين، ويجب أن يشير المحور Y إلى أعلى المستند.

ext marker tracking qr

الشكل 26: رمز استجابة سريعة مع النص OpenXR

ext marker tracking apriltag

الشكل 27: ‫AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT برقم التعريف 42

تتبُّع علامات Aruco الخارجية

الشكل 28: علامة ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT بالرقم التعريفي 43

مثال على الشفرة

ضبط إمكانية تتبُّع رمز الاستجابة السريعة

يوضّح الرمز البرمجي في المثال التالي كيفية ضبط ميزة تتبُّع رمز الاستجابة السريعة عند إنشاء سياق مكاني.

// Check if marker tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) == capabilities.end()) {
  return;
}

uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT, featureCount, &featureCount, capabilityFeatures.data()));

bool supportsFixedMarkerSize = std::find(capabilityFeatures.begin(), capabilityFeatures.end(), XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT) != capabilityFeatures.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the qr code tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};
XrSpatialCapabilityConfigurationQrCodeEXT markerConfiguration{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT};
markerConfiguration.capability = XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT;
markerConfiguration.enabledComponentCount = static_cast<uint32_t>(enabledComponents.size());
markerConfiguration.enabledComponents = enabledComponents.data();

// only chained if features.markerSideLength is true.
XrSpatialMarkerSizeEXT markerSize{XR_TYPE_SPATIAL_MARKER_SIZE_EXT};
markerSize.markerSideLength = 0.10f;
if (supportsFixedMarkerSize) {
  markerConfiguration.next = &markerSize;
}


std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&markerConfiguration),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

اكتشاف الكيانات المكانية وبيانات مكوّنات طلبات البحث

يوضّح الرمز البرمجي في المثال التالي كيفية اكتشاف الكيانات المكانية لسياق تم ضبطه باستخدام XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT والاستعلام عن بيانات المكوّنات الخاصة به.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the bounded2D and marker component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    bounded2DList.boundCount = bounded2D.size();
    bounded2DList.bounds = bounded2D.data();
    queryResult.next = &bounded2DList;

    std::vector<XrSpatialMarkerDataEXT> markers;
    XrSpatialComponentMarkerListEXT markerList{XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT};
    markers.resize(queryResult.entityIdCountOutput);
    markerList.markerCount = markers.size();
    markerList.markers = markers.data();
    bounded2DList.next = &markerList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (markers[i].capability == XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) {
        // Check if marker data has been decoded.
        if (markers[i].data.bufferId != XR_NULL_SPATIAL_BUFFER_ID_EXT) {
          if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_STRING_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferStringEXT(completion.snapshot, &getInfo, ...)
          } else if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_UINT8_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferUint8(completion.snapshot, &getInfo, ...)
          }
        }
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

منشآت جديدة

عمليات تعداد جديدة

ثوابت تعداد جديدة

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

  • توسيع XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

  • توسيع XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

  • توسيع XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

  • توسيع XrStructureType :

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_APRIL_TAG_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ARUCO_MARKER_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MICRO_QR_CODE_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT
    • XR_TYPE_SPATIAL_MARKER_SIZE_EXT
    • XR_TYPE_SPATIAL_MARKER_STATIC_OPTIMIZATION_EXT

سجلّ الإصدارات

  • المراجعة 1، ‏29-07-2024 (رون بيسمز، Meta)

    • الوصف الأولي للإضافة