XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

744

Revisione

1

Stato della ratifica

Ratificato

Dipendenze di estensioni e versioni

XR_EXT_spatial_entity

Collaboratori

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

Panoramica

Questa estensione si basa su XR_EXT_spatial_entity e consente alle applicazioni di rilevare e monitorare i marker nel loro ambiente. I marker sono codici 2D che possono includere codici QR, codici Micro QR, marker ArUco o AprilTag.

Un indicatore monitorato è rappresentato come un'entità spaziale con (o "che ha") i seguenti componenti:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Assistenza per i runtime

Un runtime deve annunciare il proprio supporto per le varie funzionalità di monitoraggio dei marker utilizzando xrEnumerateSpatialCapabilitiesEXT ed elencando una delle seguenti funzionalità:

  • 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

Configurazione

Per attivare il rilevamento di un tipo di indicatore, l'applicazione deve passare la struttura di configurazione corrispondente a xrCreateSpatialContextAsyncEXT .

Configurazioni dei tipi di indicatori

Codici QR

La struttura XrSpatialCapabilityConfigurationQrCodeEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • capability deve essere XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
  • enabledComponentCount è un uint32_t con il numero di elementi in enabledComponents .
  • enabledComponents è un puntatore a un array di componenti da attivare per questa funzionalità.

Se i codici QR sono supportati, il runtime deve attivare il monitoraggio dei codici QR quando viene passata una struttura XrSpatialCapabilityConfigurationQrCodeEXT in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando viene chiamato xrCreateSpatialContextAsyncEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Utilizzo valido (implicito)

Codici Micro QR

La struttura XrSpatialCapabilityConfigurationMicroQrCodeEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • capability deve essere XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
  • enabledComponentCount è un uint32_t con il numero di elementi in enabledComponents .
  • enabledComponents è un puntatore a un array di componenti da attivare per questa funzionalità.

Se i codici Micro QR sono supportati, il runtime deve attivare il monitoraggio dei codici Micro QR quando viene passata una struttura XrSpatialCapabilityConfigurationMicroQrCodeEXT in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando viene chiamato xrCreateSpatialContextAsyncEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Utilizzo valido (implicito)

Marcatori ArUco

La struttura XrSpatialCapabilityConfigurationArucoMarkerEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • capability deve essere XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
  • enabledComponentCount è un uint32_t con il numero di elementi in enabledComponents .
  • enabledComponents è un puntatore a un array di componenti da attivare per questa funzionalità.
  • arUcoDict è il dizionario di indicatori da rilevare.

Se i marker ArUco sono supportati, il runtime deve attivare il monitoraggio dei marker ArUco quando una struttura XrSpatialCapabilityConfigurationArucoMarkerEXT viene passata in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando viene chiamato xrCreateSpatialContextAsyncEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT da xrCreateSpatialContextAsyncEXT se una struttura XrSpatialCapabilityConfigurationArucoMarkerEXT si trova in XrSpatialContextCreateInfoEXT :: capabilityConfigs, ma XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Utilizzo valido (implicito)

L'enumerazione XrSpatialMarkerArucoDictEXT è definita come:

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;

Dizionario ArUco predefinito supportato:

Descrizioni degli enumeranti

  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT: dizionario di marker ArUco da 4 x 4 pixel con 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT: dizionario di marker ArUco da 4 x 4 pixel con 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT: dizionario di marker ArUco da 4 x 4 pixel con 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT: dizionario di marker ArUco da 4 x 4 pixel con 1000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT: dizionario di marker ArUco da 5 x 5 pixel con 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT: dizionario di marker ArUco da 5 x 5 pixel con 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT: dizionario di marker ArUco da 5 x 5 pixel con 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT: dizionario di marker ArUco da 5 x 5 pixel con 1000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT: dizionario di marker ArUco da 6 x 6 pixel con 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT: dizionario di marker ArUco 6 x 6 pixel con 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT: dizionario di marker ArUco da 6 x 6 pixel con 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT: dizionario di marker ArUco da 6 x 6 pixel con 1000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT: dizionario di marker ArUco da 7 x 7 pixel con 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT: dizionario di marker ArUco da 7 x 7 pixel con 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT: dizionario di marker ArUco da 7 x 7 pixel con 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT: dizionario di marker ArUco da 7 x 7 pixel con 1000 ID.
AprilTag

La struttura XrSpatialCapabilityConfigurationAprilTagEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • capability deve essere XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
  • enabledComponentCount è un uint32_t con il numero di elementi in enabledComponents .
  • enabledComponents è un puntatore a un array di componenti da attivare per questa funzionalità.
  • aprilDict è il dizionario di indicatori da rilevare.

Se gli AprilTag sono supportati, il runtime deve attivare il monitoraggio degli AprilTag quando viene passata una struttura XrSpatialCapabilityConfigurationAprilTagEXT in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando viene chiamato xrCreateSpatialContextAsyncEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT da xrCreateSpatialContextAsyncEXT se una struttura XrSpatialCapabilityConfigurationAprilTagEXT si trova in XrSpatialContextCreateInfoEXT :: capabilityConfigs, ma XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Utilizzo valido (implicito)

L'enumerazione XrSpatialMarkerAprilTagDictEXT è definita come:

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;

Dizionario AprilTag predefinito supportato:

Descrizioni degli enumeranti

  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT: 4 x 4 bit, distanza di Hamming minima tra due codici qualsiasi = 5, 30 codici.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT: 5 x 5 bit, distanza di Hamming minima tra due codici qualsiasi = 9, 35 codici.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT: 6 x 6 bit, distanza di Hamming minima tra due codici qualsiasi = 10, 2320 codici.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT: 6 x 6 bit, distanza di Hamming minima tra due codici qualsiasi = 11, 587 codici.

Configurazioni facoltative dei marker

Le applicazioni devono chiamare xrEnumerateSpatialCapabilityFeaturesEXT per ottenere l'elenco delle funzionalità facoltative supportate.

Consulta XrSpatialCapabilityFeatureEXT per un elenco completo di tutte le funzionalità di spatial capability supportate da qualsiasi estensione.

Dimensione indicatore

La struttura XrSpatialMarkerSizeEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • markerSideLength è la dimensione in metri di tutti i marker.

Se XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT viene enumerato da xrEnumerateSpatialCapabilityFeaturesEXT per una determinata funzionalità e se l'applicazione concatena XrSpatialMarkerSizeEXT alla struttura di configurazione corrispondente di quella funzionalità, il runtime deve presumere che tutti i marker rilevati abbiano larghezza e altezza pari a markerSideLength . Fornire queste informazioni al runtime consente di restituire una posa e una dimensione più accurate. Questa struttura deve essere collegata alla catena next di XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT o XrSpatialCapabilityConfigurationAprilTagEXT .

Utilizzo valido (implicito)

Ottimizzazione degli indicatori statici

La struttura XrSpatialMarkerStaticOptimizationEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • optimizeForStaticMarker indica se si prevede che tutti i marker nello spazio non si muovano.

Se XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT viene enumerato da xrEnumerateSpatialCapabilityFeaturesEXT per una determinata funzionalità e se l'applicazione concatena XrSpatialMarkerStaticOptimizationEXT alla struttura di configurazione corrispondente di quella funzionalità, il runtime deve presumere che tutti i marker rilevati siano statici se optimizeForStaticMarker è impostato su XR_TRUE . In questo modo, il runtime può generare una posa e una dimensione più accurate. Questa struttura deve essere collegata alla catena next di XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT o XrSpatialCapabilityConfigurationAprilTagEXT .

Utilizzo valido (implicito)

Componenti garantiti

Un runtime che supporta 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 o XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT deve fornire i seguenti componenti spaziali come componenti garantiti di tutte le entità rilevate da queste funzionalità e deve enumerarli in xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente Marker

Dati dei componenti

La struttura XrSpatialMarkerDataEXT è definita come:

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

Descrizioni dei membri

  • capability è l'XrSpatialCapabilityEXT che ha rilevato il marker.
  • markerId è l'identificatore codificato del marker. Per i marker ArUco e AprilTag, questo campo deve essere valido e compilato con l'ID codificato. Per i codici QR, questo campo deve essere impostato su zero.
  • data è l'ID buffer e il tipo di informazioni aggiuntive contenute nell'indicatore.

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT e XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT supportano dati aggiuntivi. Se capability è uno di questi:

  • Se il runtime ha decodificato correttamente i dati per l'indicatore, deve impostare il tipo di buffer data su XR_SPATIAL_BUFFER_TYPE_UINT8_EXT o XR_SPATIAL_BUFFER_TYPE_STRING_EXT , a seconda dei dati nell'indicatore. Il runtime deve anche impostare un ID buffer valido in data che l'applicazione può utilizzare con la funzione xrGetSpatialBuffer* appropriata per ottenere i dati.
  • Se il runtime non ha ancora decodificato i dati del marker, deve impostare l'ID buffer data su XR_NULL_SPATIAL_BUFFER_ID_EXT e il tipo di buffer su XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT .

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT e XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT non supportano dati aggiuntivi e il runtime deve impostare l'ID buffer di data su XR_NULL_SPATIAL_BUFFER_ID_EXT .

Utilizzo valido (implicito)

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentMarkerListEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • markerCount è il numero di elementi nel membro markers.
  • markers è un array di XrSpatialMarkerDataEXT .

L'applicazione può eseguire query sul componente indicatore delle entità spaziali in un XrSpatialSnapshotEXT aggiungendo XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes e aggiungendo XrSpatialComponentMarkerListEXT alla catena di puntatori successiva di XrSpatialComponentDataQueryResultEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentMarkerListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se markerCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, un'applicazione può attivarla includendo l'enumerante nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents della struttura derivata XrSpatialCapabilityConfigurationBaseHeaderEXT della funzionalità che supporta questo componente.

Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Componente 2D delimitato

Il componente 2D delimitato fornisce il centro e le estensioni dell'indicatore rappresentato dall'entità su cui si trova. Per ulteriori dettagli sul componente 2D delimitato, consulta 2D delimitato.

XrSpatialBounded2DDataEXT :: center deve puntare al centro del marker. Quando guardi la parte anteriore del marker, l'asse X deve puntare a destra e l'asse Y deve puntare verso la parte superiore del marker. Il runtime deve seguire la convenzione del sistema di coordinate destrorso, pertanto l'asse Z esce dalla superficie anteriore del marker. Ciò significa che un indicatore con una posizione di {0, 0, 0}, una rotazione di {0, 0, 0, 1} (nessuna rotazione) e un'estensione di {1, 1} si riferisce a un indicatore di 1 metro x 1 metro centrato su {0, 0, 0} con il vettore normale della superficie anteriore rivolto verso la direzione +Z nello spazio del componente.

Di seguito è riportata una rappresentazione dell'orientamento dell'indicatore.

xr ml marker understanding axis

Figura 25. Indicatore del codice QR con asse

Codici di test

I seguenti codici devono avere il piano X-Y all'interno del documento e l'asse Z rivolto verso lo spettatore. L'origine dell'asse deve apparire al centro di ogni indicatore. L'asse X deve puntare a destra, l'asse Y deve puntare alla parte superiore del documento.

ext marker tracking qr

Figura 26. Codice QR con il testo "OpenXR"

ext marker tracking apriltag

Figura 27. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT con ID 42

ext marker tracking aruco

Figura 28. Indicatore ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT con ID 43

Esempio di codice

Configura la funzionalità di monitoraggio dei codici QR

Il seguente codice di esempio mostra come configurare la funzionalità di monitoraggio dei codici QR durante la creazione di un contesto spaziale.

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

Scopri le entità spaziali ed esegui query sui dati dei componenti

Il seguente codice di esempio mostra come rilevare entità spaziali per un contesto configurato con XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT ed eseguire query sui dati dei relativi componenti.

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

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

  • Estensione di 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

  • Estensione di XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

  • Estensione di XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

  • Estensione di 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

Cronologia delle versioni

  • Revisione 1, 29/07/2024 (Ron Bessems, Meta)

    • Descrizione iniziale dell'estensione