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 entitas spasial dengan (atau "yang memiliki") komponen berikut:

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Dukungan runtime

Runtime harus mengiklankan 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 ditentukan 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 di-enum oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Kode QR mikro

Struktur XrSpatialCapabilityConfigurationMicroQrCodeEXT ditentukan 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 QR Mikro didukung, runtime harus mengaktifkan pelacakan Kode QR Mikro saat struktur XrSpatialCapabilityConfigurationMicroQrCodeEXT diteruskan dalam 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 di-enum oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Penanda ArUco

Struktur XrSpatialCapabilityConfigurationArucoMarkerEXT ditentukan 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 dalam 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 di-enum oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Enumerasi XrSpatialMarkerArucoDictEXT ditentukan 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 5 x 5 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 7x7 piksel dengan 250 ID.
  • XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — Kamus penanda Aruco 7x7 piksel dengan 1.000 ID.
AprilTags

Struktur XrSpatialCapabilityConfigurationAprilTagEXT ditentukan 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 dalam 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 di-enum oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Enumerasi XrSpatialMarkerAprilTagDictEXT ditentukan 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 bawaan 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 kali 6 bit, jarak Hamming minimum antara dua kode = 10, 2320 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 ditentukan 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 semua penanda dalam meter.

Jika XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT di-enum oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan tertentu, dan jika aplikasi merangkai 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 postur 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 ditentukan 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 diperkirakan tidak bergerak.

Jika XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT di-enum oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan tertentu, dan jika aplikasi merangkai XrSpatialMarkerStaticOptimizationEXT ke struktur konfigurasi yang sesuai dari kemampuan tersebut, runtime harus mengasumsikan bahwa semua penanda yang terdeteksi bersifat statis jika optimizeForStaticMarker disetel 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 yang 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 terjamin dari semua entity yang ditemukan oleh kemampuan tersebut, dan harus mencantumkannya di xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponen Penanda

Data komponen

Struktur XrSpatialMarkerDataEXT ditentukan 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 berikut ini -

  • Jika runtime telah berhasil mendekode data untuk penanda, runtime harus menyetel jenis buffer 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 menyetel ID buffer data ke XR_NULL_SPATIAL_BUFFER_ID_EXT dan jenis buffer 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 menyetel ID buffer data ke XR_NULL_SPATIAL_BUFFER_ID_EXT .

Penggunaan yang Valid (Implisit)

Struktur daftar komponen untuk membuat kueri data

Struktur XrSpatialComponentMarkerListEXT ditentukan 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 entitas spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT di XrSpatialComponentDataQueryConditionEXT :: componentTypes dan menambahkan XrSpatialComponentMarkerListEXT ke rantai penunjuk berikutnya dari XrSpatialComponentDataQueryResultEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentMarkerListEXT berada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: 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 tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan enumerasi dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 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 rentang penanda yang diwakili oleh entitas yang ada di dalamnya. Lihat 2D Terikat untuk mengetahui detail selengkapnya tentang komponen 2D terikat.

XrSpatialBounded2DDataEXT :: center harus mengarah ke tengah penanda. Saat melihat bagian 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 sisi depan penanda. Artinya, penanda dengan posisi {0, 0, 0}, rotasi {0, 0, 0, 1} (tanpa rotasi), dan luas {1, 1} merujuk ke penanda 1 meter x 1 meter yang berpusat di {0, 0, 0} dengan vektor normal muka depannya mengarah ke arah +Z dalam 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 penampil. Asal sumbu harus muncul di tengah setiap penanda. Sumbu X harus mengarah ke kanan, sumbu Y harus mengarah ke bagian atas dokumen.

pelacakan penanda ext qr

Gambar 26. Kode QR dengan teks 'OpenXR'

pelacakan penanda ext apriltag

Gambar 27. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT dengan ID 42

pelacakan aruco penanda eksternal

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 Entitas Spasial & Data Komponen Kueri

Contoh kode berikut menunjukkan cara menemukan entitas 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