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.

Publicités

07/04/2009

[Virtual Earth] Développement Microsoft Virtual Earth Web Services – Part 2 : Géocoding Service

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

Cet article est une suite de l’article se trouvant ici. Il était question de créer un compte Virtual Earth et se connecter en C# aux différents services Web de Virtual Earth.

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)

L’article courant va parler de l’utilisation de un de ces services : Le Géocoding/Géocoding inverse.

Géocoding

Comme expliqué dans l’article précédent, le Géocoding est le processus permettant de retrouver des coordonnées géographiques d’un lieu à partir d’informations sur celui-ci (nom,adresse postale…). Un service de Virtual Earth est entièrement dédié à cette tache : Le GeocodeService.

Afin d’accéder aux informations de ce service, il faut d’abord générer la classe proxy permettant de communiquer avec ce service. Ce service étant un service WCF, il suffit d’ajouter la référence de service suivante (“Add Service Reference”) à votre projet : http://staging.dev.virtualearth.net/webservices/v1/geocodeservice/geocodeservice.svc (nous travaillons toujours dans l’environnement de test).

Un fois la référence rajoutée, vous devriez avoir accès aux classes suivantes :

  • GeocodeServiceClient : Classe proxy principale gérant la connexion avec le service
  • GeocodeRequest : Classe permettant de fournir les données pour une requête de Géocoding
  • GeocodeResponse : Classe contenant les informations renvoyés par le service suite à un requête de Géocoding ou de Géocoding inverse.
  • ReverseGeocodeRequest : Classe permettant de fournir les données pour une requête de Géocoding inverse.

Fonctionnement générale d’une requête de Géocoding

Avant de commencer, il est nécessaire d’avoir un token d’authentification valide (voir le tutorial précédent). Ensuite, on utilise le code suivant :

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

On crée le proxy vers le service de Géocoding en utilisant le constructeur par défaut. On crée ensuite une requête de Géocoding. On lui fournit les données d’authentification au travers de la propriété Credentials de la requête. On remplit la donnée token afin de prouver notre identité au serveur Virtual Earth. On remplit ensuite les données qui seront utilisées pour la requête (on utilise ici la propriété Query par simplicité, mais nous verrons plus loin qu’il y a beaucoup plus de possibilités). La requête proprement dite se réalise par la méthode Geocode de la classe proxy GeocodeServiceClient en lui fournissant les données de la requête. On récupère le résultat dans une classe GeocodeResponse.

Découverte de la classe GeocodeRequest

Pierre angulaire du système de Géocoding, la classe GeocodeRequest regroupe de nombreuses propriétés permettant d’affiner sa recherche géographique au maximum.

  • Query

La propriété la plus simple est la propriété Query. Cette propriété est une chaine de caractères dans laquelle il est possible de rentrer plusieurs mot clés (nom de pays,ville …). Cette propriété sera ensuite comparé par Virtual Earth avec la base de données d’entités géographiques afin de renvoyer les résultats les plus pertinents.

  • Options

Il est possible de restreindre ces résultats grâce à la propriété Options. Cette propriété possède une propriété Count permettant de définir le nombre maximal de réponses (5 par défaut). Il est aussi possible de définir des filtres (propriété Filters). Ces filtres permettent de supprimer des réponses en fonction de critères supplémentaires. Ces filtres/critères sont disponible au travers de classes spécialement conçues à cette effet. Ainsi si l’on souhaite n’avoir que les résultats avec une note de confiance forte, on utilisera le code suivant :

GeocodeService.ConfidenceFilter[] filters = new GeocodeService.ConfidenceFilter[1]; 
filters[0] = new GeocodeService.ConfidenceFilter(); 
filters[0].MinimumConfidence = GeocodeService.Confidence.High; 
GeocodeService.GeocodeOptions geocodeOptions = new GeocodeService.GeocodeOptions(); 
geocodeOptions.Filters = filters; 

Le dernier paramètre, ExtensionData, de la propriété Options est lié à WCF et ne concerne pas ce tutorial.

  • Culture : Cette propriété permet de définir la langue dans laquelle vous souhaitez que les informations soient retournées. Par défaut, c’est l’anglais (‘en-US’).
  • ExecutionOptions : Cette propriété n’a qu’un booléen suppressFault. Par défaut à false, cette variable indique si vous souhaitez récupérer les erreurs Virtual Earth (false = je souhaite récupérer les erreurs).
  • UserProfile : Cette propriété permet de définir des informations sur l’utilisateur courant. On peut ainsi donner les informations concernant sa position, son déplacement, s’il est sur un appareil mobile … Cela permet au serveur de choisir les informations à retourner afin qu’elle soit le plus proche possible de ce que souhaite l’utilisateur.
  • Address

Après Query, c’est la propriété la plus important de GeocodeRequest. Cette propriété permet de rentrer les informations pour trouver les coordonnées d’une adresse postale en fonction de critères tel que la rue, la ville, le pays, le code postal. Les informations peuvent être incomplètes (fournir le code postal uniquement avec l’adresse suffit à localiser le lieu par exemple). Un tableau sur le site MSDN décrit les données minimales à fournir pour avoir une localisation précise : http://msdn.microsoft.com/en-us/library/cc966788.aspx.

Attention : Au sein d’une requête GeocodeRequest, il faut remplir, au minimum, le champ Query ou le champ Address afin d’obtenir une réponse de la part du serveur. Les autres champs sont optionnels

Afin de tester tout cela, nous allons prendre l’exemple de l’emplacement du siège de ma société Winwise (Winwise – 16 rue Gaillon,75002 PARIS). Je souhaite un seul résultat et je veux qu’il soit “sûr à 100 %”. On écrit donc le code suivant :

GeocodeServiceClient geoCodeSvc = new GeocodeServiceClient();
GeocodeRequest geoCodeRequest = new GeocodeRequest();

geoCodeRequest.Credentials = new VETutorial.GeoCodeService.Credentials();
geoCodeRequest.Credentials.Token = token;
	
ConfidenceFilter[] filters = new ConfidenceFilter[1] { new ConfidenceFilter() { MinimumConfidence = VETutorial.GeoCodeService.Confidence.High } };
geoCodeRequest.Options = new GeocodeOptions() { Count = 1, Filters = filters};

geoCodeRequest.Address = new Address()
{
	AddressLine = "16 rue Gaillon",
	PostalCode = "75002",
	PostalTown = "Paris",
};

GeocodeResponse result = geoCodeSvc.Geocode(geoCodeRequest);

J’obtiens le résultat suivant : Longitude : 2.334231 Latitude : 48.868681 ce qui correspond bien à l’emplacement de notre société comme le montre cette image ci-dessous prise avec le service d’imagerie de Virtual Earth (sujet d’un prochain tutorial).

winwise

Analyse  de la classe GeocodeResponse

Nous allons maintenant apprendre à traiter la réponse de Virtual Earth suite à une requête de Géocoding. Cette réponse possède deux propriétés : ResponseSummary et Results.

  • ResponseSummary

Cette propriété regroupe les informations sur le déroulement de la requête. On retrouve les informations sur les droits (propriété Copyright), l’identifiant de la requête (propriété TraceId), le statut de la requête (propriété StatusCode) indiquant s’il y a eu une erreur durant la requête. Si c’est le cas, la propriété FaultReason donne l’erreur lancée du coté Virtual Earth. Enfin la propriété AuthentificationResultCode indique si les informations concernant l’authentification sont valide.

  • Results

C’est dans cette propriété que l’on retrouve les résultats de la requête proprement dite. Il s’agit d’un tableau de GeocodeResult où chacune des cases représente une réponse possible. La taille du tableau peut varier de 0 jusqu’au nombre fourni dans la propriété Count des options de la requête.

Chacun des GeocodeResult contient les informations suivantes :

    • L’adresse du point dans la propriété Address.
    • Les deux points géographiques (haut gauche et bas droit) permettant d’avoir la meilleure vue de ce que l’on souhaite voir (Propriété BestView)
    • Le niveau de confiance du résultat (Propriété Confidence)
    • Un représentation en chaine de caractères de la confiance du résultat (Propriété MatchCode)
    • Un nom pour le résultat (propriété DisplayName)
    • Le type d’entité ciblé par le résultat sous forme d’une chaine de caractère (propriété EntityType)
    • Des positions géographiques possibles pour le résultat (propriété Locations). Cette propriété contient aussi le type de calcul de calcul a été utilisé (généralement “Interpolation”).

Parlons un peu du géocoding inverse : ReverseGeocodeRequest

Bien que beaucoup moins utilisé que le Géocoding classique, le Géocoding inverse est le processus permettant de retrouver une adresse depuis des coordonnées géographiques. Pour cela, on utilise la classe ReverseGeocodeRequest. Celle ci contient les mêmes champs que GeocodeRequest décrit précédemment sauf Query et Address (ce qui est normal vu que ce n’est pas l’objet de la requête). En revanche, on remarque l’apparition d’une propriété Location sur laquelle on peut indiquer la latitude, longitude, altitude désiré.

ReverseGeocodeRequest rgr = new ReverseGeocodeRequest();
rgr.Credentials = new VETutorial.GeoCodeService.Credentials();
rgr.Credentials.Token = token;
	
rgr.Location = new VETutorial.GeoCodeService.Location() { Longitude = 2.334231, Latitude = 48.868681 };

GeocodeResponse result2 = geoCodeSvc.ReverseGeocode(rgr);

Le résultat de la requête est, comme pour le Géocoding, un GeocodeResponse.

La suite au prochain épisode …

Dans le prochain article, nous parlerons de la récupération de cartes (images) au travers du ImageryService. Un autre article est prévu sur le calcul d’itinéraire entre N points.

N’hésitez pas à me faire des commentaires sur ces articles (bons ou mauvais je m’en fiche du moment que c’est constructif et que ça me permet de faire des articles meilleurs à l’avenir).

Créez un site Web ou un blog gratuitement sur WordPress.com.

%d blogueurs aiment cette page :