XR_ANDROID_trackables_marker

Chaîne de nom

XR_ANDROID_trackables_marker

Type d'extension

Extension d'instance

Numéro d'extension enregistré

708

Révision

1

État de ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_trackables

État d'abandon

  • Obsolète en raison de l'extension XR_EXT_spatial_marker_tracking

Date de dernière modification

03/07/2025

État de la propriété intellectuelle

Aucune réclamation connue concernant la propriété intellectuelle.

Participants

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

Présentation

Cette extension permet le suivi des marqueurs physiques et permet aux applications d'associer efficacement du contenu XR à des marqueurs physiques.

L'extension est compatible avec les types de marqueurs courants, en particulier les marqueurs ArUco et April. Elle permet aux environnements d'exécution de prendre en charge l'estimation de la taille des marqueurs.

Autorisations

Les applications Android doivent disposer de l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE dans leur fichier manifeste, car cette extension dépend de XR_ANDROID_trackables et expose la géométrie de l'environnement. L'autorisation android.permission.SCENE_UNDERSTANDING_COARSE est considérée comme une autorisation dangereuse, c'est-à-dire que les applications doivent la demander explicitement.

(niveau de protection : dangereux)

Inspecter la capacité du système

La structure XrSystemMarkerTrackingPropertiesANDROID est définie comme suit :

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

Description des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans le noyau OpenXR ni dans cette extension. Pour en savoir plus sur la chaîne de structures, consultez la structure en cours d'extension ( XrSystemProperties ).
  • supportsMarkerTracking est un XrBool32 indiquant si le système actuel offre une fonctionnalité de suivi des marqueurs.
  • supportsMarkerSizeEstimation est un XrBool32 indiquant si le système actuel offre une fonctionnalité d'estimation de la taille des marqueurs.
  • maxMarkerCount est le nombre maximal de marqueurs que l'environnement d'exécution peut suivre en même temps.

Une application peut vérifier si le système est capable de suivre les marqueurs en étendant XrSystemProperties avec la structure XrSystemMarkerTrackingPropertiesANDROID lors de l'appel de xrGetSystemProperties . L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED pour la création du suivi des marqueurs si et seulement si supportsMarkerTracking est XR_FALSE .

Si un environnement d'exécution est compatible avec le suivi des marqueurs, maxMarkerCount doit être au moins égal à 1.

Utilisation valide (implicite)

Suivi des marqueurs

Cette extension ajoute XR_TRACKABLE_TYPE_MARKER_ANDROID à XrTrackableTypeANDROID .

L'application crée un XrTrackableTrackerANDROID en appelant xrCreateTrackableTrackerANDROID et en spécifiant XR_TRACKABLE_TYPE_MARKER_ANDROID comme type de suivi dans XrTrackableTrackerCreateInfoANDROID :: trackableType, ainsi qu'en définissant une configuration valide en ajoutant un XrTrackableMarkerConfigurationANDROID à la chaîne suivante de XrTrackableTrackerCreateInfoANDROID .

L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType est XR_TRACKABLE_TYPE_MARKER_ANDROID et que XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking renvoie XR_FALSE via xrGetSystemProperties .

La structure XrTrackableMarkerConfigurationANDROID est définie comme suit :

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

Description des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • trackingMode est un XrTrackableMarkerTrackingModeANDROID indiquant le mode de suivi souhaité.
  • databaseCount est un uint32_t décrivant le nombre d'éléments dans le tableau databases.
  • databases est un pointeur vers un tableau de XrTrackableMarkerDatabaseANDROID , contenant chacun les marqueurs souhaités d'un dictionnaire donné à suivre.

L'application doit définir une configuration valide en ajoutant un XrTrackableMarkerConfigurationANDROID à la chaîne XrTrackableTrackerCreateInfoANDROID :: next lors de l'appel de xrCreateTrackableTrackerANDROID avec XrTrackableTrackerCreateInfoANDROID :: trackableType défini sur XR_TRACKABLE_TYPE_MARKER_ANDROID . Sinon, si le type de suivi est défini comme ci-dessus, mais que la structure de configuration n'est pas présente ou n'est pas valide, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Si un environnement d'exécution est compatible avec l'estimation de la taille des marqueurs, l'application peut définir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize sur 0 dans XrTrackableMarkerDatabaseANDROID :: entries pour indiquer l'utilisation de l'estimation de la taille. Sinon, l'application doit définir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize sur une valeur positive, ou l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

L'environnement d'exécution doit filtrer la sortie de xrGetAllTrackablesANDROID pour qu'elle corresponde à trackingMode et à XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Utilisation valide (implicite)

L'enum XrTrackableMarkerTrackingModeANDROID décrit les modes de suivi des marqueurs compatibles.

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;

Description des énumérants

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID : suivi des marqueurs dynamiques. Ce mode offre la plus grande justesse et fonctionne sur les repères statiques et en mouvement, mais il consomme également le plus d'énergie.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID : suivi des marqueurs statiques. Ce mode est principalement utile pour les marqueurs connus pour être statiques, ce qui entraîne une consommation d'énergie inférieure à celle du mode dynamique.

La structure XrTrackableMarkerDatabaseANDROID définit un dictionnaire et les ID de marqueurs correspondants à suivre.

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

Description des membres

  • dictionary est le XrTrackableMarkerDictionaryANDROID auquel appartiennent toutes les entries.
  • entryCount est un uint32_t décrivant le nombre d'éléments dans le tableau entries. L'application peut définir entryCount sur 0 pour suivre tous les marqueurs du dictionary .
  • entries est un pointeur vers un tableau de XrTrackableMarkerDatabaseEntryANDROID , contenant chacun la configuration d'un marqueur à suivre.

Utilisation valide (implicite)

L'enum XrTrackableMarkerDictionaryANDROID décrit les dictionnaires de marqueurs compatibles.

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;

La structure XrTrackableMarkerDatabaseEntryANDROID configure un seul ID de marqueur d'un dictionnaire.

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

Description des membres

  • id est l'ID de marqueur tel qu'il est indiqué dans le dictionnaire.
  • edgeSize représente la taille du bord du marqueur en mètres. Si l'environnement d'exécution est compatible avec l'estimation de la taille des marqueurs, l'application peut définir cette valeur sur zéro, et la taille du marqueur sera estimée en ligne. Si cette valeur est définie sur zéro, mais que l'environnement d'exécution n'est pas compatible avec l'estimation de la taille des marqueurs, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Utilisation valide (implicite)

Obtenir les marqueurs

La fonction xrGetTrackableMarkerANDROID est définie comme suit :

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

Description des paramètres

L'environnement d'exécution doit renvoyer XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si le type de suivi du XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_MARKER_ANDROID , ou si le type de suivi du XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_MARKER_ANDROID .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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

La structure XrTrackableMarkerANDROID est définie comme suit :

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

Description des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans le noyau OpenXR ni dans cette extension.
  • trackingState est le XrTrackingStateANDROID du marqueur.
  • lastUpdatedTime est le XrTime de la dernière mise à jour du marqueur.
  • dictionary est le XrTrackableMarkerDictionaryANDROID du marqueur.
  • markerId est l'ID de marqueur tel qu'il est indiqué dans le dictionnaire.
  • centerPose est le XrPosef du marqueur situé dans XrTrackableGetInfoANDROID :: baseSpace . Le marqueur se trouve dans le plan XZ, avec X pointant vers la droite du marqueur, Z pointant vers le bas et Y sortant du marqueur comme normale.
  • extents correspond aux dimensions XrExtent2Df du marqueur. La limite du cadre de délimitation se trouve aux points suivants : centerPose +/- ( extents / 2).

Utilisation valide (implicite)

Exemple de code pour obtenir des marqueurs suivis

L'exemple de code suivant montre comment obtenir des marqueurs suivis.

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

Nouvelles commandes

Nouvelles structures

Nouveaux enums

Nouvelles constantes d'enum

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Extension de XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Extension de XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problèmes

Historique des versions

  • Révision 1, 03/07/2025 (Levana Chen)

    • Description initiale de l'extension.