From 15fb32f4a960a4278d24538dcebf5265bd228305 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Tue, 26 Nov 2024 09:49:38 -0700 Subject: [PATCH] Add detailed wmsConfig.xml documentation --- .../src/site/pages/thredds/WmsRef.md | 4 +- .../src/site/_data/sidebars/user_sidebar.yml | 4 ++ .../src/site/pages/thredds/WmsConfig.md | 63 +++++++++++++++++++ 3 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 docs/userguide/src/site/pages/thredds/WmsConfig.md diff --git a/docs/quickstart/src/site/pages/thredds/WmsRef.md b/docs/quickstart/src/site/pages/thredds/WmsRef.md index b39081a61d..2dca5ac915 100644 --- a/docs/quickstart/src/site/pages/thredds/WmsRef.md +++ b/docs/quickstart/src/site/pages/thredds/WmsRef.md @@ -1,6 +1,6 @@ --- title: TDS Web Map Service (WMS) -last_updated: 2020-08-24 +last_updated: 2020-11-26 sidebar: quickstart_sidebar toc: false permalink: adding_wms.html @@ -43,7 +43,7 @@ Additional WMS configuration options can be set in the `threddsConfig.xml` file. 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 `$tds.content.root.path{}/content/thredds` directory. -A detailed description of the wmsConfig.xml file can be found at the MyOcean "Detailed WMS Configuration" page. +A detailed description of the wmsConfig.xml file can be on the [Customizing WMS](../adminguide/customizing_wms.html) reference page. 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`. diff --git a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml index 09977584ca..5187f7a216 100644 --- a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml +++ b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml @@ -331,6 +331,10 @@ entries: url: /adding_wms.html output: web, pdf + - title: Customizing WMS + url: /customizing_wms.html + output: web, pdf + - title: Configuring TDS With DatasetScan url: /tds_dataset_scan_ref.html output: web, pdf diff --git a/docs/userguide/src/site/pages/thredds/WmsConfig.md b/docs/userguide/src/site/pages/thredds/WmsConfig.md new file mode 100644 index 0000000000..518b336771 --- /dev/null +++ b/docs/userguide/src/site/pages/thredds/WmsConfig.md @@ -0,0 +1,63 @@ +--- +title: Customizing WMS +last_updated: 2021-08-06 +sidebar: user_sidebar +toc: false +permalink: customizing_wms.html +--- + +Several properties related to the generation of images from the WMS service can be configured using the `wmsConfig.xml` file. +By default, this file is located in the `${tds.content.root.path}/thredds` directory. +An example `wmsConfig.xml` file is shipped with the TDS, which looks like: + +{% capture rmd %}{% includefile ../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %} + +~~~xml +{{ rmd }} +~~~ + +This file provides a way to set default values for WMS parameters when they are missing from a request. +In general, you can provide default values for the following properties: + * _allowFeatureInfo_: Allow _GetFeatureInfo_ requests. + * _defaultColorScaleRange_: Range of values to when generating images. + * _defaultPaletteName_: A color palette name (see the [ncWMS User Guide](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap){:target="_blank"} for options). + * _defaultNumColorBands_: The number of colour bands to use. + * _logScaling_: Use a logarithmic scale when generating images. + * _intervalTime_: Deprecated, does not work. + +There are two main elements to the `wmsConfig.xml` file - the ``, and the ``. +Each controls the level of granularity at which default values are chosen. +Settings in `` take precedence over settings in ``. + +## Global + +The `` element contains one `` and one `` child element. +It is within these elements that you can control default settings at a `global` level. + +### Default + +All options must be configured in this section. +These set the default values for all WMS requests. + +### Standard Names + +Values set under `` can be overridden by matching on the value of a `standard_name` attribute of a variable. +With the exception of _allowFeatureInfo_, all other properties can be set based on `standard_name`. +Because this is global, you must include information about the `units` used to define the ``. +This allows the WMS service to deal with variables that have the same `standard_name` yet have different, but comparable, units. +The units must be defined using a `udunits` compatible string. +The current set of unit strings support can be found in [this xml document](https://docs.unidata.ucar.edu/thredds/udunits2/current/udunits2_combined.xml){:target="_blank"}. +A more user-friendly version can be found at [this very helpful site](https://ncics.org/portfolio/other-resources/udunits2/){:target="_blank"}, which is maintained by the [North Carolina Institute for Climate Studies](https://ncics.org/){:target="_blank"}. + +## Overrides + +The `` element contains a series of `` children. +The `pathSpec` attribute of a `` element allows for applying default settings based on the dataset path as seen in the TDS url (i.e. the dataset ID). +Default values can be set for all properties based on the path. +With the exception of _allowFeatureInfo_, these can be overridden on a variable by variable basis based on the name of the variable. + +## Default Precedence Summary + +Default values for a given property are selected based on matches (lowest to highest precedence): + +`global/defaults` < `global/standardName` < `overrides/pathDefaults` < `overrides/variable`