>  Docs Center  >  IDL Reference  >  I/O - Network  >  IDLnetOGCWMS::GetMap

IDLnetOGCWMS::GetMap

IDLnetOGCWMS::GetMap

The IDLnetOGCWMS::GetMap function method retrieves a map file from a remote OGC WMS server, and writes the file to disk. The file location is specified by the MAP_FILENAME property, and will be overwritten if this property value remains unchanged between GetMap requests.

The URL_PATH and URL_HOSTNAME properties must be set before requesting information from a remote WMS server. You can either set these properties manually or pass a URL to the IDLnetOGCWMS::ParseUrl method prior to making a request. If you are working 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 IDLnetOGCWMS Object for details. This method will throw an error if the GetMap request fails.

Syntax


Result = Obj->[IDLnetOGCWMS::]GetMap(Map_Request)

Return Value


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

Arguments


Map_Request

The Map_Request argument must be a string that contains the required parameters separated by the & character. These elements can be extracted from the structures returned by the IDLnetOGCWMS::GetLayers method. The required and optional elements are shown in the following table, and match those described in OGC Web Map Service (WMS) specification. See the OGC web site (www.opengeospatial.org) for specification details.

Request Parameter

Description

LAYERS=layer_list

Comma-separated list of one or more map layers. Required.

Source: In the Main Layer Structure see NAME . Also see Layer Names and Titles below for more information.

STYLES=styles_list

Comma-separated list of one rendering style per requested layer. If set to “Style=” then the server will use the default style of the first layer requested. Required.

Source: In the Style Structure see NAME.

SRS= namespace:identifier

Spatial Reference System used in 1.1.1 requests. Required.

Source: In the Main Layer Structure see SRS.

CRS= namespace:identifier

Spatial Reference System used in 1.3.0 requests. Required.

Source: In the Main Layer Structure see CRS.

BBOX=minx, miny, maxx, maxy

Request a coverage subset as defined by the bounding box coordinate pairs defining corners (lower left, upper right), in SRS or CRS units. Required.

Source: In the Main Layer Structure, see one of the following:

LAT_LON_BBOX (version 1.1.1)

EX_GEOBOX (version 1.3.0)

BOUNDING_BOX (version 1.1.1, 1.3.0)

WIDTH=output_width

Width of map image in pixels. Required.

HEIGHT=output_height

Height of map image in pixels. Required.

FORMAT= output_format

Output format of map. Required.

Source: In the Main Layer Structure, see MAP_FORMAT.

TRANSPARENT= TRUE | FALSE

Background transparency of map. Default is false. Optional.

BG_COLOR= color_value

Hexadecimal RGB color value for the background color (default=0xFFFFFF). Optional.

TIME=time

Time value of layer desired in UTC format. Optional.

ELEVATION=elevation

Elevation of layer desired. Refer to section on Handling Multi-dimensional Datasets in the OGC WMS standard specification for details. Optional.

Other sample dimension(s)

Value of other dimensions as appropriate. Optional.

Layer Names and Titles

If, and only if, a layer has a NAME, then that map layer can be requested using that NAME in the LAYERS=layer_list parameter of the Map_Request argument. A layer that contains a NAME element is referred to as a “named layer.” If the layer has a TITLE but no NAME (see TITLE), then that layer is only a category title for all the layers nested within and cannot be requested. You need to access the names of the internal layers to request the corresponding maps. If a containing category does have a NAME, you can use this name to request all of the nested layers at one time. For example, a parent layer “Roads” may have children “Interstates” and “State Highways” and allow the user to request either child individually or both together. The NAME element is not inherited by child layers.

Keywords


None

Examples


The following example connects to an OGC server and calls GetCapabilities, GetLayers, and GetMap to return data from the server. Elements of the structure returned by GetLayers provide the required request parameters of the query defining the map file to return.

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

;-----------------------------------------------------------------
FUNCTION ogc_wms_status_callback, status, data
   PRINT, status
   RETURN, 1
END
 
;-----------------------------------------------------------------
PRO ogc_wms_GetMap_example
   compile_opt idl2
   ; Catch all errors and display an error dialog.
   CATCH, errorStatus
   IF (errorStatus NE 0) THEN BEGIN
      CATCH, /CANCEL
      PRINT, !error_state.msg
      RETURN
   ENDIF
 
   ; Create a new OGC WMS object.
   owms = OBJ_NEW('idlnetogcwms')
 
   ; Set a callback so we can see some status messages
   owms->SetProperty, CALLBACK_FUNCTION ='ogc_wms_status_callback'
 
   ; Get required property values by parsing URL.
   url ='http://igskmncngs056.cr.usgs.gov/wmsconnector/' + $
      'com.esri.wms.Esrimap/world?'
   owms->ParseURL, url
 
   ; Determine what information is available.
   count = oWMS->GetCapabilities()
 
   ; Make sure server returned layers.
   IF count EQ 0 THEN BEGIN
      void = $
         DIALOG_MESSAGE('No information avaiable from WMS server')
      RETURN
   ENDIF
 
   ; Get a single second level entry.
   xlayer = owms->GetLayers(INDEX=1, NUMBER=1, COUNT=cnt)
 
   ; Get name.
   vLayerName = xlayer[0].name
 
   ; Get style.
   vStyle = ''
   IF (xlayer[0].num_style NE 0) THEN BEGIN
      vStyle = xlayer[0].style[0].name
   ENDIF
 
   ; Determine spatial reference system.
   IF (xlayer[0].version EQ '1.3.0') THEN BEGIN
      vCrs = xlayer[0].crs
   ENDIF ELSE BEGIN
      vCrs = xlayer[0].srs
   ENDELSE
 
   ; Get a bounding box
   vBBox =    xlayer[0].bounding_box[0].minx + $
      ', ' + xlayer[0].bounding_box[0].miny + $
      ', ' + xlayer[0].bounding_box[0].maxx + $
      ', ' + xlayer[0].bounding_box[0].maxy
 
   ; Get map format.
   IF (xlayer[0].num_map_format NE 0) THEN BEGIN
      vMapFmt = xlayer[0].map_format
   ENDIF
 
   ; Hard-code width and height.
   width  = '500'
   height = '500'
 
   ; Create layer query string of required request elements.
   queryString = 'LAYERS=' + vLayerName
   queryString = queryString + '&STYLES=' + vStyle
   queryString = queryString + '&SRS='    + vCrs
   queryString = queryString + '&BBOX='   + $
      STRCOMPRESS(vBBox, /REMOVE_ALL)
   queryString = queryString + '&WIDTH='  + width
   queryString = queryString + '&HEIGHT=' + height
   queryString = queryString + '&FORMAT=' + vMapFmt
 
   ; Submit request for first file.
   mapFile = oWMS->GetMap(queryString[0])
 
   ; Print location of map file.
   PRINT, 'file retrieved = ', mapfile
   OBJ_DESTROY, owms
 
   ; Scale the map image data into byte range and
   ; open in the iImage iTool.
   imgData = READ_IMAGE(mapfile)
   iImage, BYTSCL(imgData)
END

Version History


6.4

Introduced

See Also


IDLnetOGCWMS::GetLayers, IDLnetOGCWMS::GetFeatureInfo



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us