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 placer du contenu 3D dans le monde réel.

Types d'ancres géospatiales

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

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

2. Ancres de relief:
   Les ancrages de relief vous permettent de placer du contenu en utilisant uniquement la latitude et la avec une hauteur par rapport au relief à cette position. L'altitude est déterminée par rapport au sol ou au sol, par VPS.

3. Ancres de toit:
   Les ancrages de toit vous permettent de placer du contenu en utilisant uniquement la latitude et la avec une hauteur par rapport au toit d'un bâtiment à cette position. L'altitude est déterminée par rapport à la partie supérieure d'un bâtiment, connue sous le nom par Streetscape Geometry. L'altitude du relief est utilisée par défaut lorsqu'il n'est pas placé sur un bâtiment.

	WGS84	Relief	Toit
Position horizontale	Latitude, Longitude	Latitude, Longitude	Latitude, Longitude
Position verticale	Altitude par rapport à WGS84	Par rapport au niveau du relief déterminé par Google Maps	Par rapport au niveau du toit déterminé par Google Maps
Le serveur doit être résolu ?	Non	Oui	Oui

Prérequis

Assurez-vous d'activer l'API Geospatial avant de continuer.

Placer des ancres géospatiales

Chaque type d'ancre dispose d'API dédiées pour la création. Pour en savoir plus, consultez la page 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 de test de positionnement. Utilisez la posture du test de positionnement et convertissez-la en ArGeospatialPose. Utilisez-le pour placer l'un des trois types de points d'ancrage décrits ci-dessous.

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

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

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

ArEarth_getPose() convertit une position horizontale, une altitude et une rotation quaternion spécifiées par Terre par rapport à une image de coordonnées est-en-sud en une posture RA par rapport aux coordonnées mondiales GL.

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

Chaque méthode de création d'une ancre comporte des compromis à prendre en compte:

• Lorsque vous utilisez la géométrie Streetscape, utiliser un test de positionnement pour associer du contenu à un bâtiment.
• Préférez les ancres de relief ou de toit aux ancres WGS84, car elles utilisent des 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 agrandir le monde avec des contenus 3D sans avoir à vous déplacer physiquement. Cela vous permet de positionner visuellement du contenu immersif en 3D à l'aide de Google Maps dans l'éditeur Unity. La latitude, la longitude, la rotation et l'altitude du contenu seront calculées automatiquement.
• Utiliser Google Maps
• Utilisez Google Earth. Notez que si vous utilisez Google Earth plutôt que Google Maps pour obtenir ces coordonnées, vous obtiendrez une marge d'erreur pouvant atteindre plusieurs mètres.
• Se rendre sur le site

Utiliser Google Maps

Pour obtenir la latitude et la longitude d'un établissement à l'aide de Google Maps, procédez comme suit:

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

   

2. Accédez à Calques > Plus.

   

   

3. Sélectionnez Satellite dans le champ Type de carte et décochez la case Vue Globe en bas à gauche de l'écran.

   

   Cela forcera l'affichage d'une perspective 2D et éliminera les erreurs possibles liées à une vue 3D inclinée.

4. Sur la carte, cliquez avec le bouton droit de la souris sur le lieu et sélectionnez la longitude et la latitude pour le copier dans le presse-papiers.

Utiliser Google Earth

Vous pouvez calculer la latitude et la longitude d'un lieu à partir de Google Earth en cliquant sur un lieu dans l'interface utilisateur et en lisant les données à partir des détails du repère.

Remarque :Si vous utilisez Google Earth plutôt que Google Maps, vous obtiendrez une marge d'erreur pouvant 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, procédez comme suit:

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

2. Accédez au menu hamburger , puis sélectionnez Style de carte.

   

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

   

4. Une fois l'option Bâtiments 3D désactivée, cliquez sur l'icône en forme de punaise pour ajouter un repère au lieu sélectionné.

5. Spécifiez un projet qui contiendra votre repère, puis cliquez sur Enregistrer.

6. Dans le champ Titre du repère, saisissez un nom pour le repère.

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

8. Sélectionnez Exporter en tant que fichier KML dans le menu.

   

Le fichier KLM indique la latitude, la longitude et l'altitude d'un repère dans la balise <coordinates> en les séparant par une virgule, 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 la position.

Se rendre sur le site

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 qui représente la matrice de rotation transformant un vecteur de la cible vers le système de coordonnées Est-Sud-Sud (EUS). Points X+ vers l'est, points Y+ vers le haut et points Z+ vers le sud. Les valeurs sont écrites dans l'ordre {x, y, z, w}.

Ancres WGS84

Une ancre WGS84 est un type d'ancrage 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é dans le monde réel. La position correspond à une latitude, une longitude et une altitude, qui sont spécifiées dans le système de coordonnées WGS84. L'orientation consiste en une rotation quaternion.

L'altitude est exprimée en mètres au-dessus de l'ellipsoïde de référence WGS84, de sorte que le niveau du sol ne soit 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 ancres:

• 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 l'évaluation GeoidEval, qui dispose à la fois d'une ligne de commande et d'une interface HTML. L'API Google Maps indique la latitude et la longitude conformément aux spécifications WGS84.
• Vous pouvez obtenir la latitude, la longitude et l'altitude d'un lieu à partir de Google Earth. La marge d'erreur sera ainsi de 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 est proche et si vous n'êtes pas sur une pente prononcée, vous pourrez peut-être utiliser l'altitude du ArGeospatialPose de la caméra sans utiliser une autre source, comme l'API Google Maps.

Créer l'ancre

Une fois que vous disposez du quaternion de latitude, de longitude, d'altitude et de rotation, utilisez ArEarth_acquireNewAnchor(). pour ancrer du contenu à des 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 :Créer des ancres à moins de 0,1 degré du pôle Nord ou du pôle Sud (90 degrés ou -90 degrés) n'est pas prise en charge. Si une telle ancre est spécifiée, le l'ancre ne sera pas créée.

Ancres de relief

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

Au lieu d'indiquer l'altitude souhaitée, vous indiquez l'altitude au-dessus du relief. Lorsque cette valeur est égale à zéro, l'ancre est au même niveau que le relief.

Définir le mode de recherche d'avion

La recherche d'avion est facultative et n'est pas obligatoire pour utiliser des ancres. Notez que seuls les plans horizontaux sont utilisés. Les plans horizontaux facilitent l'alignement dynamique des ancrages de relief au sol.

Utilisez ArPlaneFindingMode pour sélectionner la façon dont votre application détecte les avions.

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 n'est pas prête immédiatement et doit être résolue. Une fois le problème résolu, il sera disponible dans la ArResolveAnchorOnTerrainFuture.

Vérifiez l'état de l'ancrage du relief à l'aide de 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 :Créer des ancres à moins de 0,1 degré des pôles Nord ou Sud (90 degrés ou -90 degrés) n'est pas prise en charge. Si une telle ancre est spécifiée, ArEarth_resolveAnchorOnTerrainAsync() renvoie un AR_ERROR_INVALID_ARGUMENT et l'ancre ne peut pas être créée.

Vérifier l'état de l'avenir

Les objets "Future" sont associés à un élément 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 du résultat Future

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

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

Ancrages de toit

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

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

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

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

Pour créer et placer une ancre de toit, appelez ArEarth_resolveAnchorOnRooftopAsync(). Comme pour les ancres de relief, vous accéderez également aux ArFutureState de demain. Vous pouvez ensuite consulter le résultat "Future" pour accéder à ArRooftopAnchorState.

Utilisez ArEarth_resolveAnchorOnRooftopAsync() pour créer un ArResolveAnchorOnRooftopFuture.

Vérifiez l'état de l'ancrage du 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);
  }
}

Vérifier l'état de l'avenir

"Future" est associé à un élément ArFutureState (voir le tableau ci-dessus).

Vérifier l'état de l'ancre sur le toit du résultat Future

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

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

Étape suivante

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