XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

708

Revision

1

Ratifizierungsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_ANDROID_trackables

Einstellungsstatus

  • Eingestellt durch die Erweiterung XR_EXT_spatial_marker_tracking

Datum der letzten Änderung

23.07.2025

IP-Status

Keine bekannten IP-Ansprüche.

Mitwirkende

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

Übersicht

Diese Erweiterung ermöglicht das Tracking physischer Marker und ermöglicht Anwendungen, XR-Inhalte auf effiziente Weise an physische Marker anzuhängen.

Die Erweiterung unterstützt bekannte Markertypen, insbesondere ArUco- und April-Tags. Sie ermöglicht es Runtimes, optional die Schätzung der Markergröße zu unterstützen.

Berechtigungen

Android-Anwendungen müssen die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE in ihrem Manifest auflisten, da diese Erweiterung von XR_ANDROID_trackables abhängt und die Geometrie der Umgebung offenlegt. Die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE gilt als gefährliche Berechtigung. Das heißt, Anwendungen müssen die Berechtigung explizit anfordern.

(Schutzstufe: gefährlich)

Systemfunktionen prüfen

Die Struktur XrSystemMarkerTrackingPropertiesANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen definiert. Weitere Informationen zur Strukturkette finden Sie in der Struktur, die erweitert wird ( XrSystemProperties).
  • supportsMarkerTracking ist ein XrBool32, das angibt, ob das aktuelle System die Funktion zum Tracking von Markern bietet.
  • supportsMarkerSizeEstimation ist ein XrBool32, das angibt, ob das aktuelle System die Schätzung der Markergröße bietet.
  • maxMarkerCount ist die maximale Anzahl von Markern, die die Runtime gleichzeitig tracken kann.

Eine Anwendung kann prüfen, ob das System Marker-Tracking unterstützt, indem sie die XrSystemProperties beim Aufruf von xrGetSystemProperties mit der Struktur XrSystemMarkerTrackingPropertiesANDROID erweitert . Die Runtime muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung des Marker-Trackers zurückgeben, wenn supportsMarkerTracking XR_FALSE ist .

Wenn eine Runtime Marker-Tracking unterstützt, muss maxMarkerCount mindestens 1 sein.

Gültige Verwendung (implizit)

Marker tracken

Diese Erweiterung fügt XR_TRACKABLE_TYPE_MARKER_ANDROID zu XrTrackableTypeANDROID hinzu .

Die Anwendung erstellt einen XrTrackableTrackerANDROID, indem sie xrCreateTrackableTrackerANDROID aufruft und XR_TRACKABLE_TYPE_MARKER_ANDROID als trackbaren Typ in XrTrackableTrackerCreateInfoANDROID :: trackableType angibt. Außerdem muss eine gültige Konfiguration festgelegt werden, indem XrTrackableMarkerConfigurationANDROID zur nächsten Kette von XrTrackableTrackerCreateInfoANDROID hinzugefügt wird.

Die Runtime muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_MARKER_ANDROID ist und XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking über xrGetSystemProperties XR_FALSE zurückgibt .

Die Struktur XrTrackableMarkerConfigurationANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • trackingMode ist ein XrTrackableMarkerTrackingModeANDROID, das den gewünschten Modus für das Tracking angibt.
  • databaseCount ist ein uint32_t, das die Anzahl der Elemente im Array databases beschreibt.
  • databases ist ein Zeiger auf ein Array von XrTrackableMarkerDatabaseANDROID, das jeweils die gewünschten Marker aus einem bestimmten Wörterbuch enthält, die getrackt werden sollen.

Die Anwendung muss eine gültige Konfiguration festlegen, indem sie beim Aufruf von xrCreateTrackableTrackerANDROID mit XrTrackableTrackerCreateInfoANDROID :: trackableType auf XR_TRACKABLE_TYPE_MARKER_ANDROID eine XrTrackableMarkerConfigurationANDROID zur Kette XrTrackableTrackerCreateInfoANDROID :: next hinzufügt . Wenn der Tracker-Typ wie oben festgelegt ist, die Konfigurationsstruktur aber nicht vorhanden oder ungültig ist, muss die Runtime XR_ERROR_VALIDATION_FAILURE zurückgeben .

Wenn eine Runtime die Schätzung der Markergröße unterstützt, kann die Anwendung XrTrackableMarkerDatabaseEntryANDROID :: edgeSize in XrTrackableMarkerDatabaseANDROID :: entries auf 0 setzen, um die Schätzung der Größe anzugeben. Andernfalls muss die Anwendung XrTrackableMarkerDatabaseEntryANDROID :: edgeSize auf einen positiven Wert setzen oder die Runtime muss XR_ERROR_VALIDATION_FAILURE zurückgeben .

Die Runtime muss die Ausgabe von xrGetAllTrackablesANDROID so filtern, dass sie mit trackingMode und XrTrackableMarkerDatabaseEntryANDROID :: edgeSize übereinstimmt .

Gültige Verwendung (implizit)

Die XrTrackableMarkerTrackingModeANDROID-Enum beschreibt die unterstützten Tracking-Modi von Markern.

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;

Beschreibungen der Enumeranten

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID – Dynamische Marker tracken. Dieser Modus bietet die höchste Genauigkeit und funktioniert mit beweglichen und statischen Markern, hat aber auch den höchsten Stromverbrauch.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID – Statische Marker tracken. Dieser Modus ist hauptsächlich für Marker nützlich, die bekanntermaßen statisch sind, was im Vergleich zum dynamischen Modus zu einem geringeren Stromverbrauch führt.

Die Struktur XrTrackableMarkerDatabaseANDROID definiert ein Wörterbuch und die entsprechenden Marker-IDs, die getrackt werden sollen.

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

Mitgliederbeschreibungen

  • dictionary ist das XrTrackableMarkerDictionaryANDROID, zu dem alle entries gehören.
  • entryCount ist ein uint32_t, das die Anzahl der Elemente im Array entries beschreibt. Die Anwendung kann entryCount auf 0 setzen, um alle Marker im dictionary zu tracken .
  • entries ist ein Zeiger auf ein Array von XrTrackableMarkerDatabaseEntryANDROID , das jeweils die Konfiguration eines zu trackenden Markers enthält.

Gültige Verwendung (implizit)

Die XrTrackableMarkerDictionaryANDROID-Enum beschreibt die unterstützten Marker-Wörterbücher.

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;

Die Struktur XrTrackableMarkerDatabaseEntryANDROID konfiguriert eine einzelne Marker-ID eines Wörterbuchs.

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

Mitgliederbeschreibungen

  • id ist die Marker-ID, wie im Wörterbuch angegeben.
  • edgeSize gibt die Größe des Markerrands in Metern an. Wenn die Runtime die Schätzung der Markergröße unterstützt, kann die Anwendung diesen Wert auf null setzen. Die Markergröße wird dann online geschätzt. Wenn dieser Wert auf null gesetzt ist, die Runtime aber die Schätzung der Markergröße nicht unterstützt, muss die Runtime XR_ERROR_VALIDATION_FAILURE zurückgeben .

Gültige Verwendung (implizit)

Marker abrufen

Die Funktion xrGetTrackableMarkerANDROID ist so definiert:

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

Parameterbeschreibungen

Die Runtime muss XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zurückgeben , wenn der trackbare Typ des XrTrackableANDROID nicht XR_TRACKABLE_TYPE_MARKER_ANDROID ist oder wenn der trackbare Typ des XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_MARKER_ANDROID ist .

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrTrackableMarkerANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen definiert.
  • trackingState ist der XrTrackingStateANDROID des Markers.
  • lastUpdatedTime ist die XrTime der letzten Aktualisierung des Markers.
  • dictionary ist das XrTrackableMarkerDictionaryANDROID des Markers.
  • markerId ist die Marker-ID, wie im Wörterbuch angegeben.
  • centerPose ist die XrPosef der Markierung in XrTrackableGetInfoANDROID :: baseSpace . Der Marker liegt in der XZ-Ebene, wobei X nach rechts vom Marker und Z nach unten zeigt und Y als Normale aus dem Marker kommt.
  • extents sind die XrExtent2Df-Abmessungen des Markers. Die Grenze des Begrenzungsrahmens liegt an den Punkten: centerPose +/- ( extents / 2).

Gültige Verwendung (implizit)

Beispielcode zum Abrufen trackbarer Marker

Der folgende Beispielcode zeigt, wie Sie trackbare Marker abrufen.

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

Neue Befehle

Neue Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType erweitern :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID erweitern :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Probleme

Versionsverlauf

  • Revision 1, 23.07.2025 (Levana Chen)

    • Erste Beschreibung der Erweiterung.