|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Jeff McKenna |
|---|---|
| Contact: | jmckenna at gatewaygeomatics.com |
| Last Updated: | 2010-10-07 |
The term ‘map context’ comes from the Open Geospatial Constortium’s (OGC) Web Map Context Specification v1.0.0, which coincides with the OGC Web Map Server Specification (WMS) v1.1.1. A map context is a XML document that describes the appearance of layers from one or more WMS servers, and can be transferred between clients while maintaining startup views, the state of the view (and its layers), and storing additional layer information.
Support for OGC Web Map Context was added to MapServer in version 3.7/4.0. This allows client applications to load and save a map configuration in a standard XML format. MapServer can read context documents of versions 0.1.2, 0.1.4, 0.1.7, 1.0.0, 1.1.0 and can export contents in versions 0.1.4, 0.1.7, 1.0.0, 1.1.0. Web Map Context 1.1.0 support was added to MapServer 4.10
This document assumes that you are already familiar with certain aspects of MapServer:
Map Context support requires PROJ4, GDAL/OGR and PHP support libraries.
Build/install the above libraries on your system and then build MapServer with the ‘–with-wmsclient –with-proj –with-ogr –with-gdal –with-php’ configure options. Also make sure that your build uses the USE_WMS_LYR and USE_OGR flags. For more details on MapServer compilation see the appropriate HowTo: Unix / Windows
Windows users can use MS4W, which is ready for Map Context use.
A map context document can ONLY contain WMS layers (e.g. CONNECTIONTYPE WMS). Please refer to the MapServer WMS Client HowTo for more information on declaring WMS layers.
The following mapfile metadata are used by MapServer to handle map context information:
(Note that some parameters have width, height, format, and href, and some only have format and href. This is because width and height are only used for images and parameters that do not have them are text or html. For consistency with the spec MapServer supports height and width for all parameters, but they should only be used for images)
wms_abstract : A blurb of text providing more information about the WMS server.
wms_dataurl_href : Link to an online resource where data corresponding to the layer can be found.
wms_dataurl_format : Format of the online resource where data corresponding to the layer can be found.
wms_dimension : Current dimension used.
New in version 4.10.
wms_dimensionlist : List of available dimensions.
New in version 4.10.
wms_dimension_%s_default : Default dimension value. MapServer will check for wms_time and wms_timedefault metadata when this is not specified. %s = the name of the dimension.
New in version 4.10.
wms_dimension_%s_multiplevalues : Multiple dimension values. %s = the name of the dimension.
New in version 4.10.
wms_dimension_%s_nearestvalue : Nearest dimension value. The default value is 0. %s = the name of the dimension.
New in version 4.10.
wms_dimension_%s_units : Units for the dimension values. The default value is ISO8601. %s = the name of the dimension.
New in version 4.10.
wms_dimension_%s_unitsymbol : Symbol for dimension units. The default value is t. %s = the name of the dimension.
New in version 4.10.
wms_dimension_%s_uservalue : User dimension value. MapServer will check for wms_time and wms_timedefault metadata when this is not specified. %s = the name of the dimension.
New in version 4.10.
wms_format : Current format used.
wms_formatlist : List of available formats for this layer.
wms_metadataurl_href : Link to an online resource where descriptive metadata of the corresponding layer can be found.
wms_metadataurl_format : Format of the online resource where descriptive metadata of the corresponding layer can be found.
wms_name : Name of the WMS layer on the server.
wms_onlineresource : Required URL to access the server.
wms_server_version : The version of the web map server specification.
wms_server_title : The title of the web map server.
wms_stylelist : Current style used.
wms_style_%s_legendurl_width : Width of an image describing the style. %s = the name of the style.
wms_style_%s_legendurl_height : Height of an image describing the style. %s = the name of the style.
wms_style_%s_legendurl_format : Format of an image describing the style. %s = the name of the style.
wms_style_%s_legendurl_href : Location of an image describing the style. %s = the name of the style.
wms_style_%s_sld : URL to the SLD document of this style. %s = the name of the style.
wms_style_%s_sld_body : SLD_BODY document of this style. %s = the name of the style.
wms_style_%s_title : Title of the layer. %s = the name of the style.
wms_title : (Required) A human-readable name for this Layer.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | MAP
NAME "mapcontext"
STATUS ON
SIZE 400 300
SYMBOLSET "../etc/symbols.txt"
EXTENT -180 -90 180 90
UNITS DD
SHAPEPATH "../data"
IMAGECOLOR 255 255 255
FONTSET "../etc/fonts.txt"
#
# Start of web interface definition
#
WEB
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
METADATA
"wms_abstract" "Demo for map context document. Blah blah..."
"wms_title" "Map Context demo" #### REQUIRED
END
END
PROJECTION
"init=epsg:4326"
END
#
# Start of layer definitions
#
LAYER
NAME "country_bounds"
TYPE RASTER
STATUS ON
CONNECTION "http://demo.mapserver.org/cgi-bin/wms?"
CONNECTIONTYPE WMS
METADATA
"wms_title" "World Country Boundaries" #### REQUIRED
"wms_onlineresource" "http://demo.mapserver.org/cgi-bin/wms?" #### REQUIRED
"wms_srs" "EPSG:4326"
"wms_name" "country_bounds"
"wms_server_version" "1.1.1"
"wms_format" "image/gif"
"wms_dimensionlist" "time,width"
"wms_dimension" "time"
"wms_dimension_time_unitsymbol" "t"
"wms_dimension_time_units" "ISO8601"
"wms_dimension_time_uservalue" "1310"
"wms_dimension_time_default" "1310"
"wms_dimension_time_multiplevalues" "1310,1410"
"wms_dimension_time_nearestvalue" "0"
END
END
END # Map File
|
The first thing to do is to save your mapfile using the saveMapContext function available from the PHP/MapScript library. An example script is shown below:
<?php
if (!extension_loaded("MapScript")) dl(MODULE);
$oMap = ms_newMapObj("mapcontext.map");
$oMap->saveMapContext("mapcontext_output.xml");
?>
Scan the XML output to look for <!– WARNING: ... –> comments. Then make the necessary changes to fix every warning that you encounter. At the end of this you should have a mapfile compatible with the Map Context specification.
Now you can load your new Map Context document into an application using the loadMapContext function from the PHP/MapScript library.
The following is a sample Map Context document:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?>
<ViewContext version="1.1.0" id="mapcontext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.opengis.net/context" xmlns:sld="http://www.opengis.net/sld" xsi:schemaLocation="http://www.opengis.net/context http://schemas.opengis.net/context/1.1.0/context.xsd">
<General>
<Window width="400" height="300"/>
<!-- Bounding box corners and spatial reference system -->
<BoundingBox SRS="EPSG:4326" minx="-180.000000" miny="-90.000000" maxx="180.000000" maxy="90.000000"/>
<!-- Title of Context -->
<Title>Map Context demo</Title>
<Abstract>Demo for map context document. Blah blah...</Abstract>
<ContactInformation>
</ContactInformation>
</General>
<LayerList>
<Layer queryable="0" hidden="0">
<Server service="OGC:WMS" version="1.1.1" title="World Country Boundaries">
<OnlineResource xlink:type="simple" xlink:href="http://demo.mapserver.org/cgi-bin/wms?"/>
</Server>
<Name>country_bounds</Name>
<Title>World Country Boundaries</Title>
<SRS>EPSG:4326</SRS>
<FormatList>
<Format current="1">image/gif</Format>
</FormatList>
<DimensionList>
<Dimension name="time" units="ISO8601" unitSymbol="t" userValue="1310" default="1310" multipleValues="1310,1410" nearestValue="0" current="1"/>
</DimensionList>
</Layer>
</LayerList>
</ViewContext>
|
MapServer CGI allows you to load a map context through the use of a CONTEXT parameter, and you can point this parameter to a locally stored context file or a context file accessible through a URL. For more information on MapServer CGI see the CGI Reference.
There is a new cgi parameter called CONTEXT that is used to specify a local context file. The user can then use MapServer to request a map using the following syntax:
http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT=
/path/to/contextfile.xml&LAYERS=layer_name1 layers_name2
Note
All layers created from a context file have their status set to ON. To be able to display layers, the user needs to add the LAYERS argument in the URL.
The syntax of using a web accessible context file would be similar to accessing a local context file:
http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT=
http://URL/path/to/contextfile.xml&LAYERS=layers_name1 layer_name2
Due to security concerns loading a file from a URL is disabled by default. To enable this functionality, the user needs to set a CONFIG parameter called CGI_CONTEXT_URL in the default mapfile that will allow this functionality. Here is an example of a map file with the CONFIG parameter:
# Start of map file
NAME "map-context"
STATUS ON
SIZE 400 300
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
IMAGECOLOR 255 255 255
IMAGETYPE png
CONFIG "CGI_CONTEXT_URL" "1"
...
WEB
...
END
LAYER
...
END
END
To smoothly run a MapServer CGI application with a Map Context, the application administrator needs to provide a default mapfile with at least the basic required parameters that will be used with the Context file. This default mapfile can contain as little information as the imagepath and imageurl or contain a list of layers. Information coming from the context (e.g.: layers, width, height, ...) would either be appended or will replace values found in the mapfile.
Here is an example of a default map file containing the minimum required parameters:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | NAME "CGI-CONTEXT-DEMO"
STATUS ON
SIZE 400 300
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
IMAGECOLOR 255 255 255
IMAGETYPE png
#
# Start of web interface definition
#
WEB
MINSCALE 2000000
MAXSCALE 50000000
#
# On Windows systems, /tmp and /tmp/ms_tmp/ should be created at the root
# of the drive where the .MAP file resides.
#
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
END
END # Map File
|
MapServer can also output your WMS layers as a Context document. MapServer extends the WMS standard by adding a request=GetContext operation that allows you to retrieve a context for a WMS-based mapfile with a call like:
http://localhost/mapserver.cgi?map=/path/to/mapfile.map&service=WMS&
request=GetContext&version=1.1.0
The VERSION parameter controls the version of context document to return.
GetContext is disabled by default because it could be considered a security issue: it could publicly expose the URLs of WMS layers used (cascaded) by a mapfile.
To enable it, set the “wms_getcontext_enabled” web metadata to “1” in your WMS server’s mapfile.