Utiliser des ancrages Geospatial pour positionner du contenu réel sur le NDK Android

Les ancres géospatiales sont un type d'ancrage qui vous permet de positionner du contenu 3D dans le monde réel.

Types d'ancrages géospatiales

Il existe trois types d'ancres géospatiales, qui gèrent chacun différemment l'altitude:

1. Ancres WGS84:
   Les ancres WGS84 vous permettent de positionner du contenu 3D à n'importe quelle latitude, longitude et altitude donnée.

2. Ancres de relief:
   Les ancres de relief vous permettent de placer du contenu en utilisant uniquement la latitude et la longitude d'une hauteur par rapport au relief à cette position. L'altitude est déterminée par rapport au sol ou au sol, ce qui est connu par le système VPS.

3. Ancres de toit:
   Les ancrages de toit vous permettent de placer du contenu en utilisant uniquement la latitude et la longitude d'une hauteur par rapport au toit d'un bâtiment à cette position. L'altitude est déterminée par rapport au sommet d'un bâtiment, grâce à la fonctionnalité de géométrie du paysage urbain. L'altitude du relief est utilisée par défaut si vous n'êtes pas placé sur un bâtiment.

	WGS84	Relief	Toit
Position horizontale	Latitude, Longitude	Latitude, Longitude	Latitude, Longitude
Position verticale	Par rapport à l'altitude WGS84	Par rapport au niveau de relief déterminé par Google Maps	Par rapport au niveau du toit déterminé par Google Maps
Doit être résolu par le serveur ?	Non	Oui	Oui

Conditions préalables

Veillez à activer l'API Geospatial avant de continuer.

Placer les ancres Geospatial

Chaque type d'ancre est associé à des API dédiées. Pour en savoir plus, consultez la section Types d'ancres géospatiales.

Créer une ancre à partir d'un test de positionnement

Vous pouvez également créer une ancre géospatiale à partir d'un résultat d'un test de positionnement. Utilisez la posture du test de positionnement et convertissez-la en ArGeospatialPose. Utilisez-le pour placer l'un des trois types d'ancrages décrits.

Obtenir une posture géospatiale à partir d'une posture en RA

ArEarth_getGeospatialPose() fournit un moyen supplémentaire de déterminer la latitude et la longitude en convertissant une posture RA en posture géospatiale.

Obtenir une posture en RA à partir d'une posture géospatiale

ArEarth_getPose() convertit une position horizontale, l'altitude et une rotation du quaternion spécifiées par la Terre par rapport à une trame de coordonnées est-sud en une posture de RA par rapport à la coordonnée mondiale GL.

Choisissez la méthode adaptée à votre cas d'utilisation

Chaque méthode de création d'une ancre présente des compromis associés à garder à l'esprit:

• Lorsque vous utilisez Streetscape Geometry, utilisez un test de positionnement pour associer du contenu à un bâtiment.
• Préférez les ancres de relief ou de toiture aux ancres WGS84, car elles utilisent les valeurs d'altitude déterminées par Google Maps.

Déterminer la latitude et la longitude d'un lieu

Il existe trois façons de calculer la latitude et la longitude d'un établissement:

• Utilisez Geospatial Creator pour visualiser et enrichir le monde avec du contenu 3D sans avoir à vous rendre physiquement à un endroit. Cela vous permet de placer visuellement des contenus 3D immersifs à l'aide de Google Maps dans l'éditeur Unity. La latitude, la longitude, la rotation et l'altitude du contenu sont calculées automatiquement.
• Utiliser Google Maps
• Utilisez Google Earth. Notez que si vous obtenez ces coordonnées à l'aide de Google Earth et non de Google Maps, la marge d'erreur peut atteindre plusieurs mètres.
• Accéder à l'adresse physique

Utiliser Google Maps

Pour obtenir la latitude et la longitude d'un lieu à l'aide de Google Maps:

1. Accédez à Google Maps sur votre ordinateur.

   

2. Accédez à Calques > Plus.

   

   

3. Définissez le Type de carte sur Satellite et décochez la case Vue Globe en bas à gauche de l'écran.

   

   Cela force une perspective 2D et élimine les erreurs qui pourraient provenir d'une vue inclinée en 3D.

4. Sur la carte, effectuez un clic droit sur le lieu, puis sélectionnez la longitude et la latitude pour la copier dans votre presse-papiers.

Utiliser Google Earth

Vous pouvez calculer la latitude et la longitude d'un lieu à partir de Google Earth. Pour ce faire, cliquez dessus dans l'interface utilisateur et lisez les données issues des détails du repère.

Remarque :Si vous obtenez ces coordonnées à l'aide de Google Earth plutôt que de Google Maps, la marge d'erreur peut atteindre plusieurs mètres. Nous vous recommandons d'utiliser Google Maps et l'API Elevation pour obtenir la latitude et la longitude d'un lieu.

Pour obtenir la latitude et la longitude d'un lieu à l'aide de Google Earth:

1. Accédez à Google Earth sur votre ordinateur.

2. Accédez au menu à trois barres , puis sélectionnez Style de carte.

   

3. Désactivez le bouton Bâtiments 3D.

   

4. Une fois que le bouton Bâtiments 3D est désactivé, cliquez sur l'icône en forme de punaise pour ajouter un repère à l'emplacement sélectionné.

5. Indiquez le projet qui contiendra votre repère, puis cliquez sur Enregistrer.

6. Dans le champ Titre du repère, saisissez le nom de ce dernier.

7. Cliquez sur la flèche de retour dans le volet du projet, puis sélectionnez le menu Autres actions .

8. Dans le menu, sélectionnez Exporter en tant que fichier KML.

   

Le fichier KLM indique la latitude, la longitude et l'altitude d'un repère dans la balise <coordinates> en les séparant par des virgules, comme suit:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

N'utilisez pas la latitude et la longitude des balises <LookAt>, qui spécifient la position de la caméra, et non l'emplacement.

Accéder à l'adresse physique

Vous pouvez calculer l'altitude d'un lieu en vous y rendant physiquement et en effectuant une observation locale.

Obtenir le quaternion de rotation

ArGeospatialPose_getEastUpSouthQuaternion() extrait l'orientation d'une posture géospatiale et génère un quaternion représentant la matrice de rotation transformant un vecteur de la cible vers le système de coordonnées Est-Sud-Sud (EUS). X+ points vers l'est, Y+ points vers le haut et Z+ points vers le sud. Les valeurs sont écrites dans l'ordre {x, y, z, w}.

Ancres WGS84

Une ancre WGS84 est un type d'ancre qui vous permet de placer du contenu 3D à n'importe quelle latitude, longitude et altitude. Il repose sur une posture et une orientation pour être placés dans le monde réel. La position comprend une latitude, une longitude et une altitude, spécifiées dans le système de coordonnées WGS84. L'orientation consiste en une rotation quaternionique.

L'altitude est indiquée en mètres au-dessus de l'ellipsoïde de référence WGS84 de sorte que le niveau du sol n'est pas à zéro. Votre application se charge de fournir ces coordonnées pour chaque ancre créée.

Placer une ancre WGS84 dans le monde réel

Déterminer l'altitude d'un lieu

Il existe plusieurs façons de déterminer l'altitude d'un lieu pour placer des ancrages:

• Si l'emplacement de l'ancre se trouve physiquement à proximité de l'utilisateur, vous pouvez utiliser une altitude semblable à celle de l'appareil de l'utilisateur.
• Une fois que vous disposez de la latitude et de la longitude, utilisez l'API Elevation pour obtenir une altitude en fonction de la spécification EGM96. Vous devez convertir l'altitude EGM96 de l'API Google Maps en WGS84 pour la comparer à l'altitude ArGeospatialPose. Consultez GeoidEval, qui propose à la fois une ligne de commande et une interface HTML. L'API Google Maps indique directement la latitude et la longitude conformément à la spécification WGS84.
• Vous pouvez obtenir la latitude, la longitude et l'altitude d'un lieu dans Google Earth. Vous obtenez ainsi une marge d'erreur pouvant atteindre plusieurs mètres. Dans le fichier KML, utilisez la latitude, la longitude et l'altitude des balises <coordinates>, et non des balises <LookAt>.
• Si une ancre existante se trouve à proximité et si vous ne vous trouvez pas sur une pente prononcée, vous pouvez peut-être utiliser l'altitude à partir du ArGeospatialPose de la caméra sans utiliser une autre source, telle que l'API Google Maps.

Créer l'ancre

Une fois que vous disposez de la latitude, de la longitude, de l'altitude et du quaternion de rotation, utilisez ArEarth_acquireNewAnchor() pour ancrer le contenu aux coordonnées géographiques que vous spécifiez.

float eus_quaternion_4[4] = {qx, qy, qz, qw};
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArAnchor* earth_anchor = NULL;
    ArStatus status = ArEarth_acquireNewAnchor(ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude,
        eus_quaternion_4, &earth_anchor);

    // Attach content to the anchor specified by geodetic location and
    // pose.
  }
}

Remarque :Il n'est pas possible de créer des ancres situées à moins de 0,1 degré du pôle Nord ou du pôle Sud (90 degrés ou -90 degrés). Si une telle ancre est spécifiée, elle ne sera pas créée.

Ancres de terrain

Une ancre de relief est un type d'ancre qui vous permet de placer des objets de RA en utilisant uniquement la latitude et la longitude, à l'aide des informations VPS pour déterminer l'altitude exacte au-dessus du sol.

Au lieu de saisir l'altitude souhaitée, vous devez indiquer l'altitude au-dessus du relief. Lorsque cette valeur est égale à zéro, l'ancre est mise au même niveau par rapport au relief.

Définir le mode de recherche d'avion

La recherche de plan est facultative et n'est pas obligatoire pour utiliser des ancres. Notez que seuls des plans horizontaux sont utilisés. Les plans horizontaux permettent d'aligner dynamiquement les ancrages du relief au sol.

Utilisez ArPlaneFindingMode pour sélectionner la manière dont votre application détecte les plans.

Créer une ancre de relief à l'aide de la nouvelle API Async

Pour créer et placer une ancre de relief, appelez ArEarth_resolveAnchorOnTerrainAsync().

L'ancre ne sera pas prête immédiatement et doit être résolue. Une fois le problème résolu, il sera disponible dans le ArResolveAnchorOnTerrainFuture.

Pour vérifier l'état d'ancrage du relief, utilisez ArResolveAnchorOnTerrainFuture_getResultTerrainAnchorState(). Obtenez l'ancre résolue à l'aide de ArResolveAnchorOnTerrainFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnTerrainCallback callback = NULL;
ArResolveAnchorOnTerrainFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnTerrainAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_terrain, eus_quaternion_4,
        context, callback, &future);
  }
}

Remarque :Il n'est pas possible de créer des ancrages situés à moins de 0,1 degré des pôles Nord ou Sud (90 degrés ou -90 degrés). Si une telle ancre est spécifiée, ArEarth_resolveAnchorOnTerrainAsync() renvoie une AR_ERROR_INVALID_ARGUMENT, et l'ancre ne peut pas être créée.

Consultez l'état de l'avenir

"Future" sera associé à un ArFutureState.

État	Description
AR_FUTURE_STATE_PENDING	L'opération est toujours en attente.
AR_FUTURE_STATE_DONE	L'opération est terminée et le résultat est disponible.
AR_FUTURE_STATE_CANCELLED	L'opération a été annulée.

Vérifier l'état d'ancrage du relief pour le résultat futur

ArTerrainAnchorState appartient à l'opération asynchrone et fait partie du résultat Future final.

switch (terrain_anchor_state) {
  case AR_TERRAIN_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

Fixations de toit

Les ancrages de toit sont un type d'ancrage et sont très semblables aux ancrages de relief ci-dessus. La différence est que vous indiquez l'altitude au-dessus du toit plutôt que l'altitude au-dessus du relief.

Remarque :Les informations sur les toits de certains établissements sont plus précises que d'autres. Pour en savoir plus, consultez la section sur la qualité dans Streetscape Geometry.

Créer une ancre sur le toit à l'aide de la nouvelle API Async

L'ancre ne sera pas prête immédiatement et doit être résolue.

Pour créer et positionner une ancre de toiture, appelez ArEarth_resolveAnchorOnRooftopAsync(). Comme pour les ancres de relief, vous accédez également au ArFutureState du futur. Vous pouvez ensuite vérifier le résultat "Future" pour accéder à ArRooftopAnchorState.

Utilisez ArEarth_resolveAnchorOnRooftopAsync() pour créer un ArResolveAnchorOnRooftopFuture.

Vérifiez l'état de l'ancrage de toit à l'aide de ArResolveAnchorOnRooftopFuture_getResultRooftopAnchorState().

Obtenez l'ancre résolue à l'aide de ArResolveAnchorOnRooftopFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnRooftopCallback callback = NULL;
ArResolveAnchorOnRooftopFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnRooftopAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_rooftop, eus_quaternion_4,
        context, callback, &future);
  }
}

Consultez l'état de l'avenir

Un ArFutureState est associé à "Future", comme dans le tableau ci-dessus.

Vérifier l'état de l'ancrage du toit pour le résultat futur

ArRooftopAnchorState appartient à l'opération asynchrone et fait partie du résultat Future final.

switch (rooftop_anchor_state) {
  case AR_ROOFTOP_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

Étapes suivantes

• Assurez-vous de bien comprendre le quota d'utilisation de l'API Geospatial.