Open WPS Platform

Navigation

How To Use the Internal MapServer W*S support

Authors:Nicolas Bozon, Gérald Fenoy, Jeff McKenna
Last Updated:$Date$

The key idea of the MapServer W*S support implementation is that it doesn’t require to change a single line of the service source code to activate the automatic publication of your result as WMS/WFS or WCS ressource. You simply need to modify the zcfg file corresponding to your service to make it working.

Here is an overview of the way to install the MapServer W*S support, the configuration required and the internal mechanisms.

How to make it working ?

Requirement

  • last ZOO-Kernel trunk version
  • MapServer version >= 6.0.1

Installation steps

First download lastest zoo-kernel directory available on the svn, do that from the directory of your previous checkout (so where zoo-api, zoo-services and zoo-kernel directories are available), we will use <PREV_SVN_CO> here for this directory:

cd <PREV_SVN_CO>
svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms

Uncompress the MapServer archive (ie. mapserver-6.0.1.tar.bz2) into /tmp/zoo-ms-src, then compile MapServer using the following command:

cd /tmp/zoo-ms-src/mapserver-6.0.1
./configure --with-ogr=/usr/bin/gdal-config --with-gdal=/usr/bin/gdal-config \
               --with-proj --with-curl --with-sos --with-wfsclient --with-wmsclient \
               --with-wcs --with-wfs --with-postgis --with-kml=yes --with-geos \
               --with-xml --with-xslt --with-threads --with-cairo
make
cp mapserv /usr/lib/cgi-bin

Autotools was updated to add the --with-mapserver configure option. From your ZOO-Project SVN trunk directory, compile the ZOO-Kernel using the following command:

cd zoo-kernel-ms
autoconf
./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
make
cp zoo_loader.cgi /usr/lib/cgi-bin

Configuration steps

Main configuration file

Add the following content to your /usr/lib/cgi-bin/main.cfg file
in the [main] section:
dataPath = /var/www/temp/
mapserverAddress=http://localhost/cgi-bin/mapserv

The dataPath directory should exists and be writable by apache user. In this directory, a symbols.sym file have to be present, containing the following:

SYMBOLSET
SYMBOL
  NAME "circle"
  TYPE ellipse
  FILLED true
  POINTS
    1 1
  END
END
END

Only one symbol definition is required with any name, used for WMS service output.

Now, your ZOO-Kernel get the MapServer support ready to be used. Note that if you don’t add the mapserverAddress then it imply the ZOO-Kernel will segfault (checking NULL value should correct this behavior).

Here you can optionally add a msOgcVersion parameter to specify which version of the OGC WebService you want to use for each services. For example, if you want to force to version 1.0.0, you can set the following in the [main] section of your main.cfg file:

msOgcVersion=1.0.0

Service configuration file

To activate MapServer WebServices output for a service, you have to add a specific parameter in the <Default> or <Supported> block: useMapserver. This can take the value true or should not appear. If true, it means that the output result is an OGR / GDAL compatible datasource and you want it to be outputted as an OGC web server instance (WMS/WFS/WCS).

You get an optional parameter, to use a custom MapServer style block (used for vector datasource only): msStyle. For example:

msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END

You get the same optional parameter msOgcVersion as for the main.cfg. This will specify that this is the specific protocol version the service want to use (so you may set also locally to service rather than globally).

When you add useMapserver option to an output <Default> or <Supported> block, then you have to know what are the sensible mimeType:

  • text/xml: will imply that the output data will be accessible through a WFS GetFeature request (default protocol version 1.1.0)
  • image/tiff: will imply that the output data will be accessible through a WCS GetCoverage request (default protocol version 2.0.0)
  • any other mimeType coupled with useMapserver option: will imply that the output data will be accessible trhough a WMS GetMap request (you have to limit yourself to what your MapServer installation support, GetCapabilities? request give information of supported output mimeType) (default protocol version 1.3.0)

How does it work ?

Whatever your service return as default output mimeType, this one will be used when one output including the useMapserver option was found.

So if you get the following <Default> and <Supported> blocks in the ZOO Configuration File of your service:

<Default>
 mimeType = text/xml
 encoding = UTF-8
 schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
</Default>
<Supported>
 mimeType = image/png
 useMapserver = true
</Supported>

It means that per default, your service return GML 3.1 Feature. When the client request for mimeType=image/png, then the ZOO-Kernel will detect that this mimeType get the useMapServer option set to true so it will:

  1. execute the service using the <Default> block definition (this should be understandable by GDAL/OGR)
  2. store the result of the service on disk (in the [main] > dataPath directory)
  3. write a Mapfile (in the [main] > dataPath directory) using the MapServer C-API to setup both WMS and WFS services.

Note

even if you don’t ask for this, the resulting Mapfile includes both configuration for WMS and WFS in case of Vector datasource.

If your service output a raster file, then the behavior is quite the same except that the ZOO-Kernel will setup both WMS and WCS services for the result of the service. Here you cannot define your own style. Nevertheless, when one band raster is returned then the ZOO-Kernel can use its own default style definitions to classify the raster using equivalent intervals (you can easily see that in the outputed Mapfile), this classification is specific to WMS protocol. You should add a msClassify parameter and set it to true in your output ComplexData <Default> or <Supported> node to activate this classification. Special note for client implementers

Note that depending on the request, the ZOO-Kernel can return a location header.

Differente request types:

Simple sample use cases

Consider the existing BufferPy service from zoo-services/ogr-base-vect-ops-py. Set the following content to your local BufferPy.zcfg file in the Result output definition, then copy it to /usr/lib/cgi-bin/:

<Default>
 mimeType = text/xml
 encoding = UTF-8
 schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
 useMapserver = true
</Default>
<Supported>
 mimeType = image/png
 useMapserver = true
 asReference = true
 msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
</Supported>
<Supported>
 mimeType = image/tif
 useMapserver = true
 asReference = true
 msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
</Supported>
<Supported>
 mimeType = application/vnd.google-earth.kmz
 useMapserver = true
 asReference = true
 msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
</Supported>

This modifications make your service ready to return result as WMS GetMap or WFS GetFeature requests. Note that some bug occurs locally using the application/vnd.google-earth.kmz output. Raster

Using the following simple service code we get a service capable to output any kind of internet files (useful for testing this functionality):

import zoo
def HelloPy(conf,inputs,outputs):
        outputs["Result"]["value"]=inputs["a"]["value"]
        return zoo.SERVICE_SUCCEEDED

Define the [Result] output in your HelloPy.zcfg file with the following ComplexData block content:

<Default>
 mimeType = image/png
 useMapServer = true
</Default>
<Supported>
 mimeType = image/tiff
 useMapServer = true
</Supported>
<Supported>
 mimeType = text/xml
 useMapServer = true
</Supported>

It means that the default output mimeType is image/png, so a WMS GetMap request will be returned, or the resulting image/tiff will be returned as WCS GetCoverage request.

With this simple service you can test the new capabilities to output result as WebServices for each mimeTypes. Note, that you’ll probably get wrong mimeType, as the default was set to image/png.

There is a support for Zipped ShapeFile but I doubt it is really useful. Anyway, as it is present you can test it easily by passing a zip file in xlink:href for the a value of the HelloPy service.

Testings

Using the simple HelloPy service code, you can use the following urls, note it supposes that you get an available http://localhost/data/data.zip file containing a ShapeFile and a http://localhost/data/demo.tif:

Test 1: Accessing a remote Zipped Shapefile as WFS GetFeatures Request

http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.zip&ResponseDocument=Result@asReference=true@mimetype=text/xml

Test 2: Accessing a remote Zipped Shapefile as WMS GetMap Request

http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.zip&ResponseDocument=Result@asReference=true@mimetype=image/png

Test 3: Accessing a remote tiff as WMS GetMap Request:

http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.tiff&ResponseDocument=Result@asReference=true@mimetype=image/png

Test 4: Accessing a remote tiff as WCS GetMap Request:

http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.tiff&ResponseDocument=Result@asReference=true@mimetype=image/tiff

Table Of Contents