Astuces DotNet (Sébastien Courtois)

08/04/2009

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

Filed under: Débutant, Virtual Earth — Étiquettes : , , , , , , — sebastiencourtois @ 16:00

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 : GetMap

  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 :

tilesystem

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  

h0331

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

12/03/2009

[Virtual Earth] Développement Microsoft Virtual Earth Web Services – Part 1

Filed under: .NET, Débutant, Virtual Earth — Étiquettes : , , , , , , , — sebastiencourtois @ 18:57

Au travers de mes stages et autres projets personnels, j’ai été amené à travailler avec des outils cartographiques divers (de Microsoft MapPoint à GoogleMap en passant par d’autres éditeurs dont je ne citerai pas le nom). Travaillant aujourd’hui majoritairement en environnement .NET, j’ai décidé de me pencher sur l’offre cartographique de Microsoft : Microsoft Virtual Earth.

Liens des posts sur 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)

Microsoft Virtual Earth ?

Virtual Earth est composé d’une série d’outils et de services Internet fournissant des informations cartographiques. Ces informations peuvent être de plusieurs types :

  • Images satellites
  • Du Géocoding : Traduire une adresse postale en coordonnées géographiques.
  • Géocoding Inverse : Traduire des coordonnées géographiques en adresse postale.
  • Moteur de recherche : A partir de données diverses, on récupère un ou plusieurs localisations (avec un degré de précision/confiance).
  • Calcul d’itinéraire : A partir de deux adresses/localisations, on récupère l’ensemble du chemin à effectuer en voiture (orientation lors des croisements, distance entre chaque croisement…).

Microsoft Virtual Earth : Comment ça marche ?

A l’inverse de Microsoft MapPoint où les données devait être stockés sur le poste client (ou sur des postes serveurs proche du client), les données de Virtual Earth sont stockées sur les datacenter Microsoft à travers le monde et l’utilisateur ne demande que les données qu’il souhaite visualiser.

Ces données ne sont pas accessible directement depuis les datacenters. Il faut passer par une couche de services Web pour y accéder. Il existe deux façons de faire :

  • Utilisation d’un contrôle ASP.NET Ajax fourni avec le SDK de Virtual Earth (démonstration : http://maps.live.com/)
  • Utilisation du Web Service Virtual Earth (SOAP over HTTP)

Blog6-1

Nous ne parlerons pas du contrôle ASP.NET dans ce tutorial. Vous pourrez trouver les informations voulues pour le développement avec ce type de contrôle à l’adresse suivante : http://dev.live.com/Virtualearth/sdk/

Microsoft Virtual Earth Web Service

Virtual Earth est composé de 5 Web Services :

  • Common (asmx) : Web Service contenant l’ensemble des données communes à tous les services Virtual Earth ainsi que les fonctions d’authentification et de sécurité.
  • Geocode Service (WCF) : Web Service de Géocoding/Géocoding Inverse.
  • Route Service (WCF) : Web Service de calcul d’itinéraire.
  • Imagery Service (WCF) : Web Service de récupération des images.
  • Search Service (WCF) : Web Service du moteur de recherche.

Microsoft Virtual Earth Web Service : Authentification

L’authentification à Virtual Earth se réalise en deux étapes :

  1. Le client fournit un couple login/password au Web Service Common.
  2. Si les informations sont correctes, le Web Service renvoie un token d’authentification sous la forme d’une longue chaine de caractères.

Les appels suivants à l’ensemble des Web Services  Virtual Earth se fera toujours en fournissant ce token.

Dans ce tutorial, nous allons voir comment récupérer un token d’authentification puis faire un appel à une fonction de Geocoding.

  • Récupération Login/Password sur la plateforme développeur Virtual Earth

Avant toute chose, il faut récupérer un couple login/password auprès de Microsoft. Pour cela, il faut une Windows Live ID (https://login.live.com).

Il faut ensuite se connecter sur la plateforme développeur Virtual Earth (https://mappoint-css.live.com/mwssignup) pour demander un compte “free evaluation developer account”. Ce type de compte est gratuit et comporte certaines limitations comme des images contenant des messages “Staging" au milieu des images satellites et une déconnexion automatique en cas d’un nombre trop important de requêtes (j’ai été très peu déconnecté pour ce motif en utilisant les services).

Une fois inscrit, aller dans “Manage account” pour récupérer votre “Account ID”  (i.e login) et pour définir votre mot de passe.

  • Configuration de la solution Visual Studio

Créer une nouvelle solution (selon le type de projet que vous souhaitez faire).

Nous allons ajouter une référence Web vers le Web Service Common. Cliquer droit sur le projet puis aller dans “Add Service Reference”. Au sein de cette fenêtre, cliquer sur “Advanced” en bas à gauche puis sur “Add Web Reference”. Indiquer dans URL l’adresse : https://staging.common.virtualearth.net/find-30/common.asmx?wsdl. Il est possible qu’une popup vous demande vos informations de login/password. Une fois validé, indiquer un nom pour la Web Reference (TokenService dans notre exemple) puis cliquer sur “Add Reference”. Il est à noter que cette opération est longue car le Web Service Common est un service asmx (ancienne génération).

Pour chacun des autres Web Service WCF, il suffit de faire “Add Service Reference” puis d’indiquer une des quatre adresses suivantes puis cliquer sur “GO” puis donner un nom de namespace (le nom des services dans la liste suivante est un convention de ma part) puis cliquer sur “Add Reference”:

Ne pas oublier d’inclure les lignes suivantes au début du code :

using VETutorial.TokenService;
using System.Net;

//Récupération de l'adresse locale
string ipadr = "127.0.0.1";
var host = Dns.GetHostEntry(Dns.GetHostName());
foreach (IPAddress ip in host.AddressList)
{
	if (ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork ||
	    ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetworkV6)
	{
		ipadr = ip.ToString();
	}
}
//Création du proxy d'accès au CommonService
CommonService common = new VETutorial.TokenService.CommonService();
common.Credentials = new NetworkCredential("AccountID", "password");
TokenSpecification tokenSpec = new TokenSpecification();
//Adresse IP de la machine du client
tokenSpec.ClientIPAddress = ipadr;
//Durée de validité du token (entre 15 et 480 minutes)
tokenSpec.TokenValidityDurationMinutes = 20;  

//Appel au Web Service Common pour récupération du token
string token = common.GetClientToken(tokenSpec);

On commence par récupérer l’adresse IP locale visible de l’extérieur. Cette adresse nous sera nécessaire pour la partie d’authentification (cette étape est inutile pour les applications Web).

On instancie ensuite la classe proxy CommonService puis on lui fournit le couple login/password récupéré sur la plateforme développeur. Cela se fait grâce à la propriété Credential de CommonService. On crée un NetworkCredential auquel on passe les informations nécessaires et on attribut ce NetworkCredential à la propriété Credential de CommonService.

La récupération d’un token se réalise grâce à la méthode GetClientToken (existe en version synchrone et asynchrone) à laquelle on passe un objet TokenSpecification.

Le TokenSpécification contient :

  • Propriété TokenValidityDurationMinutes: Le temps de validité du token en minutes (entre 15 et 480 minutes)
  • Propriété ClientIPAddress : L’adresse IP du client (inutile pour une application Web).

GetClientToken renvoie une chaine de caractères contenant le token.

  • Appel à une méthode Géocoding

Afin de vérifier que tout est bien configurer, on va demander les coordonnées géographiques de la ville de Paris.

GeocodeServiceClient geoCodeSvc = new GeocodeServiceClient();
GeocodeRequest geoCodeRequest = new GeocodeRequest();
geoCodeRequest.Credentials = new Credentials();
geoCodeRequest.Credentials.Token = token;
geoCodeRequest.Query = "Paris";
var result = geoCodeSvc.Geocode(geoCodeRequest);

On instancie un proxy pour GeocodeService. On crée un objet GeocodeServiceClient contenant une méthode GeoCode qui prend un paramètre un GeocodeRequest contenant les informations nécessaires à la requête. En général, les paramètres de requêtes des Web Services Virtual Earth demandent le token d’authentification dans la propriété Credential.Token. Afin de faire la recherche la plus simple possible, on fournit une chaine de caractères contenant “Paris” à la propriété Query. (nous reviendrons sur les requêtes plus complexe de Géocoding dans un autre post).

On obtient un GeoCodeResponse en retour qui nous fournit un certain nombre d’informations dont la localisation exacte de la ville de Paris.

Dans un prochain post, nous verrons plus en détail le Géocoding (et Géocoding Inverse) ainsi que les requêtes basiques au Web Service d’imagerie satellite.

Propulsé par WordPress.com.

%d blogueurs aiment cette page :