This page provides information and hints about how to implement an OGC Web Map Server. (Eventually, this will become a chapter in a series of cookbook descriptions). Using a WMS, you can provide your spatial information in the form of a map or series of maps that can be accessed in a useful way by others. In particular, if you implement the OpenGIS® Web Map Server Interfaces Specification the maps your server produces will be properly georeferenced. That means that each pixel in your map will correspond to a location on the Earth and that the mapping of pixels to ground coordinates and back is based on a known function. In other words, your maps can be combined with other maps without having to have been produced at the same time by the same server or software.

There are other OGC-related and WMS related cookbooks available:

Guide to Making Your Data Products WMS-Compliant: A Tutorial for Data Providers By Rob Raskin, Ocean ESIP, Jet Propulsion Lab

Spatial Data Infrastructure Cookbook v1.1 (1.16 MB PDF) from GSDI.org

The University of Minnesota's MapServer group has put together a WMS HOWTO.

There are several possible ways to implement a WMS. These include purchase of WMS software from a vendor, using an available open source package, or "rolling your own". The first thing we're going to do here is show you how to build a WMS from free parts, just to get your feet wet. Later we'll take a look at some "real" WMS implementations and see what makes them tick.

We'll build a map server that can produce pictures like this:

Throughout this document, the term map server will mean a web service that conforms to the OpenGIS® Web Map Server Interfaces Specification. Also, references to the the WMS spec will mean the 1.0.0 version unless otherwise stated. (There's a Discussion Paper available that talks about extensions to the spec - the version is 1.0.7). More about versions later.

At this point, it would be good if you read WMS Section 3. It's fast reading and sets the stage.

We'll concentrate on WMS Section 6. We'll be examining a WMS built using Python. The list of what's needed to build it is

• A Linux box. This one is running RedHat 7.
• Python 2.1.1c1 - get it at Python.org
• Apache 1.3.20 - get it at Apache.org
• mod_python 2.7.5 - get it at modpython.org
• Netpbm - get it at SourceForge
• A decent JPEG image of the world (note: that's a 1.7 MByte file)- the one we're using is from CubeWerx and was obtained by running their CubeWerx Web Demo
• Depending on your hardware/software setup, you may have to pull in things like Tcl/Tk, JPEG libraries, etc. in order to build some of this stuff.
• Some help from your friends.

Here's the result. basic-wms2.py (html version) (downloadable version) (license). This could probably also be done in PERL or Tcl or the programming environment of your choice.So here we go.

The general flow from a client's perspective is to first ask the WMS to return a list of what map layers it can draw, then the client can ask for maps by requesting specific layers or combinations of layers over specific geographic regions. In practice, the hard parts of this are done by people who set up web pages that provide user interface controls. Two examples of this are the CubeWerx demo and the NASA Digital Earth viewer. A later "chapter" in this cookbook will take a look at how these web pages work. These are known as Viewer Clients. A viewer client can be as simple as a web browser that you paste a fully formed WMS request into or as complex as a commercial GIS system that can make WMS requests based on the context of what a user is doing.

Our viewer client for the rest of this chapter will be a web browser. All examples will be shown as URLs that you can click on. The map above was generated by this URL:

A WMS has a base URI prefix (or URL prefix if you prefer).

http://www.intl-interfaces.net/cookbook/WMS/basic-wms2/basic-wms2.py?

In order to find out what layers it supplies and what projections it supports, a client makes a "Capabilities Request" (note, the next example should be on one line, it's split because it runs over the edge otherwise. Here's the prefix with a Capabilities request (WMS Section 6.2.7):

(you can click on the link in your browser to see what comes back). The response is formatted according to the WMS Appendix A. Comments in that DTD are considered normative and must be followed by WMS providers. The response has to be valid XML, meaning that it should pass a validation test. Here's a nice color-coded html version. And here's a text-only version. As you can see, the response has a MIME type of text/xml. If you want to see the header your client program gets back, try this link. Let's take a quick look at the parts. First there's some XML info:

The DOCTYPE entry states that this is a WMT_MS_Capabilities document and that you can find the DTD for this file at the given location. The bit about VendorSpecificCapablities means that this WMS has none (see WMS section 6.2.5.1.5)

The next section describes the overall service. (There's a lot of work going on within OGC about service descriptions and service models. The WMS 1.0.0 spec predates most of this work. Thus if you look at the 1.0.7 spec or at other materials coming from OGC, you will see different points on an evolutionary path. The ultimate goal is to develop a service model that can be used to describe many spatial services.)

A WMS must be named GetMap. It's stated so in the DTD.

As a WMS implementor/provider, you pick the Title, Abstract, and Keywords. The Title is meant to be used in user interfaces software (i.e. in Viewer Clients) as part of a list of map servers that the Viewer Client can access. Keep it short. Abstract is meant to provide a longer description of the service. Keep it informative! The Keywords are meant to be useful if someone were searching for your service. These are hard to think of.

The OnlinResource should contain a URI that leads to a description of the service. In this case, it points to this WMS Cookbook. The Fees and AccessConstraints elements are really not well defined except that the spec states that the string none indicates no constraint exists.

Note that all the elements of the Service section can be gathered into a searchable catalog of WMS implementations. In such a catalog, it would be possible to look for WMS implementations that have no associated Fees, or to find those whose Keywords do not include the term "Demo" and so on. If you searched a catalog and found an entry that interests you, you could use the OnlineResource to find out more about that implementation. In fact, the rest of the capabilities, the Capability section is used in catalogs as well.

The Capability section for basic-wms has three subsections: Request, Exception, and Layer

   <Request>
    <Map>
      <Format>
        <PNG />
        <JPEG />
        <PPM />
        <TIFF />
      </Format>
      <DCPType>
        <HTTP>
          <Get onlineResource=
               "http://www.intl-interfaces.net/cookbook/WMS/basic-wms2/basic-wms2.py?" />
        </HTTP>
      </DCPType>
    </Map>
    <Capabilities>
      <Format>
        <WMS_XML />
      </Format>
      <DCPType>
        <HTTP>
          <Get onlineResource=
               "http://www.intl-interfaces.net/cookbook/WMS/basic-wms2/basic-wms2.py?" />
        </HTTP>
      </DCPType>
    </Capabilities>
  </Request>

As you can see, the Request section is split into two sections, Map and Capabilities. These each describe the two operations that this WMS supports. For the Map request, it can handle PNG, JPEG, PPM, and TIFF return formats, and is listening for Map requests at the URI specified by onlineResource. These requests must be made using the HTTP Get request (as opposed to HTTP Put or SOAP or anything else). For the Capabilities request, it can return WMS_XML (the tag "XML" was already reserved, hence the WMS_ prefix) and again, listens at the onlineResource URI.

It's worth noting that the WMS spec allows the onlineResource values for each request type to be different. Depending on how you set up your WMS implementation, it may be more convenient for the two to be the same or it may be easier for them to be different. A WMS client should always start with a Capabilities request to find the Map request URI. Never assume they are the same.

<Exception>
  <Format>
    <INIMAGE />
    <BLANK />
  </Format>
</Exception>

The Exception tag tells about the exception formats a client can ask for when making requests. The basic-wms advertises that it can return INIMAGE or BLANK style exceptions (see WMS spec 6.2.8.2.8)

At last we get to the Layer section. This is how the map server tells the clients what kinds of maps they can request.

  <Layer>
    <Title>Demo Map Server</Title>
    <SRS>EPSG:4326</SRS>
    <LatLonBoundingBox minx="-180" miny="-90" maxx="180" maxy="90" />
    <Layer queryable="0">
      <Name>RELIEF</Name> 
      <Title>Relief (ETOPO/GTOPO)</Title>
      <Abstract>Colored relief map with political boundaries and coastlines</Abstract>
    </Layer>
   </Layer>

Our map server says that it has a top level Layer with a Title, SRS, and LatLonBoundingBox, and a single sub-Layer. Note that the top level Layer has no Name. That means that it's just being used to gather other layers into a logical group. Instead of that grouping, we could have used the form below:

  <Layer queryable="0">
      <SRS>EPSG:4326</SRS>
      <Name>RELIEF</Name> 
      <Title>Relief (ETOPO/GTOPO)</Title>
      <Abstract>Colored relief map with political boundaries and coastlines</Abstract>
    <LatLonBoundingBox minx="-180" miny="-90" maxx="180" maxy="90" />
  </Layer>

However, the WMS 1.0.0 DTD (Appendix A) shows that there can only be zero or one Layer elements inside a Capability. By using the top level grouping Layer, we ensure that later addition of new Layers will be easier to do. So here's the Layer info again:

  <Layer>
    <Title>Demo Map Server</Title>
    <SRS>EPSG:4326</SRS>
    <LatLonBoundingBox minx="-180" miny="-90" maxx="180" maxy="90" />
    <Layer queryable="0">
      <Name>RELIEF</Name> 
      <Title>Relief (ETOPO/GTOPO)</Title>
      <Abstract>Colored relief map with political boundaries and coastlines</Abstract>
    </Layer>
   </Layer>

The top level Layer has an SRS and a LatLonBoundingBox. These are inherited by the sub Layer elements. The sub Layer elements can add SRS values to this list by including its own SRS element. It can replace the LatLonBoundingBox by including one of its own. These inheritance/replacement rules are given in a table in the DTD in Appendix A. Our single sub Layer must have a Name and a Title. We also include an Abstract. The queryable="0" attribute says that our WMS will not responde to GetFeatureInfo requests (see WMS section 6.2.9) for this layer.

In order to actually test this WMS implementation, we can make use of a service offered by CubeWerx. If you go to their demo page, down at the bottom is a text entry box labeled "'URL of server: ". If you enter the prefix of your WMS implemetation in there and hit one of the "Go" button on the page, it will query your WMS for its capabilities, fill in the user-interface elements on the page, and let you exercise your WMS.