[Virtual Earth] Développement Microsoft Virtual Earth Web Services – Part 3 : Imagery Service

Liens des posts sur le sujet sur ce blog :

1. Introduction à Microsoft Virtual Earth (Part 1)
2. Géocoding / Géocoding Inverse (Part 2)
3. Récupération des images satellites (Part 3)
4. Calcul d’itinéraires (Part 4)

Dans ce post, nous allons parler la partie la plus intéressante de Virtual Earth : La récupération des images satellites.

Tout d’abord, il est nécessaire d’ajouter une référence vers le service d’imagerie de Virtual Earth : http://staging.dev.virtualearth.net/webservices/v1/imageryservice/imageryservice.svc. On instancie ensuite une classe proxy nommée ImageryServiceClient afin d’avoir accès au service.

ImageryServiceClient imagerySvc = new ImageryServiceClient();

On peut utiliser ce service pour récupérer les images de deux manières : Récupération des images à la demande et Récupération des images à la volée (Tiles).

• Récupération des images à la demande : MapUriRequest

Il est possible de récupérer des images satellites en fournissant des coordonnées géographiques puis de spécifier des informations supplémentaires pour avoir l’image souhaitée.

On utilise pour cela la classe MapUriRequest que l’on va fournir en paramètre de la méthode GetMapUri de la classe ImageryServiceClient.

Cette classe MapUriRequest est composée des propriétés spécifiques suivantes : (je ne mets que les propriétés spécifiques aux requêtes MapUri. Pour les autres paramètres, voir les posts précédents).

Nom de la propriété	Description
Center	Coordonnées géographiques du point central de l’image (classe Location avec des propriétés Latitude/Longitude/Altitude)
MajorRoutesDestination	Paramètre ne fonctionnant pas chez moi et dont je ne comprends pas l’intérêt. Voir la documentation MSDN.
Options	Options de paramétrage de l’image sous la forme d’une classe MapUriOptions. Cette classe est décrite par la suite.
Pushpins	Ajout de puce pour indiquer les emplacements importants. Il s’agit d’un tableau de Pushpin. Il est possible de définir, pour chaque puce, sa position, son nom ainsi que l’icône à utiliser parmi une liste prédéfini par Microsoft (Liste des icones disponible par défaut). Le nombre maximum d’icones est de 10 par image.

• MapUriOptions

La classe MapUriOptions permet de définir un certain nombre de paramètres sur l’image que l’on souhaite obtenir.

Nom de la propriété	Description
DisplayLayers	Il est possible de superposer sur l’image des calques d’informations. Pour cela, il suffit de fournir une chaine de caractères contenant la liste des calques disponibles.
ImageSize	Taille de l’image souhaitée (valeurs entre 80 et 830 pixels sur les deux dimensions)
ImageType	Format de l’image (GIF, JPEG, PNG). Par défaut, cela dépend du style de carte voulue. (voir la documentation MSDN)
PreventIconCollision	Valeur booléen pour indiquer si l’on souhaite que les icones (pushpins) se superposent lorsqu’ils sont proche.
Style	Type de carte parmi les suivantes : Route (Road), Aérien (Aerial), Aérien avec titre (AerialWithLabels). Les images de type  Birdseye et BirdseyeWithLabel ne sont pas disponible sur le Web Service.
UriScheme	Type d’URL : HTTP ou HTTPS
ZoomLevel	Niveau de zoom compris entre 1 et 21. (1 étant le plus éloigné et 21 étant le plus proche de la cible).

• Un exemple d’utilisation

N.B : Les variables positions et token sont reprises des exemples précédents.

MapUriRequest mapUriRequest = new MapUriRequest();
mapUriRequest.Credentials = new VETutorial.ImageryService.Credentials();
mapUriRequest.Credentials.Token = token;

mapUriRequest.Center  = new VETutorial.ImageryService.Location() { Latitude = position.Latitude, Longitude = position.Longitude };
mapUriRequest.Options = new MapUriOptions() 
{
	ImageSize = new VETutorial.ImageryService.SizeOfint() {  Width=800, Height = 600},
	ImageType = ImageType.Jpeg,
	Style = MapStyle.AerialWithLabels,
	UriScheme = UriScheme.Https,
	ZoomLevel = 18
};
mapUriRequest.Pushpins = new Pushpin[] { new Pushpin() { Location = new VETutorial.ImageryService.Location() { Latitude = position.Latitude, Longitude = position.Longitude } } };

MapUriResponse reponseMapUrl = imagerySvc.GetMapUri(mapUriRequest);
string finalUrl = reponseMapUrl.Uri.Replace("{token}",token);

L’exemple ci-dessus, crée une requête MapUri et lui indique le token d’authentification à utiliser (ne pas oublier cette étape). On définit ensuite les différents paramètres comme la position centrale, taille et format de l’image et niveau de zoom. Après l’appel de la méthode GetMapUri, on obtient un objet MapUriResponse contenant une propriété Uri contenant un modèle d’URL pour récupérer l’image. Ce modèle permet de construire soit même l’url pour récupérer l’image.

Dans mon cas, je reçois l’url suivant : https://staging.tiles.virtualearth.net/api/GetMap.ashx?c=48.868681,2.334231&ppl=48.868681,2.334231&w=800&h=600&o=jpeg&b=h,mkt.en-US&z=18&token={token}

Sans rentrer dans les détails des différentes paramètres contenues dans cette url, nous nous intéresserons sur le dernier paramètre : &token={token}. Au sein des services Virtual Earth, le modèle URL contiennent des zones “à remplacer” toujours représenté par des {}. Dans ce cas précis, il faut remplacer le {token} par la valeur de notre token. La façon la plus simple pour remplacer ces zones est d’utiliser la méthode Replace de la classe String. On arrive finalement à une adresse finale qui pourra être utilisé dans un navigateur, WebClient ou autres pour récupérer l’image.

L’image obtenue est la suivante :

  Un des trucs sympas est que l’on peut mettre cet adresse sur la propriété Source des contrôles d’images (Winforms,ASP.NET …) et l’image est téléchargée directement et affichée.

• Récupération des images à la volée (Tiles)

Demander à Virtual Earth de générer une image pour nous est pratique. Toutefois, il y a un certain cout en termes de performance qui fait que cela n’est utilisable que pour afficher des images ponctuellement. Un déplacement fluide sur une carte avec l’API MapURI n’est pas envisageable. C’est pourquoi Virtual Earth fournit une autre façon de récupérer des images : Le Tile System.

• Qu’est ce que le Tile System ?

Un Tile est une image d’une taille fixe représentant une partie d’une image plus grande. Dans le cas de la cartographie, ces images représentent un morceau du monde et, une fois l’ensemble de ces Tiles assemblés, on obtient une image du monde. Au sein de Virtual Earth, ces Tiles font 256×256 pixels. Le nombre de Tiles représentant le monde dépend du zoom. Au zoom le plus haut, on a 4 Tiles. Au zoom suivant on a 16 Tiles et ainsi de suite. Chaque Tile est numéroté en fonction de son emplacement et son zoom. Ce concept est décrit par le schéma suivant :

Afin d’obtenir chacune des images, il est nécessaire de construire l’url vers l’image. On obtient l’url d’un Tile de la façon suivante :

https://staging.tiles.virtualearth.net/tiles/{type}{code}.jpeg?g={version}&mkt={culture}&token={token}

Nom	Description
{type}	Type de carte représenté par un caractère : h pour Hybrid (Aérien avec textes), a pour Aerial (Aérien), r pour Road (Carte routière)
{code}	Identifiant du tile comme décrit dans le schéma ci-dessus
{version}	Numéro de version de Virtual Earth (275 au moment de l’écriture de ce tutorial)
{culture}	Culture à utiliser dans l’affichage du texte (‘en-US’, ‘fr-FR’ …)
{token}	Token d’authentification

Exemple : https://staging.tiles.virtualearth.net/tiles/h0331.jpeg?g=275&mkt=fr-FR&token=12345  

• Informations sur les Tiles

Il est possible d’avoir des informations d’un Tile en fonction de son emplacement (coordonnées géographiques). Pour cela, on utilise la classe ImageryMetadataRequest. Cette classe contient les  mêmes propriétés que la classe MapUriRequest décrit plus haut. La seule différence se trouve dans la propriété Options qui est une classe ImageryMetadataOptions. Elle contient les propriétés suivantes :

Nom de la propriété	Description
Heading	Orientation de la carte ( 0° = Nord en haut)
Location	Centre de la carte (coordonnées géographiques)
ReturnImageryProviders	Booléen indiquant si l’on souhaite récupérer les données sur les fournisseurs des cartes (copyrights …)
UriScheme	Type d’URL : HTTP ou HTTPS
ZoomLevel	Niveau de zoom

ImageryMetadataRequest metadataRequest = new ImageryMetadataRequest();
metadataRequest.Credentials = new VETutorial.ImageryService.Credentials();
metadataRequest.Credentials.Token = token;

metadataRequest.Style = MapStyle.AerialWithLabels;
metadataRequest.Options = new ImageryMetadataOptions() 
{
	Heading = new VETutorial.ImageryService.Heading() { Orientation = 0 } ,
	Location = new VETutorial.ImageryService.Location() { Latitude = position.Latitude, Longitude = position.Longitude },  
	ZoomLevel = 8,		 
	ReturnImageryProviders = true,	
	UriScheme = UriScheme.Https   
};

ImageryMetadataResponse resultImageMetadata = imagerySvc.GetImageryMetadata(metadataRequest);

En réponse de la méthode GetImageryMetadata, on récupère une classe  ImageryMetadataResponse  contenant une propriété Result étant représenté par un tableau de ImageryMetadataResult celui-ci contient les informations suivantes :

Nom de la propriété	Description
ImageryProvider	Liste des fournisseurs de données
ImageSize	Taille de l’image (normalement 256×256 pixels)
ImageUri	Schéma de l’URL pour récupérer l’image (voir plus loin dans ce post)
ImageUriSubDomains	Liste des sous domaines disponible pour cette image
Vintage	Date de validité des images
ZoomRange	Zoom lié à l’image

L’une des informations importantes de cette structure de données est ImageUri. Il est nécessaire de la modifier comme décrit ci-dessus. Ainsi, dans mon exemple, on obtient : https://t1.staging.tiles.virtualearth.net/tiles/h12022001.jpeg?g=275&mkt={culture}&token={token}. Il suffit de remplacer {culture} et {token} pour avoir accès à l’image centrée sur la propriété Location définie dans la requête.

Ainsi se conclut la description du service d’imagerie de Virtual Earth. Comme certains d’entre vous l’auront remarqué, il manque de nombreuses fonctionnalités comme le BirdEye ou la 3D. Cela est du au fait que les services Web Virtual Earth ne sont pas aussi complète que le contrôle ASP.NET. Ces fonctionnalités arriveront par la suite.

Dans les prochains posts nous parlerons du service de calcul d’itinéraire ainsi que du moteur de recherche d’entités (magasins, écoles, points d’intérêt …) de Virtual Earth. Je vais aussi faire une démo intégrant l’ensemble des services décrit afin de montrer les possibilités de Virtual Earth de façon plus parlante. Cette démo sera surement en WPF ou en Silverlight (selon mes envies du moment).

N’hésitez pas à me faire des retours sur ces posts. Si vous avez des idées de sujets à traiter pour ce blog, merci de les indiquer dans les commentaires ci-dessous.