1 | .. _kernel-mapserver:
|
---|
2 |
|
---|
3 | Optional MapServer support
|
---|
4 | ==========================
|
---|
5 |
|
---|
6 | Processing 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 |
|
---|
21 | How does it work ?
|
---|
22 | -------------------------
|
---|
23 |
|
---|
24 | If 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 |
|
---|
30 | Existing 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 |
|
---|
36 | Depending on the requests, ZOO-Kernel is able to return a location header and different request types:
|
---|
37 |
|
---|
38 | * ResponseDocument=XXXX@asReference=true
|
---|
39 |
|
---|
40 | In 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 |
|
---|
44 | In 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 |
|
---|
48 | In 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 |
|
---|
50 | Whatever 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 |
|
---|
64 | Installation and configuration
|
---|
65 | ------------------------------
|
---|
66 |
|
---|
67 | Follow the step described bellow in order to activate the ZOO-Project optional MapServer support.
|
---|
68 |
|
---|
69 | Prerequisites
|
---|
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 |
|
---|
75 | First 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 |
|
---|
82 | Then 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 |
|
---|
94 | Once 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 |
|
---|
103 | You 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 |
|
---|
112 | Main configuration file
|
---|
113 | ........................
|
---|
114 |
|
---|
115 | Open 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 |
|
---|
122 | The ``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 |
|
---|
129 | A ``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 |
|
---|
147 | The 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 |
|
---|
157 | Service configuration file
|
---|
158 | ............................
|
---|
159 |
|
---|
160 | useMapserver
|
---|
161 | *************
|
---|
162 |
|
---|
163 | In 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 |
|
---|
165 | When 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 |
|
---|
172 | 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).
|
---|
173 |
|
---|
174 | Styling
|
---|
175 | *************
|
---|
176 |
|
---|
177 | The 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 |
|
---|
183 | If 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 |
|
---|
189 | Example
|
---|
190 | **************
|
---|
191 |
|
---|
192 | An 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 |
|
---|
221 | In 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 |
|
---|
224 | Test requests
|
---|
225 | --------------
|
---|
226 |
|
---|
227 | The optional MapServer support can be tested using any service. The
|
---|
228 | simple *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 |
|
---|
233 | Accessing 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 |
|
---|
239 | Accessing 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 |
|
---|
245 | Accessing 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 |
|
---|
251 | Accessing 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 |
|
---|