XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

拡張機能の種類

インスタンス拡張

登録済みの内線番号

708

リビジョン

1

承認ステータス

未批准

拡張機能とバージョンの依存関係

XR_ANDROID_trackables

サポート終了の状態

  • XR_EXT_spatial_marker_tracking 拡張機能によって非推奨

最終更新日

2025-07-23

IP ステータス

既知の IP 申し立てはありません。

寄与者

Christopher Doer、Google
Diego Tipaldi、Google
Levana Chen、Google
Jared Finder、Google
Spencer Quin、Google
Nihav Jain、Google
Ken Mackay、Google
Daniel Guttenberg、Qualcomm

概要

この拡張機能により、物理マーカーのトラッキングが可能になり、アプリは XR コンテンツを物理マーカーに効率的にアタッチできるようになります。

この拡張機能は、よく知られているマーカータイプ（具体的には ArUco と AprilTag）をサポートしています。これにより、ランタイムは必要に応じてマーカーサイズの推定をサポートできます。

権限

この拡張機能は XR_ANDROID_trackables に依存し、環境のジオメトリを公開するため、Android アプリのマニフェストに android.permission.SCENE_UNDERSTANDING_COARSE 権限を記載する必要があります。android.permission.SCENE_UNDERSTANDING_COARSE 権限は危険な権限と見なされます。つまり、アプリは明示的に権限をリクエストしなければなりません。

（保護レベル: dangerous）

システム機能を検査する

XrSystemMarkerTrackingPropertiesANDROID 構造体は次のように定義されます。

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。構造チェーンの詳細については、拡張される構造（XrSystemProperties）をご覧ください。
  • supportsMarkerTracking は、現在のシステムがマーカー トラッキング機能を提供しているかどうかを示す XrBool32 です。
  • supportsMarkerSizeEstimation は、現在のシステムがマーカーサイズの推定を提供するかどうかを示す XrBool32 です。
  • maxMarkerCount は、ランタイムが同時に追跡できるマーカーの最大数です。

アプリは、xrGetSystemProperties を呼び出すときに、XrSystemMarkerTrackingPropertiesANDROID 構造体を使用して XrSystemProperties を拡張することで、システムがマーカー トラッキングに対応しているかどうかを検査できます。ランタイムは、supportsMarkerTracking が XR_FALSE の場合に限り、マーカー トラッカーの作成に対して XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

ランタイムがマーカー トラッキングをサポートしている場合、maxMarkerCount は 1 以上でなければなりません。

有効な使用方法（暗黙的）

トラッキング マーカー

この拡張機能により、XrTrackableTypeANDROID に XR_TRACKABLE_TYPE_MARKER_ANDROID が追加されます。

アプリは、xrCreateTrackableTrackerANDROID を呼び出し、XrTrackableTrackerCreateInfoANDROID :: trackableType でトラッキング可能なタイプとして XR_TRACKABLE_TYPE_MARKER_ANDROID を指定し、XrTrackableTrackerCreateInfoANDROID の次のチェーンに XrTrackableMarkerConfigurationANDROID を追加して有効な構成を設定することで、XrTrackableTrackerANDROID を作成します。

XrTrackableTrackerCreateInfoANDROID :: trackableType が XR_TRACKABLE_TYPE_MARKER_ANDROID で、XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking が xrGetSystemProperties を介して XR_FALSE を返す場合、ランタイムは XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

XrTrackableMarkerConfigurationANDROID 構造体は次のように定義されます。

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • trackingMode は、トラッキングの目的のモードを示す XrTrackableMarkerTrackingModeANDROID です。
  • databaseCount は、databases 配列内の要素の数を表す uint32_t です。
  • databases は、XrTrackableMarkerDatabaseANDROID の配列へのポインタです。各配列には、特定の辞書から追跡する目的のマーカーが含まれています。

XrTrackableTrackerCreateInfoANDROID :: trackableType を XR_TRACKABLE_TYPE_MARKER_ANDROID に設定して xrCreateTrackableTrackerANDROID を呼び出す場合、アプリケーションは XrTrackableTrackerCreateInfoANDROID :: next チェーンに XrTrackableMarkerConfigurationANDROID を追加して、有効な構成を設定する必要があります。それ以外の場合、トラッカー タイプが上記のように設定されているが、構成構造が存在しないか無効である場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムがマーカーサイズ推定をサポートしている場合、アプリケーションは XrTrackableMarkerDatabaseANDROID :: entries の XrTrackableMarkerDatabaseEntryANDROID :: edgeSize を 0 に設定して、サイズ推定の使用を示すことができます。それ以外の場合、アプリは XrTrackableMarkerDatabaseEntryANDROID :: edgeSize を正の値に設定しなければなりません。または、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムは、xrGetAllTrackablesANDROID からの出力をフィルタして、trackingMode と XrTrackableMarkerDatabaseEntryANDROID :: edgeSize に一致させる必要があります。

有効な使用方法（暗黙的）

XrTrackableMarkerTrackingModeANDROID 列挙型は、サポートされているマーカーのトラッキング モードを示します。

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

列挙子の説明

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID - 動的マーカーのトラッキング。このモードは精度が最も高く、移動するマーカーと静止したマーカーの両方に対応しますが、消費電力も最も高くなります。
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID - 静的マーカーをトラッキングします。このモードは、主に静的であることがわかっているマーカーに役立ちます。動的モードと比較して消費電力が少なくなります。

XrTrackableMarkerDatabaseANDROID 構造体は、追跡する辞書と対応するマーカー ID を定義します。

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

メンバーの説明

  • dictionary は、すべての entries が属する XrTrackableMarkerDictionaryANDROID です。
  • entryCount は、entries 配列内の要素の数を表す uint32_t です。アプリケーションは、entryCount 0 を設定して、dictionary 内のすべてのマーカーを追跡できます。
  • entries は XrTrackableMarkerDatabaseEntryANDROID の配列へのポインタです。各エントリには、追跡するマーカーの構成が含まれています。

有効な使用方法（暗黙的）

XrTrackableMarkerDictionaryANDROID 列挙型は、サポートされているマーカー辞書を記述します。

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

XrTrackableMarkerDatabaseEntryANDROID 構造体は、辞書の単一のマーカー ID を構成します。

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

メンバーの説明

  • id は、辞書で指定されたマーカー ID です。
  • edgeSize は、マーカーのエッジのサイズをメートル単位で表します。ランタイムがマーカーサイズの推定をサポートしている場合、アプリケーションはこれをゼロに設定できます。マーカーサイズはオンラインで推定されます。この値が 0 に設定されているが、ランタイムがマーカーサイズの推定をサポートしていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

有効な使用方法（暗黙的）

マーカーを取得する

xrGetTrackableMarkerANDROID 関数は次のように定義されます。

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

パラメータの説明

XrTrackableANDROID のトラッキング可能なタイプが XR_TRACKABLE_TYPE_MARKER_ANDROID でない場合、または XrTrackableTrackerANDROID のトラッキング可能なタイプが XR_TRACKABLE_TYPE_MARKER_ANDROID でない場合、ランタイムは XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID を返さなければなりません。

有効な使用方法（暗黙的）

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrTrackableMarkerANDROID 構造体は次のように定義されます。

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • trackingState は、マーカーの XrTrackingStateANDROID です。
  • lastUpdatedTime は、マーカーの最終更新の XrTime です。
  • dictionary は、マーカーの XrTrackableMarkerDictionaryANDROID です。
  • markerId は、辞書で指定されたマーカー ID です。
  • centerPose は、XrTrackableGetInfoANDROID :: baseSpace にあるマーカーの XrPosef です。マーカーは XZ 平面にあり、X はマーカーの右側、Z はマーカーの下部、Y はマーカーから法線として出ています。
  • extents は、マーカーの XrExtent2Df ディメンションです。境界ボックスの境界は、centerPose +/-（extents / 2）のポイントにあります。

有効な使用方法（暗黙的）

追跡可能なマーカーを取得するサンプルコード

次のサンプルコードは、追跡可能なマーカーを取得する方法を示しています。

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

新しいコマンド

新しい構造

新しい列挙型

新しい列挙型定数

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType の拡張:

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID の拡張:

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

問題

変更履歴

  • リビジョン 1、2025-07-23（Levana Chen）

    • 拡張機能の初期説明。