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.

<GDAL_WMS>
<Service name="WMS"> Define what mini-driver to use, currently supported are: WMS, WorldWind, TileService, TMS, TiledWMS or VirtualEarth. (required)
<Version>1.1.1</Version> WMS version. (optional, defaults to 1.1.1)
<ServerUrl>http://onearth.jpl.nasa.gov/wms.cgi?</ServerUrl> WMS server URL. (required)
<SRS>EPSG:4326</SRS> Image projection (optional, defaults to EPSG:4326, WMS version 1.1.1 or below only)
<CRS>CRS:83</CRS> Image projection (optional, defaults to EPSG:4326, WMS version 1.3.0 or above only)
<ImageFormat>image/jpeg</ImageFormat> Format in which to request data. Paletted formats like image/gif will be converted to RGB. (optional, defaults to image/jpeg)
<Transparent>FALSE</Transparent> Set to TRUE to include "transparent=TRUE" in the WMS GetMap request (optional defaults to FALSE).  The request format and BandsCount need to support alpha.
<Layers>modis%2Cglobal_mosaic</Layers> A URL encoded, comma separated string of layers (required, except for TiledWMS)
<TiledGroupName>Clementine</TiledGroupName> Comma separated list of layers. (required for TiledWMS)
<Styles></Styles> Comma separated list of styles. (optional)
<BBoxOrder>xyXY</BBoxOrder> Reorder bbox coordinates arbitrarly. May be required for version 1.3 servers. (optional)
x - low X coordinate, y - low Y coordinate, X - high X coordinate, Y - high Y coordinate
</Service>
<DataWindow> Define size and extents of the data. (required, except for TiledWMS and VirtualEarth)
<UpperLeftX>-180.0</UpperLeftX> X (longitude) coordinate of upper-left corner. (optional, defaults to -180.0, except for VirtualEarth)
<UpperLeftY>90.0</UpperLeftY> Y (latitude) coordinate of upper-left corner. (optional, defaults to 90.0, except for VirtualEarth)
<LowerRightX>180.0</LowerRightX> X (longitude) coordinate of lower-right corner. (optional, defaults to 180.0, except for VirtualEarth)
<LowerRightY>-90.0</LowerRightY> Y (latitude) coordinate of lower-right corner. (optional, defaults to -90.0, except for VirtualEarth)
<SizeX>2666666</SizeX> Image size in pixels.
<SizeY>1333333</SizeY> Image size in pixels.
<TileX>0</TileX> Added to tile X value at highest resolution. (ignored for WMS, tiled image sources only, optional, defaults to 0)
<TileY>0</TileY> Added to tile Y value at highest resolution. (ignored for WMS, tiled image sources only, optional, defaults to 0)
<TileLevel>0</TileLevel> Tile level at highest resolution. (tiled image sources only, optional, defaults to 0)
<TileCountX>0</TileCountX> Can be used to define image size, SizeX = TileCountX * BlockSizeX * 2TileLevel. (tiled image sources only, optional, defaults to 0)
<TileCountY>0</TileCountY> Can be used to define image size, SizeY = TileCountY * BlockSizeY * 2TileLevel. (tiled image sources only, optional, defaults to 0)
<YOrigin>top</YOrigin> Can be used to define the position of the Y origin with respect to the tile grid. Possible values are 'top', 'bottom', and 'default', where the default behavior is mini-driver-specific. (TMS mini-driver only, optional, defaults to 'bottom' for TMS)
</DataWindow>
<Projection>EPSG:4326</Projection> Image projection (optional, defaults to value reported by mini-driver or EPSG:4326)
<BandsCount>3</BandsCount> Number of bands/channels, 1 for grayscale data, 3 for RGB. (optional, defaults to 3)
<DataType>Byte</DataType> Band data type, amont Byte, Int16, UInt16, Int32, UInt32, Float32, Float64, etc.. (optional, defaults to Byte)
<BlockSizeX>1024</BlockSizeX> Block size in pixels. (optional, defaults to 1024, except for VirtualEarth)
<BlockSizeY>1024</BlockSizeY> Block size in pixels. (optional, defaults to 1024, except for VirtualEarth)
<OverviewCount>10</OverviewCount> Count of reduced resolution layers each having 2 times lower resolution. (optional, default is calculated at runtime)
<Cache> Enable local disk cache. Allows for offline operation. (optional, defaults to no cache)
<Path>./gdalwmscache</Path> Location where to store cache files. It is safe to use same cache path for different data sources. (optional, defaults to ./gdalwmscache if GDAL_DEFAULT_WMS_CACHE_PATH configuration option is not specified)
<Depth>2</Depth> Number of directory layers. 2 will result in files being written as cache_path/A/B/ABCDEF... (optional, defaults to 2)
<Extension>.jpg</Extension> Append to cache files. (optional, defaults to none)
</Cache>
<MaxConnections>2</MaxConnections> Maximum number of simultaneous connections. (optional, defaults to 2)
<Timeout>300</Timeout> Connection timeout in seconds. (optional, defaults to 300)
<OfflineMode>true</OfflineMode> Do not download any new images, use only what is in cache. Usefull only with cache enabled. (optional, defaults to false)
<AdviseRead>true</AdviseRead> Enable AdviseRead API call - download images into cache. (optional, defaults to false)
<VerifyAdviseRead>true</VerifyAdviseRead> Open each downloaded image and do some basic checks before writing into cache. Disabling can save some CPU cycles if server is trusted to always return correct images. (optional, defaults to true)
<ClampRequests>false</ClampRequests> Should requests, that otherwise would be partially outside of defined data window, be clipped resulting in smaller than block size request. (optional, defaults to true)
<UserAgent>GDAL WMS driver (http://www.gdal.org/frmt_wms.html)</UserAgent> HTTP User-agent string. Some servers might require a well-known user-agent such as "Mozilla/5.0" (optional, defaults to "GDAL WMS driver (http://www.gdal.org/frmt_wms.html)"). Added in GDAL 1.8.0
<UserPwd>user:password</UserPwd> User and Password for HTTP authentication (optional). Added in GDAL 1.10.0
<Referer>http://example.foo/</Referer> HTTP Referer string. Some servers might require it (optional). Added in GDAL 1.9.0
<ZeroBlockHttpCodes>204,404</ZeroBlockHttpCodes> Comma separated list of HTTP response codes that will be interpreted as a 0 filled image (i.e. black for 3 bands, and transparent for 4 bands) instead of aborting the request. Added in GDAL 1.9.0. (optional, defaults to 204)
<ZeroBlockOnServerException>true</ZeroBlockOnServerException> Wether to treat a Service Exception returned by the server as a 0 filled image instead of aborting the request. Added in 1.9.0. (optional, defaults to false)
</GDAL_WMS>

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
    
Output:
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 :

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>
Most of the other information is automatically fetched from the remote server using the GetTileService method at open time.

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 :

Examples

Open syntax

The WMS driver can open :

See Also: