XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

744

Revision

1

Ratification Status (Status der Ratifizierung)

Ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

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 basiert auf XR_EXT_spatial_entity und ermöglicht es Anwendungen, Marker in ihrer Umgebung zu erkennen und zu verfolgen. Marker sind 2D-Codes, die möglicherweise QR‑Codes, Micro‑QR‑Codes, ArUco-Marker oder AprilTags enthalten.

Eine verfolgte Markierung wird als räumliche Einheit 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 Marker-Tracking-Funktionen mit xrEnumerateSpatialCapabilitiesEXT bewerben, 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 Markertypen

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 beim Aufrufen von xrCreateSpatialContextAsyncEXT eine XrSpatialCapabilityConfigurationQrCodeEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs übergeben 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 Nutzung (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 Tracking von Micro-QR-Codes aktivieren, wenn beim Aufrufen von xrCreateSpatialContextAsyncEXT eine XrSpatialCapabilityConfigurationMicroQrCodeEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs ü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 Nutzung (implizit)

ArUco-Marker

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 Tracking von ArUco-Markern aktivieren, wenn beim Aufrufen von xrCreateSpatialContextAsyncEXT eine XrSpatialCapabilityConfigurationArucoMarkerEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs ü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 Nutzung (implizit)

Die Enumeration 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ützte vordefinierte ArUco-Wörterbücher:

Beschreibungen der Aufzählungstypen

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

Die Struktur XrSpatialCapabilityConfigurationAprilTagEXT 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 beim Aufrufen von xrCreateSpatialContextAsyncEXT eine XrSpatialCapabilityConfigurationAprilTagEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs ü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 Nutzung (implizit)

Die Enumeration 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 Aufzählungstypen

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

Optionale Markierungskonfigurationen

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

Eine vollständige Liste aller räumlichen Funktionen, die von einer Erweiterung unterstützt werden, 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 aufgelistet wird und die Anwendung XrSpatialMarkerSizeEXT an die entsprechende Konfigurationsstruktur dieser Funktion anhängt, muss die Laufzeit davon ausgehen, dass alle erkannten Markierungen eine Breite und Höhe von markerSideLength haben . Wenn Sie diese Informationen an die Laufzeit weitergeben, kann sie eine genauere Position und Größe zurückgeben. Diese Struktur muss in die next-Kette von XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT oder XrSpatialCapabilityConfigurationAprilTagEXT eingebunden werden .

Gültige Nutzung (implizit)

Optimierung statischer Markierungen

Die Struktur XrSpatialMarkerStaticOptimizationEXT wird 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 sich alle Markierungen im Bereich nicht bewegen sollen.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT von xrEnumerateSpatialCapabilityFeaturesEXT für eine bestimmte Funktion aufgelistet wird und die Anwendung XrSpatialMarkerStaticOptimizationEXT an die entsprechende Konfigurationsstruktur dieser Funktion anhängt, muss die Laufzeit davon ausgehen, dass alle erkannten Markierungen statisch sind, wenn optimizeForStaticMarker auf XR_TRUE gesetzt ist . So kann die Laufzeit eine genauere Position und Größe generieren. Diese Struktur muss in die next-Kette von XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT oder XrSpatialCapabilityConfigurationAprilTagEXT eingebunden werden .

Gültige Nutzung (implizit)

Komponenten mit Garantie

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 von diesen Funktionen erkannten Einheiten bereitstellen und muss sie in xrEnumerateSpatialCapabilityComponentTypesEXT auflisten :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Marker-Komponente

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 des Markers. Bei ArUco-Markern und AprilTag muss dieses Feld gültig sein und die codierte ID enthalten. Bei QR-Codes muss dieses Feld null sein.
  • data ist die Puffer-ID und der Typ der zusätzlichen Informationen, die im Marker 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 den Marker erfolgreich decodiert hat, muss der Puffertyp data je nach den Daten im Marker auf XR_SPATIAL_BUFFER_TYPE_UINT8_EXT oder XR_SPATIAL_BUFFER_TYPE_STRING_EXT festgelegt werden. 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 des Markers noch nicht decodiert hat, muss sie die data-Puffer-ID auf XR_NULL_SPATIAL_BUFFER_ID_EXT und den Puffertyp auf XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT festlegen .

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 Nutzung (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 in OpenXR oder dieser Erweiterung nicht definiert.
  • markerCount ist die Anzahl der Elemente im markers-Member.
  • markers ist ein Array von XrSpatialMarkerDataEXT .

Die Anwendung kann die Markierungskomponente der räumlichen Einheiten in einem XrSpatialSnapshotEXT abfragen, indem sie XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes hinzufügt und XrSpatialComponentMarkerListEXT der 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 Nutzung (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 Enumerator in die XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents-Liste der XrSpatialCapabilityConfigurationBaseHeaderEXT-abgeleiteten Struktur der Funktion aufnimmt, die diese Komponente unterstützt.

Für diese Komponente ist keine spezielle Konfiguration erforderlich, damit sie in die XrSpatialCapabilityConfigurationBaseHeaderEXT :: next-Kette aufgenommen wird.

Begrenzte 2D-Komponente

Die umrissene 2D-Komponente enthält die Mitte und die Ausdehnung der Markierung, die durch die zugehörige Entität dargestellt wird. Weitere Informationen zur Komponente „Begrenztes 2D“ finden Sie unter Begrenztes 2D.

XrSpatialBounded2DDataEXT :: center muss auf die Mitte der Markierung verweisen. Wenn Sie auf die Vorderseite der Markierung schauen, muss die X-Achse nach rechts und die Y-Achse nach oben zeigen. Die Laufzeit muss der Konvention des rechtshändigen Koordinatensystems folgen. Die Z-Achse verläuft also aus der Vorderseite des Markers heraus. Das bedeutet, dass ein Marker mit der Position {0, 0, 0}, der Drehung {0, 0, 0, 1} (keine Drehung) und der Ausdehnung {1, 1} einen 1 Meter × 1 Meter großen Marker darstellt, der an der Position {0, 0, 0} zentriert ist und dessen Normalenvektor der Vorderseite in die +Z-Richtung im Raum der Komponente zeigt.

Unten sehen Sie eine Darstellung der Ausrichtung der Markierung.

xr ml marker understanding axis

Abbildung 25: QR‑Code-Markierung mit Achse

Testcodes

Die folgenden Codes müssen ihre XY-Ebene im Dokument haben und die Z-Achse muss auf den Betrachter zeigen. Der Achsenursprung muss in der Mitte jeder Markierung angezeigt werden. 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-Markierung 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 Einheiten entdecken und Komponentendaten abfragen

Im folgenden Beispielcode wird gezeigt, wie Sie räumliche Einheiten 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 Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

  • Erweitern 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

  • XrSpatialCapabilityFeatureEXT erweitern :

    • 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

  • XrStructureType erweitern :

    • 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

  • Revision 1, 29.07.2024 (Ron Bessems, Meta)

    • Erste Beschreibung der Erweiterung