Using Web Mapping Services (WMS)

Xastir comes with a handful of pre-rolled ".geo" files for accessing online OGC-compliant WMS (Web Mapping Service) servers. However, we provide a general purpose capability that can be used to access any WMS server you have a need for, so long as it supports the GetMap and VERSION= keywords, and must support the older version URLS (1.1.1 or 1.0.0).

Requirements for using Web Map Services

You must have curl and GraphicsMagick installed for this process to work. The former is used to handle to the web interaction, the latter to display the images that are returned. These packages are in the package management systems of most operating systems. See Installing Xastir.

Ready-to-use online maps

Xastir installs several files that allow access to WMS servers that we found interesting. Most of these are specific to the United States, because that's where we live and work. Some user-contributed files provide coverage in Canada.

Map name	Description
Online/nationalmap.gov/WMS_USGS_*.geo	several useful maps from the US Geological Survey, worldwide coverage
Online/USTigermap.geo	A good street-level map from the US Census, but of course only helpful if you're in the US
Online/geogratis.gc.ca/	a directory of National, regional, sub-national, and sub-regional online maps of Canada
Online/NWS/	a directory of weather radar overlays (US-specific)

Rolling your own

WMS servers follow a standard for the URLs that provide map images, and Xastir knows how to fill in the blanks needed. All you need to do is provide the base URL that tells which server to connect to, what layers to include in the map, and any other standard-compliant parts of the URL that help refine the map you get. Xastir will fill in the required bounding box.

To get Xastir to use your WMS map source, you must create a ".geo" file that contains the necessary information, and then must place this file in a directory that Xastir searches for maps.

The structure of the file is like this:

WMSSERVER

URL https://tigerweb.geo.census.gov/arcgis/services/TIGERweb/tigerWMS_PhysicalFeatures/MapServer/WMSServer?VERSION=1.1.1&SERVICE=WMS&REQUEST=GetMap&SRS=EPSG:4326&LAYERS=1,2,7,8,10,11,12,13,14,15,17,18,19,20,21,22,23,24&STYLES=&FORMAT=image/png&TRANSPARENT=TRUE

That's it, two lines: the first line should be "WMSSERVER" and then there has to be a URL. This particular URL specifies a US Census "Tiger" map, a large number of layers (roads, railroads, and so forth), that the map produced should be a PNG image file, and that they should be rendered using the default styles. Notably, it specifies "SRS=EPSG:4326" which directs the server to warp the image into WGS84 geographic coordinates before delivering it to us --- this is essential for getting Xastir to render it properly and place it correctly in the world. Specifying anything else here will create a map image you can't use in Xastir.

You need to work out all the parts of the URL with the help of the web site that provides the data

The URL following the URL keyword in the .geo file must be a complete request to the server for a map excpet for specification of the bounding box and image size.

Xastir will put those two things in for you, but the rest of it has to be ready to go. You can try out a few requests in your web browser, adding a "BBOX=", "HEIGHT=", and "WIDTH=" keywoard to the URL.

HEIGHT and WIDTH are the size of the image produced in pixels.

BBOX in the 1.1.1 format is in the form of decimal degrees, with the lower left and upper right corners of the bounding box specified in longitude/latitude order, e.g.:

BBOX=-109.02000,31.36000,-103.00000,37.00000

There must be three digits to the left of the decimal longitudes (pad on the left with 0 if necessary) and two for latitudes (again, pad with 0 if needed). There must be no spaces.

Once you have a URL that works to give you a map image in your browser, you know what you have to put into the .geo file --- just take out the BBOX and height/width specifiers.

In addition to the WMSSERVER and URL keywords, may add the additional keyword "TRANSPARENT" with a hexadecimal color value following it, to indicate to Xastir which color in the image should be considered transparent. Most maps provided by WMS use "0xFFFFFF" as the transparent color unless the URL specifies otherwise. This is useful to use for things like weather radar. The weather radar geo files we provide all have

TRANSPARENT 0xFFFFFF

so that only the pixels that represent radar returns are drawn, and everything else is ignored.

Xastir will add a bounding box to the URL it sends to the server, getting you an image appropriate to where your Xastir window is centered.

You must not use VERSION=1.3.0

Xastir's WMS server code was written before the 1.3.0 WMS standard. As such, it produces URLs that comply with the older standard and WILL NOT WORK if you specify "VERSION=1.3.0" in the URL.

You will find many WMS server documentation that tells you to use that. But if you replace it with "VERSION=1.1.1" in your .geo file Xastir will be telling the server that it's an older format URL and the server should know what to do.

Note that all of our examples do exactly that.

The reason we can't work with the 1.3.0 version is that they've changed the way bounding boxes are specified. Xastir is stuffing in a bounding box in the old format.

Yes, we do intend to update Xastir's WMS code to deal with this change in the standard, but for now, just tell the server to process the URL according to the VERSION=1.1.1 standard and all will be well.

Caching

If you have compiled Xastir with Berkeley DB support, maps downloaded from the server will be cached in your ~/.xastir/map_cache directory so they don't have to be downloaded again every time you come back to the same screen position and zoom level. This provides a functional off-line map capability if you've prepopulated your cache for the area where you'll be working off-line.

Auto-refreshing

For maps like NWS radar images, you don't want a static, cached image, you want Xastir to download a new image periodically.

To do this, simply add a REFRESH keyword to the .geo file. The keyword is followed by a refresh interval in seconds. For example, our NWS CONUS radar geo file does this:

WMSSERVER

URL https://opengeo.ncep.noaa.gov/geoserver/conus/conus_cref_qcd/ows?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&LAYERS=conus_cref_qcd&STYLE=&FORMAT=image/png&TRANSPARENT=TRUE

TRANSPARENT 0xFFFFFF
REFRESH 600

This .geo file asks the server for a radar map, tells Xastir that any pure white pixel in the image should not be rendered, and to refresh the image every ten minutes.

Maps that are auto refreshed are not cached.

Figuring out the layer names

For any WMS request to work, you have to know what the layers are called.

Fortunately, WMS servers provide a "GetCapabilities" feature that lets you know what layers are available and what they are called. Simply replace "GetMap" and all the stuff that follows it in the WMS URL with "GetCapabilities", put that URL into your web browser, and you'll get an XML file of information about the server and what it provides.

You'll have to scan this XML file for a "<Layer>" element and then look for a "<Name>" element within it. For example, here's an excerpt from the National Weather Service's WMS server for weather radar:

Capabilities from NWS CREF_QCD server

...
    <Layer>
      <Title/>
      <Abstract/>
...
      <Layer queryable="1" opaque="0">
        <Name>conus_cref_qcd</Name>
        <Title>conus_cref_qcd</Title>
        <Abstract>Quality Controlled 1km x 1km CONUS Radar Composite Reflectivity. This data is provided Multi-Radar-Multi-Sensor (MRMS) algorithm.</Abstract>
...

Here, the layer name we want is conus_cref_qcd and that's what we'd provide in the URL. It's the thing in the "Name" block we want, not the "Title".

This can sometimes be a challenge to figure out, as a lot of WMS servers have gone to simply having layers named as numbers, and you have to figure out which number corresponds to which layer you actually want. For example, the US Census used to have layers named nice, logical things like "Primary Roads", but then changed that to "24".

The XML capabilities file will usually have enough information in it for you to work out the correspondence between layer names and the information you want.

Capabilities from the Tigerweb Physical Features server

...
    <Layer>
      <Title><![CDATA[Census Physical Features WMS]]></Title>
      ...
      <Layer queryable="1">
        <Title><![CDATA[Other]]></Title>
        <Abstract><![CDATA[]]></Abstract>
      ... 
      <Layer queryable="1">
        <Name>1</Name>
        <Title><![CDATA[Military Installations Labels]]></Title>
        <Abstract><![CDATA[Military Installations labels; January 1, 2025]]></Abstract>
...
      <Layer queryable="1">
        <Name>2</Name>
        <Title><![CDATA[Military Installations]]></Title>
        <Abstract><![CDATA[Military Installations; January 1, 2025]]></Abstract>

Here we have names 1, 2, etc. and the title thankfully describes what the layer contains. The numbers are what we'll put into the LAYERS part of the URL. This is how the URL in the USTigermap.geo file was constructed.

It might be helpful to use VERSION=1.3.0 in GetCapabilities requests

While Xastir can't deal with the newer format URLs of version 1.3.0 of the WMS standard, you might want to use it when you're using the GetCapabilities feature in your web browser. In my case, using 1.1.1 causes my browser to download the XML data to a file, whereas 1.3.0 provides it directly to be viewed in my browser. Your mileage may vary.

QGIS can be your friend

If you're really having a hard time working out layer names to use, the QGIS open-source GIS can really help. You can tell QGIS the base url of the server you want to use, such as the one for the US Tiger Physical Features WMS server and when you "connnect" to that server it'll give you a complete list of available layers, complete with their names.

You can even select the layers and see what the resulting map would look like with the selected layers.

QGIS has a learning curve and it's pretty steep, but for something like this they have a basic tutorial on using WMS that can get you off the ground.

There is a helper script in Xastir's script directory that might help

The "wms.pl" script takes as its command line argument a full URL for a "GetCapabilities" request and attempts to parse its returned XML. If the XML conforms to the assumptions this script makes, it'll output several suggested .geo file contents for use with that site.

Unfortunately, it has been found that many servers return XML that doesn't conform to the assumptions this script makes and so it doesn't work with them (the US Census and the NWS weather radar sites didn't work with it). If it works for you, great, otherwise you've just got to puzzle out the correct layer names yourself by reading that XML.

Yes, we plan to fix that script to make it more robust, but we're volunteers and there's only so much time available.

For more details

See the OGC WMS standard for more details about how to use WMS servers. All the details about the construction of URLs for the WMS API are in there.