GSIP 109 Customizable dimension default values for WMS layers
Add support for user-controlled default values for layer dimensions. Also fixes the unexpected “current” default values for times in the future.
Ilkka Rinne
2.6.0
Choose one of: Under Discussion, In Progress, Completed, Rejected, Deferred
The current Geoserver code always selects the maximum available time for the default time dimension value in WMS GetMap requests. For the data sets with the TIME dimension representing future times, like weather forecasts, this default is very bad one in most cases, as the forecast representing the furtherest forecast time is chosen by default if the user does not explicitly select a time dimension value. From the user perspective this interpretation of “current” time is quite unexpected.
This point is also included as Recommendation b. in the “OGC Best Practice for using Web Map Services (WMS) with Time-Dependent or Elevation-Dependent Data” {quote} Rec. b The default time dimension value SHOULD be the value that is closest to the time at which the request was received. (http://external.opengeospatial.org/twiki_public/pub/MetOceanDWG/MetOceanWMSBPOnGoingDrafts/12-111r1_Best_Practices_for_WMS_with_Time_or_Elevation_dependent_data.pdf, page 18) {quote}
For most cases, the default time should be the one nearest to the current system time. For past times, this yields the same result as before, but for time steps in the future, the one nearest to the current system time should be chosen. The same need is there also with other dimensions, such as elevation, where it would be very useful to be able to select the default value in case it’s not given as GetMap request’s ELEVATION dimension parameter.
The implementation changes in this proposal make configuring and handling of dimension default values possible for any dimension of a vector or raster based layers, while using good defaults in cases where the users wish to let Geoserver decide the default values. As the typical WMS GetMap requests cannot return info about the actual dimension values selected for the returned image, it should be possible to expose the resolved default value for each dimension to the users of the service. This proposal exposes the resolved default values to the WMS capabilities documents according to the OGC WMS specifications also when the default value is not “current”.
The implementation is based on the Strategy design pattern, where the user-defined or built-in layer configuration defines the strategy to use for selection the default values to be used for each of undefined dimension values of a GetMap request.
As with the case of the “current” time dimension default values, the resolved default value for each dimension should be able vary based on both the properties of the resource behind the layer and external information, such as the current system time or a user given reference value. For example a reasonable default value for elevation dimension in many cases could be the elevation value available in the data closest to the ground or some other base height. To support the different cases for selecting the dimension default values, the following selection strategies have been implemented:
- Select the MINIMUM value from the domain of the dimension (currently explicitly used for ELEVATION),
- Select the MAXIMUM value from the domain of the dimension (currently explicitly used for TIME),
- Select the NEAREST domain value to a user-defined reference value, or
- Select a FIXED, user-defined value.
The special transient value “current” for the TIME dimension should be resolved to current system time at the time of the request, and then used as the reference value for the NEAREST strategy.
The implementation available as https://github.com/geoserver/geoserver/pull/530 contains changes in three Geoserver core modules:
-
gs-wms: The new dimension selection logic implemented as
Strategies (package
org.geoserver.wms.dimension), changes for using these strategies via a Factory in classorg.geoserver.wms.WMSand changes for exposing the resolved default values in the capabilities document in classorg.geoserver.wms.capabilities.DimensionHelper. -
gs-main: The new class
org.geoserver.catalog.DimensionDefaultValueSettingused for persisting the user-defined default value settings for a layer, changes for classesorg.geoserver.catalog.DimensionInfoandorg.geoserver.catalog.impl.DimensionInfoImplfor adding support for the new property “defaultValue” in DimensionInfo catalog entries. -
gs-web-core: The UI changes for DimensionEditor panel for
implementing selection fields for the selection strategy and the
reference value (if applicable) in class
org.geoserver.web.data.resource.DimensionEditor, the HTML templatesrc/main/java/org/geoserver/web/data/resource/DimensionEditor.htmland localization filesrc/main/resources/GeoServerApplication.properties)
The default implementation classes for the different strategies (the
org.geoserver.wms.dimension.impl package) are initialized in the
application context and injected into the
dimensionDefaultValueStrategyFactory bean. For the strategies
requiring a reference value, the factories able to provide a customized
strategy objects are injected instead of the strategies. The
dimensionDefaultValueStrategyFactory bean is then used for returning
the appropriate strategy based on the user settings, the resource type
(vector/raster), and the given dimension. The returned strategy then
provides the default value and the capabilities document representation
for the given resource and dimension combination.
The default value setting UI component are included in the
DimensionEditor:
The editor field for the reference value checks the validity of the given value: For the time dimension only ISO8601 DateTimes or the string “current” are allowed, for the elevation the give value must be parseable to Double.
The implementation also requires some new features in Geotools for finding the features with attribute value nearest to the given value (https://jira.codehaus.org/browse/GEOT-4730) added to the Geotools master with commit https://github.com/geotools/geotools/commit/d0d371de0c46fc0f8fca06f1d9e6dca69483739f
Note: the localization for the new UI components is only provided for English, I’d suppose it needs native speakers to translate the new properties for the rest of the supported languages.
Any feedback is highly appreciated. The majority of the discussion should be kept in the developer list to keep all the interested parties in the loop.
The changes will not be backwards compatible because of the changes in the catalog (new property in DimensionInfo). Setting the XStream serialization into the ignore-unknown -mode as done in http://jira.codehaus.org/browse/GEOS-6075 avoid parsing errors if the layer configurations created with the default value setting are parsed by an older version of Geoserver. Note that this XStream configuration change was only committed (https://github.com/geoserver/geoserver/commit/5ec2759225017ccd1b59dd172a6528ec19ee7a59) in the master and 2.5.x branches, and thus 2.4.x branch Geoserver is likely to throw an error when parsing layer configurations with the dimension default value setting.
However, it would be possible to backport the new default behavior for dimension default values into 2.4.x branch without the possibility of user-defined default value settings. This would still fix the original issue of selecting the time furtherest in the future for “current” time.
Alessio Fabiani: Andrea Aime: +1 Ben Caradoc Davies: +1 Christian Mueller: Gabriel Roldan: +1 Jody Garnett: +1 Jukka Rahkonen: +1+1 Justin Deoliveira: Phil Scadden: +1+1 Simone Giannecchini: +1