C'est le 15e anniversaire de Google Maps Platform. Découvrez les dernières actualités et annonces.

Superpositions au sol

Les superpositions au sol sont des superpositions d'image qui sont liées aux coordonnées de latitude/longitude. Elles se déplacent donc lorsque vous faites glisser la carte ou effectuez un zoom.

Exemples de code

Le référentiel ApiDemos sur GitHub inclut un exemple qui illustre les superpositions au sol :

Introduction

Une superposition au sol est une image fixée sur une carte. Contrairement aux repères, les superpositions au sol sont orientées vers la surface de la Terre plutôt que vers l'écran. Par conséquent, si vous appliquez une rotation, une inclinaison ou un zoom sur la carte, l'orientation de l'image est modifiée. Les superpositions au sol sont utiles lorsque vous souhaitez corriger une seule image sur une zone de la carte. Si vous souhaitez ajouter un grand nombre d'images afin de couvrir une grande zone de la carte, nous vous conseillons de recourir aux superpositions de tuiles.

Ajouter une superposition

Pour ajouter une GroundOverlay, créez un objet GroundOverlayOptions qui définit à la fois une image et une position. Vous avez également la possibilité de définir des paramètres supplémentaires qui influent sur le positionnement de l'image sur la carte. Après avoir défini les options nécessaires, transmettez l'objet à la méthode GoogleMap.addGroundOverlay() afin d'ajouter l'image à la carte. La méthode addGroundOverlay() renvoie un objet GroundOverlay ; vous devez conserver une référence à cet objet si vous souhaitez le modifier ultérieurement.

Procédure détaillée :

  1. Instanciez un nouvel objet GroundOverlayOptions.
  2. Spécifiez l'image en tant que BitmapDescriptor.
  3. Définissez la position de l'image en utilisant l'une des méthodes disponibles :
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. Définissez des propriétés facultatives, telles que transparency, si vous le souhaitez.
  5. Appelez GoogleMap.addGroundOverlay() pour ajouter l'image à la carte.

L'exemple ci-dessous montre comment ajouter une superposition au sol à un objet GoogleMap existant.

LatLng NEWARK = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
        .position(NEWARK, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

Si vous souhaitez modifier ou supprimer une superposition au sol après l'avoir ajoutée à la carte, veillez à conserver l'objet GroundOverlay. Vous pourrez modifier la superposition ultérieurement en appliquant des changements à cet objet.

LatLng NEWARK = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
        .position(NEWARK, 8600f, 6500f);

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

Supprimer une superposition

Vous pouvez supprimer une superposition au sol à l'aide de la méthode GroundOverlay.remove().

imageOverlay.remove();

Modifier une superposition

Vous pouvez modifier l'image de superposition au sol après l'avoir ajoutée à la carte à l'aide de la méthode GroundOverlay.setImage(BitmapDescriptor).

// Add an overlay, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

La méthode setImage() remplace alors l'image existante par une autre image aux dimensions identiques.

Positionner une superposition au sol

Il y a deux façons d'indiquer la position d'une superposition au sol :

  • À l'aide d'un objet LatLng pour centrer la superposition et des dimensions exprimées en mètres pour spécifier la taille de l'image
  • À l'aide d'un objet LatLngBounds pour spécifier les angles nord-est et sud-ouest de l'image

Vous devez spécifier la position de la superposition au sol avant de l'ajouter à la carte.

Utiliser la localisation pour positionner une image

Lorsque vous ajoutez l'image, vous indiquez une valeur LatLng à laquelle l'ancre sera fixée, ainsi que la largeur de la superposition (en mètres). La valeur par défaut de anchor correspond au centre de l'image. Vous pouvez éventuellement fournir la hauteur de la superposition (en mètres). Si vous ne fournissez pas la hauteur de la superposition, elle sera automatiquement calculée pour conserver les proportions de l'image.

Le code ci-dessous place une image à la position 40.714086, -74.228697, mesurant 8,6 km de large par 6,5 km de haut. L'image est ancrée en bas à gauche.

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
        .anchor(0, 1)
        .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

Utiliser LatLngBounds pour positionner une image

Vous fournissez un objet LatLngBounds qui contient l'image. Le LatLngBounds définit les angles nord-est et sud-ouest de l'image. Lorsque l'image est dessinée sur la carte, elle fait l'objet d'une rotation pour respecter les limites. Si les limites ne correspondent pas au rapport hauteur-largeur d'origine, l'image est déformée.

Le code ci-dessous place une image sur la carte avec la limite de l'angle sud-ouest à 40.712216,-74.22655 et celle de l'angle nord-est à 40.773941, -74.12544.

LatLngBounds newarkBounds = new LatLngBounds(
        new LatLng(40.712216, -74.22655),       // South west corner
        new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
        .positionFromBounds(newarkBounds);

Associer des données à une superposition au sol

Vous pouvez appeler GroundOverlay.setTag() pour stocker un objet de données arbitraire avec une superposition au sol, puis récupérer l'objet de données en utilisant GroundOverlay.getTag().

L'exemple de code suivant stocke une description de chaîne avec une superposition au sol :

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

Voici des exemples de scénarios pour lesquels il peut s'avérer utile de stocker et de récupérer des données avec des superpositions au sol :

  • Votre application peut prendre en charge différents types de superpositions au sol et vous souhaitez les traiter différemment lorsque l'utilisateur clique dessus.
  • Vous pouvez être en interface avec un système qui présente des identifiants d'enregistrement uniques et dans lequel les superpositions représentent des enregistrements spécifiques.
  • Les données de superposition peuvent indiquer une priorité pour déterminer la propriété z-index de la superposition.

Gérer les événements liés aux superpositions au sol

Par défaut, les superpositions au sol ne sont pas cliquables. Vous pouvez activer et désactiver la cliquabilité en appelant GroundOverlay.setClickable(boolean).

Utilisez un écouteur OnGroundOverlayClickListener pour écouter les événements de clic sur une superposition au sol cliquable. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Lorsqu'un utilisateur clique sur une superposition au sol, vous recevez un rappel onGroundOverlayClick(GroundOverlay).