.. _kernel-mapserver: How To Use the Internal MapServer W*S support ============================================= :Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna :Last Updated: $Date: 2015-02-09 15:26:31 +0000 (Mon, 09 Feb 2015) $ 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. .. contents:: Table of Contents :depth: 3 :backlinks: top 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 ```` here for this directory: .. code-block:: guess cd 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: .. code-block:: guess 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: .. code-block:: guess 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: .. code-block:: guess 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: .. code-block:: guess 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: .. code-block:: guess msOgcVersion=1.0.0 Service configuration file ^^^^^^^^^^^^^^^^^^^^^^^^^^ To activate MapServer WebServices output for a service, you have to add a specific parameter in the ```` or ```` 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: .. code-block:: guess 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 ```` or ```` 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 ```` and ```` blocks in the ZOO Configuration File of your service: .. code-block:: guess mimeType = text/xml encoding = UTF-8 schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd mimeType = image/png useMapserver = true 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 ```` 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 ```` or ```` 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: * ResponseDocument=XXXX@asReference=true - in this case, the Kernel will return the GetMap/GetFeature/GetCoverage request in KVP in the href of the result. * ResponseDocument=XXXX@asReference=false - in this case, the Kernel will return the result he get using the GetMap/GetFeature/GetCoverage request in KVP used for the href in previous case. * RawDataOutput=XXXX@asReference=true/false - in this case, the Kernel will return the GetMap/GetFeature/GetCoverage request in KVP in the specific location header, which imply that the browser should follow and request MapServer directly. 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/: .. code-block:: guess mimeType = text/xml encoding = UTF-8 schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd useMapserver = true mimeType = image/png useMapserver = true asReference = true msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END mimeType = image/tif useMapserver = true asReference = true msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END mimeType = application/vnd.google-earth.kmz useMapserver = true asReference = true msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END 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): .. code-block:: guess 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: .. code-block:: guess mimeType = image/png useMapServer = true mimeType = image/tiff useMapServer = true mimeType = text/xml useMapServer = true 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess 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: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess 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: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess 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