Utiliser des ancrages Geospatial pour positionner du contenu réel sur le SDK Android (Kotlin/Java)

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.

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 GeospatialPose. 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

Earth.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

Earth.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.

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

GeospatialPose.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 GeospatialPose. 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 GeospatialPose 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 Earth.createAnchor(). pour ancrer du contenu à des coordonnées géographiques que vous spécifiez.

if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  Anchor anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw);

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

if (earth.trackingState == TrackingState.TRACKING) {
  val anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw
    )

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

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 Config.PlaneFindingMode 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 Earth.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 ResolveAnchorOnTerrainFuture.

final ResolveAnchorOnTerrainFuture future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    /* altitudeAboveTerrain= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

var future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    altitudeAboveTerrain,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

Vérifier l'état de l'avenir

Les objets "Future" sont associés à un élément FutureState.

Vérifier l'état d'ancrage du relief du résultat Future

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

switch (terrainAnchorState) {
  case SUCCESS:
    // A resolving task for this Terrain anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

when (state) {
  TerrainAnchorState.SUCCESS -> {
    // A resolving task for this Terrain anchor has finished successfully.
  }
  TerrainAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  TerrainAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  TerrainAnchorState.ERROR_INTERNAL -> {
    // The Terrain anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

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.

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 Earth.resolveAnchorOnRooftopAsync(). Comme pour les ancres de relief, vous accéderez également aux FutureState de demain. Vous pouvez ensuite consulter le résultat "Future" pour accéder à Anchor.RooftopAnchorState.

final ResolveAnchorOnRooftopFuture future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    /* altitudeAboveRooftop= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

var future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    altitudeAboveRooftop,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

Vérifier l'état de l'avenir

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

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

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

switch (rooftopAnchorState) {
  case SUCCESS:
    // A resolving task for this Rooftop anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API.
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

when (state) {
  RooftopAnchorState.SUCCESS -> {
    // A resolving task for this Rooftop anchor has finished successfully.
  }
  RooftopAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  RooftopAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  RooftopAnchorState.ERROR_INTERNAL -> {
    // The Rooftop anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

Étape suivante

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