How to set up and use the WCS
From Intamap
This document describes the integration of the Web Coverage Service (WCS) in the INTAMAP framework. To show the resulting coverages the AGUILA client can be used. The UMN Map Server represents one implementation of the WCS. We decided to use this variant for two reason
- easy to install
- its architecture allows to manage several coverages
Contents |
How the WCS works
The WCS delivers raster formats to clients. As input file a raster which is (physically) located on this server is used. The following diagram shows the essential workflow of file creation needed for WCS requests:
In general the xml file is not necessary to get a result from the WCS. This is an AGUILA/GDAL specific procedure. Within INTAMAP a WCS request has to be done manually (there is no automatic communication with WCS). The class WCSOutput generates an ArrayList of the urls which can be used to request a result from the WCS. It is important to know that the usage of MapServer to integrate the WCS is just one way. It is easy to use and only a few settings are necessary to integrate it to INTAMAP. An important difference to other implementations of WCS is the usage of the MapServer specific .map file. Its context and structure is described below. In general a request looks like:
http://localhost/cgi-bin/mapserv.exe?map=/ms4w/mapfiles/Request_1.map&service=WCS&version=1.1.1&request=GetCoverage& Identifier=excprob6.8&format=GTIFF&BoundingBox=178605,329714,182565,333674,urn:ogc:def:crs:EPSG::28992
This link can be inserted into a browser which returns a GeoTIFF file. The file can be saved and displayed in a client which is raster format compatible. The complete request string is created by the WPS. The first part of the URL descibes the hostname of the MapServer and its application:
http://localhost/cgi-bin/mapserv.exe
It is divided by a '?' from the request part. The request consists of the following parameter
- service
- map (more information about this is listed below)
- request = to get a GeoTIFF as a result this must be set to 'GetCoverage' (The other request types are 'DescribeCoverage' and 'GetCababilities')
- identifier = name of the requested coverage
- format = to get a GeoTiff this must be set to GTIFF; of course there can be specified other formats
- BoundingBox
The .map file
On the one hand the map file can be understood as a container which includes associated raster files (associated means one observation set and different statistics). On the other hand it is a configuration file which describes how coverages shall be handled by the WCS. This is different to other WCS implementations: between“ the request and the service there is a mapfile .
MAP NAME Request IMAGETYPE GTiff STATUS ON SIZE 100 100 EXTENT 178605 329714 182565 333674 UNITS METERS SHAPEPATH 'data' IMAGECOLOR 255 255 255 OUTPUTFORMAT NAME GTiff DRIVER 'GDAL/GTiff' MIMETYPE 'image/tiff' IMAGEMODE FLOAT32 EXTENSION 'tif' END WEB IMAGEPATH '/ms4w/tmp/ms_tmp/' IMAGEURL'/ms_tmp/' METADATA 'wcs_label' 'GMap WCS Demo Server' 'ows_title' 'Intamap WCS' 'ows_abstract' 'Creation of GTiffs for Aguila' 'ows_keywordlist' ' ' 'ows_contactorganization' 'www.intamap.org' 'ows_title' 'Label' END END PROJECTION 'init=epsg:28992' END LAYER NAME excprob6.8 METADATA 'wcs_label' 'excprob6.8_2009-06-2_04h08m18sec' 'wcs_rangeset_name' 'Range 1' 'wcs_rangeset_label' 'My Label' 'wcs_rangeset_axes_label' 'Band Numbers' 'wcs_rangeset_axes_values' '1' END TYPE RASTER STATUS ON DATA excprob6.8.tif PROJECTION 'init=epsg:28992' END DUMP TRUE END END
This mapfile consists different main parts
- MAP: General settings like size or extension of the raster data
- OUTPUFORMAT: Specifies the driver of format
- PROJECTION: projection to use
- WEB: information for mandatory XML tags
- LAYER: refers to the raster file (DATA tag) which is the input for creation of the geotiff; here are all coverages are listed (i.e. mean, variance etc.)
There is no need to understand the mapfile in detail. This example shall give an impression of the simple structure of a mapfile. All settings listed here are needed for the WCS. In the example request
http://localhost/cgi-bin/mapserv.exe?map=/ms4w/mapfiles/<b>Request_1.map</b>&service=WCS&version=1.1.1&request=GetCoverage& Identifier=excprob6.8&format=GTIFF&BoundingBox=178605,329714,182565,333674,urn:ogc:def:crs:EPSG::28992
the map 'Request_1.map' is used. Usually a WCS request WCS does not include the map key. As already mentioned this is a implementation specific file. But in INTAMAP there also is the opportunity to exclude this key. This is possible because
- a default map (i.e. 'Request_default.map') can be defined in the MapServer
- for the current request two map files are created
- name with a unique ID like timestamp
- default name (i.e. 'Request_default.map')
So when the user calls
http://localhost/cgi-bin/mapserv.exe?service=WCS&version=1.1.1&request=GetCoverage&Identifier=excprob6.8&format=GTIFF& BoundingBox=178605,329714,182565,333674,urn:ogc:def:crs:EPSG::28992
the default map file is accessed. Note: Everytime a WPS request is done the default map is overwritten. It only consists on the current request.
Output of WPS for WCS
As shown in the blue workflow in the diagram shown above the following files are created
- .map file
- .tif files for coverages like mean, variance etc...
- .xml file for client request
The mapfile is the configuration file for the WCS request. It consists for example of following attributes
- .extension
- .units
- .projection
- .output of coverage
- .names of coverages (of requested statistics)
In the end a mapfile is a unique container for resulting coverages (.tif files). Each request creates its own mapfile (and coverage files):
The GeoTiff (.tif) format is not described here.
The xml document specifies the following keys
- ServiceURL = URL of UMN MapServer
- CoverageName
- GetCoverageExtra = Additional key for the GetCoverage request to specifiy mapname
- DescribeCoverageExtra = Additional key for the DescribeCoverage request to specifiy mapname
This xml file is required by AGILA. The four keys specified in the xml file are read by GDAL which creates the request string for the WCS (not for the MapServer). In fact that a wcs request does not include a map key, it must be added manually by using the GDAL specific key GetCoverageExtra/ DescribeCoverageExtra.
Examples
The WPS generates two map files (one with unique identification given the exact instant of time and one general type)
- Request_2009-05-6_02h25m51sec.map
- Request.map (is the default mapfile for the last request if the specific map name is unknown, i. e. if a simple GetCoverage without a specified mapfile is proceeded)
the associated shapefiles (note that more statistics can be calculated than the listed below):
- excprob6.8_2009-05-6_02h25m45sec.tif
- excprob8.9_2009-05-6_02h25m46sec.tif
- quantile0.9_2009-05-6_02h25m47sec.tif
- quantile0.1_2009-05-6_02h25m49sec.tif
- quantile0.5_2009-05-6_02h25m48sec.tif
- mean1_2009-05-6_02h25m50sec.tif
- variance1_2009-05-6_02h25m51sec.tif
and the xml files
- 2009-05-6_02h25m45sec_excprob_6.8.xml
- 2009-05-6_02h25m46sec_excprob_8.9.xml
- 2009-05-6_02h25m47sec_quantile_0.9.xml
- 2009-05-6_02h25m49sec_quantile_0.1.xml
- 2009-05-6_02h25m48sec_quantile_0.5.xml
- 2009-05-6_02h25m50sec_mean1.xml
- 2009-05-6_02h25m51sec_variance1.xml
Installation of MapServer
MapServer can be used as WCS. There's no need for a separate installation. For installing the WCS Server (as a part of MapServer) following steps have to be done
nstall the MapServer:
- Windows: http://maptools.org/dl/ms4w/ms4w-2.3.1-setup.exe (Version used in INTAMAP)
- Linux: http://maptools.org/dl/fgs/releases/1.0/1.0.0/self-installers/fgs-mapserver_5.0.2-fgs_1.0.0-linux-i386.bin
Additional notes
- Complete MapServer solution for windows
- here a HowTo Installer for Linux can be found: http://maptools.org/fgs/index.phtml?page=install.html
- Apache HTTP Server version 2.2.10
- More Infos: http://maptools.org/ms4w/
The preconfigured installation folder is "//ms4w".
A default mapfile should be used. This means that the key map must not be specified in the WCS request. The resulting GeoTiffs represents the latest interpolation request. To define a default map file do the following steps
- Go to folder '\ms4w\Apache\conf'
- Open the configuration file 'httpd.conf'
- Insert the following line
SetEnv MS_MAPFILE "c:/ms4w/mapfiles/Request.map"
This is how a request would look like (below you can find a complete request string):
http://localhost/cgi-bin/mapserv.exe?service=WCS&version=1.1.1&request=GetCoverage&Identifier=excprob6.8.tif&format=GTIFF& BoundingBox=178605,329714,182565,333674,urn:ogc:def:crs:EPSG::28992
Configurations (intamap.properties )
General configurations for WCS can be set in the intamap.properties file. The relevant section begins with
# Properties for WCS output # Set standard prefix for mapfile name default_mapname=Request
This key defines the prefix of mapfiles respectively the name of the default mapfile. This is also important for setting a default map in the map server file which is used if the map parameter is not set (See below for description of configuring a default map in MapServer). Rasterfiles should be stored relative to the mapfiles.
#Unit for calculating WCS output units=METERS #Set relative path for shapefiles shapepath=data # Set path for mapfiles path=//ms4w/mapfiles/
The class IntamapProperties.java creates the necessary strings. E.g. based on the upper settings the path for raster files are:
- //ms4w/mapfiles/
- //ms4w/mapfiles/data/
Setting http_path=http://localhost/cgi-bin/mapserv.exe is the part of the URL to request a rasterfile:
#url for the mapserv application http_path=http://localhost/cgi-bin/mapserv.exe
E.g. a simple WCS request looks like this:
http://localhost/cgi-bin/mapserv.exe?map=/ms4w/mapfiles/Request_1.map&service=WCS&version=1.1.1&request=GetCoverage& Identifier=excprob6.8.tif&format=GTIFF&BoundingBox=178605,329714,182565,333674,urn:ogc:def:crs:EPSG::28992
Using Aguila
AGUILA uses the GDAL library. To use AGUILA as client for visualizing the interpolated results a XML is written for every single GeoTiff by the WPS. These files represent a conform WCS request. The xml files should be written to the installation folder of AGUILA. The following lines specify the installation folder (in intamap.properties)
#Path for aguila; when nothing is set, all outputs necessary for aguila/gdal are ignored aguila_path=//Programmes/Aguila-i686-1.1.0-alpha7/bin
The written XML file names are subject to the following convention:
- Date[yyyy-mm-dd]_Time[hhmmss]_{statistic name}_{statistic value}.xml
e.g.
- 2009-09-21_01h44m19sec_quantile_0.95.xml
Example:
To open a simple GeoTiff with AGUILA go to the folder of Aguila , e.g.
- //Programmes/Aguila-i686-1.1.0-alpha7/bin
Note: If Windows is your OS use the command shell.
With the command
aguila.exe -WCS_OUTPUT\2009-09-21_01h44m19sec_quantile_0.95
the requested GeoTiff is opened in Aguila.
One advantage in using Aguila is the opportunity to display quantiles. To display this information the following quantiles must be computed
- 0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0,95, 0.9, 0.99
To open the resulting xml files at once the following command should be used, e.g.
aguila.exe -q[0.01,0.99,0.01] WCS_OUTPUT\2009-09-21_01h44m19sec_quantile
AGUILA automatically searches for the appendices, which represents the statistic value.
General information
To avoid storage problems (for each mapfile typically seven or more .tifs are created) a simple mechanism is implemented. At the moment there is a criteria that checks number of created mapfiles in mapfiles folder :
#Criteria for deleting map files: number of mapfiles deleteOutput=5
