.. _wcs_server:

*****************************************************************************
 WCS Server
*****************************************************************************

:Author:       Jeff McKenna
:Contact:      jmckenna at gatewaygeomatics.com
:Last Updated: 2010-10-19

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top


Introduction
============

A WCS (or Web Coverage Service) allows for the publication of "coverages"- digital 
geospatial information representing space-varying phenomena. In the MapServer world 
it allows for unfiltered access to raster data. Conceptually it is easy think of 
WCS as a raster equivalent of WFS. The following documentation is based on the `Open 
GIS Consortium's (OGC) Web Coverage Server Interfaces Implementation Specification 
version 1.0.0`_.

Links to WCS-Related Information
--------------------------------

- `WCS 1.0.0 specification`_
- `WCS 1.1.1c1 specification`_
- :ref:`WMS Server HowTo <wms_server>`

Software Requirements
---------------------

In order to enable MapServer to serve WCS data, it MUST be compiled against certain 
libraries:

- PROJ.4: The reprojection library. Version 4.4.3 or greater is required.
- GDAL: raster support library.
- MapServer: version >= 4.4 (tested with 5.0.2 while updating this document)

For WCS 1.1.x support (MapServer 5.2) there is an additional requirement:

- libxml2: An xml parser and generation library. 

Please see the :ref:`MapServer UNIX Compilation and Installation HowTo <unix>` for detailed 
instructions on compiling MapServer with support for these libraries and features. 
For Windows users, `MapServer for Windows (MS4W)`_ comes WCS Server support.

Configuring Your Mapfile to Serve WCS Layers
============================================

Much as in the WMS and WFS support, WCS publishing is enabled by adding certain 
magic METADATA keyword/value pairs to a .map file.

MapServer will serve and include in its WCS capabilities only the layers that 
meet the following conditions:

- Data source is a raster, which is processed using GDAL 
  (e.g GeoTIFF, Erdas Imagine, ...)
- LAYER NAME must be set
- LAYER TYPE is set to RASTER
- LAYER DUMP parameter set to TRUE
- WEB metadata "wcs_label" must be set
- LAYER metadata "wcs_label" must be set
- LAYER metadata "wcs_rangeset_name" must be set
- LAYER metadata "wcs_rangeset_label" must be set


Example WCS Server Mapfile
--------------------------

The following is an example of a simple WCS Server mapfile. Note the comments 
for the required parameters.

.. code-block:: mapfile
        
	NAME WCS_server
	STATUS ON
	SIZE 400 300
	SYMBOLSET "../etc/symbols.txt"
	EXTENT -2200000 -712631 3072800 3840000
	UNITS METERS
	SHAPEPATH "../data"
	IMAGECOLOR 255 255 255
	FONTSET "../etc/fonts.txt"


	#
	# Start of web interface definition
	#
	WEB
	  IMAGEPATH "/ms4w/tmp/ms_tmp/" 
	  IMAGEURL "/ms_tmp/"
	  METADATA
	    "wcs_label"                    "GMap WCS Demo Server" ### required  
	    "wcs_description"              "Some text description of the service"  
	    "wcs_onlineresource"           "http://127.0.0.1/cgi-bin/mapserv.exe?" ### recommended
	    "wcs_fees"                     "none"
	    "wcs_accessconstraints"        "none"
	    "wcs_keywordlist"              "wcs,test"
            "wcs_metadatalink_type"        "TC211" 
            "wcs_metadatalink_format"      "text/plain" 
            "wcs_metadatalink_href"        "http://someurl.com"
            "wcs_address"                  "124 Gilmour Street"
            "wcs_city"                     "Ottawa"
            "wcs_stateorprovince"          "ON"
            "wcs_postcode"                 "90210"
            "wcs_country"                  "Canada"
            "wcs_contactelectronicmailaddress" "blah@blah"
            "wcs_contactperson"            "me"
            "wcs_contactorganization"      "unemployed"
            "wcs_contactposition"          "manager"
            "wcs_contactvoicetelephone"    "613-555-1234"
            "wcs_contactfacimiletelephone" "613-555-1235"
            "wcs_service_onlineresource"   "http://127.0.0.1/cgi-bin/mapserv.exe?"            
	  END
	END

	PROJECTION
	  "init=epsg:42304"
	END


	LAYER
	  NAME bathymetry
	  METADATA
	    "wcs_label"           "Elevation/Bathymetry"  ### required
	    "wcs_rangeset_name"   "Range 1"               ### required to support DescribeCoverage request
	    "wcs_rangeset_label"  "My Label"              ### required to support DescribeCoverage request 
	  END
	  TYPE RASTER ### required
	  STATUS ON
	  DATA bath_mapserver.tif
	  PROJECTION
	    "init=epsg:42304"
	  END
	  DUMP TRUE ### required
	END


	END # Map File
	
Test Your WCS 1.0 Server
========================

Validate the Capabilities Metadata
----------------------------------

OK, now that we've got a mapfile, we have to check the XML capabilities returned 
by our server to make sure nothing is missing.

Using a web browser, access your server's online resource URL to which you add 
the parameters "SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities" to the end, e.g.

::

  http://my.host.com/cgi-bin/mapserv?map=mywcs.map&SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities
        

If you get an error message in the XML output then take necessary actions. Common 
problems and solutions are listed in the FAQ at the end of this document.

If everything went well, you should have a complete XML capabilities document. 
Search it for the word "WARNING"... MapServer inserts XML comments starting with 
"<!--WARNING: " in the XML output if it detects missing mapfile parameters or 
metadata items.

Note that when a request happens, it is passed through WMS, WFS, and WCS in MapServer (in that order) 
until one of the services respond to it.

Here is a working example of a GetCapabilities request:

http://demo.mapserver.org/cgi-bin/wcs?SERVICE=wcs&VERSION=1.0.0&REQUEST=GetCapabilities

Test With a DescribeCoverage Request
------------------------------------

OK, now that we know that our server can produce a valid XML GetCapabilities response 
we should test the DescribeCoverage request.  The DescribeCoverage request lists more information
about specific coverage offerings.

Using a web browser, access your server's online resource URL to which you add 
the parameters "SERVICE=WCS&VERSION=1.0.0&REQUEST=DescribeCoverage&COVERAGE=layername" to the end, e.g.

::

  http://my.host.com/cgi-bin/mapserv?map=mywcs.map&SERVICE=WCS&VERSION=1.0.0&REQUEST=DescribeCoverage&COVERAGE=bathymetry
  
Here is a working example of a DescribeCoverage request:

http://demo.mapserver.org/cgi-bin/wcs?SERVICE=wcs&VERSION=1.0.0&REQUEST=DescribeCoverage&COVERAGE=modis


Test With a GetCoverage Request
-------------------------------

The GetCoverage request allows for the retrieval of coverages in a specified output format to the client.


The following is a list of the required GetCoverage parameters according to the WCS spec:

   **VERSION=version:** Request version

   **REQUEST=GetCoverage:** Request name

   **COVERAGE=coverage_name:** Name of an available coverage, as stated in the GetCapabilities

   **CRS=epsg_code:** Coordinate Reference System in which the request is expressed.

   **BBOX=minx,miny,maxx,maxy:** Bounding box corners (lower left, upper right) in CRS units.  One of BBOX or TIME is required.
   
   **TIME=time1,time2:** Request a subset corresponding to a time. One of BBOX or TIME is required..    

   **WIDTH=output_width:** Width in pixels of map picture.  One of WIDTH/HEIGHT or RESX/Y is required.

   **HEIGHT=output_height:** Height in pixels of map picture.  One of WIDTH/HEIGHT or RESX/Y is required.
   
   **RESX=x:** When requesting a georectified grid coverage, this requests a subset with a specific spatial resolution.  One of WIDTH/HEIGHT or RESX/Y is required.     

   **RESY=y:** When requesting a georectified grid coverage, this requests a subset with a specific spatial resolution.  One of WIDTH/HEIGHT or RESX/Y is required.        
   
   **FORMAT=output_format:** Output format of map, as stated in the DescribeCoverage response.
   
The following are optional GetCoverage parameters according to the WCS spec:

   **RESPONSE_CRS=epsg_code:** Coordinate Reference System in which to express coverage responses.
   
So to follow our above examples, a valid DescribeCoverage request would look like:

::

  http://my.host.com/cgi-bin/mapserv?map=mywcs.map&SERVICE=wcs&VERSION=1.0.0&REQUEST=GetCoverage
    &coverage=bathymetry&CRS=EPSG:42304&BBOX=-2200000,-712631,3072800,3840000
    &WIDTH=3199&HEIGHT=2833&FORMAT=GTiff

Here is a working example of a GetCoverage request (note that a 350KB tif is being requested, so this may take a second):

http://demo.mapserver.org/cgi-bin/wcs?SERVICE=wcs&VERSION=1.0.0&REQUEST=GetCoverage&COVERAGE=modis-001&CRS=EPSG:26915&BBOX=159707,4597395,1400707,5501395&WIDTH=400&HEIGHT=300&FORMAT=GEOTIFF_RGB
        
WCS 1.1.0+ Issues
=================

WCS 1.1.0 and later versions of the WCS protocol are supported by MapServer 5.2.  For the most 
part the map file setup for WCS 1.1.0 is similar to WCS 1.0.0, but the actual protocol is
substantially changed.

GetCapabilities
---------------

The GetCapabilities request is the same as WCS 1.0 but with a different VERSION value::

   SERVICE=WCS&VERSION=1.1.0&REQUEST=GetCapabilities

The format of the returned capabilities document is substantially altered from WCS 1.0, 
and makes use of OWS Common for service descriptions.


DescribeCoverage
----------------

The DescribeCoverage request is similar to WCS 1.0, but the IDENTIFIER keyword is used
instead of COVERAGE to name the coverage being requested::

  SERVICE=WCS&VERSION=1.1.0&REQUEST=DescribeCoverage&IDENTIFIER=spaceimaging


GetCoverage
-----------

The format for GetCoverage is substantially changed from 1.0.  The following is a list of 
GetCoverage required parameters:

   **VERSION=version:** Request version

   **REQUEST=GetCoverage:** Request name

   **IDENTIFIER=coverage_name:** Name of an available coverage, as stated in the GetCapabilities

   **BOUNDINGBOX=minx,miny,maxx,maxy,crs:** Bounding box corners (lower left, upper right), and the CRS they are in.  The CRS is described using a URN. 
   
   **FORMAT=output_format:** Output format (mime type) of grid product, as stated in the GetCapabilities.

If an alternate spatial resolution is desired, then the following set of keywords must
be used to specify the sample origin and step size of the output grid to be produced.  The
produced grid will be of a number of pixels and lines as can be fit in the BOUNDINGBOX starting
at GridOrigin, at GridOffsets resolution.

   **GRIDBASECRS=crs:** The grid base CRS (URN). 

   **GRIDCS=crs:** The grid CRS (URN).

   **GridType=urn:ogc:def:method:WCS:1.1:2dGridIn2dCrs:** This is the only supported value for MapServer.

   **GridOrigin=x_origin,y_origin:** The sample point for the top left pixel.

   **GridOffsets=xstep,ystep:** The x and y step size for grid sampling (resolution). Both are positive. 

As well, the following optional parameters are available.

   **RangeSubset=selection:** Selects a range subset, and interpolation method.  Currently only subsetting on bands are allowed.  Depending on rangeset names, this might take the form "BandsName[bands[1]]" to select band 1, or "BandsName:bilinear[bands[1]]" to select band 1 with bilinear interpolation. 

So a simple GetCoverage might look like::

  SERVICE=WCS&VERSION=1.1.0&REQUEST=GetCoverage&IDENTIFIER=dem&FORMAT=image/tiff
    &BOUNDINGBOX=43,33,44,34,urn:ogc:def:crs:EPSG::4326

A more complex request might look like::

  SERVICE=WCS&VERSION=1.1.0&REQUEST=GetCoverage&IDENTIFIER=dem&FORMAT=image/tiff
    &BOUNDINGBOX=33,43,34,44,urn:ogc:def:crs:EPSG::4326
    &GridBaseCRS=urn:ogc:def:crs:EPSG::4326&GridCS=urn:ogc:def:crs:EPSG::4326
    &GridType=urn:ogc:def:method:WCS:1.1:2dGridIn2dCrs
    &GridOrigin=33,44&GridOffsets=0.01,0.01
    &RangeSubset=BandsName:bilinear[bands[1]]

It should also be noted that return results from WCS 1.1 GetCoverage requests are in multi-part mime format.  Typically this consists of a first part with an xml document referencing the other parts of the message, and an image file part.  However, for output formats that return multiple files, each will be a separate part.  For instance, this means it is possible to return a jpeg file with a world file, the OUTPUTFORMAT is appropriately configured.

URNs
----

In WCS 1.1 protocol coordinate systems are referenced by URN.  Some typical URNs are::

  urn:ogc:def:crs:EPSG::4326
  urn:ogc:def:crs:EPSG:27700
  urn:ogc:def:crs:OGC::CRS84

The first two are roughly equivalent to EPSG:4326, and EPSG:27700 while the third
is a CRS defined by OGC (essentially WGS84).  One critical thing to note is that
WCS 1.1 follows EPSG defined axis/tuple ordering for geographic coordinate systems. 
This means that coordinates reported, or provided in urn:ogc:def:EPSG::4326 (WGS84)
are actually handled as lat, long, not long,lat.  So, for instance the BOUNDINGBOX
for an area in California might look like::

  BOUNDINGBOX=34,-117,35,-116,urn:ogc:def:crs:EPSG::4326

And, likewise the bounds reported by GetCapabilities, and DescribeCoverage will be
in this ordering as appropriate.  


Reference Section
=================

WCS support tries to leverage existing WMS or OWS metadata definitions. The 
rationale being that many values will be the same regardless of the type of service. 
The module will look for the following metadata prefixes (in order): wcs, ows and 
finally wms unless otherwise noted.

The following metadata are available in the setup of the mapfile:

Web Object Metadata
-------------------

**wcs_abstract**

- *Description:* (Optional) A brief description of the service, maps to ows:Abstract (WCS 1.1+ only). 

**wcs_accessconstraints**

- *Description:* (Optional) A list of codes describing any access constraints imposed by the service provider. The keyword NONE is reserved to mean no access constraints are imposed.

**wcs_address, wcs_city, wcs_contactelectronicmailaddress, wcs_contactfacimiletelephone, wcs_contactorganization, wcs_contactperson, wcs_contactposition, wcs_contactvoicetelephone, wcs_country, wcs_postcode, wcs_service_onlineresource, wcs_stateorprovince**

- *Description:* (Optional) Contact address information. If provided then all twelve metadata 
  items are required.  You can also use the responsibleparty* metadata instead.

**wcs_description**

- *Description:* (Optional) A description of the server. 

**wcs_fees**

- *Description:* (Optional) A text string indicating any fees imposed by the service provider. 

**wcs_keywords**

- *Description:* (Optional) Short words for catalog searching. 

**wcs_label**

- *Description:* (Required) A human-readable label for the server.  

**wcs_metadatalink_format**

- *Description:* (Optional) The file format MIME type of the metadata record (e.g. 
  "text/plain"). The web metadata wcs_metadatalink_type and wcs_metadatalink_href must 
  also be specified.

**wcs_metadatalink_href**

- *Description:* (Optional) The URL to the server's metadata. The web metadata 
  wcs_metadatalink_format and wcs_metadatalink_type must also be specified.

**wcs_metadatalink_type**

- *Description:* (Optional) The standard to which the metadata complies. Currently 
  only two types are valid: "TC211" which refers to [ISO 19115], and "FGDC" which 
  refers to [FGDC-STD-001-1988]. The web metadata wcs_metadatalink_format and 
  wcs_metadatalink_href must also be specified.

**wcs_name**

- *Description:* (Optional) A name for the server. 

**wcs_responsibleparty_address_administrativearea, wcs_responsibleparty_address_city, 
wcs_responsibleparty_address_country, wcs_responsibleparty_address_deliverypoint, 
wcs_responsibleparty_address_electronicmailaddress, wcs_responsibleparty_address_postalcode,
wcs_responsibleparty_individualname, wcs_responsibleparty_onlineresource, 
wcs_responsibleparty_organizationname, wcs_responsibleparty_phone_facsimile, 
wcs_responsibleparty_phone_voice, wcs_responsibleparty_postionname** 

- *Description:* (Optional) Contact address information. If provided then all twelve metadata 
  items are required.  You can also use the address* metadata instead. 

Layer Object Metadata
---------------------

**wcs_abstract**

- *Description:* (Optional) A brief description of the service, maps to ows:Abstract (WCS 1.1+ only). 

**wcs_description**

- *Description:* (Optional) A description of the layer.

**wcs_extent**

- *Description:* (Optional) Bounding box of layer, which must be provided for tiled data.  Comma-delimited, in the format of: minx,miny,maxx,maxy

**wcs_formats**

- *Description:* (Optional) The formats which may be requested for this layer, separated by a space. (e.g. "GTiff MrSID")

**wcs_keywords**

- *Description:* (Optional) Short words for catalog searching. 

**wcs_label**

- *Description:* (Required) A human-readable label for the layer.  

**wcs_metadatalink_format**

- *Description:* (Optional) The file format MIME type of the metadata record (e.g. 
  "text/plain"). The web metadata wcs_metadatalink_type and wcs_metadatalink_href must 
  also be specified.

**wcs_metadatalink_href**

- *Description:* (Optional) The URL to the layer's metadata. The web metadata 
  wcs_metadatalink_format and wcs_metadatalink_type must also be specified.

**wcs_metadatalink_type**

- *Description:* (Optional) The standard to which the metadata complies. Currently 
  only two types are valid: "TC211" which refers to [ISO 19115], and "FGDC" which 
  refers to [FGDC-STD-001-1988]. The web metadata wcs_metadatalink_format and 
  wcs_metadatalink_href must also be specified.
  
**wcs_name**

- *Description:* (Optional) A name for the layer. 

**wcs_nativeformat**

- *Description:* (Optional) The current format of the served raster layer. (e.g. "GTiff")

*Axes Descriptions*

MapServer allows you define a number of these for a layer. Individual axis are 
identified by name when defining specific metadata (e.g. description). All 
defined axes must be listed in the rangeset_axes metadata tag so MapServer 
knows in advance what to expect. A special rangeset for multiband date is 
automatically generated by adding the name "bands" to the rangeset_axes list. 
If found MapServer will automatically generate metadata for the image bands. 
You may of course extend that basic support using the naming conventions below.

**wcs_rangeset_axes**

- *Description:* (Optional) Delimited list of defined range sets.  If defined, you can
  also use the following nine metadata items, where *rangeset axis* matches the axis name
  provided in this *wcs_rangeset_axes* metadata:

     **{rangeset axis}_semantic**

     **{rangeset axis}_refsys**

     **{rangeset axis}_refsyslabel**

     **{rangeset axis}_description**

     **{rangeset axis}_label**

     **{rangeset axis}_values**

     **{rangeset axis}_values_semantic**

     **{rangeset axis}_values_type**

     **{rangeset axis}_interval**

**wcs_rangeset_label**

- *Description:* (Required for DescribeCoverage request)

**wcs_rangeset_name**

- *Description:* (Required for DescribeCoverage request)

**wcs_srs**

- *Description:* (Optional) Spatial reference system of the layer, in the form of: EPSG:code (e.g. EPSG:42304)  

**wcs_timeitem**

- *Description:* (Optional) The attribute in the spatio/temporal index that contains time values.

**wcs_timeposition**

- *Description:* (Optional) A list of the start and end time of a given coverage (i.e. "2000-11-11T11:11:11Z,2001-11-11T11:11:11Z"), used when advertising GetCapabilities.


Rules for handling SRS in a MapServer WCS
=========================================

TODO!

Spatio/Temporal Indexes
=======================

MapServer has long supported a method of breaking a dataset into smaller, more
manageable pieces or tiles. In this case a shapefile is used to store the
boundary of each tile, and an attribute holds the location of the actual data.
Within a MapServer mapfile the layer keywords TILEINDEX and TILEITEM are used
to activate tiling.

Consider the example where an organization wants to serve hundreds or even
thousands of MODIS scenes. Five images cover the spatial extent and each group
of five varies by date of acquisition. This turns out to be a fairly common
scenario for organizations interested in WCS, one that the existing tiling
support does not adequately address. In previous versions of MapServer a
developer would have to create one tile index and one layer definition for
each group of five images. This could result in configuration files that are
prohibitively long and difficult to manage.

In order to more efficiently support the WCS specification a new tiling scheme
has been implemented within MapServer. One that supports spatial sub-setting,
but also ad hoc sub-setting based on any attributes found within tile index.
In many cases a temporal attribute could be used, but sub-setting is not
limited to that case. The new scheme introduces the concept of tile index
layers, that is, a separate layer definition is used to describe the tile
index dataset. With this we get all the benefits of any MapServer layer, most
importantly we can apply MapServer filters to the data. Filters can be defined
at runtime using MapServer CGI, MapScript or via the WCS server interface. The
syntax for the layer using the index remains unchanged except that the value
for :ref:`TILEINDEX` refers to the index layer instead of an external shapefile.

So, looking at the example above again we can reduce our MapServer
configuration to two layer definitions, one for the tile index and one for the
imagery itself. Extracting a single dates worth of imagery is now a matter of
setting the appropriate filter within the tile index layer.

Building Spatio-Temporal Tile Indexes
-------------------------------------

Developing these tile indexes is more difficult than basic indexes simply
because there are no ready-made tools to do so. Fortunately we can leverage
existing tool available within MapServer or supporting libraries such as GDAL
by post processing their output.

Taking the above example, building an index is relatively simple task if you
are willing to roll up your sleeves and write a bit of code. First, the basic
spatial index needs to be built. The GDAL utility gdaltindex already does
this. Simply point gdaltindex at the directory containing the collection of
MODIS images and it will build a shapefile index suitable for use with
MapServer. The next step would be to add the temporal information. The pseudo
code would look something like:

- open the index .dbf file for reading

- create a new column to hold the image acquisition date

- for each image; 1) extract the image acquisition date and 2) insert it into 
  the new column
  
- close the index .dbf file

This general approach could be used for many cases. A scripting language such
as Perl, PHP or Python works well since they all have readily available
modules for manipulating .dbf files. A worst case would involve hand editing
the resulting .dbf file using a desktop tool such as Mircosoft Access or ESRI
Arcview.

To-do Items and Known Limitations
=================================

- For now we support only GET requests. The spec also talks about XML-encoded 
  POST requests but that is not supported at this time. It is anticipated that 
  a general XML request solution will be created for all OWS services.

- MapServer does not derive all of the metadata it could from a given dataset. 
  For example, you must explicitly list time periods covered by a layer. This 
  should get better with time.

- Only spatial, simple temporal and radiometric band subsetting is possible 
  with the current implementation. Furture enhancements should allow for arbitrary
  subsets based on pixel values or tile/image attributes.


.. #### rST Link Section ####

.. _`Open GIS Consortium's (OGC) Web Coverage Server Interfaces Implementation Specification version 1.0.0`: https://portal.opengeospatial.org/files/?artifact_id=3837
.. _`WCS 1.0.0 specification`: https://portal.opengeospatial.org/files/?artifact_id=3837
.. _`WCS 1.1.1c1 specification`: http://portal.opengeospatial.org/files/?artifact_id=22560
.. _`Open Geospatial Consortium (OGC)`: http://www.opengeospatial.org/
.. _`MapServer for Windows (MS4W)`: http://www.maptools.org/ms4w/index.phtml