XR_EXT_spatial_marker_tracking

رشته نام

XR_EXT_spatial_marker_tracking

نوع افزونه

افزونه نمونه

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

744

بازبینی

1

وضعیت تصویب

تصویب‌شده

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

XR_EXT_spatial_entity

همیاران

Ron Bessems،‏ Meta
Nihav Jain،‏ Google
Natalie Fleury،‏ Meta
Yuichi Taguchi،‏ Meta
Yin Li،‏ Microsoft
Jimmy Alamparambil،‏ ByteDance
Zhipeng Liu،‏ ByteDance
Jun Yan،‏ 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 باید XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT باشد.
  • enabledComponentCount یک uint32_t با تعداد عناصر در enabledComponents است.
  • enabledComponents اشاره‌گری به آرایه‌ای از مؤلفه‌ها است که باید برای این قابلیت فعال شود.

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

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

استفاده معتبر (ضمنی)

رمزینه‌های پاسخ‌سریع میکرو

ساختار 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 پشتیبانی می‌شوند، زمان اجرا باید ردیابی «رمزینه پاسخ‌سریع Micro» را وقتی ساختار 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 — فرهنگ لغت نشانگر Aruco با ۴ در ۴ پیکسل و ۵۰ شناسه.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT — فرهنگ لغت نشانگر Aruco با ۴ در ۴ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT — فرهنگ لغت نشانگر Aruco با ۴ در ۴ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT — فرهنگ لغت نشانگر Aruco با ۴ در ۴ پیکسل و ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT — فرهنگ لغت نشانگر Aruco با ۵ در ۵ پیکسل و ۵۰ شناسه.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT — واژه‌نامه نشانگر Aruco با ۵ در ۵ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT — واژه‌نامه نشانگر Aruco با ۵ در ۵ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT — واژه‌نامه نشانگر Aruco با ۵ در ۵ پیکسل و ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT — فرهنگ لغت نشانگر Aruco با پیکسل ۶ در ۶ با ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT — فرهنگ لغت نشانگر Aruco با ۶ در ۶ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT — فرهنگ لغت نشانگر Aruco با ۶ در ۶ پیکسل و ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT — فرهنگ لغت نشانگر Aruco با پیکسل ۶ در ۶ با ۱۰۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT — واژه‌نامه نشانگر Aruco با پیکسل ۷ در ۷ با ۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — واژه‌نامه نشانگر Aruco با ۷ در ۷ پیکسل و ۱۰۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT — فرهنگ لغت نشانگر Aruco با پیکسل ۷ در ۷ با ۲۵۰ شناسه.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — فرهنگ لغت نشانگر Aruco با پیکسل ۷ در ۷ با ۱۰۰۰ شناسه.
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 باید 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، این فیلد باید معتبر باشد و با شناسه کدبندی‌شده پر شود. برای رمزینه‌های پاسخ‌سریع، این فیلد باید صفر باشد.
  • 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 مربوط به قابلیتی که از این مؤلفه پشتیبانی می‌کند فعال کند.

این مؤلفه برای گنجانده شدن در زنجیره XrSpatialCapabilityConfigurationBaseHeaderEXT :: next به پیکربندی خاصی نیاز ندارد.

عنصر دوبعدی محدودشده

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

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

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

xr ml marker understanding axis

شکل ۲۵. نشانگر رمزینه پاسخ‌سریع با محور

کدهای آزمایشی

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

ext marker tracking qr

شکل ۲۶. رمزینه پاسخ‌سریع با نوشتار «OpenXR»

ext marker tracking apriltag

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

ext marker tracking aruco

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

کد نمونه

پیکربندی قابلیت ردیابی رمزینه پاسخ‌سریع

کد نمونه زیر نشان می‌دهد که چگونه قابلیت ردیابی رمزینه پاسخ‌سریع را هنگام ایجاد بافت فضایی پیکربندی کنید.

// 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
  // ...
}

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

Enums جدید

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

  • 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

سابقه نسخه

  • بازبینی ۱، ۲۰۲۴/۰۷/۲۹ (ران بسمز، متا)

    • شرح اولیه افزونه