# 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.

<GDAL_WMS> |
<Service name="WMS"> | Define what mini-driver to use, currently supported are: WMS, WorldWind, TileService. (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)
<Layers>modis,global_mosaic</Layers> | Comma separated list of layers. (required)
<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)
<UpperLeftX>-180.0</UpperLeftX> | X (longitude) coordinate of upper-left corner. (optional, defaults to -180.0)
<UpperLeftY>90.0</UpperLeftY> | Y (latitude) coordinate of upper-left corner. (optional, defaults to 90.0)
<LowerRightX>180.0</LowerRightX> | X (longitude) coordinate of lower-right corner. (optional, defaults to 180.0)
<LowerRightY>-90.0</LowerRightY> | Y (latitude) coordinate of lower-right corner. (optional, defaults to -90.0)
<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. (ignored for WMS, 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)
</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)
<BlockSizeX>1024</BlockSizeX> | Block size in pixels. (optional, defaults to 1024)
<BlockSizeY>1024</BlockSizeY> | Block size in pixels. (optional, defaults to 1024)
<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)
<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> |
<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)
</GDAL_WMS> |

## OGC Web Map Service

Accessing a WMS server is accomplished by creating a local service description xml file looking something like the following. It is important that there be no spaces or other content before the `<GDAL_WMS>` element.

    <GDAL_WMS>
        <Service name="WMS">
            <Version>1.1.1</Version>
            <ServerUrl>http://onearth.jpl.nasa.gov/wms.cgi?</ServerUrl>
            <SRS>EPSG:4326</SRS>
            <ImageFormat>image/jpeg</ImageFormat>
            <Layers>modis,global_mosaic</Layers>
            <Styles></Styles>
        </Service>
        <DataWindow>
            <UpperLeftX>-180.0</UpperLeftX>
            <UpperLeftY>90.0</UpperLeftY>
            <LowerRightX>180.0</LowerRightX>
            <LowerRightY>-90.0</LowerRightY>
            <SizeX>2666666</SizeX>
            <SizeY>1333333</SizeY>
        </DataWindow>
        <Projection>EPSG:4326</Projection>
        <BandsCount>3</BandsCount>
    </GDAL_WMS>

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_WMS>
        <Service name="WMS">
            <Version>1</Version>
            <ServerUrl>http://labs.metacarta.com/wms-c/Basic.py?</ServerUrl>
            <Layers>basic</Layers>
        </Service>
        <DataWindow>
            <UpperLeftX>-180.0</UpperLeftX>
            <UpperLeftY>90.0</UpperLeftY>
            <LowerRightX>180.0</LowerRightX>
            <LowerRightY>-90.0</LowerRightY>
            <SizeX>268435456</SizeX>
            <SizeY>134217728</SizeY>
            <TileLevel>19</TileLevel>
        </DataWindow>
        <Projection>EPSG:4326</Projection>
        <OverviewCount>19</OverviewCount>
        <BlockSizeX>256</BlockSizeX>
        <BlockSizeY>256</BlockSizeY>
        <BandsCount>3</BandsCount>
    </GDAL_WMS>

## TileService

TileService is a specific type of request format used by WorldWind. It is described as being "a bunch of PHP scripts used to serve image data to World Wind, GDAL and some other software."

Example TileService Configuration:

    <GDAL_WMS>
        <Service name="TileService">
            <Version>1</Version>
            <ServerUrl>http://s0.tileservice.worldwindcentral.com/getTile?</ServerUrl>
            <Dataset>za.johannesburg_2006_20cm</Dataset>
        </Service>
        <DataWindow>
            <UpperLeftX>-180.0</UpperLeftX>
            <UpperLeftY>90.0</UpperLeftY>
            <LowerRightX>180.0</LowerRightX>
            <LowerRightY>-90.0</LowerRightY>
            <SizeX>268435456</SizeX>
            <SizeY>134217728</SizeY>
            <TileLevel>19</TileLevel>
        </DataWindow>
        <Projection>EPSG:4326</Projection>
        <OverviewCount>16</OverviewCount>
        <BlockSizeX>512</BlockSizeX>
        <BlockSizeY>512</BlockSizeY>
        <BandsCount>3</BandsCount>
    </GDAL_WMS>

- :

See Also:

- OGC WMS Standards
- WMS Tiling Client Recommendation
- TileService