source: branches/prototype-v0/docs/kernel/mapserver.rst @ 904

Last change on this file since 904 was 904, checked in by djay, 5 years ago

Add documentation for the HPC support, update the MapServer? suport documentation to show how to produce hetmap, update SAGA-GIS documentation to add option for version 7.2. Add metadb support documentation in kernel/configurationa dn install/installation.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 13.0 KB
Line 
1.. _kernel-mapserver:
2   
3Optional MapServer support
4==========================
5
6Processing geospatial data using WPS Services is usefull. Publishing their results directly as WMS, WFS or WCS ressources is even more convenient. This is possible since `ZOO-Project 1.3 <http://zoo-project.org>`__ using the **optional MapServer support**. The latter thus allows for automatic publication of WPS Service output as WMS/WFS or WCS using a :ref:`kernel_index` specific internal mechanism which is detailed in this section.
7
8
9.. note::
10
11  |mapserver| `MapServer <http://mapserver.org>`__ is an open source WMS/WFS/WCS server. Learn more by reading its `documentation <http://mapserver.org/documentation.html>`__.
12 
13
14.. |mapserver| image:: ../_static/mapserver.png
15       :height: 74px
16       :width: 74px
17       :scale: 50%
18       :alt: MapServer logo
19
20
21How does it work ?
22-------------------------
23
24If a request with ``mimeType=image/png`` is sent to :ref:`kernel_index`, the latter will detect that the *useMapServer* option is set to true an it will automatically:
25
26   * Execute the service using the *<Default>* block definition (these values must be understood by `GDAL <http:/gdal.org>`__)
27   * Store the resulting output on disk (in the ``[main]`` > ``dataPath`` directory)
28   * Write a `mapfile <http://mapserver.org/mapfile/index.html>`__ (in the ``[main]`` > ``dataPath`` directory) using the `MapServer <http://mapserver.org>`__ C-API (this sets up both WMS and WFS services).
29
30Existing WPS Services source code doesn't need to be modified once the MapServer support is activated. It only takes to edit their respective :ref:`services-zcfg` files accordingly.
31
32.. note:: In case of a vector data source output, both WMS and WFS configuration are included by default in the resulting mapfile.
33
34.. note:: In case of a raster data source output, both WMS and WCS configuration are included by default in the resulting mapfile.
35
36Depending on the requests, ZOO-Kernel is able to return a location header and different request types:
37
38    * ResponseDocument=XXXX@asReference=true
39
40In this case, ZOO-Kernel will return the GetMap/GetFeature/GetCoverage request as KVP in the *href* of the result.
41
42    * ResponseDocument=XXXX@asReference=false
43
44In this case, ZOO-Kernel will return the result of the GetMap/GetFeature/GetCoverage request as KVP of the href used in the previous case.
45
46    * RawDataOutput=XXXX@asReference=true/false
47
48In this case, ZOO-Kernel will return the GetMap/GetFeature/GetCoverage request as KVP in a specific location header, which implies that the browser is supposed to request MapServer directly.
49
50Whatever the default output *mimeType* returned by a WPS service is, it is used if the *useMapserver* option is found at runtime. As an example, if ``<Default>`` and ``<Supported>`` blocks are found in the ZOO Service configuration file as shown bellow, this means that the service returns GML 3.1.0 features by default.
51
52.. code-block:: guess
53
54    <Default>
55     mimeType = text/xml
56     encoding = UTF-8
57     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
58    </Default>
59    <Supported>
60     mimeType = image/png
61     useMapserver = true
62    </Supported>
63
64Installation and configuration
65------------------------------
66
67Follow the step described bellow in order to activate the ZOO-Project optional MapServer support.
68
69Prerequisites
70.............
71
72   * latest `ZOO-Kernel <http://zoo-project.org/trac/browser/trunk/zoo-project/zoo-kernel>`__ trunk version
73   * `MapServer <http://mapserver/org>`__ version >= 6.0.1
74
75First download the lastest zoo-kernel by checking out the svn. Use the following command from do the directory where your previously checked out (in this example we will use ``$PREV_SVN_CO`` to design this directory).
76
77.. code-block:: guess
78
79    svn checkout http://svn.zoo-project.org/svn/trunk/ $PREV_SVN_CO
80    cd $PREV_SVN_CO
81   
82Then uncompress the MapServer archive (ie. ``mapserver-6.0.1.tar.bz2``) into ``/tmp/zoo-ms-src``, and compile it using the following command:
83
84.. code-block:: guess
85
86     cd /tmp/zoo-ms-src/mapserver-6.0.1
87     ./configure --with-ogr=/usr/bin/gdal-config --with-gdal=/usr/bin/gdal-config \
88                    --with-proj --with-curl --with-sos --with-wfsclient --with-wmsclient \
89                    --with-wcs --with-wfs --with-postgis --with-kml=yes --with-geos \
90                    --with-xml --with-xslt --with-threads --with-cairo
91     make
92     cp mapserv /usr/lib/cgi-bin
93
94Once done, compile ZOO-Kernel with MapServer support from the ``$PREV_SVN_CO`` directory, using the following command:
95
96.. code-block:: guess
97
98     cd zoo-kernel
99     autoconf
100     ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
101     make
102     sudo make install
103
104
105.. _kernel-mapserver-main.cfg:
106
107Main configuration file
108........................
109
110Open and edit the ``/usr/lib/cgi-bin/main.cfg`` file, by adding the following content in the ``[main]`` section:
111
112.. code-block:: guess
113
114      dataPath = /var/www/temp/
115      mapserverAddress=http://localhost/cgi-bin/mapserv
116
117You can also add the following lines to the ``[main]`` section, in case
118you want to use a default style for Polygon, Lines and Points vector
119layer.
120
121.. code-block:: guess
122
123      msStylePoly=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 WIDTH 3 END
124      msStyleLine=STYLE OUTLINECOLOR 202 109 19 WIDTH 3 END
125      msStylePoint=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 SYMBOL 0 SIZE 14 END
126
127The ``dataPath`` directory is mandatory and must belong to the Apache user.
128
129.. code-block:: guess
130
131     mkdir /var/www/temp/
132     chown -r apache:apache /var/www/temp/
133
134A ``symbols.sym`` file is required in this directory. Create it and add the following content in it:
135
136.. code-block:: guess
137
138      SYMBOLSET
139      SYMBOL
140        NAME "circle"
141        TYPE ellipse
142        FILLED true
143        POINTS
144          1 1
145        END
146      END
147      END
148
149.. note::
150  Only one symbol definition is required (with any name) for the WMS service output.
151
152The ZOO-Project optional MapServer support is activated at this step. Don't forget to add the ``mapserverAddress`` and  ``msOgcVersion`` parameters to the ``main.cfg`` file in order to  to specify the path to MapServer and the OGC WebService version used by the Services.
153
154.. code-block:: guess
155     mapserverAddress=http://localhost/cgi-bin/mapserv.cgi
156     msOgcVersion=1.0.0
157
158.. warning::
159   ZOO-kernel will segfault (checking ``NULL`` value should correct this behavior) if the ``mapserverAddress`` parameter is not found
160
161
162Service configuration file
163............................
164
165useMapserver
166*************
167
168In order to activate the MapServer WMS/WFS/WCS output for a specific service, the ``useMapserver`` parameter must be added to the ``<Default>`` or ``<Supported>`` blocks of the Service `services-zcfg`. If ``useMapserver=true``, this means that the output result of the Service is a GDAL compatible datasource and that you want it to be automatically published by MapServer as WMS,WFS or WCS.
169
170When the useMapserver option is used in a ``<Default>`` or ``<Supported>`` block, then you have to know what are the corresponding mimeType:
171
172   * text/xml: Implies that the output data will be accessible through a WFS GetFeature request (default protocol version 1.1.0)
173   * image/tiff: Implies that the output data will be accessible through a WCS GetCoverage request (default protocol version 2.0.0)
174   * any other mimeType coupled with useMapserver option: Implies that the output data will be accessible through a WMS GetMap request (default protocol version 1.3.0). You can check the supported output mimeType by sending a GetCapabilities request to MapServer.
175
176
177You 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).
178
179Styling
180*************
181
182You have different options to define the style of the layer created
183using the data returned by your service.
184
185msStyle
186+++++++
187
188The optional ``msStyle`` parameter can also be used to define a custom MapServer style block (used for vector datasource only), as follow:
189
190.. code-block:: guess
191
192     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
193
194msClassify
195++++++++++
196
197If a WPS service outputs a one band raster file, then it is possible
198to add a ``msClassify`` parameter and set it to ``true`` in the output
199ComplexData ``<Default>`` or ``<Supported>`` nodes of its zcfg
200file. This allows ZOO-Kernel to use its own default style definitions
201in order to classify the raster using equivalent intervals. 
202
203.. code-block:: guess
204
205     msClassify = true
206
207
208msInclude
209+++++++++
210
211In case you want to use another layer which use the result of your
212service, for instance to produce a `heatmap
213<https://mapserver.org/output/kerneldensity.html>`_, then you can use
214the
215``msInclude`` and ``msLayer`` options in the output ``ComplexData``
216``<Default>`` or ``<Supported>`` nodes of its zcfg file. You can see below an
217example of use of this two options with the associated mapfile.
218
219.. code-block:: guess
220
221     msInclude = /var/data/template.map
222     msLayer = heatmap
223
224You can find below a sample ``/var/data/template.map``:
225
226.. code-block:: guess
227
228     MAP
229       SIZE 1000 500
230       EXTENT -180 -90 180 90
231       NAME "test heat"
232       IMAGETYPE "png"
233
234       WEB
235         METADATA
236           "ows_srs" "epsg:4326  epsg:3857 epsg:900913"
237           "ows_enable_request" "*"
238         END # METADATA
239       END # WEB
240       
241       PROJECTION
242         "+init=epsg:4326"
243       END # PROJECTION
244
245       LAYER
246         NAME "heatmap" # Corresponding to the msLayer defined
247         TYPE raster
248         CONNECTIONTYPE kerneldensity
249         CONNECTION "Result"
250         STATUS on
251         PROCESSING "RANGE_COLORSPACE=HSL"
252         PROCESSING "KERNELDENSITY_RADIUS=20"
253         PROCESSING "KERNELDENSITY_COMPUTE_BORDERS=ON"
254         PROCESSING "KERNELDENSITY_NORMALIZATION=AUTO"
255         OFFSITE 0 0 0
256         CLASS
257           STYLE
258             COLORRANGE  "#0000ff00"  "#0000ffff"
259             DATARANGE 0 32
260           END # STYLE
261           STYLE
262             COLORRANGE  "#0000ffff"  "#ff0000ff"
263             DATARANGE 32 255
264           END # STYLE
265         END # CLASS
266       END # LAYER
267       
268       LAYER
269         NAME "points"
270         STATUS on
271         TYPE POINT
272         #DATA "/Library/WebServer/cache//ef76ee6642c1ea704e847e28120ba1ca.zca"
273       END # LAYER
274     END # MAPFILE
275
276
277
278
279Example
280**************
281
282An example :ref:`services-zcfg` file configured for the optional MapServer support is shown bellow:
283
284.. code-block:: guess
285
286    <Default>
287     mimeType = text/xml
288     encoding = UTF-8
289     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
290     useMapserver = true
291    </Default>
292    <Supported>
293     mimeType = image/png
294     useMapserver = true
295     asReference = true
296     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
297    </Supported>
298    <Supported>
299     mimeType = application/vnd.google-earth.kmz
300     useMapserver = true
301     asReference = true
302     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
303    </Supported>
304    <Supported>
305     mimeType = image/tif
306     useMapserver = true
307     asReference = true
308     msClassify = true
309    </Supported>
310
311In this example, 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.
312
313
314Test requests
315--------------
316
317The optional MapServer support can be tested using any service. The
318simple *HelloPy* Service is used in the following example requests.
319
320.. note::
321  The following examples require a zip file containing a Shapefile (http://localhost/data/data.zip) and a tif file (http://localhost/data/demo.tif)
322
323Accessing a remote Zipped Shapefile as WFS GetFeatures Request:
324
325.. code-block:: guess
326
327     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
328
329Accessing a remote Zipped Shapefile as WMS GetMap Request:
330
331.. code-block:: guess
332
333     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
334
335Accessing a remote tiff as WMS GetMap Request:
336
337.. code-block:: guess
338
339     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
340
341Accessing a remote tiff as WCS GetMap Request:
342
343.. code-block:: guess
344
345     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
346
347
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