Detailed configuration of the THREDDS Web Map Service
- Introduction
- Installing the wmsConfig.xml file
- Validating the config file
- Overview of the config file
- Properties that can be configured
- Config file examples
Introduction
The basic configuration for the THREDDS Web Map Service sets simple properties, including whether or not the WMS is enabled and the maximum image width and height. You will also need to configure some more detailed properties, particularly those relating to the styling of WMS images.
THREDDS follows ncWMS's extensions for controlling the styling of images that are requested from the server using the GetMap request. These extensions are described here. The extensions give the client control over which colour palette is used to render an image, and how the data values should map onto the colours of the palette.
It is not always clear to clients of a Web Map Service which values of these "extension" parameters should be used to present data to their best advantage. Additionally, standard WMS clients (which don't understand the ncWMS extensions) need to be able to see sensible default styles. Therefore there is a mechanism for the server administrator to set default styles for each of the datasets served through the WMS. These defaults will be used in the MyOcean View Service when a dataset is first displayed to a user in the web portal. Therefore it is important to be able to specify sensible defaults.
Installing the wmsConfig.xml file
The configuration is performed through a new configuration file, called wmsConfig.xml. If you install a new THREDDS installation from scratch, a sample file will automatically will automatically be placed in ${tomcat.home}/content/thredds. If you have upgraded from a previous installation, you will have to copy this sample file into ${tomcat.home}/content/thredds manually from the WEB-INF/altContent/startup directory.
Validating the config file
The syntactic structure of the config file is defined by its inline DTD (Document Type Definition). Do not edit or remove the DTD declaration. If you are using a DTD-aware text editor, you can validate that your config file is valid, or you may be able to find a command-line tool that validates your file.
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>
