source: trunk/docs/kernel/mapserver.rst @ 873

Last change on this file since 873 was 752, checked in by djay, 9 years ago

Add optional CORS support. Fix issue when dealing with Array in JavaScript? support.

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