XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

744

Revision

1

Ratification Status

Ratified

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_entity

Mitwirkende

Ron Bessems, Meta
Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Übersicht

Diese Erweiterung baut auf XR_EXT_spatial_entity auf und ermöglicht es Anwendungen, Markierungen in ihrer Umgebung zu erkennen und zu verfolgen. Markierungen sind 2D-Codes, die QR-Codes, Micro-QR-Codes, ArUco-Markierungen oder AprilTags enthalten können.

Ein getrackter Marker wird als räumliche Entität mit den folgenden Komponenten dargestellt:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Laufzeitunterstützung

Eine Laufzeit muss ihre Unterstützung für die verschiedenen Funktionen zur Markierungserkennung mit xrEnumerateSpatialCapabilitiesEXT angeben, indem sie eine der folgenden Funktionen auflistet:

  • 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

Konfiguration

Damit ein Markertyp erkannt werden kann, muss die Anwendung die entsprechende Konfigurationsstruktur an xrCreateSpatialContextAsyncEXT übergeben.

Konfigurationen für Markierungstypen

QR-Codes

Die Struktur XrSpatialCapabilityConfigurationQrCodeEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability muss XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT sein.
  • enabledComponentCount ist ein uint32_t mit der Anzahl der Elemente in enabledComponents .
  • enabledComponents ist ein Zeiger auf ein Array von Komponenten, die für diese Funktion aktiviert werden sollen.

Wenn QR-Codes unterstützt werden, muss die Laufzeit das QR-Code-Tracking aktivieren, wenn eine XrSpatialCapabilityConfigurationQrCodeEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs übergeben wird, wenn xrCreateSpatialContextAsyncEXT aufgerufen wird.

Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT zurückgeben, wenn XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT nicht von xrEnumerateSpatialCapabilitiesEXT aufgezählt wird.

Gültige Verwendung (implizit)

Micro-QR-Codes

Die Struktur XrSpatialCapabilityConfigurationMicroQrCodeEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability muss XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT sein.
  • enabledComponentCount ist ein uint32_t mit der Anzahl der Elemente in enabledComponents .
  • enabledComponents ist ein Zeiger auf ein Array von Komponenten, die für diese Funktion aktiviert werden sollen.

Wenn Micro-QR-Codes unterstützt werden, muss die Laufzeit das Micro-QR-Code-Tracking aktivieren, wenn eine XrSpatialCapabilityConfigurationMicroQrCodeEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs beim Aufruf von xrCreateSpatialContextAsyncEXT übergeben wird.

Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT zurückgeben, wenn XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT nicht von xrEnumerateSpatialCapabilitiesEXT aufgezählt wird.

Gültige Verwendung (implizit)

ArUco-Markierungen

Die Struktur XrSpatialCapabilityConfigurationArucoMarkerEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability muss XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT sein.
  • enabledComponentCount ist ein uint32_t mit der Anzahl der Elemente in enabledComponents .
  • enabledComponents ist ein Zeiger auf ein Array von Komponenten, die für diese Funktion aktiviert werden sollen.
  • arUcoDict ist das zu erkennende Markierungswörterbuch.

Wenn ArUco-Marker unterstützt werden, muss die Laufzeit das ArUco-Marker-Tracking aktivieren, wenn eine XrSpatialCapabilityConfigurationArucoMarkerEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs beim Aufruf von xrCreateSpatialContextAsyncEXT übergeben wird.

Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT von xrCreateSpatialContextAsyncEXT zurückgeben, wenn eine XrSpatialCapabilityConfigurationArucoMarkerEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs enthalten ist, aber XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT nicht von xrEnumerateSpatialCapabilitiesEXT aufgezählt wird.

Gültige Verwendung (implizit)

Die Aufzählung XrSpatialMarkerArucoDictEXT ist so definiert:

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;

Unterstütztes vordefiniertes ArUco-Wörterbuch:

Beschreibungen der Enumeranten

  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT: 4 × 4 Pixel großes Aruco-Marker-Wörterbuch mit 50 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT: 4 × 4 Pixel großes Aruco-Marker-Wörterbuch mit 100 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT: 4 × 4-Pixel-Aruco-Marker-Wörterbuch mit 250 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT: 4 × 4 Pixel großes Aruco-Marker-Wörterbuch mit 1.000 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT – 5 × 5 Pixel großes Aruco-Marker-Wörterbuch mit 50 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT: 5 × 5 Pixel großes Aruco-Marker-Wörterbuch mit 100 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT: 5 × 5 Pixel großes Aruco-Marker-Wörterbuch mit 250 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT: 5 × 5 Pixel großes Aruco-Marker-Wörterbuch mit 1.000 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT: 6 × 6 Pixel großes Aruco-Marker-Wörterbuch mit 50 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT: 6 × 6 Pixel großes Aruco-Marker-Wörterbuch mit 100 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT: 6 × 6 Pixel großes ArUco-Marker-Wörterbuch mit 250 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT: 6 × 6 Pixel großes Aruco-Marker-Wörterbuch mit 1.000 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT: 7 × 7 Pixel großes Aruco-Marker-Wörterbuch mit 50 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT: 7 × 7 Pixel großes Aruco-Marker-Wörterbuch mit 100 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT: 7 × 7 Pixel großes Aruco-Marker-Wörterbuch mit 250 IDs.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT: 7 × 7 Pixel großes Aruco-Marker-Wörterbuch mit 1.000 IDs.
AprilTags

Die XrSpatialCapabilityConfigurationAprilTagEXT-Struktur ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability muss XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT sein.
  • enabledComponentCount ist ein uint32_t mit der Anzahl der Elemente in enabledComponents .
  • enabledComponents ist ein Zeiger auf ein Array von Komponenten, die für diese Funktion aktiviert werden sollen.
  • aprilDict ist das zu erkennende Markierungswörterbuch.

Wenn AprilTags unterstützt werden, muss die Laufzeit das AprilTag-Tracking aktivieren, wenn eine XrSpatialCapabilityConfigurationAprilTagEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs beim Aufruf von xrCreateSpatialContextAsyncEXT übergeben wird.

Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT von xrCreateSpatialContextAsyncEXT zurückgeben, wenn eine XrSpatialCapabilityConfigurationAprilTagEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs enthalten ist, aber XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT nicht von xrEnumerateSpatialCapabilitiesEXT aufgezählt wird.

Gültige Verwendung (implizit)

Die Aufzählung XrSpatialMarkerAprilTagDictEXT ist so definiert:

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;

Unterstütztes vordefiniertes AprilTag-Wörterbuch:

Beschreibungen der Enumeranten

  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT: 4 × 4 Bit, minimale Hamming-Distanz zwischen zwei Codes = 5, 30 Codes.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT: 5 × 5 Bit, minimale Hamming-Distanz zwischen zwei Codes = 9, 35 Codes.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT – 6 × 6 Bit, minimaler Hamming-Abstand zwischen zwei Codes = 10, 2.320 Codes.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT: 6 × 6 Bit, minimaler Hamming-Abstand zwischen zwei Codes = 11, 587 Codes.

Optionale Markierungskonfigurationen

Anwendungen sollten xrEnumerateSpatialCapabilityFeaturesEXT aufrufen, um die Liste der unterstützten optionalen Funktionen abzurufen.

Eine vollständige Liste aller von Erweiterungen unterstützten räumlichen Funktionen finden Sie unter XrSpatialCapabilityFeatureEXT.

Markierungsgröße

Die Struktur XrSpatialMarkerSizeEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • markerSideLength ist die Größe aller Markierungen in Metern.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT von xrEnumerateSpatialCapabilityFeaturesEXT für eine bestimmte Funktion aufgezählt wird und die Anwendung XrSpatialMarkerSizeEXT mit der entsprechenden Konfigurationsstruktur dieser Funktion verknüpft, muss die Laufzeit davon ausgehen, dass alle erkannten Markierungen eine Breite und Höhe von markerSideLength haben. Wenn du diese Informationen der Laufzeitumgebung zur Verfügung stellst, kann sie eine genauere Pose und Größe zurückgeben. Diese Struktur muss mit der next-Kette von XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT oder XrSpatialCapabilityConfigurationAprilTagEXT verknüpft sein.

Gültige Verwendung (implizit)

Optimierung statischer Markierungen

Die Struktur XrSpatialMarkerStaticOptimizationEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • optimizeForStaticMarker gibt an, ob alle Markierungen im Raum voraussichtlich nicht bewegt werden.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT von xrEnumerateSpatialCapabilityFeaturesEXT für eine bestimmte Funktion aufgezählt wird und die Anwendung XrSpatialMarkerStaticOptimizationEXT mit der entsprechenden Konfigurationsstruktur dieser Funktion verknüpft, muss die Laufzeit davon ausgehen, dass alle erkannten Markierungen statisch sind, wenn optimizeForStaticMarker auf XR_TRUE gesetzt ist. Dadurch kann die Laufzeit eine genauere Pose und Größe generieren. Diese Struktur muss mit der next-Kette von XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT oder XrSpatialCapabilityConfigurationAprilTagEXT verknüpft sein.

Gültige Verwendung (implizit)

Garantierte Komponenten

Eine Laufzeit, die 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 oder XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT unterstützt, muss die folgenden räumlichen Komponenten als garantierte Komponenten aller Entitäten bereitstellen, die von diesen Funktionen erkannt werden, und sie muss sie in xrEnumerateSpatialCapabilityComponentTypesEXT auflisten:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Markierungskomponente

Komponentendaten

Die Struktur XrSpatialMarkerDataEXT ist so definiert:

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

Mitgliederbeschreibungen

  • capability ist die XrSpatialCapabilityEXT, die die Markierung erkannt hat.
  • markerId ist die codierte Kennung aus der Markierung. Bei ArUco-Markern und AprilTags muss dieses Feld gültig sein und die codierte ID enthalten. Bei QR-Codes muss dieses Feld „0“ sein.
  • data ist die Puffer-ID und der Typ der zusätzlichen Informationen, die in der Markierung enthalten sind.

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT und XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT unterstützen zusätzliche Daten. Wenn capability einer dieser Werte ist:

  • Wenn die Laufzeit die Daten für die Markierung erfolgreich decodiert hat, muss sie den Puffertyp data je nach den Daten in der Markierung entweder auf XR_SPATIAL_BUFFER_TYPE_UINT8_EXT oder XR_SPATIAL_BUFFER_TYPE_STRING_EXT setzen. Die Laufzeit muss außerdem eine gültige Puffer-ID in data festlegen, die die Anwendung mit der entsprechenden xrGetSpatialBuffer*-Funktion verwenden kann, um die Daten abzurufen.
  • Wenn die Laufzeit die Daten der Markierung noch nicht decodiert hat, muss sie die Puffer-ID data auf XR_NULL_SPATIAL_BUFFER_ID_EXT und den Puffertyp auf XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT setzen.

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT und XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT unterstützen keine zusätzlichen Daten und die Laufzeit muss die Puffer-ID von data auf XR_NULL_SPATIAL_BUFFER_ID_EXT festlegen.

Gültige Verwendung (implizit)

Komponentenlistenstruktur zum Abfragen von Daten

Die Struktur XrSpatialComponentMarkerListEXT ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • markerCount ist die Anzahl der Elemente im markers-Mitglied.
  • markers ist ein Array von XrSpatialMarkerDataEXT .

Die Anwendung kann die Markierungskomponente der räumlichen Entitäten in einem XrSpatialSnapshotEXT abfragen, indem sie XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes und XrSpatialComponentMarkerListEXT zur nächsten Zeigerkette von XrSpatialComponentDataQueryResultEXT hinzufügt.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn XrSpatialComponentMarkerListEXT in der nächsten Kette von XrSpatialComponentDataQueryResultEXT :: next enthalten ist, aber XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes enthalten ist.

Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn markerCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist.

Gültige Verwendung (implizit)

Konfiguration

Wenn XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT in XrSpatialCapabilityComponentTypesEXT :: componentTypes für eine bestimmte Funktion aufgeführt ist, kann eine Anwendung sie aktivieren, indem sie den Enumeranten in die Liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents der abgeleiteten Struktur XrSpatialCapabilityConfigurationBaseHeaderEXT der Funktion aufnimmt, die diese Komponente unterstützt.

Für diese Komponente ist keine spezielle Konfiguration erforderlich, um sie in die XrSpatialCapabilityConfigurationBaseHeaderEXT-Kette (next) aufzunehmen.

Begrenzte 2D-Komponente

Die begrenzte 2D-Komponente liefert den Mittelpunkt und die Ausdehnung der Markierung, die durch die Entität dargestellt wird, auf der sie sich befindet. Weitere Informationen zur Komponente „Bounded 2D“ finden Sie unter Bounded 2D.

XrSpatialBounded2DDataEXT :: center muss auf die Mitte des Markers zeigen. Wenn Sie die Vorderseite der Markierung betrachten, muss die X-Achse nach rechts und die Y-Achse nach oben zeigen. Die Laufzeit muss der Konvention des rechtshändigen Koordinatensystems folgen, sodass die Z-Achse aus der Vorderseite der Markierung herausragt. Das bedeutet, dass eine Markierung mit der Position {0, 0, 0}, der Rotation {0, 0, 0, 1} (keine Rotation) und der Ausdehnung {1, 1} eine 1 m x 1 m große Markierung ist, die bei {0, 0, 0} zentriert ist und deren Normalenvektor der Vorderseite in die +Z-Richtung im Raum der Komponente zeigt.

Unten sehen Sie eine Darstellung der Ausrichtung der Markierung.

XR-ML-Marker-Verständnisachse

Abbildung 25: QR-Code-Markierung mit Achse

Testcodes

Bei den folgenden Codes muss sich die X-Y-Ebene innerhalb des Dokuments befinden und die Z-Achse muss auf den Betrachter zeigen. Der Achsenursprung muss in der Mitte jeder Markierung liegen. Die X-Achse muss nach rechts und die Y-Achse muss nach oben zeigen.

ext marker tracking qr

Abbildung 26: QR-Code mit dem Text „OpenXR“

ext marker tracking apriltag

Abbildung 27: AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT mit ID 42

ext marker tracking aruco

Abbildung 28: ArUco-Marker XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT mit ID 43

Beispiel-Code

QR-Code-Tracking konfigurieren

Im folgenden Beispielcode wird gezeigt, wie Sie die QR-Code-Tracking-Funktion beim Erstellen eines räumlichen Kontexts konfigurieren.

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

Räumliche Entitäten entdecken und Komponentendaten abfragen

Im folgenden Beispielcode wird gezeigt, wie Sie räumliche Entitäten für einen mit XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT konfigurierten Kontext ermitteln und die zugehörigen Komponentendaten abfragen.

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

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

  • Erweiterung von 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

  • Erweiterung von XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

  • Erweiterung von XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

  • Erweiterung von 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

Versionsverlauf

  • Version 1, 29.07.2024 (Ron Bessems, Meta)

    • Anfängliche Beschreibung der Erweiterung