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 dépôt ApiDemos sur GitHub inclut un exemple qui présente les superpositions au sol :

• GroundOverlayDemoActivity (Java) : fonctionnalités et écouteurs des superpositions au sol en Java
• GroundOverlayDemoActivity (Kotlin) : fonctionnalités et écouteurs des superpositions au sol en Kotlin

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 fixer une seule image sur une zone de la carte. Pour ajouter de nombreuses images afin de couvrir une grande zone de la carte, nous vous conseillons d'utiliser des 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 pouvez aussi spécifier 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() affiche 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. Si vous le souhaitez, définissez des propriétés facultatives, comme transparency.
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.

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

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

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 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.

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

      

// 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()

      

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

// Update the GroundOverlay with a new image of the same dimension

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

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

Positionner une superposition au sol

Pour indiquer la position d'une superposition au sol, vous avez le choix entre deux méthodes :

• Utilisez LatLng pour centrer la superposition et des dimensions exprimées en mètres pour spécifier la taille de l'image.
• Utilisez 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 le faites pas, 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.

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

      

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.

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

      

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 :

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.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 :

• Si votre application prend en charge différents types de superpositions au sol, vous pouvez les traiter différemment lorsque l'utilisateur clique dessus.
• Vous interagissez peut-être 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).