Abstract
This document describes the procedures for using MapServer's WMS connection type to include layers from remote WMS servers in MapServer applications.
Last Updated: 2004/03/30
Table of Contents
A WMS (or Web Map Server) allows for use of data from several different servers, and enables for the creation of a network of Map Servers from which clients can build customized maps.The following document contains information about using MapServer's WMS connection type to include layers from remote WMS servers in MapServer apps.
This document assumes that you are already familiar with certain aspects of MapServer:
MapServer application development and setting up .map files.
Familiarity with the WMS spec would be an asset. A link to the WMS specification document is included in the "WMS-Related Information" section below.
The WMS Server HOWTO at http://mapserver.gis.umn.edu/doc/wms-server-howto.html.
WMS 1.1.0 specification at http://www.opengis.org/docs/01-047r2.pdf.
WMS 1.1.1 specification at http://www.opengis.org/docs/01-068r2.pdf.
The WMS connection type is enabled by the --with-wmsclient configure switch. It requires PROJ4, libcurl version 7.10.1 or more recent, and GDAL is optional (see below).
For PROJ4 and GDAL installation, see the MapServer Compilation HOWTO ( unix / win32)
For libcurl, make sure you have version 7.10.1 or more recent installed on your system. You can find out your libcurl version using 'curl-config --version'. See http://curl.haxx.se/libcurl/c/ (If your system came with an older version of libcurl preinstalled then you MUST uninstall it prior to installing the new version)
You might want to also include GDAL support if you want your application to be able to reproject map slides received from remote servers. This is because raster resampling works only together with the GDAL library in MapServer. If GDAL is not included in your MapServer build then your application can only serve maps in the subset of the projections supported by all the remote servers (this should be sufficient for most applications). If you compile with GDAL then make sure that your GDAL includes GIF and/or PNG support, depending on which image format you request from remote servers.
Once the required libraries are installed, then configure MapServer using the --with-wmsclient switch (plus all the other switches you used to use) and recompile.
This will give you a new set of executables (and possibly php_mapscript.so if you requested it). See the MapServer Compilation HOWTO for installation details.
To check that your mapserv executable includes WMS support, use the "-v" command-line switch and look for "SUPPORTS=WMS_CLIENT".
Example 1. On Unix:
$ ./mapserv -v
MapServer version 3.5 (pre-alpha) OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
SUPPORTS=PROJ SUPPORTS=TTF SUPPORTS=WMS_CLIENT INPUT=EPPL7 INPUT=JPEG INPUT=OGR
INPUT=GDAL INPUT=SHAPEFILE
Example 2. On Windows:
C:\apache\cgi-bin> mapserv -v
MapServer version 3.5 (pre-alpha) OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
SUPPORTS=PROJ SUPPORTS=TTF SUPPORTS=WMS_CLIENT INPUT=EPPL7 INPUT=JPEG INPUT=OGR
INPUT=GDAL INPUT=SHAPEFILE
(Note: installing those PROJ4 codes is optional, install only if you need them)
Some Canadian WMS servers will use some non-standard projection codes not included in the default distribution (e.g. EPSG:42304, etc.). If you are planning to use MapServer to connect to canadian WMS servers then you might want to download a custom 'espg' file with those codes from http://www2.dmsolutions.ca/mapserver/dl/proj4-epsg-with-42xxx.zip and unzip it in the /usr/local/share/proj directory.
Finally, ESRI WMS servers also come with their own series of non-standard codes. If you are planning to connect to ESRI WMS servers then you might want to get a custom epsg file that contains the canadian codes and the ESRI codes, allowing you to connect to any server. Download the file http://www2.dmsolutions.ca/mapserver/dl/proj4-epsg-with-42xxx-and-esri.zip and unzip it in /usr/local/share/proj
You should install only the epsg projection codes that you need, the epsg file with all ESRI codes in it is 20% larger than the default one, so it comes with extra overhead that you may not need. Also note that when creating WMS servers, in order to be really interoperable, only EPSG codes that are part of the standard EPSG list should be used. i.e. it is a bad idea for interoperability to use the custom canadian codes or the custom ESRI codes and we do not want to promote their use too much.
A PROJECTION must be set in the mapfile for the MAP unless you are sure that all your WMS layers support only a single projection which is the same as the PROJECTION of the map. The MAP PROJECTION can be set using "init=epsg:xxxx" codes or using regular PROJ4 parameters. Failure to set a MAP PROJECTION may result in blank maps coming from remote WMS servers (because of inconsistent BBOX+SRS combination being used in the WMS cnonection URL).
You have to set the IMAGEPATH value in the WEB object of your mapfile to point to a valid and writable directory. MapServer will use this directory to store temporary files downloaded from the remote servers. The temporary files are automatically deleted by MapServer so you won't notice them... but a valid IMAGEPATH is still required.
WMS layers are accessed via the WMS connection type. Here is an example of a layer using this connection type:
LAYER
NAME "prov_bound"
TYPE RASTER
STATUS ON
CONNECTION "http://www2.dmsolutions.ca/cgi-bin/mswms_gmap?"
CONNECTIONTYPE WMS
METADATA
"wms_srs" "EPSG:42304 EPSG:42101 EPSG:4269 EPSG:4326 EPSG:42304"
"wms_name" "prov_bound"
"wms_server_version" "1.1.0"
"wms_formatlist" "image/gif,image/png,image/jpeg,image/wbmp"
"wms_format" "image/gif"
END
END
The following items are required for the WMS connection type:
CONNECTIONTYPE WMS: of course!
CONNECTION parameter: This is the remote server's online resource URL, just the base URL without any of the WMS parameters. The server version, image format, layer name, etc. will be provided via metadata, see below.
Note that if the CONNECTION parameter value is not set the the value of the "wms_onlineresource" metadata will be used. If both CONNECTION and "wms_onlineresource" are set then the "wms_onlineresource" metadata takes precedence.
"wms_srs" metadata: a space-delimited list of EPSG projection codes supported by the remote server. You normally get this from the server's capabilities output. This value should be upper case (EPSG:42304.....not epsg:42304) to avoid problems with case sensitive platforms. The value is used to set the SRS WMS URL parameter.
"wms_name" metadata: A 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.
"wms_server_version" metadata: The version of the WMS protocol supported by the remote WMS server and that will be used for issuing GetMap requests.
"wms_format" metadata: The image format to use in GetMap requests.
Note that if wms_formatlist is provided then wms_format is optional and MapServer will pick the first supported format in wms_formatlist for use in GetMap requests. If both wms_format and wms_formatlist are provided then wms_format takes precedence.
The following layer parameters and metadata are optional:
"wms_connectiontimeout" metadata: The maximum time to wait for a remote WMS layer to load, set in seconds (default is 30 seconds). This metadata can be added at the layer level so that it affects only that layer, or it can be added at the map level (in the web object) so that it affects all of the layers. Note that wms_connectiontimeout at the layer level has priority over the map level.
e.g.
METADATA
...
"wms_connectiontimeout" "60"
...
END
PROJECTION object: It is optional at this point. MapServer will create one internally if needed.
MINSCALE, MAXSCALE: If the remote server's capabilities contains a ScaleHint value for this layer then you might want to set the MINSCALE and MAXSCALE in the LAYER object in the mapfile. This will allow MapServer to request the layer only at scales where it makes sense.
"wms_latlonboundingbox" metadata: The bounding box of this layer in geographic coordinates in the format "lon_min lat_min lon_max lat_max". If it is set then MapServer will request the layer only when the map view overlaps that bounding box. You normally get this from the server's capabilities output.
e.g.
METADATA
"wms_latlonboundingbox" "-124 48 -123 49"
END
"wms_formatlist" metadata: Comma-separated list of image formats supported by the remote WMS server.
Note that wms_formatlist is used only if wms_format is not set. If both wms_format and wms_formatlist are provided then wms_format takes precedence.
"wms_style" metadata: Name of style to use for the STYLES parameter in GetMap requests for this layer.
"wms_<stylename>_sld" metadata: URL of a SLD to use in GetMap requests. Replace <stylename> in the metadta name with the name of the style to which the SLD applies.
e.g.
METADATA
...
"wms_style" "mystyle"
"wms_mystyle_sld" "http://my.host.com/mysld.xml"
...
END
"wms_time" metadata: Value to use for the TIME parameter in GetMap requests for this layer. See the WMS specification for details on the valid values of the TIME parameter.
"wms_force_separate_request" metadata: Set this to "1" to force this WMS layer to be requested using its own separate GetMap request. By default MapServer will try to merge multiple adjacent WMS layers from the same server into a single multi-layer GetMap request to reduce the load on remote servers and improve response time. This metadata is used to bypass that behavior.
In MapServer version 3.5 and 3.6, the CONNECTION parameter had to include at a minimum the VERSION, LAYERS, FORMAT and TRANSPARENT WMS parameters. This mode of operation is still supported but is deprecated and you are encouraged to use metadata items for those parameters as documented in the previous section above.
Here is an example of a layer definition using this deprecated CONNECTION parameter format:
LAYER
NAME bathymetry
METADATA
"wms_title" "Elevation/Bathymetry"
"wms_srs" "EPSG:42304 EPSG:4269 EPSG:4326"
END
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www2.dmsolutions.ca/cgi-bin/mswms_gmap?VERSION=1.1.0&LAYERS=bathymetry&FORMAT=image/png"
PROJECTION
"init=epsg:42304"
END
END
When a WMS layer is requested, MapServer locally creates a temporary image returned by the server until the map is drawn. This temporary file is created in the IMAGEPATH directory of the client machine. This file is then autmatically deleted.
If you want to keep this temporary file for debugging puposes, you should add the following statement to the LAYER object of your mapfile:
LAYER
....
DEBUG ON
...
END
MapServer WMS connections always request exceptions "INIMAGE", but it may be nice to support XML exceptions at some point and return the message via the MapServer error reporting mechanisms.
GetFeatureInfo is not fully supported since the output of getFeatureInfo is left to the discretion of the remote server. A method layer.getWMSFeatureInfoURL() has been added to MapScript for applications that want to access featureInfo results and handle them directly.
MapServer does not attempt to fetch the layer's capabilities. Doing so at every map draw would be extremely inefficient. And caching that information does not belong in the core of MapServer. This is better done at the application level, in a script, and only the necessary information is passed to the MapServer core via the CONNECTION string and metadata. (We will soon release the MapBrowser PHP application which demonstrates the use of PHP to fetch and parse remote WMS server capabilities).
Copyright (c) 2004, Jeff McKenna, DM Solutions Group Inc.
This documentation is covered by the same Open Source license as the MapServer software itself. See MapServer's License and Credits page for the complete text.
No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies that may be damaging to your system. Although this is highly unlikely, the author(s) do not take any responsibility for that: proceed with caution.
This is a new document for a new project; input is appreciated. Send any comments or suggestions to the MapServer Documentation Coordinator at <mdp@lists.gis.umn.edu>.
| Add a Comment |