Client WMS

Author:Jeff McKenna
Contact:jmckenna at gatewaygeomatics.com
Last Updated:2016-02-26

Introduction

Un WMS (ou Web Map Service) autorise l’utilisation de données depuis de nombreux serveurs différents, et permet la création de réseaux de serveurs cartographiques depuis lesquels les clients peuvent personnaliser leurs cartes. Le document suivant contient des informations sur le type de connexion WMS MapServer pour inclure les couches depuis des serveurs WMS distants dans des applications MapServer.

MapServer supporte les version WMS suivantes quand il fonctionne en tant que client: 1.0.0, 1.0.7, 1.1.0, 1.1.1 (voir Support des spécifications OGC dans MapServer pour une liste à jour).

Ce document assume que vous êtes déjà familier avec certains aspects de MapServer :

  • Développement d’application MapServer et configuration des fichiers .map.

  • La familiarité avec la spécification WMS est un avantage. Un lien vers le document de spécification WMS est inclus ci-dessous.

Compilation / Installation

Le type de connexion WMS est activé par l’option –with-wmsclient lors de configure. Il nécessite PROJ4, GDAL et libcurl version 7.10.1 ou plus récent. Les utilisateurs Windows qui ne veulent pas compiler MapServer devrait utiliser MS4W (qui est fourni prêt pour les usages client et serveur WMS/WFS), ou vérifiez la disponibilité d’autres binaires Windows avec le support WMS.

  • Pour l’installation de PROJ4 et GDAL, voir le guide de compilation MapServer (Compiler sous Unix / Compiler sous Win32)

  • Pour libcurl, assurez-vous d’avoir la version 7.10.1 ou plus récente installée sur votre système. Vous pouvez trouver votre version de libcurl en utilisant curl-config –version. (si votre système vient avec une ancienne version de libcurl préinstallée alors vous DEVEZ le désinstaller avant d’installer la nouvelle version)

Une fois les bibliothèques requises installées, alors configurez MapServer en utilisant l’option –with-wmsclient (avec toutes les autres options que vous avez l’habitude d’utiliser) et recompilez. Cela vous donnera un nouveau jeu d’exécutables (et éventuellement php_mapscript.si vous l’avez demandé). Voir le guide de compilation MapServer (liens ci-dessus) pour les détails d’installation.

Vérifiez votre exécutable MapServer

Pour vérifier que votre exécutable mapserv inclut le support WMS, utilisez l’option de ligne de commande “-v” et confirmez la présence de “SUPPORTS=WMS_CLIENT”.

Exemple 1. Information de version de Mapserv sous Unix:

$ ./mapserv -v
MapServer version 7.0.1 OUTPUT=PNG OUTPUT=JPEG OUTPUT=KML SUPPORTS=PROJ
SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=CAIRO SUPPORTS=ICONV
SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER
SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI
SUPPORTS=THREADS SUPPORTS=GEOS INPUT=JPEG INPUT=POSTGIS INPUT=OGR
INPUT=GDAL INPUT=SHAPEFILE

Exemple 2. Information de version de Mapserv sous Windows:

C:\ms4w> setenv.bat

C:\ms4w> mapserv -v
MapServer version 7.0.1 (MS4W 3.1.3) OUTPUT=PNG OUTPUT=JPEG OUTPUT=KML
SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=CAIRO SUPPORTS=ICONV
SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER
SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI
SUPPORTS=THREADS SUPPORTS=GEOS INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL
INPUT=SHAPEFILE

Installation de codes de projection EPSG optionnels

(Note: l’installation des codes PROJ4 est optionnelle, installez-les seulement si vous en avez besoin)

Quelques serveurs WMS Canadiens utiliseront quelques codes de projection non standard non inclus dans la distribution par défaut (par exemple, EPSG:42304, etc.). Si vous prévoyez d’utiliser MapServer pour vous connecter à des serveurs WMS Canadiens alors vous aurez peut-être besoin de télécharger un fichier epsg Canadien personnalisé avec ces codes, et décompressez-le dans le répertoire /usr/local/share/proj (ou /ms4w/proj/nad/ pour les utilisateurs de MS4W users).

Enfin, les serveurs WMS ESRI viennent aussi avec leur propres séries de codes non-standard. Si vous prévoyez de vous connecter à des serveurs WMS ESRI alors vous aurez peut-être besoin d’un fichier epsg personnalisé qui contienne les codes Candiens et les codes ESRI, vous permettant de vous connecter à n’importe quel serveur. Téléchargez le fichier epsg ESRI personnalisé et décompressez-le dans /usr/local/share/proj (ou /ms4w/proj/nad/ pour les utilisateurs de MS4W users).

Q:

Mais pourquoi ne pas toujours installer et distribuer le fichier the proj4-epsg-with-42xxx-and-esri.zip alors qu’il est plus complet?

A:

Vous devez seulement installer les codes de projection epsg dont vous avez besoin, le fichier epsg avec tous les codes ESRI est environ 20% plus gros que celui par défaut, ainsi cela provoque une surcharge dont vous n’avez pas forcément besoin. Notez aussi quand vous créez les serveurs WMS, pour être vraiment interopérable, seulement les codes EPSG qui sont dans la liste EPSG standard devraient être utilisés. C’est une mauvaise idée pour l’interopérabilité d’utiliser les codes Canadiens personnalisés ou ceux d’ESRI et nous ne souhaitons pas trop promouvoir leur utilisation.

Configuration du MapFile

Note

Un bloc PROJECTION doit être défini dans le mapfile dans la partie MAP à moins que vous soyez sûr que toutes vos couches WMS supportent une seule projection qui soit la même que la PROJECTION de la carte. La PROJECTION de MAP peut être définie en utilisant le codes “init=epsg:xxxx” ou en utilisant des paramètres PROJ4 classiques. L’incapacité à définir une PROJECTION pour MAP peut causer un renvoi de cartes vides/blanches à partir de serveurs WMS distants (à cause de combinaisons inconsistantes entre BBOX et SRS utilisées dans une URL de connexion WMS).

Stocker les fichiers temporaires

Avant la version 6.0, et en version 6.0 quand la métadonnée wms_cache_to_disk est activée,vous devez définir la valeur de IMAGEPATH dans l’objet WEB de votre mapfile pour qu’il pointe vers un répertoire valide et supportant un fonctionnement en écriture. MapServer utilisera ce répertoire pour stocker les fichiers temporaires téléchargés depuis les serveurs distants. Les The fichiers temporaires sont automatiquement supprimés par MapServer et ainsi vous ne les remarquerez pas.

Exemple 3. Définir le paramètre IMAGEPATH dans un Mapfile

MAP
  ...
  WEB
    IMAGEPATH "/tmp/ms_tmp/"
    IMAGEURL ...
  END
  ...
END

MS4W Users Should Specify the Following for IMAGEPATH and IMAGEURL:

MAP
  ...
  WEB
    IMAGEPATH "/ms4w/tmp/ms_tmp/"
    IMAGEURL "/ms_tmp/"
  END
  ...
END

Si vous souhaitez garder ce fichier temporaire pour effectuer du debuggage, vous devez ajouter la déclaration suivante à l’objet LAYER de votre mapfile:

LAYER
  ....
  DEBUG ON
  ...
END

Ajout d’une couche WMS

Les couches WMS sont accédés via un type de connexion WMS dans le Mapfile. Voici un exemple de couche utilisant ce type de connexion:

LAYER
  NAME "country_bounds"
  TYPE RASTER
  STATUS ON
  CONNECTION "http://demo.mapserver.org/cgi-bin/wms?"
  CONNECTIONTYPE WMS
  METADATA
    "wms_srs"             "EPSG:4326"
    "wms_name"            "country_bounds"
    "wms_server_version"  "1.1.1"
    "wms_format"          "image/gif"
  END
END

You can also combine remote WMS layers from a server into one layer, separated by a comma (,) such as:

LAYER
  NAME "census_tracts"
  TYPE RASTER
  STATUS ON
  CONNECTION "http://tigerweb.geo.census.gov/arcgis/services/TIGERweb/tigerWMS_ACS2015/MapServer/WMSServer?"
  CONNECTIONTYPE WMS
  METADATA
      "wms_srs"             "EPSG:4326"
      "wms_name"            "Census Tracts,Census Tracts Labels"
      "wms_server_version"  "1.1.1"
      "wms_format"          "image/png24"
  END
END

Note

Layer names must be separated by a comma, without any spaces around the comma

Paramètres et métadonnées requises

  • CONNECTIONTYPE WMS
  • CONNECTION - c’est l’URL “online resource” du serveur distant, juste l’URL de base sans aucun des paramètres WMS. La version diu serveur, le format d’image, le nom de la couche, etc. seront fournis par les métadonnées, voir ci-dessous.

Note

Notez que si la valeur du paramètre CONNECTION n’est pas définie, la valeur de la métadonnée “wms_onlineresource” sera utilisée. Si à la fois CONNECTION et “wms_onlineresource” sont définis alors la métadonnée “wms_onlineresource” à la précédence.

  • métadonnée “wms_format” - le format d’image à utiliser dans les requêtes GetMap.

Note

Si wms_formatlist est fourni alors wms_format est optionnel et MapServer prendra le premier format supporté dans wms_formatlist pour effectuer les requêtes GetMap. Si à la fois, wms_format et wms_formatlist sont fournis alors wms_format prend la précédence. Notez aussi que les serveurs WMS n’affichent seulement les formats supportés qui font partis des bibliothèques GD/GDAL.

  • “wms_name” metadata - comma-separated list of layers to be fetched from the remote WMS server. This value is used to set the LAYERS and QUERY_LAYERS WMS URL parameters. Note that when specifying multiple layers there must not be any spaces between the comma and the layer name.
  • métadonnée “wms_server_version” - la version du protocole WMS supportée par le serveur WMS distant et qui sera utilisé pour résoudre les requêtes GetMap.

  • métadonnée “wms_srs” - liste délimitée par des espaces de codes de projection EPSG supportés par le serveur distant. Vous obtenez normalement cette sortie des “capabilities” du serveur. Cette valeur devrait être mise en majuscule (EPSG:4236.....et pas epsg:4236) pour éviter les problèmes avec les plates-formes sensibles à la casse. La valeur est utilisée pour définir le paramètre SRS de l’URL WMS.

Métadonnées et paramètres optionnels de la couche

  • MINSCALE, MAXSCALE - si les “capabilities” du serveur distant contient une valeur dans ScaleHint pour cette couche alors vous voudrez peut-être définir l’échelle minimum MINSCALE et maximum MAXSCALE dans l’objet LAYER dans le mapfile. Cela permettra à MapServer d’interroger la couche seulement aux échelles où cela fait sens

  • objet PROJECTION - il est optionnel. MapServer en créera un en interne seulement si requis. En inclure un peut permettre à MapServer d’éviter la recherche de définition dans les fichiers PROJ.4.

  • métadonnée “wms_auth_username” - chaîne d’autorisation avec style msEncrypt. Les chaînes vides sont aussi acceptées.

    METADATA
      "wms_auth_username" "foo"
      "wms_auth_password" "{FF88CFDAAE1A5E33}"
    END
    
  • métadonnée “wms_auth_type” - Type d’autorisation . Les types supportés incluent:

    • basic
    • digest
    • ntlm
    • any (la bibliothèque http sous-jacente prend la meilleure option parmi celles supportées par le serveur distant)

    • anysafe (la bibliothèque http sous-jacente prend seulement les méthodes sûres parmi celles supportées par le serveur distant)

    METADATA
      "wms_auth_type" "ntlm"
    END
    
  • métadonnée “wms_connectiontimeout” - le temps maximum à attendre pour charger une couche WMS distante, définit en secondes (par défaut est à 30 secondes). Cette métadonnée peut être ajoutée au niveau du bloc LAYER afin qu’elle n’affecte que cette couche, ou peut être ajoutée au niveau du bloc MAP (dans l’objet WEB) afin qu’elles affectent toutes les couches. Notez que wms_connectiontimeout au niveau de LAYER a priorité sur celle au niveau MAP.

    METADATA
      ...
      "wms_connectiontimeout" "60"
      ...
    END
    
  • “wms_exceptions_format” metadata - set the format for exceptions (as of MapServer 4.6). MapServer defaults to application/vnd.ogc.se_inimage (the exception will be in a picture format). You can check the GetCapabilities of the server to see what formats are available for exceptions. The application/vnd.ogc.se_inimage exception format is actually a non-required exception format in the WMS 1.1.1 spec, so there are servers out there which don’t support this format. In that case you would use:

    LAYER
      ...
      METADATA
        "wms_exceptions_format" "application/vnd.ogc.se_xml"
      END
      ...
    END
    

    qui devrait retourner cette exception xml dans le MS_ERRORFILE:

    Tue Jan 17 18:05:13 2006 - msDrawWMSLayerLow(): WMS server error.
    WMS GetMap request got XML exception for layer 'prov_bound':
    <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?>
    <!DOCTYPE ServiceExceptionReport SYSTEM
    "http://schemas.opengis.net/wms/1.1.1/exception_1_1_1.dtd">
    <ServiceExceptionReport version="1.1.1"><ServiceException
    code="LayerNotDefined">
    msWMSLoadGetMapParams(): WMS server error. Invalid layer(s)
    given in the LAYERS parameter.
    </ServiceException>
    </ServiceExceptionReport>
    
  • métadonnée “wms_force_separate_request” - définir celle-ci à “1” pour forcer cette couche WMS à être interrogée en utilisant sa propre requête spéarée GetMap. Par défaut, MapServer essayera de fusionner des couches WMS multiples adjacentes depuis le même serveur dans une seule requête GetMap multi-couches pour réduire la charge sur les serveurs distants et améliorer le temps de réponse. Cette métadonnée est utilisée pour contourner ce comportement.

  • métadonnée “wms_formatlist” - liste séparée par des virgules des formats d’image supportés par le serveur WMS distant. Notez que wms_formatlist est utilisé seulement si wms_format n’est pas défini. Si à la fois wms_format et wms_formatlist sont fournis alors wms_format prend la précédence.

  • métadonnée “wms_latlonboundingbox” - le rectangle englobant de cette couche en coordonnées géographiques dans le format “lon_min lat_min lon_max lat_max”. S’il est défini alors MapServer interrogera seulement la couche quand la vue de la carte se superpose avec ce rectangle englobant. Vous obtenez normalement ceci depuis la sortie “capabilities” du serveur.

    METADATA
      "wms_latlonboundingbox" "-124 48 -123 49"
    END
    
  • métadonnée “wms_proxy_auth_type” - le type d’autorisation à utiliser pour une connexion par proxy. Les types supportés incluent:

    • basic
    • digest
    • ntlm
    • any (la bibliothèque http sous-jacente prend la meilleure option parmi celles supportées par le serveur distant)

    • anysafe (la bibliothèque http sous-jacente prend seulement les méthodes sûres parmi celles supportées par le serveur distant)

    METADATA
      "wms_proxy_auth_type" "ntlm"
    END
    
  • métadonnée “wms_proxy_host” - le nom de domaine du proxy à utiliser, en format “décimale à point”, avec un composant de port optionnel (par exemple ‘192.168.2.10:8080’).

    METADATA
      "wms_proxy_host" "192.168.2.10"
    END
    
  • métadonnée “wms_proxy_port” - le port à utiliser pour une connexion proxy.

    METADATA
      "wms_proxy_port" "8080"
    END
    
  • métadonnée “wms_proxy_type” - le type de connexion proxy. Les valeurs valides sont ‘http’ et ‘socks5’, qui sont sensibles à la casse.

    METADATA
      "wms_proxy_type" "http"
    END
    
  • métadonnée “wms_proxy_username” - chaîne avec style msEncrypt pour une connexion proxy. Les chaînes vides sont aussi acceptées.

    METADATA
      "wms_proxy_username" "foo"
      "wms_proxy_password" "{FF88CFDAAE1A5E33}"
    END
    
  • métadonnée “wms_sld_body” - peut être utilisée pour spécifier un document SLD “inline”.

  • métadonnée “wms_sld_url” - peut être utilisée pour spécifier un lien vers un document SLD.

  • métadonnée “wms_style” - nom du style à utiliser pourle paramètre de STYLES dans les requêtes GetMap pour cette couche.

  • métadonnée “wms_style_<stylename>_sld” metadata URL d’un SLD à utiliser dans les requêtes GetMap. Remplace <stylename> dans le nom de métadonnée avec le nom de style auxquel le SLD s’applique.

    METADATA
      ...
      "wms_style"              "mystyle"
      "wms_style_mystyle_sld"  "http://my.host.com/mysld.xml"
      ...
    END
    

    Pour plus d’informations sur les SLDs dans MapServer, voir le guide sur SLD.

  • métadonnée “wms_time” - valeur à utiliser pour le paramètre TIME dans les requêtes GetMap pour cette couche. Merci de regarder le guide WMS Time pour plus d’informations.

  • métadonnée “wms_bgcolor” - spécifie la couleur à utiliser comme fond pour la carte. Le format général de BGCOLOR est un encodage hexadécimal d’une valeur RGB où deux caractères hexadécimaux sont utilisés pour chacune des valeurs de couleur rouge (Red), vert (Green), et bleu (Blue). les valeurs sont comprises entre 00 et FF pour chacune (0 et 255, en base 10). Le format est 0xRRGGBB; les caractères majuscules ou minuscules sont autorisés pour les valeurs RR, GG et BB. Le préfixe “0x” doit avoir une casse minuscule avec “x”.

  • métadonnée “wms_transparent” - spécifie si le fond de la carte doit être transparent ou non. TRANSPARENT peut prendre deux valeurs, “TRUE” ou “FALSE”. S’il n’est pas spécifié, MapServer définit par défaut la valeur à “TRUE”

  • métadonnée “wms_cache_to_disk” - définit celle-ci à “1” pour forcer MapServer à écrire les images récupérées sur le disque. Ecrire sur le disque est nécessaire pour tirer parti du de la logique de mise en cache de MapServer afin d’aviter de redemander les requêtes WMS déjà effectuées. Cette fonctionnalité est nouvelle depuis MapServer 6.0 - les résultats étaient antérieurement toujours écrit sur le disque.

  • métadonnée “wms_nonsquare_ok” - définit celle-ci à “0” pour indiquer que le WMS distant supporte seulement des requêtes pour des pixels carré. Dans ce cas, MapServer fera attention à seulement faire des requêtes en pixels carré même si cela signifie suréchantillonner dans une dimension en comparant avec la résolution de la donnée image requise. Cette fonctionnalité est nouvelle depuis MapServer 6.0.

  • métadonnée “wms_extent” - S’il y a exactement un seul SRS supporté par cette couche (comme listé dans la métadonnée wms_srs), et si l’élement de métadonnée wms_extent (ou une étendue spécifiée via le mot-clé EXTENT) est défini alors MapServer gérera les requêtes qui sont comprises à l’intérieur de cette zone. Cela permet de court-circuiter les requêtes complètement en dehors de la couche, de réduire le traitement pour les couches qui ne superposent que partiellement avec l’aire de la carte cible et d’éviter les mauvais fonctionnements avec reprojection dans certaines aires. Le contenu de l’élément de métadonnée doit être de la forme “minx miny maxx maxy”. Cette fonctionnalité est nouvelle depuis MapServer 6.0.

Note

Notez que chacune des métadonnées ci-dessus peut aussi être référée comme ‘ows_*’ plutôt que ‘wms_*’. MapServer essaye en premier la métadonnée ‘wms_*’, et s’il ne le trouve pas, il essaye le nom ‘ows_*’ correspondant. Utiliser ceci réduit la quantité de duplication dans les mapfiles qui supportent des interfaces OGC multiples, comme la métadonnée “ows_*” peut être utilisée presque partout pour les éléments de métadonnées partagés par les interfaces OGC multiples.

Ancien format de paramètre de CONNECTION depuis les versions 3.5 et 3.6 (déprécié)

Dans les versions 3.5 et 3.6 de MapServer, le paramètre de CONNECTION devait inclure au minimum les paramètres WMS VERSION, LAYERS, FORMAT et TRANSPARENT. Ce mode de fonctionnement est encore supportémais est déprécié et vous êtes encouragés à utiliser les éléments métadonnées pour ces paramètres comme documenté dans la section précédente ci-dessus.

Voici un exemple de definition de couche utilisant le format de paramètre de CONNECTION déprécié:

LAYER
 NAME "bathymetry_elevation"
 TYPE RASTER
 STATUS ON
 CONNECTIONTYPE WMS
 CONNECTION "http://demo.org/cgi-bin/wms?VERSION=1.1.0&LAYERS=bm&FORMAT=image/png"
 PROJECTION
   "init=epsg:4326"
 END
END

Limitations/A faire

  1. GetFeatureInfo n’est pas complètement supporté comme la sortie de getFeatureInfo est laissée à la discrétion du serveur distant. Une méthode layer.getWMSFeatureInfoURL() a été ajoutée à MapScript pour les applications qui veulent accéder aux résultats de featureInfo et les manipuler directement.

  2. MapServer ne cherche pas à récupérer les “capabilities” de la couche. Faire ainsi à chaque à dessin de carte serait extrêmement inefficace. Et mettre en cache cette information ne fait parti du coeur de MapServer. Cela peut être mieux fait au niveau applicatif, dans un script, et seule l’information nécessaire est passée au coeur de MapServer via la chaîne CONNECTION et les métadonnées.