XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

744

Revision

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 и позволяет приложениям обнаруживать и отслеживать маркеры в окружающей среде. Маркеры – это двухмерные коды, которые могут включать QR-коды, микро-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_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, если XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT не перечислено в xrEnumerateSpatialCapabilitiesEXT .

Допустимое использование (неявное)

Микро-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 – указатель на массив компонентов, которые нужно включить для этой функции.

Если микро-QR-коды поддерживаются, среда выполнения должна включить отслеживание микро-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 должно быть XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
  • enabledComponentCount – это uint32_t с количеством элементов в enabledComponents .
  • enabledComponents – указатель на массив компонентов, которые нужно включить для этой функции.
  • arUcoDict – словарь маркеров, которые нужно обнаружить.

Если маркеры 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 x 4 пикселя с 50 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT – словарь маркеров Aruco размером 4 x 4 пикселя со 100 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT – словарь маркеров Aruco размером 4 x 4 пикселя с 250 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT – словарь маркеров ArUco размером 4 x 4 пикселя с 1000 идентификаторов.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT – словарь маркеров Aruco размером 5 x 5 пикселей с 50 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT – словарь маркеров Aruco размером 5 x 5 пикселей со 100 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT – словарь маркеров Aruco размером 5 x 5 пикселей с 250 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT – словарь маркеров Aruco размером 5 x 5 пикселей с 1000 идентификаторов.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT – словарь маркеров Aruco размером 6 x 6 пикселей с 50 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT – словарь маркеров Aruco размером 6 x 6 пикселей со 100 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT – словарь маркеров Aruco размером 6 x 6 пикселей с 250 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT – словарь маркеров ArUco размером 6 x 6 пикселей с 1000 идентификаторов.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT – словарь маркеров Aruco размером 7 x 7 пикселей с 50 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT – словарь маркеров Aruco размером 7 x 7 пикселей со 100 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT – словарь маркеров ArUco размером 7 x 7 пикселей с 250 идентификаторами.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT – словарь маркеров Aruco размером 7 x 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 должно быть 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 x 4 бита, минимальное расстояние Хэмминга между любыми двумя кодами – 5, 30 кодов.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT – 5 x 5 бит, минимальное расстояние Хэмминга между любыми двумя кодами – 9, 35 кодов.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT – 6 x 6 бит, минимальное расстояние Хэмминга между любыми двумя кодами – 10, 2320 кодов.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT – 6 x 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 это поле должно быть заполнено закодированным идентификатором. Для 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 .

Допустимое использование (неявное)

  • Расширение XR_EXT_spatial_marker_tracking должно быть включено до использования XrSpatialMarkerDataEXT.
  • capability должно быть допустимым значением XrSpatialCapabilityEXT.
  • data должен быть допустимой структурой XrSpatialBufferEXT.
Структура списка компонентов для запроса данных

Структура 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 не требуется специальная конфигурация.

Ограниченный двухмерный компонент

Ограниченный 2D-компонент предоставляет центр и границы маркера, представленного объектом, на котором он находится. Подробнее о компоненте Bounded 2D…

XrSpatialBounded2DDataEXT :: center должен указывать на центр маркера. Если смотреть на лицевую сторону маркера, ось X должна указывать вправо, а ось Y – вверх. Среда выполнения должна использовать правостороннюю систему координат, в которой ось Z направлена от лицевой стороны маркера. Это означает, что маркер с положением {0, 0, 0}, поворотом {0, 0, 0, 1} (без поворота) и размером {1, 1} относится к маркеру размером 1 м x 1 м с центром в точке {0, 0, 0} и нормальным вектором передней грани, направленным в сторону +Z в пространстве компонента.

Ниже показано, как ориентирован маркер.

xr ml marker understanding axis

Рисунок 25. Маркер QR-кода с осью

Коды тестов

У следующих кодов плоскость X-Y должна находиться внутри документа, а ось Z – указывать на зрителя. Начало координат должно находиться в центре каждого маркера. Ось X должна быть направлена вправо, а ось Y – вверх.

ext marker tracking qr

Рисунок 26. QR-код с текстом OpenXR

ext marker tracking apriltag

Рисунок 27. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT с идентификатором 42

ext marker tracking aruco

Рисунок 28. Маркер ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT с идентификатором 43

Пример кода

Как настроить отслеживание 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));

Обнаружение пространственных объектов и запрос данных компонентов

В примере кода ниже показано, как обнаружить пространственные объекты для контекста, настроенного с помощью 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 июля 2024 г. (Рон Бессемс, Meta)

    • Описание расширения