TDS Web Map Service (WMS)

The TDS WMS implementation uses the ncWMS software developed by Jon Blower (Reading E-Science Center at the University of Reading).

It supports OGC Web Map Service (WMS) versions 1.3.0 and 1.1.1.

Which files can be served through the WMS server?

Data files must contain gridded data.
The NetCDF-Java Common Data Model must be able to identify the coordinates system used. Check this by opening in the Grid Panel of the ToolsUI application. There should be one or more variables shown as a GeoGrid.

Enabling and Using WMS

By default the WMS service is disabled in the TDS. It can be enabled for locally served datasets by including the following in the threddsConfig.xml file:

<WMS>
  <allow>true</allow>
</WMS>

Once WMS is enabled, datasets can be configured to have a WMS access method in the TDS catalog configuration files similar to how other services are configured. The service element's serviceType and base attribute values must be as follows:

<service name="wms" serviceType="WMS" base="/thredds/wms/" />

The dataset to be served must reference this service (or a containing compound service) by the service name:

<dataset ID="sample" name="Sample Data" urlPath="sample.nc">
  <serviceName>wms</serviceName>
</dataset>

WMS clients may not be able to directly use the THREDDS catalogs to find the WMS services but the catalogs are useful for users to browse and for separate search services (e.g., OGC catalog services).

WMS Configuration

Additional WMS configuration options can be set in the threddsConfig.xml file. More details on these options are available here.

Further WMS configuration properties are set in the wmsConfig.xml file. These properties are mainly related with styling of WMS images. Similar to the threddsConfig.xml file, the WMS configuration file (wmsConfig.xml) is found in the ${tomcat_home}/content/thredds directory.

If you are installing a new TDS, you should find a default wmsConfig.xml file (along with other configuration files) in your content/thredds directory after you first deploy the TDS. If you are upgrading from a TDS version before version 4.2.20100615.*, you will have to copy the default file from ${tomcat_home}/webapps/thredds/WEB-INF/altContent/startup/wmsConfig.xml.

Overview of the config file

The file allows the system administrator to configure default style information at a number of levels:

Global defaults that apply to the entire server
Overrides for specific parameters (identified by standard names), applied to all datasets
Overrides for specific datasets
Overrides for specific variables within a dataset

Each level of configuration in the list above overrides the previous ones. The sections below give examples of each level of configuration.

Properties that can be configured

The config file allows the following properties to be configured:

Property key	Syntax/possible values	Level	Meaning
allowFeatureInfo	`true` or `false`	Global or per-dataset	Whether or not the GetFeatureInfo operation is allowed for a dataset*
defaultColorScaleRange	`min` `max` (two floating-point numbers, separated by a space)	Global, per-standard name or per-variable	A sensible value range, to be applied to the bottom and top of the colour scale. Does not have to be precise.
defaultPaletteName	palette name	Global, per-standard name or per-variable	The name of the default palette to be used
defaultNumColorBands	integer between 5 and 254 inclusive	Global, per-standard name or per-variable	The number of individual colours to use by default in creating images
logScaling	`true` or `false`	Global, per-standard name or per-variable	Whether to use logarithmic or linear spacing of values along the colour scale. Logarithmic spacing is appropriate for variables whose values span several orders of magnitude, and are always greater than zero

*The allowFeatureInfo property is almost always enabled (i.e. set "true"). It can be disabled in rare cases in which the sysadmin does not wish to expose data values through this operation.

Note that these quantities must always be defined in the config file in this order, otherwise validation will fail. (It is OK to omit quantities, except in the global defaults section.)

Config file examples

A simple config file

The simplest legal config file contains only global defaults. The example below omits the DTD declaration for brevity: please do not omit this in your wmsConfig.xml file, or the automatic validation will not work:

<wmsConfig>
    <global>
        <defaults>
            <allowFeatureInfo>true</allowFeatureInfo>
            <defaultColorScaleRange>-50 50</defaultColorScaleRange>
            <defaultPaletteName>rainbow</defaultPaletteName>
            <defaultNumColorBands>254</defaultNumColorBands>
            <logScaling>false</logScaling>
        </defaults>
    </global>
</wmsConfig>

Most of these defaults will be acceptable for most datasets on your server. However, the defaultColorScaleRange will not be appropriate for many of the variables you are serving. Note that all five quantities must be defined in this section.

Overriding settings based upon standard names

One way to define more sensible defaults is to override the global default settings for all variables with certain CF standard names (see �here) for a current list of standard names. For example, the file below sets a colour scale range for all variables with the standard name of sea_water_temperature and defines that chlorophyll measurements should be displayed with a logarithmic scaling.

<wmsConfig>
    <global>
        <defaults>
            ... (omitted for brevity: still mandatory in the config file)
        </defaults>
        <standardNames>
            <standardName name="sea_water_temperature" units="K">
                <defaultColorScaleRange>268 308</defaultColorScaleRange>
            </standardName>
            <standardName name="mass_concentration_of_chlorophyll_in_sea_water" units="kg m-3">
                <logScaling>true</logScaling>
            </standardName>
        </standardNames>
    </global>
</wmsConfig>

A few things are noteworthy here:

Any properties that are not set on a per-standard name basis will be taken from the global defaults.
These defaults are still considered "global" and will apply to all datasets unless overridden on a per-dataset basis.
It is mandatory to specify the units in which you are specifying the default colour scale range. If a variable in one of your datasets uses the same standard name but different units, the scale will automatically be converted to the new units, provided that the units can be identified as valid UDUNITS strings.

Per-dataset overrides

You may specify settings for particular datasets, which override any settings in the <global> section. The only tricky part is creating a string that identifies a dataset. In THREDDS, datasets are identified by their URL path. For example, for the WMS capabilities document at:

http://myserver.com/thredds/wms/NCOF/POLCOMS/IRISH_SEA/POLCOMS-Irish-Sea_best.ncd?service=WMS&version=1.3.0&request=GetCapabilities

the URL path is NCOF/POLCOMS/IRISH_SEA/POLCOMS-Irish-Sea_best.ncd. It is the part of the above URL that is unique to the dataset.

To specify that all variables in this dataset should use the occam palette, use the following config file:

<wmsConfig>
    <global>
        ...
    </global>
    <overrides>
        <datasetPath pathSpec="NCOF/POLCOMS/IRISH_SEA/POLCOMS-Irish-Sea_best.ncd">
            <pathDefaults>
                <defaultPaletteName>occam</defaultPaletteName>
            </pathDefaults>
        </datasetPath>
    </overrides>
</wmsConfig>

Note that the pathSpec also accepts wildcards. So you could also have set:

<datasetPath pathSpec="NCOF/POLCOMS/IRISH_SEA/*.ncd">

which would match all URL paths with the above pattern. If you specify a number of pathSpecs that all match the same URL path, the longest pattern is deemed to be the most specific and will be used. So, for example, in the config file below:

<wmsConfig>
    <global>
        ...
    </global>
    <overrides>
        <datasetPath pathSpec="NCOF/*">
            <pathDefaults>
                <defaultPaletteName>redblue</defaultPaletteName>
            </pathDefaults>
        </datasetPath>
        <datasetPath pathSpec="NCOF/POLCOMS/IRISH_SEA/POLCOMS-*.ncd">
            <pathDefaults>
                <defaultPaletteName>occam</defaultPaletteName>
            </pathDefaults>
        </datasetPath>
    </overrides>
</wmsConfig>

The dataset with URL path NCOF/POLCOMS/IRISH_SEA/POLCOMS-Irish-Sea_best.ncd matches both pathSpecs, but the second pathSpec is longer, and so the dataset will use the occam palette by default. However, the URL path NCOF/METOFFICE/foo/bar.nc only matches the first pathSpec and will use the redblue palette.

Per-variable overrides

The most specific (and most verbose) way to specify a style is to specify the style of a particular variable within a particular dataset. Variables are identified by their internal names (note: not their standard names) with a dataset. For example, the following config file overrides the global default colour scale range for a particular variable within a dataset:

<wmsConfig>
    <global>
        ...
    </global>
    <overrides>
        <datasetPath pathSpec="NCOF/POLCOMS/IRISH_SEA/POLCOMS-*.ncd">
            <pathDefaults>
                ... (can still specify defaults for this dataset)
            </pathDefaults>
            <variables>
                <variable id="TMP">
                    <defaultColorScaleRange>280 290</defaultColorScaleRange>
                </variable>
                <variable id="SAL">
                    <defaultColorScaleRange>30 35</defaultColorScaleRange>
                </variable>
            </variables>
        </datasetPath>
        <datasetPath pathSpec="foo/bar">
            ...
        </datasetPath>
    </overrides>
</wmsConfig>

Change to CRS List in WMS GetCapabilities Documents

The number of CRS listed in the WMS GetCapabilities documents has been reduced between TDS 4.1 and 4.2. More information is available at this FAQ entry.

Add a JVM Option to Avoid an X Server Bug

WMS uses a number of graphics packages. In some situations, WMS can run into an X Server bug that can cause Tomcat to crash. This can be avoided by telling the code there is no display device. You may see error messages like the following:

"java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment"

To avoid this situation, the graphics code needs to be told that there is no graphics console available. This can be done by setting the java.awt.headless system property to true which can be done using JAVA_OPTS:

JAVA_OPTS="-Xmx1024m -Xms256m -server -Djava.awt.headless=true"
export JAVA_OPT

What the option means:

-Djava.awt.headless=true sets the value of the java.awt.headless system property to true. Setting this system property to true prevent graphics rendering code from assuming that a graphics console exists.

More on using the headless mode in Java SE here.

Add a JVM Option to Avoid java.util.prefs Problem Storing System Preferences

Some libraries that WMS depends on use the java.util.prefs package and there are some known issues that can crop up with storing system preferences. This problem can be avoided by setting the java.util.prefs.systemRoot system property to point to a directory in which the TDS can write. The given directory must exist and must contain a directory named ".systemPrefs" which must be writable by the user under which Tomcat is run.

JAVA_OPTS="-Xmx1024m -Xms256m -server -Djava.util.prefs.systemRoot=$CATALINA_HOME/content/thredds/javaUtilPrefs"
export JAVA_OPT

What the option means:

-Djava.util.prefs.systemRoot=<directory> sets the value of the java.util.prefs.systemRoot system property to the given directory. The java.util.prefs code will use the given directory to persist the system (as opposed to user) preferences.

More information on the issue can be found on the TDS FAQ page.

Serving Remote Datasets

The TDS can also serve remote datasets with the WMS protocol if configured to do so. It must be explicitly configured in the threddsConfig.xml configuration file. This is done by adding an allowRemote element to the WMS element as follows:

<WMS>
  <allow>true</allow>
  <allowRemote>true</allowRemote>
  ...
</WMS>

A slight extension of the WMS Dataset URL format allows the TDS to serve remote datasets. The dataset is identified by adding the parameter dataset whose value is a URL:

http://servername:8080/thredds/wms?dataset=datasetURL

The URL must be a dataset readable by the NetCDF-Java library, typically an OPeNDAP dataset on another server. It must have gridded data with identifiable coordinate systems (see above). For example, an OPeNDAP URL might be

http://las.pfeg.noaa.gov/cgi-bin/nph-dods/data/oceanwatch/nrt/gac/AG14day.nc

This can be served remotely as a WMS dataset with this URL:

http://servername:8080/thredds/wms?dataset=http://las.pfeg.noaa.gov/cgi-bin/nph-dods/data/oceanwatch/nrt/gac/AG14day.nc

Capabilities/Limitations

This document is maintained by Unidata. Send comments to THREDDS support.