Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  IDL Reference  >  I/O - Network  >  IDLnetOGCWCS::GetCoverage

IDLnetOGCWCS::GetCoverage

IDLnetOGCWCS::GetCoverage

The IDLnetOGCWCS::GetCoverage function method retrieves a data file from a remote OGC WCS server, and writes the file to disk. The file location is specified by the COVERAGE_FILENAME property, and will be overwritten if this property value remains unchanged between GetCoverage requests.

Note: The URL_PATH and URL_HOSTNAME properties must be set before requesting information from a remote WCS server. You can either set these properties manually or pass a URL to the IDLnetOGCWCS::ParseUrl method prior to making a request. If you are dealing with a proxy server, you must also set the PROXY_HOSTNAME and PROXY_PORT properties to the correct values.

This method returns only when one of the following occur:

  • Completes retrieval of information from server
  • Encounters an HTTP error
  • Encounters an OGC exception
  • Responds to a cancel request as specified in a callback return value

You can implement a callback to return status information during the request by setting the CALLBACK_FUNCTION property. You can also use a callback to cancel a request. See Using Callbacks with the IDLnetOGCWCS Object for details. This method will throw an error if the GetCoverage request fails.

Syntax


Result = Obj->[IDLnetOGCWCS::]GetCoverage(Coverage_Request)

Return Value


The return value is string containing the path to the file returned by this request or an empty string if no file was returned.

Arguments


Coverage_Request

The Coverage_Request argument must be a string that contains the required key-value pairs separated by the & character. These elements can be extracted from the structures returned by the IDLnetOGCWCS::GetCoverageOffering method. The required elements are shown in the following table, and match those described in OGC Web Coverage Service (WCS) specification. See the OGC web site (www.opengeospatial.org) for specification details.

Key-value Pair

Description

COVERAGE=name

Name of the available coverage. Required.

Source — in the Main Coverage Offering Structure see CO_NAME .

CRS=crs_identifier

Coordinate Reference System used for the request. Required.

Source — in the CRS Structure see:

RESPONSE_CRS= crs_identifier

Coordinate Reference System to use for the coverage response. Optional. The default is the request CRS.

Source — in the CRS Structure see RESPONSE.

BBOX=minx, miny, maxx, maxy, minz, maxz

Request a coverage subset as defined by the bounding box coordinate pairs, ordered according to the CRS parameter reference system. Either BBOX or TIME is required.

Source — in the Spat_Dom_LonLatEnv Structure, see:

If the WCS server supports returning a subset of the data, then the bounding box values can be any that fall inside of the bounding box.

TIME=time1, time2, ... or TIME=min/max/res, ...

Request a coverage subset defined by specific time instances or intervals expressed in an extended ISO 8601 syntax. This parameter is optional if the selected layer has a default time, fixed time, or no time defined. Either BBOX or TIME is required.

Source — in the Spat_Dom_LonLatEnv Structure, see the following fields:

If the WCS server supports returning a subset of the data, then the time values can be any that occur within the available time span.

PARAMETER=val1, val2, .. or
PARAMETER= min/max/res

(Only for range sets with compound values.) Use a constraining PARAMETER to request a subset where PARAMETER is a variable string that matches the name of a parameter listed in the selected coverage’s range description set. For example:

band=1,5,3 (e.g., radiance values in bands 1, 5, 3) 
age=0/18 (e.g., counts of people with ages under 18 yrs.) 

Optional when the range component has default parameter values. Set this only if the WCS server supports optional parameters.

WIDTH=w (integer)

HEIGHT=h (integer)

[DEPTH=d (integer)]

Request a grid defined by integer values for width, height and depth (the number of gridpoints if a 3D grid).

Either these parameters (including DEPTH if 3D) or RESX, RESY, and RESZ (if 3D) are required.

See the elements in the Spat_Dom_Grid Structure in order to determine the original resolution of the data.

RESX=x (double)

RESY=y (double)

[RESZ=z (double)]

Use when requesting georectified grid coverages. Request a coverage subset defined using specific spatial resolutions along each axis of the CRS reply. Units of the values are appropriate for each axis of the CRS. Either these parameters or WIDTH, HEIGHT, and DEPTH (if a 3D grid) are required.

FORMAT=format

Define the requested output format of the coverage. This must be one of the mandatory formats. Required.

Source — in the Main Coverage Offering Structure see:

Keywords


None

Examples


The following example connects to an OGC server and calls GetCapabilities, GetCoverageOfferingBriefs, DescribeCoverage, GetCoverageOffering and GetCoverage to return data from the server. Elements of the structure returned by GetCoverageOffering provide the required key-value pair elements of the query defining the coverage data to return.

Note: You may need to replace the URL in the following example as there is no guarantee that the given OCG server will be available when you attempt to establish the connection.

FUNCTION ogcwcs_callback,  StatusInfo, CallbackData
 
PRINT, StatusInfo
 
; Indicate all is well.
vCancelFlag = 1
RETURN, vCancelFlag
 
END
 
PRO ogc_wcs_getcoverage_doc
 
; Use the GetCoverage method to return data from an OGC server. 
; The GetCoverageOffering structure provides parameters required 
; for the GetCoverage request.
 
; This example queries an OGC server at the following URL. Change 
; the value of this variable to access a server of your choice.
url="http://mydataserver.com:80/cgi-bin" + $ 
   "/mapserv.exe?MAP=/OGC_Data/WCS/wcs_demo.map" + $
   "&SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities"
 
; Catch error.
CATCH, errorStatus
IF (errorStatus NE 0) THEN BEGIN
   CATCH,/CANCEL
   r = DIALOG_MESSAGE(!ERROR_STATE.MSG, $
      TITLE='OGC WCS Error', /ERROR)
   PRINT, !ERROR_STATE.MSG
   IF OBJ_VALID(oWcs) THEN OBJ_DESTROY, oWcs
   RETURN
ENDIF
 
; Create an IDLnetOGCWCS object and parse a known, working URL to
; set mandatory properties. 
oWcs = OBJ_NEW("IDLnetOGCWCS", $
   CALLBACK_FUNCTION="ogcwcs_callback")
oWcs->ParseUrl, url
 
; Return and parse a brief description of all data holdings 
; on the WCS server.
count = oWCS->GetCapabilities()
arrName=' '
 
; Make sure the server returned some coverage offering briefs.
IF (count NE 0) THEN BEGIN
 
   ; Return information about the holding using the 
   ; GetCoverageOfferingBriefs method.
   briefStruct = oWCS->GetCoverageOfferingBriefs $
      (COUNT=briefcount, NUMBER=1)
   PRINT, "Returning structures for ", + briefcount, + " briefs"
 
   ; Access the name element of the GetCoverageOfferingBriefs
   ; structure.
   FOR x=0, briefCount-1 DO BEGIN
      PRINT, 'CoverageOfferingBrief = ', strtrim(x,2)
      PRINT, '  name             = ', briefStruct[x].name
      ; Add the name to the string array.
      arrName = [arrName, briefStruct[x].name]
   ENDFOR
 
   ; Strip out empty string element.
   arrName=arrName[1:*]
   PRINT, "Number of arrName elements = " $
      + STRING(N_ELEMENTS(arrName))
 
   ; Call DescribeCoverage to acccess coverage details for the 
   ; first coverage in the array. 
   covName = oWCS->DescribeCoverage(NAMES=arrName[0], $
      COUNT=numCov)
 
ENDIF ELSE BEGIN
   void = DIALOG_MESSAGE("No information available " $
      + "from WCS Server", /ERROR)
   RETURN   
ENDELSE
 
; Get coverage offering details using GetCoverageOffering method. 
mainStruct=oWCS->GetCoverageOffering()
 
; Access elements of the structure that are required for the 
; GetCoverage request. This consists of coverage name, CRS,
; bounding box, time or parameter, width/height or resoution x/y,
; and format.
coverageName= mainStruct.co_name
crs = mainStruct.crs.request_response[0]
 
; Find the number of samples and lines in the full image
; from the spatial domain grid.
extent = $
   LONG(STRSPLIT(mainStruct.spat_dom_grid.limits_env_high, $
      /EXTRACT))- $
   LONG(STRSPLIT(mainStruct.spat_dom_grid.limits_env_low, $
      /EXTRACT))
nSamples=extent[0]
nLines=extent[1]
 
PRINT, 'Number of samples: ', nSamples
PRINT, 'Number of lines: ', nLines
 
pos1=STRSPLIT(mainStruct.spat_dom_lonlatenv[0].pos1, /extract)
posDims=SIZE(pos1, /n_dimensions) ? N_ELEMENTS(pos1) : 0
pos2=STRSPLIT(mainStruct.spat_dom_lonlatenv[0].pos2, /extract)
bbox=''
 
IF (posDims EQ 2) THEN BEGIN
bbox = pos1[0] + ',' + $
       pos1[1] + ',' + $
       pos2[0] + ',' + $
       pos2[1]
ENDIF
 
IF (posDims EQ 3) THEN BEGIN
bbox = pos1[0] + ',' + $
       pos1[1] + ',' + $
       pos1[2] + ',' + $
       pos2[0] + ',' + $
       pos2[1] + ',' + $
       pos2[2]
ENDIF
 
format=mainStruct.formats[0]
PRINT, 'format = ' + string(format)
 
; Hard-code width and height.
width = '1000'
height = '1000'
 
; Create coverage query string of required key-value pairs.
queryString = 'Coverage=' + coverageName
queryString = queryString + '&CRS=' + crs
queryString = queryString + '&BBOX=' + bbox
queryString = queryString + '&FORMAT=' + format
queryString = queryString + '&WIDTH=' + width
queryString = queryString + '&HEIGHT=' + height
 
dataFile = oWCS->GetCoverage(queryString[0])
PRINT, "file written to " + dataFile
 
data = READ_IMAGE(dataFile) 
IIMAGE, data, /ORDER
 
; Cleanup.
OBJ_DESTROY, oWcs
 
END

Version History


6.4

Introduced

See Also


IDLnetOGCWCS::GetCoverageOffering



© 2018 Harris Geospatial Solutions, Inc. |  Privacy Policy
My Account    |    Store    |    Contact Us