source: branches/branch-1.3/docs/kernel/mapserver.txt @ 473

Last change on this file since 473 was 415, checked in by djay, 11 years ago

Add the MapServer? W*S initial documentation based on ticket #34

File size: 12.0 KB
Line 
1.. _kernel-mapserver:
2   
3How To Use the Internal MapServer W*S support
4=============================================
5
6:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
7:Last Updated: $Date$
8
9The key idea of the MapServer W*S support implementation is that it
10doesn't require to change a single line of the service source code to
11activate the automatic publication of your result as WMS/WFS or WCS
12ressource. You simply need to modify the ``zcfg`` file corresponding
13to your service to make it working.
14
15Here is an overview of the way to install the MapServer W*S support, the
16configuration required and the internal mechanisms.
17
18.. contents:: Table of Contents
19    :depth: 3
20    :backlinks: top
21
22How to make it working ?
23------------------------
24
25Requirement
26**************
27
28   * last ZOO-Kernel trunk version
29   * MapServer version >= 6.0.1
30
31Installation steps
32********************
33
34First 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:
35
36.. code-block:: guess
37
38    cd <PREV_SVN_CO>
39    svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms
40
41Uncompress the MapServer archive (ie. ``mapserver-6.0.1.tar.bz2``) into ``/tmp/zoo-ms-src``, then compile MapServer using the following command:
42
43.. code-block:: guess
44
45     cd /tmp/zoo-ms-src/mapserver-6.0.1
46     ./configure --with-ogr=/usr/bin/gdal-config --with-gdal=/usr/bin/gdal-config \
47                    --with-proj --with-curl --with-sos --with-wfsclient --with-wmsclient \
48                    --with-wcs --with-wfs --with-postgis --with-kml=yes --with-geos \
49                    --with-xml --with-xslt --with-threads --with-cairo
50     make
51     cp mapserv /usr/lib/cgi-bin
52
53Autotools was updated to add the ``--with-mapserver`` configure option. From your ZOO-Project SVN trunk directory, compile the ZOO-Kernel using the following command:
54
55.. code-block:: guess
56
57     cd zoo-kernel-ms
58     autoconf
59     ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
60     make
61     cp zoo_loader.cgi /usr/lib/cgi-bin
62
63Configuration steps
64*************************
65
66Main configuration file
67^^^^^^^^^^^^^^^^^^^^^^^
68
69Add the following content to your ``/usr/lib/cgi-bin/main.cfg`` file
70 in the ``[main]`` section:
71
72.. code-block:: guess
73
74      dataPath = /var/www/temp/
75      mapserverAddress=http://localhost/cgi-bin/mapserv
76
77The ``dataPath`` directory should exists and be writable by apache user. In this directory, a ``symbols.sym`` file have to be present, containing the following:
78
79.. code-block:: guess
80
81      SYMBOLSET
82      SYMBOL
83        NAME "circle"
84        TYPE ellipse
85        FILLED true
86        POINTS
87          1 1
88        END
89      END
90      END
91
92Only one symbol definition is required with any name, used for WMS service output.
93
94Now, 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).
95
96Here 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:
97
98.. code-block:: guess
99
100     msOgcVersion=1.0.0
101
102Service configuration file
103^^^^^^^^^^^^^^^^^^^^^^^^^^
104
105To 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).
106
107You get an optional parameter, to use a custom MapServer style block (used for vector datasource only): msStyle. For example:
108
109.. code-block:: guess
110
111     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
112
113You 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).
114
115When you add useMapserver option to an output ``<Default>`` or ``<Supported>`` block, then you have to know what are the sensible mimeType:
116
117   * text/xml: will imply that the output data will be accessible through a WFS GetFeature request (default protocol version 1.1.0)
118   * image/tiff: will imply that the output data will be accessible through a WCS GetCoverage request (default protocol version 2.0.0)
119   * 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)
120
121How does it work ?
122---------------------
123
124Whatever your service return as default output ``mimeType``, this one will be used when one output including the ``useMapserver`` option was found.
125
126So if you get the following ``<Default>`` and ``<Supported>`` blocks in the ZOO Configuration File of your service:
127
128.. code-block:: guess
129
130    <Default>
131     mimeType = text/xml
132     encoding = UTF-8
133     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
134    </Default>
135    <Supported>
136     mimeType = image/png
137     useMapserver = true
138    </Supported>
139
140It 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:
141
142    1) execute the service using the ``<Default>`` block definition (this should be understandable by GDAL/OGR)
143
144    2) store the result of the service on disk (in the ``[main]`` > ``dataPath`` directory)
145
146    3) write a Mapfile (in the ``[main]`` > ``dataPath`` directory) using the MapServer C-API to setup both WMS and WFS services.
147
148.. Note:: even if you don't ask for this, the resulting Mapfile includes both configuration for WMS and WFS in case of Vector datasource.
149
150If 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.
151Special note for client implementers
152
153Note that depending on the request, the ZOO-Kernel can return a location header.
154
155Differente request types:
156
157    * ResponseDocument=XXXX@asReference=true - in this case, the Kernel will return the GetMap/GetFeature/GetCoverage request in KVP in the href of the result.
158    * 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.
159    * 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.
160
161Simple sample use cases
162-----------------------
163
164Consider 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/:
165
166.. code-block:: guess
167
168    <Default>
169     mimeType = text/xml
170     encoding = UTF-8
171     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
172     useMapserver = true
173    </Default>
174    <Supported>
175     mimeType = image/png
176     useMapserver = true
177     asReference = true
178     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
179    </Supported>
180    <Supported>
181     mimeType = image/tif
182     useMapserver = true
183     asReference = true
184     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
185    </Supported>
186    <Supported>
187     mimeType = application/vnd.google-earth.kmz
188     useMapserver = true
189     asReference = true
190     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
191    </Supported>
192
193This 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.
194Raster
195
196Using the following simple service code we get a service capable to output any kind of internet files (useful for testing this functionality):
197
198.. code-block:: guess
199
200    import zoo
201    def HelloPy(conf,inputs,outputs):
202            outputs["Result"]["value"]=inputs["a"]["value"]
203            return zoo.SERVICE_SUCCEEDED
204
205Define the ``[Result]`` output in your ``HelloPy.zcfg`` file with the following ComplexData block content:
206
207.. code-block:: guess
208
209    <Default>
210     mimeType = image/png
211     useMapServer = true
212    </Default>
213    <Supported>
214     mimeType = image/tiff
215     useMapServer = true
216    </Supported>
217    <Supported>
218     mimeType = text/xml
219     useMapServer = true
220    </Supported>
221
222It 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.
223
224With 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``.
225
226There is a support for Zipped ShapeFile but I doubt it is really
227useful. Anyway, as it is present you can test it easily by passing a
228zip file in ``xlink:href`` for the ``a`` value of the ``HelloPy``
229service.
230
231Testings
232***********
233
234Using 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:
235
236Test 1: Accessing a remote Zipped Shapefile as WFS GetFeatures Request
237^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
238
239.. code-block:: guess
240
241     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
242
243Test 2: Accessing a remote Zipped Shapefile as WMS GetMap Request
244^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245
246.. code-block:: guess
247
248     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
249
250Test 3: Accessing a remote tiff as WMS GetMap Request:
251^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
252
253.. code-block:: guess
254
255     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
256
257Test 4: Accessing a remote tiff as WCS GetMap Request:
258^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
259
260.. code-block:: guess
261
262     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
263
264
Note: See TracBrowser for help on using the repository browser.

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png