ردیابی نشانگر فضایی XR_EXT

رشته نام

XR_EXT_spatial_marker_tracking

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۴۴ عدد

بازنگری

۱

وضعیت تصویب

تصویب شده

وابستگی‌های افزونه و نسخه

XR_EXT_spatial_entity

مشارکت‌کنندگان

ران بسمس، متا
نیهاو جین، گوگل
ناتالی فلوری، متا
یویچی تاگوچی، متا
یین لی، مایکروسافت
جیمی آلمپارامبیل، بایت‌دنس
ژیپنگ لیو، ByteDance
جون یان، بایت‌دنس

نمای کلی

این افزونه بر اساس XR_EXT_spatial_entity ساخته شده و به برنامه‌ها اجازه می‌دهد تا نشانگرها را در محیط خود شناسایی و ردیابی کنند. نشانگرها کدهای دوبعدی هستند که ممکن است شامل کدهای QR، کدهای Micro QR، نشانگرهای 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 ارسال کند.

پیکربندی نوع نشانگر

کدهای QR

ساختار XrSpatialCapabilityConfigurationQrCodeEXT به صورت زیر تعریف می‌شود:

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • capability باید XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT باشد.
  • enabledComponentCount یک uint32_t با تعداد عناصر موجود در enabledComponents است.
  • enabledComponents یک اشاره‌گر به آرایه‌ای از کامپوننت‌ها برای فعال‌سازی این قابلیت است.

اگر کدهای QR پشتیبانی می‌شوند، زمان اجرا باید ردیابی کد QR را فعال کند، زمانی که ساختار XrSpatialCapabilityConfigurationQrCodeEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی xrCreateSpatialContextAsyncEXT ارسال می‌شود.

اگر XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

کاربرد معتبر (ضمنی)

کدهای QR میکرو

ساختار XrSpatialCapabilityConfigurationMicroQrCodeEXT به صورت زیر تعریف می‌شود:

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • capability باید XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT باشد.
  • enabledComponentCount یک uint32_t با تعداد عناصر موجود در enabledComponents است.
  • enabledComponents یک اشاره‌گر به آرایه‌ای از کامپوننت‌ها برای فعال‌سازی این قابلیت است.

اگر کدهای Micro QR پشتیبانی می‌شوند، زمان اجرا باید ردیابی Micro QR Code را فعال کند، زمانی که ساختار XrSpatialCapabilityConfigurationMicroQrCodeEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی xrCreateSpatialContextAsyncEXT ارسال می‌شود.

اگر XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

کاربرد معتبر (ضمنی)

نشانگرهای 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 باید XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT باشد.
  • enabledComponentCount یک uint32_t با تعداد عناصر موجود در enabledComponents است.
  • enabledComponents یک اشاره‌گر به آرایه‌ای از کامپوننت‌ها برای فعال‌سازی این قابلیت است.
  • arUcoDict دیکشنری نشانگر برای تشخیص است.

اگر نشانگرهای ArUco پشتیبانی شوند، زمان اجرا باید ردیابی نشانگر ArUco را فعال کند، زمانی که یک ساختار XrSpatialCapabilityConfigurationArucoMarkerEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی xrCreateSpatialContextAsyncEXT ارسال می‌شود.

اگر ساختار XrSpatialCapabilityConfigurationArucoMarkerEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs باشد اما XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT از xrCreateSpatialContextAsyncEXT برگرداند.

کاربرد معتبر (ضمنی)

شمارش 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 — دیکشنری نشانگر آروکو با ابعاد ۴ در ۴ پیکسل و ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT — دیکشنری نشانگر آروکو با ابعاد ۴ در ۴ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT — دیکشنری نشانگر آروکو با ابعاد ۴ در ۴ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT — دیکشنری نشانگر آروکو با ابعاد ۴ در ۴ پیکسل و ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT — دیکشنری نشانگر آروکو با ابعاد ۵ در ۵ پیکسل و ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT — دیکشنری نشانگر آروکو با ابعاد ۵ در ۵ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT — دیکشنری نشانگر آروکو با ابعاد ۵ در ۵ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT — دیکشنری نشانگر آروکو با ابعاد ۵ در ۵ پیکسل و ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT — دیکشنری نشانگر آروکو با ابعاد ۶ در ۶ پیکسل و ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT — دیکشنری نشانگر آروکو با ابعاد ۶ در ۶ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT — دیکشنری نشانگر آروکو با ابعاد ۶ در ۶ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT — دیکشنری نشانگر آروکو با ابعاد ۶ در ۶ پیکسل و ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT — دیکشنری نشانگر آروکو با ابعاد ۷ در ۷ پیکسل و ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — دیکشنری نشانگر آروکو با ابعاد ۷ در ۷ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT — دیکشنری نشانگر آروکو با ابعاد ۷ در ۷ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — دیکشنری نشانگر آروکو با ابعاد ۷ در ۷ پیکسل و ۱۰۰۰ شناسه.
برچسب‌های آوریل

ساختار 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 باید XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT باشد.
  • enabledComponentCount یک uint32_t با تعداد عناصر موجود در enabledComponents است.
  • enabledComponents یک اشاره‌گر به آرایه‌ای از کامپوننت‌ها برای فعال‌سازی این قابلیت است.
  • aprilDict دیکشنری نشانگر برای تشخیص است.

اگر AprilTags پشتیبانی شوند، زمان اجرا باید ردیابی AprilTag را فعال کند، زمانی که یک ساختار XrSpatialCapabilityConfigurationAprilTagEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی xrCreateSpatialContextAsyncEXT ارسال می‌شود.

اگر ساختار XrSpatialCapabilityConfigurationAprilTagEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs باشد اما XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT از xrCreateSpatialContextAsyncEXT برگرداند.

کاربرد معتبر (ضمنی)

شمارش 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 — ۴ در ۴ بیت، حداقل فاصله همینگ بین هر دو کد = ۵، ۳۰ کد.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT — ۵ در ۵ بیت، حداقل فاصله همینگ بین هر دو کد = ۹، ۳۵ کد.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT — ۶ در ۶ بیت، حداقل فاصله همینگ بین هر دو کد = ۱۰، ۲۳۲۰ کد.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT — ۶ در ۶ بیت، حداقل فاصله همینگ بین هر دو کد = ۱۱۵۸۷ کد.

پیکربندی‌های اختیاری نشانگر

برنامه‌ها باید 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 این فیلد باید معتبر باشد و با شناسه رمزگذاری شده پر شود. برای کدهای QR این فیلد باید صفر باشد.
  • 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 هستند.

برنامه می‌تواند با اضافه کردن XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes و اضافه کردن XrSpatialComponentMarkerListEXT به زنجیره اشاره‌گر بعدی XrSpatialComponentDataQueryResultEXT ، کامپوننت نشانگر موجودیت‌های مکانی را در XrSpatialSnapshotEXT جستجو کند.

اگر XrSpatialComponentMarkerListEXT در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE از xrQuerySpatialComponentDataEXT بازگرداند.

اگر markerCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT از xrQuerySpatialComponentDataEXT برگرداند.

کاربرد معتبر (ضمنی)

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT برای برخی قابلیت‌ها در XrSpatialCapabilityComponentTypesEXT :: componentTypes شمارش شده باشد، یک برنامه می‌تواند با قرار دادن شمارشگر در لیست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents از ساختار مشتق شده XrSpatialCapabilityConfigurationBaseHeaderEXT از قابلیتی که از این مولفه پشتیبانی می‌کند، آن را فعال کند.

این کامپوننت برای قرار گرفتن در زنجیره next XrSpatialCapabilityConfigurationBaseHeaderEXT :: نیازی به پیکربندی خاصی ندارد.

کامپوننت دوبعدی محدود

مؤلفه دوبعدی محدود، مرکز و محدوده نشانگری را که توسط موجودیتی که روی آن قرار دارد نمایش داده می‌شود، فراهم می‌کند. برای جزئیات بیشتر در مورد مؤلفه دوبعدی محدود، به بخش «دوبعدی محدود» مراجعه کنید.

center XrSpatialBounded2DDataEXT :: باید به مرکز نشانگر اشاره کند. هنگام نگاه کردن به سطح جلویی نشانگر، محور X باید به سمت راست و محور Y باید به بالای نشانگر اشاره کند. زمان اجرا باید از قرارداد سیستم مختصات راست‌گرد پیروی کند، بنابراین محور Z از سطح جلویی نشانگر خارج می‌شود. این بدان معناست که یک نشانگر با موقعیت {0، 0، 0}، چرخش {0، 0، 0، 1} (بدون چرخش) و وسعت {1، 1} به یک نشانگر 1 متر در 1 متر اشاره دارد که در مرکز {0، 0، 0} قرار دارد و بردار نرمال سطح جلویی آن به سمت جهت +Z در فضای مؤلفه است.

نمایی از جهت گیری نشانگر در زیر نشان داده شده است.

محور درک نشانگر xr ml

شکل ۲۵. نشانگر کد QR با محور

کدهای تست

کدهای زیر باید صفحه XY خود را درون سند و محور Z را به سمت بیننده داشته باشند. مبدا محور باید در مرکز هر نشانگر ظاهر شود. محور X باید به سمت راست و محور Y باید به بالای سند اشاره کند.

ردیابی نشانگر خارجی qr

شکل ۲۶. کد QR با متن «OpenXR»

ردیابی نشانگر ext آوریل

شکل ۲۷. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT با شناسه ۴۲

ردیابی نشانگر ext آروکو

شکل ۲۸. نشانگر ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT با شناسه ۴۳

کد مثال

پیکربندی قابلیت ردیابی کد QR

کد نمونه زیر نحوه پیکربندی قابلیت ردیابی کد QR را هنگام ایجاد یک زمینه مکانی نشان می‌دهد. 

// 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));

کشف موجودیت‌های مکانی و جستجوی داده‌های کامپوننت

کد نمونه زیر نحوه کشف موجودیت‌های مکانی برای یک context پیکربندی شده با 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
  // ...
}

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • 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 (ران بسمز، متا)

    • توضیحات اولیه افزونه