Merge pull request #551 from lesserwhirls/wms

wmsConfig enhancements
Unidata · Dec 16, 2024 · 35494e8 · 35494e8
2 parents 719c0cc + 70469a1
commit 35494e8
Show file tree

Hide file tree

Showing 12 changed files with 218 additions and 24 deletions.
diff --git a/docs/adminguide/src/site/pages/thredds/WmsConfig.md b/docs/adminguide/src/site/pages/thredds/WmsConfig.md
@@ -1,6 +1,6 @@
 ---
 title: Customizing WMS
-last_updated: 2021-08-06
+last_updated: 2024-12-16
 sidebar: admin_sidebar
 toc: false
 permalink: customizing_wms.html
@@ -16,15 +16,21 @@ An example `wmsConfig.xml` file is shipped with the TDS, which looks like:
 {{ rmd }}
 ~~~
 
+Note that as of TDS v5.6, the Document Type Definition has been updated from `wmsConfig.dtd` to `wmsConfig_2_0.dtd`.
 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.
+ * _defaultAboveMaxColor_: The color to plot values above the maximum end of the scale range.
+ * _defaultBelowMinColor_: The color to plot values below the minimum end of the scale range.
+ * _defaultNoDataColor_: The color to use for values which have no data.
+ * _defaultOpacity_: The percentage opacity of the final output image.
+ * _defaultPaletteName_: A color palette name.
+ * _defaultNumColorBands_: The number of color bands to use.
  * _logScaling_: Use a logarithmic scale when generating images.
- * _intervalTime_: Deprecated, does not work.
+ * _intervalTime_: Deprecated, is not supported in the new wms service.
 
+Details regarding these properties can be found in the [ncWMS User Guide](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap){:target="_blank"}
 There are two main elements to the `wmsConfig.xml` file - the `<global>`, and the `<overrides>`.
 Each controls the level of granularity at which default values are chosen.
 Settings in `<overrides>` take precedence over settings in `<global>`.

diff --git a/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md
@@ -1,6 +1,6 @@
 ---
 title: Upgrading to TDS version 5
-last_updated: 2020-08-26
+last_updated: 2024-12-16
 sidebar: quickstart_sidebar
 toc: false
 permalink: upgrade.html
@@ -11,12 +11,12 @@ permalink: upgrade.html
 * Java 11 is required
 * Tomcat 8 (servlet 3.1)
 * On the command line when starting up Tomcat/TDS, you must specify `-Dtds.content.root.path=<content root>` where `<content root>` points to the top of the content directory.
-  Note that this is `${tomcat_home}/content/`, not`${tomcat_home}/content/thredds/`. 
+  Note, in this example, that this is `/data/content/`, not`/data/content/thredds/`. 
   Don't forget the trailing slash. 
   For example:
 
   ~~~bash
-  -Dtds.content.root.path=/opt/tomcat-home/content/
+  -Dtds.content.root.path=/data/content/
   ~~~
 
 ## Overview
@@ -77,10 +77,28 @@ The following is no longer used:
 
 * By default, most services are enabled, but may still be turned off in `threddsConfig.xml`.
 
+### WMS/ Godiva
+TDS 5.x uses the [edal-java](https://github.com/Reading-eScience-Centre/edal-java) library (formerly ncWMS 1.x).
+As this is a major version change to that library, there may be some breaking changes.
+See also the [edal user guide](https://reading-escience-centre.gitbooks.io/edal-user-guide/content/) and the 
+[changes from ncWMS 1.x](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/01-ncwms1x.html#changes).
+Starting with TDS 5.6, `wmsConfig.xml` has been extended to support four new default options:
+* defaultAboveMaxColor
+* defaultBelowMinColor
+* defaultNoDataColor
+* defaultOpacity
+
+As a result, the Document Type Definition used in the `DOCTYPE` element of the config file has been updated from `wmsConfig.dtd` to `wmsConfig_2_0.dtd`.
+
+### ncISO services
+To use the ncISO services, you must add the `tds-plugin-jar-with-dependencies.jar` artifact to your TDS for TDS versions >= 5.5.
+For TDS versions prior to 5.5 this artifact was included in the TDS war file.
+See [ncISO configuration](adding_ogc_iso_services.html#nciso-configuration) for more details.
+
 ## Java Web Start
 
 Java Web Start has been [deprecated as of Java 9](https://www.oracle.com/technetwork/java/javase/9-deprecated-features-3745636.html#JDK-8184998){:target="_blank"}, and has been removed in [Java 11](https://www.oracle.com/technetwork/java/javase/11-relnote-issues-5012449.html){:target="_blank"}, which is the Long-term Release post-Java 8.
-Due to these changes, the netCDF-Java project no longer provide Java Web Start files as of version 5.0.0.
+Due to these changes, the netCDF-Java project no longer provide Java Web Start files as of version 5.0.
 Following suite, the TDS no longer provide any Web Start based Viewers on Dataset pages out of the box.
 
 ### Catalogs
@@ -147,7 +165,7 @@ Schema version is now `1.2`.
 
 * Feature Collection details are [here](feature_collections_ref.html)
 
-### Recommendations for 5.0 catalogs
+### Recommendations for 5.x catalogs
 
 * Put all `<datasetRoot>` elements in root catalog.
 * Put all `<catalogScan>` elements in root catalog.

diff --git a/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md
@@ -1,6 +1,6 @@
 ---
 title: Upgrading to TDS version 5
-last_updated: 2020-08-26
+last_updated: 2024-12-16
 sidebar: user_sidebar
 toc: false
 permalink: upgrade.html
@@ -10,7 +10,7 @@ permalink: upgrade.html
 
 * Java and tomcat versions listed [here](install_java_tomcat.html#system-requirements)
 * On the command line when starting up Tomcat/TDS, you must specify `-Dtds.content.root.path=<content root>` where `<content root>` points to the top of the content directory.
-  Note, in this exmaple, that this is `/data/content/`, not`/data/content/thredds/`. 
+  Note, in this example, that this is `/data/content/`, not`/data/content/thredds/`. 
   Don't forget the trailing slash. 
   For example:
 
@@ -81,6 +81,13 @@ TDS 5.x uses the [edal-java](https://github.com/Reading-eScience-Centre/edal-jav
 As this is a major version change to that library, there may be some breaking changes.
 See also the [edal user guide](https://reading-escience-centre.gitbooks.io/edal-user-guide/content/) and the 
 [changes from ncWMS 1.x](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/01-ncwms1x.html#changes).
+Starting with TDS 5.6, `wmsConfig.xml` has been extended to support four new default options:
+* defaultAboveMaxColor
+* defaultBelowMinColor
+* defaultNoDataColor
+* defaultOpacity
+
+As a result, the Document Type Definition used in the `DOCTYPE` element of the config file has been updated from `wmsConfig.dtd` to `wmsConfig_2_0.dtd`.
 
 ### ncISO services
 To use the ncISO services, you must add the `tds-plugin-jar-with-dependencies.jar` artifact to your TDS for TDS versions >= 5.5.

diff --git a/docs/userguide/src/site/pages/thredds/WmsConfig.md b/docs/userguide/src/site/pages/thredds/WmsConfig.md
@@ -1,6 +1,6 @@
 ---
 title: Customizing WMS
-last_updated: 2021-08-06
+last_updated: 2024-12-16
 sidebar: user_sidebar
 toc: false
 permalink: customizing_wms.html
@@ -16,15 +16,21 @@ An example `wmsConfig.xml` file is shipped with the TDS, which looks like:
 {{ rmd }}
 ~~~
 
+Note that as of TDS v5.6, the Document Type Definition has been updated from `wmsConfig.dtd` to `wmsConfig_2_0.dtd`.
 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.
+ * _defaultAboveMaxColor_: The color to plot values above the maximum end of the scale range.
+ * _defaultBelowMinColor_: The color to plot values below the minimum end of the scale range.
+ * _defaultNoDataColor_: The color to use for values which have no data.
+ * _defaultOpacity_: The percentage opacity of the final output image.
+ * _defaultPaletteName_: A color palette name.
+ * _defaultNumColorBands_: The number of color bands to use.
  * _logScaling_: Use a logarithmic scale when generating images.
- * _intervalTime_: Deprecated, does not work.
+ * _intervalTime_: Deprecated, is not supported in the new wms service.
 
+Details regarding these properties can be found in the [ncWMS User Guide](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap){:target="_blank"}
 There are two main elements to the `wmsConfig.xml` file - the `<global>`, and the `<overrides>`.
 Each controls the level of granularity at which default values are chosen.
 Settings in `<overrides>` take precedence over settings in `<global>`.

diff --git a/tds/src/main/java/thredds/server/wms/TdsEnhancedVariableMetadata.java b/tds/src/main/java/thredds/server/wms/TdsEnhancedVariableMetadata.java
@@ -104,12 +104,12 @@ public String getMoreInfo() {
   public PlottingStyleParameters getDefaultPlottingParameters() {
     List<Extent<Float>> scaleRanges = Collections.singletonList(layerSettings.getDefaultColorScaleRange());
     String palette = layerSettings.getDefaultPaletteName();
-    Color aboveMaxColour = null;
-    Color belowMinColour = null;
-    Color noDataColour = null;
+    Color aboveMaxColour = layerSettings.getDefaultAboveMaxColor();
+    Color belowMinColour = layerSettings.getDefaultBelowMinColor();
+    Color noDataColour = layerSettings.getDefaultNoDataColor();
+    Float opacity = layerSettings.getDefaultOpacity();
     Boolean logScaling = layerSettings.isLogScaling();
     Integer numColourBands = layerSettings.getDefaultNumColorBands();
-    Float opacity = 100f;
 
     return new PlottingStyleParameters(scaleRanges, palette, aboveMaxColour, belowMinColour, noDataColour, logScaling,
         numColourBands, opacity);

diff --git a/tds/src/main/java/thredds/server/wms/config/LayerSettings.java b/tds/src/main/java/thredds/server/wms/config/LayerSettings.java
@@ -28,9 +28,12 @@
 
 package thredds.server.wms.config;
 
+import java.awt.Color;
 import org.jdom2.Element;
 import uk.ac.rdg.resc.edal.domain.Extent;
+import uk.ac.rdg.resc.edal.exceptions.EdalParseException;
 import uk.ac.rdg.resc.edal.graphics.utils.ColourPalette;
+import uk.ac.rdg.resc.edal.graphics.utils.GraphicsUtils;
 import uk.ac.rdg.resc.edal.util.Extents;
 
 /**
@@ -46,6 +49,8 @@ public class LayerSettings {
 
   private Boolean allowFeatureInfo = null;
   private Extent<Float> defaultColorScaleRange = null;
+  private Color defaultAboveMaxColor, defaultBelowMinColor, defaultNoDataColor = null;
+  private Float defaultOpacity = null;
   private String defaultPaletteName = null;
   private Boolean logScaling = null;
   private Boolean intervalTime = null;
@@ -56,6 +61,10 @@ public class LayerSettings {
       return; // Create a set of layer settings with all-null fields
     this.allowFeatureInfo = getBoolean(parentElement, "allowFeatureInfo");
     this.defaultColorScaleRange = getRange(parentElement, "defaultColorScaleRange");
+    this.defaultAboveMaxColor = getColor(parentElement, "defaultAboveMaxColor");
+    this.defaultBelowMinColor = getColor(parentElement, "defaultBelowMinColor");
+    this.defaultNoDataColor = getColor(parentElement, "defaultNoDataColor");
+    this.defaultOpacity = getFloat(parentElement, "defaultOpacity", Extents.newExtent(0f, 100f));
     this.defaultPaletteName = parentElement.getChildTextTrim("defaultPaletteName");
     // If the default palette name tag is used, it must be populated
     // TODO: can we check this against the installed palettes?
@@ -107,6 +116,36 @@ else if (val > validRange.getHigh())
       return val;
   }
 
+  private static Float getFloat(Element parentElement, String childName, Extent<Float> validRange)
+      throws WmsConfigException {
+    String str = parentElement.getChildTextTrim(childName);
+    if (str == null)
+      return null;
+    float val;
+    try {
+      val = Float.parseFloat(str);
+    } catch (NumberFormatException nfe) {
+      throw new WmsConfigException(nfe);
+    }
+    if (val < validRange.getLow())
+      return validRange.getLow();
+    else if (val > validRange.getHigh())
+      return validRange.getHigh();
+    else
+      return val;
+  }
+
+  private static Color getColor(Element parentElement, String childName) throws WmsConfigException {
+    String str = parentElement.getChildTextTrim(childName);
+    if (str == null)
+      return null;
+    try {
+      return GraphicsUtils.parseColour(str);
+    } catch (EdalParseException e) {
+      throw new WmsConfigException(String.format("Invalid color value in %s", str));
+    }
+  }
+
   private static Extent<Float> getRange(Element parentElement, String childName) throws WmsConfigException {
     String str = parentElement.getChildTextTrim(childName);
     if (str == null)
@@ -132,6 +171,22 @@ public Extent<Float> getDefaultColorScaleRange() {
     return defaultColorScaleRange;
   }
 
+  public Color getDefaultAboveMaxColor() {
+    return defaultAboveMaxColor;
+  }
+
+  public Color getDefaultBelowMinColor() {
+    return defaultBelowMinColor;
+  }
+
+  public Color getDefaultNoDataColor() {
+    return defaultNoDataColor;
+  }
+
+  public Float getDefaultOpacity() {
+    return defaultOpacity;
+  }
+
   public String getDefaultPaletteName() {
     return defaultPaletteName;
   }
@@ -160,6 +215,14 @@ void replaceNullValues(thredds.server.wms.config.LayerSettings newSettings) {
       this.allowFeatureInfo = newSettings.allowFeatureInfo;
     if (this.defaultColorScaleRange == null)
       this.defaultColorScaleRange = newSettings.defaultColorScaleRange;
+    if (this.defaultAboveMaxColor == null)
+      this.defaultAboveMaxColor = newSettings.defaultAboveMaxColor;
+    if (this.defaultBelowMinColor == null)
+      this.defaultBelowMinColor = newSettings.defaultBelowMinColor;
+    if (this.defaultNoDataColor == null)
+      this.defaultNoDataColor = newSettings.defaultNoDataColor;
+    if (this.defaultOpacity == null)
+      this.defaultOpacity = newSettings.defaultOpacity;
     if (this.defaultPaletteName == null)
       this.defaultPaletteName = newSettings.defaultPaletteName;
     if (this.logScaling == null)
@@ -177,8 +240,9 @@ void setDefaultColorScaleRange(Extent<Float> defaultColorScaleRange) {
   @Override
   public String toString() {
     return String.format(
-        "allowFeatureInfo = %s, defaultColorScaleRange = %s, defaultPaletteName = %s, defaultNumColorBands = %s, logScaling = %s",
-        this.allowFeatureInfo, this.defaultColorScaleRange, this.defaultPaletteName, this.defaultNumColorBands,
+        "allowFeatureInfo = %s, defaultColorScaleRange = %s, defaultAboveMaxColor = %s, defaultBelowMinColor = %s, defaultNoDataColor = %s, defaultOpacity = %s, defaultPaletteName = %s, defaultNumColorBands = %s, logScaling = %s",
+        this.allowFeatureInfo, this.defaultColorScaleRange, this.defaultAboveMaxColor, this.defaultBelowMinColor,
+        this.defaultNoDataColor, this.defaultOpacity, this.defaultPaletteName, this.defaultNumColorBands,
         this.logScaling);
   }
 }
diff --git a/tds/src/main/java/thredds/server/wms/config/WmsDetailedConfig.java b/tds/src/main/java/thredds/server/wms/config/WmsDetailedConfig.java
@@ -38,6 +38,10 @@
  * <ul>
  * <li>allowFeatureInfo</li>
  * <li>defaultColorScaleRange</li>
+ * <li>defaultAboveMaxColor</li>
+ * <li>defaultBelowMinColor</li>
+ * <li>defaultNoDataColor</li>
+ * <li>defaultOpacity</li>
  * <li>defaultPaletteName</li>
  * <li>defaultNumColorBands</li>
  * <li>logScaling</li>
@@ -111,7 +115,7 @@ public static WmsDetailedConfig loadFromStream(InputStream in) {
       Element defaultSettingsEl = defaultSettingsExpression.evaluateFirst(doc);
 
       // We don't have to check for a null return value since we validated
-      // the document against the DTD upon reading. Similarly we know that
+      // the document against the DTD upon reading. Similarly, we know that
       // all the default settings are non-null: null values would have caused
       // a validation error
       wmsConfig.defaultSettings = new LayerSettings(defaultSettingsEl);

diff --git a/tds/src/main/resources/schema/wmsConfig.dtd b/tds/src/main/resources/schema/wmsConfig.dtd
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!ELEMENT wmsConfig (global, overrides?)>
+
+<!ELEMENT global (defaults, standardNames?)>
+
+<!ELEMENT defaults (allowFeatureInfo, defaultColorScaleRange, defaultPaletteName, defaultNumColorBands, logScaling, intervalTime)>
+
+<!ELEMENT standardNames (standardName*)>
+
+<!ELEMENT standardName (defaultColorScaleRange?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+<!ATTLIST standardName name CDATA #REQUIRED>
+<!ATTLIST standardName units CDATA #REQUIRED>
+
+<!ELEMENT overrides (datasetPath*)>
+
+<!ELEMENT datasetPath (pathDefaults?, variables?)>
+<!ATTLIST datasetPath pathSpec CDATA #REQUIRED>
+
+<!ELEMENT pathDefaults (allowFeatureInfo?, defaultColorScaleRange?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+
+<!ELEMENT variables (variable*)>
+
+<!ELEMENT variable (defaultColorScaleRange?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+<!ATTLIST variable id CDATA #REQUIRED>
+
+<!ELEMENT allowFeatureInfo (#PCDATA)>
+<!ELEMENT defaultColorScaleRange (#PCDATA)>
+<!ELEMENT defaultPaletteName (#PCDATA)>
+<!ELEMENT defaultNumColorBands (#PCDATA)>
+<!ELEMENT logScaling (#PCDATA)>
+<!ELEMENT intervalTime (#PCDATA)> <!-- Allows to use time ranges instead of lists in the capabilities documents -->
diff --git a/tds/src/main/resources/schema/wmsConfig_2_0.dtd b/tds/src/main/resources/schema/wmsConfig_2_0.dtd
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!ELEMENT wmsConfig (global, overrides?)>
+
+<!ELEMENT global (defaults, standardNames?)>
+
+<!ELEMENT defaults (allowFeatureInfo, defaultColorScaleRange, defaultAboveMaxColor, defaultBelowMinColor, defaultNoDataColor, defaultOpacity, defaultPaletteName, defaultNumColorBands, logScaling, intervalTime)>
+
+<!ELEMENT standardNames (standardName*)>
+
+<!ELEMENT standardName (defaultColorScaleRange?, defaultAboveMaxColor?, defaultBelowMinColor?, defaultNoDataColor?, defaultOpacity?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+<!ATTLIST standardName name CDATA #REQUIRED>
+<!ATTLIST standardName units CDATA #REQUIRED>
+
+<!ELEMENT overrides (datasetPath*)>
+
+<!ELEMENT datasetPath (pathDefaults?, variables?)>
+<!ATTLIST datasetPath pathSpec CDATA #REQUIRED>
+
+<!ELEMENT pathDefaults (allowFeatureInfo?, defaultColorScaleRange?, defaultAboveMaxColor?, defaultBelowMinColor?, defaultNoDataColor?, defaultOpacity?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+
+<!ELEMENT variables (variable*)>
+
+<!ELEMENT variable (defaultColorScaleRange?, defaultAboveMaxColor?, defaultAboveMaxColor?, defaultBelowMinColor?, defaultNoDataColor?, defaultOpacity?, defaultPaletteName?, defaultNumColorBands?, logScaling?, intervalTime?)>
+<!ATTLIST variable id CDATA #REQUIRED>
+
+<!ELEMENT allowFeatureInfo (#PCDATA)>
+<!ELEMENT defaultColorScaleRange (#PCDATA)>
+<!ELEMENT defaultAboveMaxColor (#PCDATA)>
+<!ELEMENT defaultBelowMinColor (#PCDATA)>
+<!ELEMENT defaultNoDataColor (#PCDATA)>
+<!ELEMENT defaultOpacity  (#PCDATA)>
+<!ELEMENT defaultPaletteName (#PCDATA)>
+<!ELEMENT defaultNumColorBands (#PCDATA)>
+<!ELEMENT logScaling (#PCDATA)>
+<!ELEMENT intervalTime (#PCDATA)> <!-- Allows to use time ranges instead of lists in the capabilities documents -->