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.
By default the WMS service is disabled in the TDS. It can be enabled for locally
served datasets by including the following in the
<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).
Additional WMS configuration options can be set in the
threddsConfig.xml file. More details on these options are
Further WMS configuration properties are set in the
wmsConfig.xml file. These
properties are mainly related with styling of WMS images. Similar to the
file, the WMS configuration file (
wmsConfig.xml) is found in the
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
you will have to copy the default file from
The file allows the system administrator to configure default style information at a number of levels:
Each level of configuration in the list above overrides the previous ones. The sections below give examples of each level of configuration.
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.)
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.
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:
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:
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:
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.
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>
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.
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
java.awt.headless system property to
true which can be done
JAVA_OPTS="-Xmx1024m -Xms256m -server -Djava.awt.headless=true" export JAVA_OPT
What the option means:
java.awt.headlesssystem 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.
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 "
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:
java.util.prefs.systemRootsystem 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.
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:
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
This can be served remotely as a WMS dataset with this URL: