XR_EXT_spatial_marker_tracking

String Nama

XR_EXT_spatial_marker_tracking

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

744

Revisi

1

Status Ratifikasi

Diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity

Kontributor

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

Ringkasan

Ekstensi ini dibuat berdasarkan XR_EXT_spatial_entity dan memungkinkan aplikasi mendeteksi serta melacak penanda di lingkungannya. Penanda adalah kode 2D yang dapat mencakup Kode QR, Kode QR Mikro, penanda ArUco, atau AprilTag.

Penanda yang dilacak direpresentasikan sebagai entity spasial dengan (atau "yang memiliki") komponen berikut:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Dukungan runtime

Runtime harus memberitahukan dukungannya untuk berbagai kemampuan pelacakan penanda menggunakan xrEnumerateSpatialCapabilitiesEXT dengan mencantumkan salah satu kemampuan berikut:

  • 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

Konfigurasi

Untuk mengaktifkan deteksi jenis penanda, aplikasi harus meneruskan struktur konfigurasi yang sesuai ke xrCreateSpatialContextAsyncEXT .

Konfigurasi Jenis Penanda

kode QR

Struktur XrSpatialCapabilityConfigurationQrCodeEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability harus berupa XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
  • enabledComponentCount adalah uint32_t dengan jumlah elemen dalam enabledComponents .
  • enabledComponents adalah pointer ke array komponen yang akan diaktifkan untuk kemampuan ini.

Jika kode QR didukung, runtime harus mengaktifkan pelacakan Kode QR saat struktur XrSpatialCapabilityConfigurationQrCodeEXT diteruskan di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil xrCreateSpatialContextAsyncEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT tidak dihitung oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Kode QR mikro

Struktur XrSpatialCapabilityConfigurationMicroQrCodeEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability harus berupa XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
  • enabledComponentCount adalah uint32_t dengan jumlah elemen dalam enabledComponents .
  • enabledComponents adalah pointer ke array komponen yang akan diaktifkan untuk kemampuan ini.

Jika kode Micro QR didukung, runtime harus mengaktifkan pelacakan Kode Micro QR saat struktur XrSpatialCapabilityConfigurationMicroQrCodeEXT diteruskan di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil xrCreateSpatialContextAsyncEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT tidak dihitung oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Penanda ArUco

Struktur XrSpatialCapabilityConfigurationArucoMarkerEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability harus berupa XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
  • enabledComponentCount adalah uint32_t dengan jumlah elemen dalam enabledComponents .
  • enabledComponents adalah pointer ke array komponen yang akan diaktifkan untuk kemampuan ini.
  • arUcoDict adalah kamus penanda yang akan dideteksi.

Jika penanda ArUco didukung, runtime harus mengaktifkan pelacakan penanda ArUco saat struktur XrSpatialCapabilityConfigurationArucoMarkerEXT diteruskan di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil xrCreateSpatialContextAsyncEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT dari xrCreateSpatialContextAsyncEXT jika struktur XrSpatialCapabilityConfigurationArucoMarkerEXT ada di XrSpatialContextCreateInfoEXT :: capabilityConfigs, tetapi XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT tidak dihitung oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Enumerasi XrSpatialMarkerArucoDictEXT didefinisikan sebagai:

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;

Kamus ArUco standar yang didukung:

Deskripsi Enumeran

  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT — Kamus penanda Aruco 4x4 piksel dengan 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT — Kamus penanda Aruco 4x4 piksel dengan 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT — Kamus penanda Aruco 4x4 piksel dengan 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT — Kamus penanda Aruco 4x4 piksel dengan 1.000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT — Kamus penanda Aruco 5x5 piksel dengan 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT — Kamus penanda Aruco 5x5 piksel dengan 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT — Kamus penanda Aruco 5x5 piksel dengan 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT — Kamus penanda Aruco 5x5 piksel dengan 1.000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT — Kamus penanda Aruco 6x6 piksel dengan 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT — Kamus penanda Aruco 6x6 piksel dengan 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT — Kamus penanda Aruco 6x6 piksel dengan 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT — Kamus penanda Aruco 6x6 piksel dengan 1.000 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT — Kamus penanda Aruco 7x7 piksel dengan 50 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — Kamus penanda Aruco 7x7 piksel dengan 100 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT — Kamus penanda Aruco 7 x 7 piksel dengan 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — Kamus penanda Aruco 7x7 piksel dengan 1.000 ID.
AprilTags

Struktur XrSpatialCapabilityConfigurationAprilTagEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability harus berupa XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
  • enabledComponentCount adalah uint32_t dengan jumlah elemen dalam enabledComponents .
  • enabledComponents adalah pointer ke array komponen yang akan diaktifkan untuk kemampuan ini.
  • aprilDict adalah kamus penanda yang akan dideteksi.

Jika AprilTag didukung, runtime harus mengaktifkan pelacakan AprilTag saat struktur XrSpatialCapabilityConfigurationAprilTagEXT diteruskan di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil xrCreateSpatialContextAsyncEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT dari xrCreateSpatialContextAsyncEXT jika struktur XrSpatialCapabilityConfigurationAprilTagEXT ada di XrSpatialContextCreateInfoEXT :: capabilityConfigs, tetapi XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT tidak dihitung oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Enumerasi XrSpatialMarkerAprilTagDictEXT didefinisikan sebagai:

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;

Kamus AprilTag standar yang didukung:

Deskripsi Enumeran

  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT — 4 x 4 bit, jarak Hamming minimum antara dua kode = 5, 30 kode.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT — 5 x 5 bit, jarak Hamming minimum antara dua kode = 9, 35 kode.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT — 6 x 6 bit, jarak Hamming minimum antara dua kode = 10, 2.320 kode.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT — 6 x 6 bit, jarak Hamming minimum antara dua kode = 11, 587 kode.

Konfigurasi Penanda Opsional

Aplikasi harus memanggil xrEnumerateSpatialCapabilityFeaturesEXT untuk mendapatkan daftar fitur opsional yang didukung.

Lihat XrSpatialCapabilityFeatureEXT untuk mengetahui daftar lengkap semua fitur kemampuan spasial yang didukung oleh ekstensi apa pun.

Ukuran Penanda

Struktur XrSpatialMarkerSizeEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • markerSideLength adalah ukuran dalam meter dari semua penanda.

Jika XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan tertentu, dan jika aplikasi merantai XrSpatialMarkerSizeEXT ke struktur konfigurasi yang sesuai dari kemampuan tersebut, runtime harus mengasumsikan bahwa semua penanda yang terdeteksi memiliki lebar dan tinggi markerSideLength . Dengan memberikan informasi ini ke runtime, runtime dapat menampilkan pose dan ukuran yang lebih akurat. Struktur ini harus ditautkan ke rantai next XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT , atau XrSpatialCapabilityConfigurationAprilTagEXT .

Penggunaan yang Valid (Implisit)

Pengoptimalan Penanda Statis

Struktur XrSpatialMarkerStaticOptimizationEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • optimizeForStaticMarker menunjukkan apakah semua penanda di ruang diharapkan tidak bergerak.

Jika XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan tertentu, dan jika aplikasi merantai XrSpatialMarkerStaticOptimizationEXT ke struktur konfigurasi yang sesuai dari kemampuan tersebut, runtime harus mengasumsikan bahwa semua penanda yang terdeteksi bersifat statis jika optimizeForStaticMarker ditetapkan ke XR_TRUE . Hal ini memungkinkan runtime menghasilkan pose dan ukuran yang lebih akurat. Struktur ini harus ditautkan ke rantai next XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT , atau XrSpatialCapabilityConfigurationAprilTagEXT .

Penggunaan yang Valid (Implisit)

Komponen Dijamin

Runtime yang mendukung 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 , atau XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT harus menyediakan komponen spasial berikut sebagai komponen yang dijamin dari semua entity yang ditemukan oleh kemampuan tersebut, dan harus menghitungnya dalam xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponen Penanda

Data komponen

Struktur XrSpatialMarkerDataEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • capability adalah XrSpatialCapabilityEXT yang mendeteksi penanda.
  • markerId adalah ID yang dienkode dari penanda. Untuk penanda ArUco dan AprilTag, kolom ini harus valid dan diisi dengan ID yang dienkode. Untuk kode QR, kolom ini harus nol.
  • data adalah ID buffer dan jenis informasi tambahan yang terdapat dalam penanda.

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT dan XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT mendukung data tambahan. Jika capability adalah salah satu dari ini -

  • Jika runtime berhasil mendekode data untuk penanda, runtime harus menetapkan jenis buffering data ke XR_SPATIAL_BUFFER_TYPE_UINT8_EXT atau XR_SPATIAL_BUFFER_TYPE_STRING_EXT , bergantung pada data dalam penanda. Runtime juga harus menetapkan ID buffer yang valid di data yang dapat digunakan aplikasi dengan fungsi xrGetSpatialBuffer* yang sesuai untuk mendapatkan data.
  • Jika runtime belum mendekode data penanda, runtime harus menetapkan ID buffering data ke XR_NULL_SPATIAL_BUFFER_ID_EXT dan jenis buffering ke XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT .

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT dan XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT tidak mendukung data tambahan dan runtime harus menetapkan ID buffering data ke XR_NULL_SPATIAL_BUFFER_ID_EXT .

Penggunaan yang Valid (Implisit)

Struktur daftar komponen untuk mengkueri data

Struktur XrSpatialComponentMarkerListEXT didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • markerCount adalah jumlah elemen dalam anggota markers.
  • markers adalah array XrSpatialMarkerDataEXT .

Aplikasi dapat mengkueri komponen penanda entity spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT di XrSpatialComponentDataQueryConditionEXT :: componentTypes dan menambahkan XrSpatialComponentMarkerListEXT ke rantai pointer berikutnya dari XrSpatialComponentDataQueryResultEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentMarkerListEXT berada dalam rantai berikutnya dari XrSpatialComponentDataQueryResultEXT :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Runtime harus menampilkan XR_ERROR_SIZE_INSUFFICIENT dari xrQuerySpatialComponentDataEXT jika markerCount kurang dari XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Penggunaan yang Valid (Implisit)

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT dienumerasi di XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan enumerasi dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT dari kemampuan yang mendukung komponen ini.

Komponen ini tidak memerlukan konfigurasi khusus untuk disertakan dalam rantai XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Komponen 2D Terikat

Komponen 2D yang dibatasi menyediakan pusat dan jangkauan penanda yang diwakili oleh entity tempatnya berada. Lihat 2D Terbatas untuk mengetahui detail selengkapnya tentang komponen 2D terbatas.

XrSpatialBounded2DDataEXT :: center harus mengarah ke pusat penanda. Saat melihat permukaan depan penanda, sumbu X harus mengarah ke kanan, dan sumbu Y harus mengarah ke bagian atas penanda. Runtime harus mengikuti konvensi sistem koordinat tangan kanan sehingga sumbu Z keluar dari permukaan depan penanda. Artinya, penanda dengan posisi {0, 0, 0}, rotasi {0, 0, 0, 1} (tanpa rotasi), dan luas {1, 1} mengacu pada penanda berukuran 1 meter x 1 meter yang berpusat di {0, 0, 0} dengan vektor normal permukaan depannya mengarah ke arah +Z di ruang komponen.

Representasi orientasi penanda ditampilkan di bawah.

sumbu pemahaman penanda ml xr

Gambar 25. Penanda kode QR dengan sumbu

Kode Pengujian

Kode berikut harus memiliki bidang X-Y di dalam dokumen dan sumbu Z mengarah ke pembaca. Titik asal sumbu harus muncul di tengah setiap penanda. Sumbu X harus mengarah ke kanan, sumbu Y harus mengarah ke bagian atas dokumen.

ext marker tracking qr

Gambar 26. Kode QR dengan teks 'OpenXR'

ext marker tracking apriltag

Gambar 27. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT dengan ID 42

ext marker tracking aruco

Gambar 28. Penanda ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT dengan ID 43

Kode Contoh

Mengonfigurasi Kemampuan Pelacakan Kode QR

Contoh kode berikut menunjukkan cara mengonfigurasi kemampuan pelacakan kode QR saat membuat konteks spasial.

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

Menemukan Entity Spasial & Membuat Kueri Data Komponen

Contoh kode berikut menunjukkan cara menemukan entity spasial untuk konteks yang dikonfigurasi dengan XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT dan mengkueri data komponennya.

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

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

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

  • Memperluas XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

  • Memperluas XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

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

Riwayat Versi

  • Revisi 1, 29-07-2024 (Ron Bessems, Meta)

    • Deskripsi ekstensi awal