WCS -- OGC Web Coverage Service

The optional GDAL WCS driver allows use of a coverage in a WCS server as a raster dataset. GDAL acts as a client to the WCS server.

Accessing a WCS server is accomplished by creating a local service description file that contains one <WCS_GDAL> XML element. It is important that there is no spaces or other content outside that element. Starting at version 2.3 the service description file is meant to be managed by the driver in a cache directory. User should control the contents of the service file using options. The dataset name is "WCS:<URL>", where the <URL> is the URL of the server appended potentially appended with WCS version, coverage, and possibly other parameters. If the WCS version is 2.0.1 further parameters can be given to control how the data model of the coverage is mapped to the GDAL data model.

If the URL does not contain a coverage name, the driver attempts to fetch the capabilities document from the server, parse it, and show the resulting metadata to the user. Coverages are shown as subdatasets. If the URL contains a coverage name as parameter (the key 'coverage' can be used irrespective of the WCS version), the driver attempts to fetch the coverage description document from the server, parse it, and create service description file. A small test GetCoverage request may be done to obtain details of the served data. If the respective server capabilities file is not cached, it will also be fetched.

With service version 2.0.1 (for which support is available starting at GDAL version 2.3), it may be that the coverage has more than two dimensions. In that case, the driver will append the coverage metadata and show zero bands. At that point, the user must use options to further instruct the driver how to deal with extra dimensions and data fields.

The WCS driver supports WCS versions 1.0.0, 1.1.0, 1.1.1, 1.1.2, and 2.0.1 at basic level (version 0.7 is not supported and support for version 2.0.1 is available starting at GDAL 2.3). Any return format that is a single file, and is in a format supported by GDAL should work. The driver will prefer a format with "tiff" in the name, otherwise it will fallback to the first offered format. However, the user may set the preferred format. Coordinate systems are read from the DescribeCoverage result.

The service description file has the following elements as immediate children of the document element. Note that when the "WCS:<URL>" syntax for dataset name is used, the contents of the service description file is meant to be modified by using options.

Range and dimension subsetting

When WCS version 2.0.1 is used, the range (fields/bands) and the dimension can and/or may need to be subsetted. If the data model of the coverage contains dimensions beyond the two geographic or map coordinates, those dimensions must be sliced for GDAL. The coverage may also contain a large number of fields, from which only a subset is wanted in the GDAL dataset.

Range and dimension subsetting must be done via URL parameters since from one coverage it is possible to create more than one different GDAL datasets. In the WCS cache this means that there may be the sets of files related to a GDAL dataset:

  1. server Capabilities file and a GDAL dataset metadata file made from it (key = URL with WCS version number)
  2. server DescribeCoverage file, a template GDAL service file made from it, and a GDAL dataset metadata file made for it (key = URL with WCS version number and coverage name)
  3. the GDAL service file specifically for this dataset, and a GDAL dataset metadata file (key = URL with WCS version number, coverage name, and range and dimension subsetting parameters)
The following URL parameters are used to control the range and dimension subsetting. Note that these can also be set through options into the service file. The ones in URL take precedence.

Other WCS parameters

The following WCS (version 2.0.1) parameters are recognized besides what has been described above. These all can be set either through options or directly into the URL. The ones in URL take precedence. Note that it is up to the server to support/recognize these.

Open options

When the "WCS:<URL>" dataset name syntax is used, open options are used to control the driver and the contents of the service description file. In the case the URL does not contain coverage name, the service description file is not used and thus in that case the options are not written into it. Open options are given separate to the dataset name, with GDAL utility programs they are given using the -oo switch (-oo "NAME=VALUE"). The -oo swicth expects only one option but more options can be given repeating the switch.

In addition to DescribeCoverageExtra and GetCoverageExtra, which are stored in the service description file, there is also GetCapabilitiesExtra, which can be used as an open option when requesting the overall capabilities from the server. The open option SKIP_GETCOVERAGE can be used to prevent the driver making a GetCoverage request to the server, which it usually does if it can't determine the band count and band data type from the capabilities or coverage descriptions. This option may be needed if GetCoverage request fails.

All above listed element names can be given as options to the WCS driver. In the case of flags the option should formally be "Name=TRUE", but only "Name" suffices.

The cache

When the "WCS:<URL>" dataset name syntax is used, the server responses, the service description file, and the metadata files are stored in a cache. Generally, if the needed resource is in the cache, it will be used and no extra calls to the server are done.

The default location of the cache directory is $HOME/.gdal/wcs_cache

The cache contents can be seen as subdatasets using an empty URL:

gdalinfo "WCS:"
The cache control options/flags are

The WCS: dataset name syntax

The URL in the dataset name is not a complete WCS request URL. The request URL, specifically, its query part, for GetCapabilities, DescribeCoverage, and GetCoverage requests is composed by the driver. Typically the user should only need to add to the server address the version and coverage parameters. The string 'coverage' can be used as the coverage parameter key although different WCS versions use different keys. 'coverage' is also always used in the cache key.

The user may add arbitrary standard and non-standard extra parameters to the URL. However, when that is done, it should be noted that the URL is a cache database key and capability documents are linked to coverage documents through the key. Please consider using the Extra open options.

Time

Starting with GDAL 1.9.0, this driver includes experimental support for time based WCS 1.0.0 servers. On initial access the last offered time position will be identified as the DefaultTime. Each time position available for the coverage will be treated as a subdataset.

Note that time based subdatasets are not supported when the service description is the filename. Currently time support is not available for versions other than WCS 1.0.0.

Examples

A gdalinfo call to a coverage served by MapServer:
gdalinfo \
-oo INTERLEAVE=PIXEL \
-oo OffsetsPositive \
-oo NrOffsets=2 \
-oo NoGridAxisSwap \
-oo BandIdentifier=none \
"WCS:http://194.66.252.155/cgi-bin/BGS_EMODnet_bathymetry/ows?VERSION=1.1.0&coverage=BGS_EMODNET_CentralMed-MCol"
A gdal_translate call to a scaled clip of a coverage served by GeoServer:
gdal_translate \
-oo CACHE=wcs_cache \
-oo CLEAR_CACHE \
-oo INTERLEAVE=PIXEL \
-projwin 377418 6683393.87938218 377717.879386966 6683094 \
-oo Subset="time(1985-01-01T00:00:00.000Z)" \
-outsize 60 0 \
"WCS:https://beta-karttakuva.maanmittauslaitos.fi/wcs/service/ows?version=2.0.1&coverage=ortokuva__ortokuva" \
scaled.tiff

See Also: