ncWMS WMS extensions support

The ncWMS module adds to GeoServer the ability to support some of the ncWMS extensions to the WMS protocol and configuration. In particular:

  • Ability to create a named style by simply providing a list of colors, that will adapt to the layer in use based on request parameters and its statistics

  • Ability to control the palette application in GetMap via a number of extra parameters

  • GetTimeSeries operation, which can retrieve a CSV or an xy chart of a time series of values on a certain point

At the time of writing the extra calls to extract elevation series, transects and NetCDF metadata are not supported. The extension is however not NetCDF specific, but can be used with any single banded raster layer instead.

The Dynamic Palette style format

A new “Dynamic palette” style format has been added that accepts a palette, one color per line, defining a color progression to be applied on raster data. Each color can be defined using these possible syntaxes (same as ncWMS):

  • #RRGGBB

  • #AARRGGBB

  • 0xRRGGBB

  • 0xAARRGGBB

Comments can be added in the file by starting the line by a percentage sign. For example, a red to blue progression might look like:

% Red to blue progression
#FF0000
#0000FF
../../_images/redblue-editor.png

Configuring a dynamic palette style

Several ready to use palettes coming from the popular “color brewer” site are available in the ncWMS source code repository.

The palette translates on the fly into a SLD with rendering transformation using the Dynamic colormap generation module, in particular, the above style translates to the following style:

 1  <?xml version="1.0" encoding="UTF-8"?>
 2  <sld:StyledLayerDescriptor xmlns="http://www.opengis.net/sld" xmlns:sld="http://www.opengis.net/sld" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" version="1.0.0">
 3    <sld:NamedLayer>
 4      <sld:Name/>
 5      <sld:UserStyle>
 6        <sld:Name/>
 7        <sld:FeatureTypeStyle>
 8          <sld:Transformation>
 9            <ogc:Function name="ras:DynamicColorMap">
10              <ogc:Function name="parameter">
11                <ogc:Literal>data</ogc:Literal>
12              </ogc:Function>
13              <ogc:Function name="parameter">
14                <ogc:Literal>opacity</ogc:Literal>
15                <ogc:Function name="env">
16                  <ogc:Literal>OPACITY</ogc:Literal>
17                  <ogc:Literal>1.0</ogc:Literal>
18                </ogc:Function>
19              </ogc:Function>
20              <ogc:Function name="parameter">
21                <ogc:Literal>colorRamp</ogc:Literal>
22                <ogc:Function name="colormap">
23                  <ogc:Literal>rgb(255,0,0);rgb(0,0,255)</ogc:Literal>
24                  <ogc:Function name="env">
25                    <ogc:Literal>COLORSCALERANGE_MIN</ogc:Literal>
26                    <ogc:Function name="bandStats">
27                      <ogc:Literal>0</ogc:Literal>
28                      <ogc:Literal>minimum</ogc:Literal>
29                    </ogc:Function>
30                  </ogc:Function>
31                  <ogc:Function name="env">
32                    <ogc:Literal>COLORSCALERANGE_MAX</ogc:Literal>
33                    <ogc:Function name="bandStats">
34                      <ogc:Literal>0</ogc:Literal>
35                      <ogc:Literal>maximum</ogc:Literal>
36                    </ogc:Function>
37                  </ogc:Function>
38                  <ogc:Function name="env">
39                    <ogc:Literal>BELOWMINCOLOR</ogc:Literal>
40                    <ogc:Literal>rgba(0,0,0,0)</ogc:Literal>
41                  </ogc:Function>
42                  <ogc:Function name="env">
43                    <ogc:Literal>ABOVEMAXCOLOR</ogc:Literal>
44                    <ogc:Literal>rgba(0,0,0,0)</ogc:Literal>
45                  </ogc:Function>
46                  <ogc:Function name="env">
47                    <ogc:Literal>LOGSCALE</ogc:Literal>
48                    <ogc:Literal>false</ogc:Literal>
49                  </ogc:Function>
50                  <ogc:Function name="env">
51                    <ogc:Literal>NUMCOLORBANDS</ogc:Literal>
52                    <ogc:Literal>254</ogc:Literal>
53                  </ogc:Function>
54                </ogc:Function>
55              </ogc:Function>
56            </ogc:Function>
57          </sld:Transformation>
58          <sld:Rule>
59            <sld:RasterSymbolizer/>
60          </sld:Rule>
61        </sld:FeatureTypeStyle>
62      </sld:UserStyle>
63    </sld:NamedLayer>
64  </sld:StyledLayerDescriptor>

The above explains a bit of how the palette is applied:

  • By default a palette of 254 colors is generated between a min and max value, plus one color for anything below the minimum and another for anything above the maximum

  • It is possible to pass the minimum and maximum values using the GetMap env parameter, if not provided, they are fetched from the configured band statistics (as found in the layer configuration)

  • The overall opacity of the palette can be controlled (using a value between 0 and 1 to conform with the SLD opacity description)

  • The scale can be either linear, or logarithmic

../../_images/bandrange.png

Editing the defaults for min/max scale range values in the GeoServer layer editor

The above parameters can all be used at will to control the palette generation using the typical environment variable approach. However, it’s also possible to use ncWMS own extensions, which are adding direct parameters in the request. See the following section for details.

ncWMS GetMap extensions

This module also adds a dynamic translator taking the ncWMS GetMap vendor parameters and mapping them to the dynamic palette expectations. In particular (copying the parameter description from the ncWMS manual, with GeoServer specific annotations):

  • COLORSCALERANGE: Of the form min,max this is the scale range used for plotting the data (mapped to the COLORSCALERANGE_MIN and COLORSCALERANGE_MAX env vars)

  • NUMCOLORBANDS: The number of discrete colours to plot the data. Must be between 2 and 250 (mapped to the NUMCOLORBANDS env variable)

  • ABOVEMAXCOLOR: The colour to plot values which are above the maximum end of the scale range. Colours are of the form 0xRRGGBB or 0xAARRGGBB, and it also accepts “transparent” and “extend”

  • BELOWMINCOLOR: The colour to plot values which are below the minimum end of the scale range. Colours are of the form 0xRRGGBB or 0xAARRGGBB, and it also accepts “transparent” and “extend”

  • LOGSCALE: “true” or “false” - whether to plot data with a logarithmic scale

  • OPACITY: The percentage opacity of the final output image as a number between 0 and 100 (maps to OPACITY env var by translating it to a number between 0 and 1)

  • ANIMATION: “true” or “false” - whether to generate an animation. The ncWMS documentation states that TIME has to be of the form starttime/endtime, but currently TIME needs to be a list of discrete times instead. Animation requires using the “image/gif” as the response format (as the only format supporting animation)

Here are a few examples based on the “ArcSample” arcgrid sample layer, containing annual precipitation data. The one band provided by this layer has been configured with a default range of 0 to 6000.

../../_images/redblue-default.png

  • Adopting a logarithmic scale by adding &COLORSCALERANGE=1,6000&LOGSCALE=true (a logarithmic scale needs a positive minimum)

../../_images/redblue-logscale.png

  • Using just 5 colors in logarithmic mode by adding &COLORSCALERANGE=1,6000&LOGSCALE=true&NUMCOLORBANDS=5

../../_images/redblue-numcolors.png

  • Limiting the range and specifying other colors above (gray) and below (yellow) by adding &COLORSCALERANGE=100,2000&BELOWMINCOLOR=0xFFFF00&ABOVEMAXCOLOR=0xAAAAAA

../../_images/redblue-range.png

ncWMS GetCapabilities extensions

ncWMS allows users to filter the contents of a capabilites document by adding a &dataset=datasetName parameter to the request.

While GeoServer does not have a concept of dataset, the ncWMS extension allows to use the same parameter to filter on workspaces, layers and layer groups, by name.

For example:

ncWMS GetTimeSeries operation

ncWMS provides a GetTimeSeries operation, which can retrieve a time series of values on a certain point, using a syntax similar to the GetFeatureInfo operation. The time series can be retrieved as a chart in PNG or JPEG image, or as a CSV.

For example:

The INFO_FORMAT accepts the following values: image/png, image/jpg and text/csv

The TIME parameter accepts a time range as defined for other operations in the WMS standard (see Annex D of the 06-042 Web Map Server Implementation Specification). Examples:

  • TIME=2008-10-31T00:00:00.000Z/2008-11-01T00:00:00.000Z

  • TIME=2008-10-31T00:00:00.000Z/2008-10-31T00:00:00.000Z

Since GeoServer 2.17, TIME parameter also supports 2 additional syntax even if not expressly supported by ncWMS specification:

  1. A List of Times:

    • Example: TIME=2014-01,2015-01,2016-01,2017-01,2018-01

    • Example: TIME=2017-01-01T00:00:00Z,2017-02-01T00:00:00Z,2017-01-03T00:00:00Z

  2. A periodic time within a range:

    • Example: TIME=2015-01/2019-01/P1Y

Note

  • Shortened time specifications in a list are parsed as time ranges by GeoServer. Therefore, a Time like 2014-01 will represent the whole month of January 2014, so a time range: 2014-01-01T00:00:00/2014-01-31T23:59:59.

  • Months and Years expressed through a Period specification (as an instance P2M, P1Y) are considered made of 30 days and 365.25 days respectively. Therefore a periodic interval like 2000-04/2000-12/P1M will be parsed as the list of time instants starting from April 2000 through December 2000 with a period of 30 days:

    • Apr 01 00:00:00 2000

    • May 01 00:00:00 2000

    • May 31 00:00:00 2000

    • Jun 30 00:00:00 2000

    • Jul 30 00:00:00 2000

    • Aug 29 00:00:00 2000

    • Sep 28 00:00:00 2000

    • Oct 28 00:00:00 2000

    • Nov 27 00:00:00 2000

    • Dec 27 00:00:00 2000

    • Therefore if your original dataset has an entry for the the first day of each month, this request will only return 2 values: Apr 01 and May 01. In that case, you might consider enabling nearest match on Layer’s time dimension.

Sample CSV output:

# Latitude: 40.396728515625
# Longitude: -0.6921386718750019
Time (UTC),Temperature (degrees)
2014-01-01T00:00:00.000Z,0.4194810092449188
2014-02-01T00:00:00.000Z,0.8373379707336426
2014-03-01T00:00:00.000Z,3.1670899391174316
2014-04-01T00:00:00.000Z,4.932330131530762

Sample chart output:

../../_images/geoserver-GetTimeSeries.png

Note: Since GeoServer 2.17, nodata pixels will not be reported in the result chart. Moreover, entries in CSV list related to nodata pixels will report time but will have no pixel value reported, as in the example below for times 2014-02-01 and 2014-05-01:

# Latitude: 40.396728515625
# Longitude: -0.6921386718750019
Time (UTC),Temperature (degrees)
2014-01-01T00:00:00.000Z,0.4194810092449188
2014-02-01T00:00:00.000Z,
2014-03-01T00:00:00.000Z,3.1670899391174316
2014-04-01T00:00:00.000Z,4.932330131530762
2014-05-01T00:00:00.000Z,
2014-06-01T00:00:00.000Z,0.8373379707336426

ncWMS extension configuration

The ncWMS extension adds a panel at the bottom of the WMS administration page:

../../_images/admin.png

Option

Description

GetTimeSeries thread pool size

Size of the thread pool used to compute GetTimeSeries results (paralellized to speed up computation)

Maximum number of times in GetTimeSeries

Maximum number of times tha GetTimeSeries will process. A user asking for more times will get back a service exception. The configuration is set the first time the admin hits save in the WMS page, even with a value of 0 (from that point on, GetTimeSeries will be independent on the WMS max dimensions setting).
Previous: Upgrading
Next: GHRSST NetCDF output