WMS -- Web Map Services

Accessing several different types of web image services is possible using the WMS format in GDAL. Services are accessed by creating a local service description XML file -- there are examples below for each of the supported image services. It is important that there be no spaces or other content before the <GDAL_WMS> element.

Minidrivers

The GDAL WMS driver has support for several internal 'minidrivers', which allow access to different web mapping services. Each of these services may support a different set of options in the Service block.

WMS

Communications with an OGC WMS server. Has support for both tiled and untiled requests.

Starting with GDAL >= 1.10, WMS layers can be queried (through a GetFeatureInfo request) with the gdallocationinfo utility, or with a GetMetadataItem("Pixel_iCol_iLine", "LocationInfo") call on a band object.

gdallocationinfo "WMS:http://demo.opengeo.org/geoserver/gwc/service/wms?SERVICE=WMS&VERSION=1.1.1&
                            REQUEST=GetMap&LAYERS=og%3Abugsites&SRS=EPSG:900913&
                            BBOX=-1.15841845090625E7,5479006.186718751,-1.1505912992109375E7,5557277.703671876&
                            FORMAT=image/png&TILESIZE=256&OVERVIEWCOUNT=25&MINRESOLUTION=0.0046653459640220&TILED=true"
                           -geoloc -11547071.455 5528616 -xml -b 1
    

Report pixel="248595" line="191985">
  <BandReport band="1">
    <LocationInfo>
      <wfs:FeatureCollection xmlns="http://www.opengis.net/wfs"
                                xmlns:wfs="http://www.opengis.net/wfs"
                                xmlns:gml="http://www.opengis.net/gml"
                                xmlns:og="http://opengeo.org"
                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                xsi:schemaLocation="http://opengeo.org http://demo.opengeo.org/geoserver/wfs?service=WFS&version=1.0.0&request=DescribeFeatureType&typeName=og%3Abugsites http://www.opengis.net/wfs http://demo.opengeo.org/geoserver/schemas/wfs/1.0.0/WFS-basic.xsd">
        <gml:boundedBy>
          <gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#26713">
            <gml:coordinates xmlns:gml="http://www.opengis.net/gml" decimal="." cs="," ts=" ">601228,4917635 601228,4917635</gml:coordinates>
          </gml:Box>
        </gml:boundedBy>
        <gml:featureMember>
          <og:bugsites fid="bugsites.40946">
            <gml:boundedBy>
              <gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#26713">
                <gml:coordinates xmlns:gml="http://www.opengis.net/gml" decimal="." cs="," ts=" ">601228,4917635 601228,4917635</gml:coordinates>
              </gml:Box>
            </gml:boundedBy>
            <og:cat>86</og:cat>
            <og:str1>Beetle site</og:str1>
            <og:the_geom>
              <gml:Point srsName="http://www.opengis.net/gml/srs/epsg.xml#26713">
                <gml:coordinates xmlns:gml="http://www.opengis.net/gml" decimal="." cs="," ts=" ">601228,4917635</gml:coordinates>
              </gml:Point>
            </og:the_geom>
          </og:bugsites>
        </gml:featureMember>
      </wfs:FeatureCollection>
    </LocationInfo>
    <Value>255</Value>
  </BandReport>
</Report>
    

TileService

Service to support talking to a WorldWind TileService. Access is always tile based.

WorldWind

Access to web-based WorldWind tile services. Access is always tile based.

TMS (GDAL 1.7.0 and later)

The TMS Minidriver is designed primarily to support the users of the TMS Specification. This service supports only access by tiles.

Because TMS is similar to many other 'x/y/z' flavored services on the web, this service can also be used to access these services. To use it in this fashion, you can use replacement variables, of the format ${x}, ${y}, etc.

Supported variables (name is case sensitive) are :

• ${x} -- x position of the tile
• ${y} -- y position of the tile. This can be either from the top or the bottom of the tileset, based on whether the YOrigin parameter is set to true or false.
• ${z} -- z position of the tile -- zoom level
• ${version} -- version parameter, set in the config file. Defaults to 1.0.0.
• ${format} -- format parameter, set in the config file. Defaults to 'jpg'.
• ${layer} -- layer parameter, set in the config file. Defaults to nothing.

A typical ServerURL might look like:
http://tilecache.osgeo.org/wms-c/Basic.py/${version}/${layer}/${z}/${x}/${y}.${format}
In order to better suit TMS users, any URL that does not contain "${" will automatically have the string above (after "Basic.py/") appended to their URL.

The TMS Service has 3 XML configuration elements that are different from other services: Format which defaults to jpg, Layer which has no default, and Version which defaults to 1.0.0.

Additionally, the TMS service respects one additional parameter, at the DataWindow level, which is the YOrigin element. This element should be one of bottom (the default in TMS) or top, which matches OpenStreetMap and many other popular tile services.

Two examples of usage of the TMS service are included in the examples below.

OnEarth Tiled WMS (GDAL 1.9.0 and later)

The OnEarth Tiled WMS minidriver supports the Tiled WMS specification implemented for the JPL OnEarth driver per the specification at http://onearth.jpl.nasa.gov/tiled.html.

A typical OnEarth Tiled WMS configuration file might look like:

<GDAL_WMS>
    <Service name="TiledWMS">
	<ServerUrl>http://onmoon.jpl.nasa.gov/wms.cgi?</ServerUrl>
	<TiledGroupName>Clementine</TiledGroupName>
    </Service>
</GDAL_WMS>

VirtualEarth (GDAL 1.9.0 and later)

Access to web-based Virtual Earth tile services. Access is always tile based.

The ${quadkey} variable must be found in the ServerUrl element.

The DataWindow element might be omitted. The default values are :

• UpperLeftX = -20037508.34
• UpperLeftY = 20037508.34
• LowerRightX = 20037508.34
• LowerRightY = -20037508.34
• TileLevel = 19
• OverviewCount = 18
• SRS = EPSG:900913
• BlockSizeX = 256
• BlockSizeY = 256

ArcGIS REST API (GDAL 2.0 and later)

Access to ArcGIS REST map service resource (untiled requests).

AGS layers can be queried (through a GetFeatureInfo request) with the gdallocationinfo utility, or with a GetMetadataItem("Pixel_iCol_iLine", "LocationInfo") call on a band object.

gdallocationinfo -wgs84 "<GDAL_WMS><Service name=\"AGS\"><ServerUrl>http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer</ServerUrl><BBoxOrder>xyXY</BBoxOrder><SRS>3857</SRS></Service><DataWindow><UpperLeftX>-20037508.34</UpperLeftX><UpperLeftY>20037508.34</UpperLeftY><LowerRightX>20037508.34</LowerRightX><LowerRightY>-20037508.34</LowerRightY><SizeX>512</SizeX><SizeY>512</SizeY></DataWindow></GDAL_WMS>" -75.704 39.75
    

Internet Imaging Protocol (IIP) (GDAL 2.1 and later)

Access to images served through IIP protocol. The server must support the JTL (Retrieve a tile as a complete JFIF image) extension of the IIP protocol.

If using the XML syntax, the ServerURL must contain the FIF parameter.

Otherwise it is also possible to use "IIP:http://foo.com/FIF=image_name" syntax as connection string, to retrieve from the server information on the full resolution dimension and the number of resolutions.

The XML definition can then be generated with "gdal_translate IIP:http://foo.com/FIF=image_name out.xml -of WMS"

Examples

• onearth_global_mosaic.xml - Landsat mosaic from a OnEarth WMS server
  

  gdal_translate -of JPEG -outsize 500 250 onearth_global_mosaic.xml onearth_global_mosaic.jpg

  gdal_translate -of JPEG -projwin -10 55 30 35 -outsize 500 250 onearth_global_mosaic.xml onearth_global_mosaic2.jpg

  Note : this particular server does no longer accept regular WMS queries.

• metacarta_wmsc.xml - It is possible to configure a WMS Service conforming to a WMS-C cache by specifying a number of overviews and specifying the 'block size' as the tile size of the cache. The following example is a sample set up for a 19-level "Global Profile" WMS-C cache.

  gdal_translate -of PNG -outsize 500 250 metacarta_wmsc.xml metacarta_wmsc.png

  example output

• tileservice_bmng.xml - TileService, Blue Marble NG (January)
  

  gdal_translate -of JPEG -outsize 500 250 tileservice_bmng.xml tileservice_bmng.jpg

  example output

• tileservice_nysdop2004.xml - TileService, NYSDOP 2004
  

  gdal_translate -of JPEG -projwin -73.687030 41.262680 -73.686359 41.262345 -outsize 500 250 tileservice_nysdop2004.xml tileservice_nysdop2004.jpg

  example output

• OpenStreetMap TMS Service Example: Connect to OpenStreetMap tile service. Note that this file takes advantage of the tile cache; more information about configuring the tile cache settings is available above.
  gdal_translate -of PNG -outsize 512 512 frmt_wms_openstreetmap_tms.xml openstreetmap.png

• MetaCarta TMS Layer Example, accessing the default MetaCarta TMS layer.
  gdal_translate -of PNG -outsize 512 256 frmt_wms_metacarta_tms.xml metacarta.png

• BlueMarble Amazon S3 Example accessed with the TMS minidriver.

• Google Maps accessed with the TMS minidriver.

• ArcGIS MapServer Tiles accessed with the TMS minidriver.

• OnEarth Tiled WMS Clementine, daily, and srtm examples.

• VirtualEarth Aerial Layer accessed with the VirtualEarth minidriver.

• ArcGIS online sample server layer accessed with the ArcGIS Server REST API minidriver.

• IIP online sample server layer accessed with the IIP minidriver.

Open syntax

• a local service description XML file :

  gdalinfo description_file.xml

• the content of a description XML file provided as filename :

  gdalinfo "<GDAL_WMS><Service name=\"TiledWMS\"><ServerUrl>http://onearth.jpl.nasa.gov/wms.cgi?</ServerUrl><TiledGroupName>Global SRTM Elevation</TiledGroupName></Service></GDAL_WMS>"

• (GDAL >= 1.9.0) the base URL of a WMS service, prefixed with WMS: :

  gdalinfo "WMS:http://wms.geobase.ca/wms-bin/cubeserv.cgi"

  A list of subdatasets will be returned, resulting from the parsing of the GetCapabilities request on that server.

• (GDAL >= 1.9.0) a pseudo GetMap request, such as the subdataset name returned by the previous syntax :

  gdalinfo "WMS:http://wms.geobase.ca/wms-bin/cubeserv.cgi?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=DNEC_250K%3AELEVATION%2FELEVATION&SRS=EPSG:42304&BBOX=-3000000,-1500000,6000000,4500000"

• (GDAL >= 1.9.0) the base URL of a Tiled WMS service, prefixed with WMS: and with request=GetTileService as GET argument:

  gdalinfo "WMS:http://onearth.jpl.nasa.gov/wms.cgi?request=GetTileService"

  A list of subdatasets will be returned, resulting from the parsing of the GetTileService request on that server.

• (GDAL >= 2.0.0) the URL of a REST definition for a ArcGIS MapServer:

  gdalinfo "http://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer?f=json&pretty=true"

• (GDAL >= 2.1.0) the URL of a IIP image:

  gdalinfo "IIP:http://merovingio.c2rmf.cnrs.fr/fcgi-bin/iipsrv.fcgi?FIF=globe.256x256.tif"

Generation of WMS service description XML file

gdal_translate "http://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer?f=json" wms.xml -of WMS

See Also:

• OGC WMS Standards
• WMS Tiling Client Recommendation (WMS-C)
• WorldWind TileService
• TMS Specification
• OnEarth Tiled WMS specification
• ArcGIS Server REST API