17.8 WCS Operations: Requests and Responses with XML Examples

WCS provides three major operations, and each operation has a request and response format.

When a client performs any sequence of WCS requests, it should first issue a GetCapabilities request to the server to obtain an up-to-date listing of available data. Then, it may issue a DescribeCoverage request to find out more details about particular coverages offered. To retrieve a coverage or part of a coverage, the client issues a GetCoverage request.

• GetCapabilities Operation (WCS)
  
• DescribeCoverage Operation (WCS)
  
• GetCoverage Operation (WCS)
  

17.8.1 GetCapabilities Operation (WCS)

A GetCapabilities operation allows a WCS client to retrieve service and coverage metadata offered by a WCS server.

All WCS servers must implement KVP protocol for GetCapabilities requests. A user begins interaction with a WCS Server by sending a GetCapabilities request using KVP protocol (HTTP GET request) to the URL. For example:

http://host:port/oraclespatial/wcs/<data source name>?service=WCS&request=GetCapabilities

A GetCapabilities operation returns an XML document describing the service and brief descriptions of the coverages that clients can request. Clients would generally run the GetCapabilities operation and cache its result for use throughout a session, or reuse it for multiple sessions.

GetCapabilities response includes the following:

• WCS response version. If the request does not specify the desired response version, the server returns latest version supported.

• The profile list of the ServiceIdentification identifies an OGC Interface Standard conformance class.

• Operation elements in OperationsMetadata contain the URL for each WCS operation of each protocol. Each WCS operation of each WCS protocol might have a different URL.

• formatSupported elements in ServiceMetadata list all available output formats by a GetCoverage request. This list includes GDAL-supported formats when configured. For example:

  <wcs:ServiceMetadata>
    <wcs:formatSupported>image/tiff</wcs:formatSupported>
    <wcs:formatSupported>image/jp2</wcs:formatSupported>
    <wcs:formatSupported>application/x-ogc-nitf</wcs:formatSupported>
    <wcs:formatSupported>application/x-ogc-aaigrid</wcs:formatSupported>
    <wcs:formatSupported>image/png</wcs:formatSupported>
    <wcs:formatSupported>image/jpeg</wcs:formatSupported>
  </wcs:ServiceMetadata>
  

• Extension elements allow WCS extension standards to define their individual extra service metadata. This element includes 16.8.2 12-039 OGC Web Coverage Service Interface Standard – Scaling Extension elements like: nearest-neighbor, bilinear, biquadratic, ... It also includes 16.8.1 11-053r1 OGC Web Coverage Service Interface Standard – CRS Extension includes crsSupported elements.

• The list of coverages offered by this server includes a coverage ID, which is a unique identifier used in DescribeCoverage and GetCoverage operation requests and the coverage subtype.

17.8.2 DescribeCoverage Operation (WCS)

A DescribeCoverage operation lets clients request detailed metadata for one or more coverages offered by a WCS server, and it provides an estimate of the amount of data to be expected in the domain and range set. A DescribeCoverage request provides a list of coverage identifiers and prompts the server to return, for each identifier, a description of the corresponding coverage. The following is an XML/POST DescribeCoverage request example:

<wcs:DescribeCoverage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:wcs="http://www.opengis.net/wcs/2.0"
        xsi:schemaLocation="http://schemas.opengis.net/wcs/2.0 ../wcsAll.xsd" service="WCS"
        version="2.0.1">
  <wcs:CoverageId>C0001</wcs:CoverageId>
  <wcs:CoverageId>C0002</wcs:CoverageId>
  ...
</wcs:DescribeCoverage>

The DescribeCoverage response contains a list of coverage metadata, one for each coverage identifier passed in the request. Coverage metadata is an XML document of type gml:Grid for GridCoverages, and of type gml:rectifiedGrid for RectifiedGridCoverages. The xsd schemas for those documents can be found in http://schemas.opengis.net/wcs/2.0/.

The gml:Grid element implicitly defines a grid, which is a network composed of two or more sets of curves in which the members of each set intersect the members of the other sets in an algorithmic way. The region of interest within the grid is given in terms of its gml:limits, being the grid coordinates of diagonally opposed corners of a rectangular region. gml:axisLabels is provided with a list of labels of the axes of the grid (gml:axisName has been deprecated). gml:dimension specifies the dimension of the grid.

The gml:limits element contains a single gml:GridEnvelope. The gml:low and gml:high property elements of the envelope are lists of integers, which are coordinate tuples. The coordinates are measured as offsets from the origin of the grid, along each axis, of the diagonally opposing corners of a "rectangular" region of interest.

A rectified grid is a grid for which there is an affine transformation between the grid coordinates and the coordinates of an external coordinate reference system. It is defined by specifying the position (in some geometric space) of the grid "origin" and of the vectors that specify the post locations.

Note that the grid limits (post indexes) and axis name properties are inherited from gml:GridType, and that gml:RectifiedGrid adds a gml:origin property (contains or references a gml:Point) and a set of gml:offsetVector properties.

17.8.3 GetCoverage Operation (WCS)

A GetCoverage operation is normally run after GetCapabilities and DescribeCoverage operation responses have shown what requests are allowed and what data is available. The GetCoverage operation returns a coverage (that is, values or properties of a set of geographic locations) encoded in a well-known coverage format.

A GetCoverage request prompts a WCS service to process a particular coverage selected from the service’s offering and return a derived coverage.

The WCS Core standard defines the domain subsetting operation, which delivers all data from a coverage inside a specified request envelope (“bounding box”), relative to the coverage’s envelope – more precisely, the intersection of the request envelope with the coverage envelope.

Domain subsetting is subdivided into trimming and slicing. A trim operation identifies a dimension and a lower and upper bound (which both must lie inside the coverage’s domain) and delivers a coverage whose domain, in the dimension specified, is reduced to these new, narrower limits. The resulting coverage’s dimension is identical to that of the input coverage. The following is an example of a DimensionTrim element:

<wcs:DimensionTrim>
  <wcs:Dimension>N</wcs:Dimension>
  <wcs:TrimLow>8.16270027015798</wcs:TrimLow>
  <wcs:TrimHigh>8.34362402047258</wcs:TrimHigh>
</wcs:DimensionTrim>

A domain slice operation receives a dimension and a position (which must lie inside the coverage’s domain) and delivers a coverage that is a slice of the offered coverage obtained at the cutting position specified. The dimension of the resulting coverage is reduced by one as compared to the original coverage.

Both trimming and slicing can be combined in a request and on as many dimensions as desired. However, in any request, at most one operation can be applied per dimension. The following is an example of a DimensionSlice element:

<wcs:DimensionSlice>
  <wcs:Dimension>N</wcs:Dimension>
  <wcs:SlicePoint>8.16270027015798</wcs:SlicePoint>
</wcs:DimensionSlice>

The encoding format in which the coverage will be returned is specified by the combination of format and mediaType elelemts. The formats supported are those listed in the server’s Capabilities document, and the default is either application/gml+xml or image/jpeg if GDAL is configured. For example:

<wcs:format>image/jpeg</wcs:format>
<wcs:mediaType>multipart/related</wcs:mediaType>