source: branches/branch-1.5/docs/kernel/mapserver.rst @ 916

Last change on this file since 916 was 725, checked in by djay, 9 years ago

Fix issue with rst files displayed from Trac. Fix strings to be translated. Always use the same string in all messages.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 10.8 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    cd <PREV_SVN_CO>
80    svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms
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-ms
99     autoconf
100     ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
101     make
102
103You can then copy the new ZOO-Kernel to ``/usr/lib/cgi-bin`` directory, as follow:
104
105.. code-block:: guess
106
107     cp zoo_loader.cgi /usr/lib/cgi-bin
108
109
110Main configuration file
111........................
112
113Open and edit the ``/usr/lib/cgi-bin/main.cfg`` file, by adding the following content in the ``[main]`` section:
114
115.. code-block:: guess
116
117      dataPath = /var/www/temp/
118      mapserverAddress=http://localhost/cgi-bin/mapserv
119
120The ``dataPath`` directory is mandatory and must belong to the Apache user.
121
122.. code-block:: guess
123
124     mkdir /var/www/temp/
125     chown -r apache:apache /var/www/temp/
126
127A ``symbols.sym`` file is required in this directory. Create it and add the following content in it:
128
129.. code-block:: guess
130
131      SYMBOLSET
132      SYMBOL
133        NAME "circle"
134        TYPE ellipse
135        FILLED true
136        POINTS
137          1 1
138        END
139      END
140      END
141
142.. note::
143  Only one symbol definition is required (with any name) for the WMS service output.
144
145The 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.
146
147.. code-block:: guess
148     mapserverAddress=http://localhost/cgi-bin/mapserv.cgi
149     msOgcVersion=1.0.0
150
151.. warning::
152   ZOO-kernel will segfault (checking ``NULL`` value should correct this behavior) if the ``mapserverAddress`` parameter is not found
153
154
155Service configuration file
156............................
157
158useMapserver
159*************
160
161In 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.
162
163When the useMapserver option is used in a ``<Default>`` or ``<Supported>`` block, then you have to know what are the corresponding mimeType:
164
165   * text/xml: Implies that the output data will be accessible through a WFS GetFeature request (default protocol version 1.1.0)
166   * image/tiff: Implies that the output data will be accessible through a WCS GetCoverage request (default protocol version 2.0.0)
167   * 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.
168
169
170You 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).
171
172Styling
173*************
174
175The optional ``msStyle`` parameter can also be used to define a custom MapServer style block (used for vector datasource only), as follow:
176
177.. code-block:: guess
178
179     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
180
181If a WPS service outputs a one band raster file, then it is possible to add a ``msClassify`` parameter and set it to ``true`` in the output ComplexData ``<Default>`` or ``<Supported>`` nodes of its ``zcfg`` file. This allows ZOO-Kernel to use its own default style definitions in order to classify the raster using equivalent intervals.
182
183.. code-block:: guess
184
185     msClassify = ....
186
187Example
188**************
189
190An example :ref:`services-zcfg` file configured for the optional MapServer support is shown bellow:
191
192.. code-block:: guess
193
194    <Default>
195     mimeType = text/xml
196     encoding = UTF-8
197     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
198     useMapserver = true
199    </Default>
200    <Supported>
201     mimeType = image/png
202     useMapserver = true
203     asReference = true
204     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
205    </Supported>
206    <Supported>
207     mimeType = application/vnd.google-earth.kmz
208     useMapserver = true
209     asReference = true
210     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
211    </Supported>
212    <Supported>
213     mimeType = image/tif
214     useMapserver = true
215     asReference = true
216     msClassify = ....
217    </Supported>
218
219In 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.
220
221
222Test requests
223--------------
224
225The optional MapServer support can be tested using any service. The
226simple *HelloPy* Service is used in the following example requests.
227
228.. note::
229  The following examples require a zip file containing a Shapefile (http://localhost/data/data.zip) and a tif file (http://localhost/data/demo.tif)
230
231Accessing a remote Zipped Shapefile as WFS GetFeatures Request:
232
233.. code-block:: guess
234
235     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
236
237Accessing a remote Zipped Shapefile as WMS GetMap Request:
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=image/png
242
243Accessing a remote tiff as WMS GetMap Request:
244
245.. code-block:: guess
246
247     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
248
249Accessing a remote tiff as WCS GetMap Request:
250
251.. code-block:: guess
252
253     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
254
255
Note: See TracBrowser for help on using the repository browser.

Search

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