wiki:CowsClient

COWS Client

Introduction

The COWS client is part of the CEDA OGC Web Services Framework. The client component provides a web application for viewing geographic data using  Open Geospatial Consortium Web Map Services. This document describes the client developed for  International Space Innovation Centre (in this context the client is known as the SVSeo client). It is similar to the previously developed WMSViz client, but with some new features (for example KML and video export) and a more flexible layout.

System Context

The components of the system are shown in the context diagram:

The client (SVSeo) web server publishes the application to web browsers. It is configured with a set of WMS endpoints (locations of WMS servers) allowing users to select the data they wish to display. COWS and other WMS servers supply images to the browser as required to display the selected data, under the control of code running in the browser.

Overview

The main functions of the SVSeo web client are:

  • Browse and select WMS endpoints, and layers from them, for display.
  • Display the layers on a map, allowing zooming and panning.
  • Display a legend as provided by the WMS server.
  • Allow a selection of an area within the map to be made.
  • Set values for additional dimensions, such as time.
  • Select between available display styles.
  • Create figures.
  • Create exports in various formats:
    • Video animations
    • KML for display by, e.g., Google Earth
    • XML containing URLs needed to reproduce images or animations
    • Data export using WCS returning, e.g., NetCDF

Architecture

Outline

The SVSeo client functionality is split between the server and web browser. The server publishes the browser application and supplies it with configuration data. The browser application makes all the image requests and displays the results. Map manipulation is entirely within the browser. The server is used to make figures and exports.

Frameworks and Libraries

The SVSeo server is a Python application using the  Pylons framework. The JavaScript browser application uses  ExtJS as its user interface framework, with  OpenLayers to render the map data. Various other libraries are used

 FFmpeg is used to combine images to form video animations.

Server Components

The main packages are shown in the following diagram:

Server components package diagram

viewdata

The server uses one controller, ViewdataController, with a number of actions:

  • index (inherited from WmsvizController): The default action, which displays the main application window using JavaScript in the viewdata.html template. This action has certain special responses if a request parameter REQUEST is set; of these REQUEST values of GetLegendUrl and GetDisplayOptions are used.
  • get_datasets: Returns as JSON the child datasets, endpoints or layers of a specified dataset.
  • get_layer_data: Returns as JSON data from the WMS capabilities document for a layer.
  • get_help: Returns the help text for a specified key.
  • get_figure: Creates and returns a figure as an image in a specified format.
  • make_export: Creates an export file in a specified format and returns its locatation in a JSON response.
  • get_export: Creates and returns an export file in a specified format.
  • download: Returns an export file previously created using the make_export action.
  • error_window: Renders an error page using the viewdata_error.html template.

ViewdataController passes a SessionEndpointData object in each call to methods that access dataset/endpoint/layer data. It encapsulates a collection of this data held in the Pylons session object, allowing sessions to maintain their own sets of endpoints for the user while the session persists.

config_file_parser

Reads the configuration files for the application. Classes are derived from ConfigFileParser to read the endpoint, outline, user interface and help text configuration files (and for other files not used in the SVSeo client).

datasets

Contains the Datasets class that reads the endpoint configuration file and provides data for get_datasets and get_layer_data requests. It holds a cache of all dataset/endpoint/layer data that has been read. This consists of a global set of data and a parallel session scoped set using a session collection passed in from ViewdataController. It provides methods to add and remove session endpoints.

wms_capability_reader

Fetches WMS capability documents for endpoints, parsing and storing the results.

wms_capability_cache

Fetches and caches responses to WMS GetCapability requests. The cache is a Beaker cache on disk, so is persistent across restarts of the server.

wms_layer

Contains the WmsLayer class, which populates itself from a WMS capability layer element and holds the required data.

endpoint_hierarchy_builder

Contains the EndpointHierarchyBuilder class, which reads an endpoint configuration file, creating and storing nodes corresponding to the datasets and endpoints.

build_figure

Builds a figure corresponding to the request parameters, using matplotlib, if available, to add axes, caption and legend.

figure_parameters

Determines the parameters used for the GetMap request for each layer.

figure_builder

Assembles a figure with axes, caption and legend.

viewdataExport

Processes the parameters for an export and delegates to the appropriate export package.

video_export

Creates a video by creating each frame as a figure then combining them into a video file.

kml_export

Processes the parameters for a KML export and creates the KML file with WMS URLs for layers for each dimension value over which animation is to occur.

svs_export

Creates a custom SVS XML file, with WMS URLs for layers for each dimension value over which animation is to occur.

wms_export

Creates a custom SVS XML file, containing the URLs for each request related to the current display: GetCapabilities, GetMap for each layer and GetLegend for the selected layer.

wcs_export

Retrieves data from a WCS server, storing it in preparation for download.

viewdataMetadataImageBuilder

Creates a caption image in the syle used by the SVSeo client.

wmsvizMetadataImageBuilder

Creates a caption image in the syle used by the WMSViz client.

ipccDdcMetadataImageBuilder

Creates caption and details images in the syle used for IPCC DDC figures.

export_parameters

Contains the ExportParameters class, which populates itself from the request parameters of a get_export request. Also, contains the ExportResult class, representing the result of an export creation operation.

Browser Components

The browser interface layout is generated entirely using the ExtJS library. The other major component is the OpenLayers library used to render the WMS map images. The viewdata template contains an Ext.onReady function that initialises the user interface. There are three major regions:

  • Control tabs
  • Layer list
  • Map area

There is also a collapsible banner region and a legend subwindow of the map area.

Each control tab has a class to create its controls (ViewdataXxxControls below). The map region uses a class extending OpenLayers.Map (DDCVisMap) together with WMSC.VisApp and ViewdataMapManager to customise the map display and fit it into the ExtJS UI.

The following diagram shows the dependencies between the components:

Browser component package diagram

The controls and OpenLayers map communicate using events propagated by the OpenLayers event manager.

Control Tabs

The main classes for the control tabs are:

  • ViewdataLayerControls: Creates and manages the dataset tree and the layer list. Population of children of nodes in the tree is performed by AJAX requests to using the viewdata/get_datasets action. Selected layers are displayed in the list.
  • ViewdataBoundingBoxControls: Only creates the bounding box fields - WMSC.BoundsControl handles and raises the bounds events.
  • ViewdataDimensionControls: Creates the dimensions tab and handles change of layer events to reconfigure the tab to contain a selector and stepper controls for each dimension with multiple values. Singel valued dimensions are shown in a text field.
  • ViewdataStyleControls: Creates the style tab and handles change of layer events to reconfigure the style selector with the styles available for the current layer.
  • ViewdataFigureControls: Creates controls for setting parameters for figure creation. When the "Make figure" button is pressed, it collects the parameters for layers, bounding box, dimensions and style, and submits a request to the viewdata/get_figure action.
  • ViewdataExportControls: Creates controls for setting parameters for export in video and other formats. Handles change of layer events to reconfigure the tab to contain a selector for the dimension over which to animate and the start and end values. When the "Make file" button is pressed, it collects the parameters for layers, bounding box, dimensions, style and animation parameters, and submits a request to the viewdata/make_export action. Displays a download link after successful creation of an export file. There are two instances, one for the "Movie" tab for video (viewdataAnimationControls) and XML export, and one for the "Data" tab for WCS download (viewdataDataControls).
  • ViewdataAbout: Displays static information about the application.

ViewdataHelp provides utilities for displaying help boxes on the tabs.

Map Region

The map region is created by ViewdataMapManager. Within the region created by ExtJS it inserts a WMSC.VisApp instance and sets up the outline layer. It also contains an ExtJS onAfterLayout event handler to resize the map when the size of the map region changes. The resizing is performed so that the zoom level remains constant, but an unzoomed map will just fit within the region. It also handles layer changes (addition, removal, layer order, dimension and style), maintaining a list of OpenLayers layers that are rendered on the map.

Added to the map are two sets of controls:

  • OpenLayers.Control.PanZoomBar for panning and zooming the map
  • SubSelectionMouseToolbar, which extends OpenLayers.Control.NavToolbar and contains:
    • SubSelectionZoomBox - extends OpenLayers.Control.ZoomBox to add the marking of the current selection, if active.
    • OpenLayers.Control.Navigation - mouse panning and other navigation handling
    • OpenLayers.Control.WMSGetFeatureInfo - makes WMS GetFeatureInfo requests for points clicked on with the mouse.

The ViewdataLegendManager creates a floating window within the map region. It handles layer selection and property changes, updating the GetLegend URL for the window.

The ViewdataFeatureInfoManager creates a floating window within the map region to display the results of GetFeatureInfo requests. Changes to the selected layer and dimension values are passed from events caught by VisApp to the WMSGetFeatureInfo tool.

Events

Once the application windows is initialised, changes in settings on the control tabs are communicated using events. The following diagrams show the event sequences.

Layer Selected on Dataset Tree

When a layer is selected on the dataset tree it is added to the layer list and events are triggered to update controls that depend on the currently selected layer and to update the map, the legend and the parameters for GetFeatureInfo requests.

Layer selected sequence diagram

Layers Reordered

A layer can be dragged to a new position in the layer list; this results in the ViewdataMapManager updating its list of OpenLayers layers, and passing on the updated list to the map control.

Layers reordered sequence diagram

Layer Removed

When a layer is removed from the layer list, the remaining layers are redrawn, the layer is removed from the list held by ViewdataMapManager and controls that depend on the currently selected layer are updated.

Layer removed sequence diagram

Map Selection

When a selection is made by dragging on the map, the bounds controls update to match and an event is triggered to update update controls that depend on the bounding box.

Map selection sequence diagram

Bounding Box Text Changed

When a bounding box is set by entering values in the bounding box fields, the map control is notified to display a new selection box and an event is triggered to update update controls that depend on the bounding box.

Bounds changed sequence diagram

Clear Selection

Selection cleared sequence diagram

When the bounding box is set cleared, the map control is notified to remove the selection box and an event is triggered to update update controls that depend on the bounding box.

Layer Dimension Value Changed

When a new dimension value is selected, the map manager updates the layer parameter and redraws the map. It triggers an event to update the legend and the parameters for GetFeatureInfo requests.

Dimension changed sequence diagram

Layer Style Changed

When a new style is selected, the map manager updates the layer parameter and redraws the map. It triggers an event to update the legend.

Style changed sequence diagram

Get Feature Info. Request Made

When the feature info. tool is selected and a point is selected on the map, an event is triggered to pop up a window with the results of the request.

Get feature info. sequence diagram

Configuration

The SVSeo client has a number of configuration options, set in configuration files that may need updating after deployment.

Configuration Files

Main configuration file

A version of this is held in Subversion as development.ini. Before putting into production use, the option: set debug = false should be active in the app:main section. The logging levels would normally be reduced.

A number of variables set the locations of other configuration files; listed below are the keys and default values for the names of the configuration files:

  • outlineConfig - outline_layers.ini
  • endpointExtendedConfig - endpoints_extended.ini
  • displayOptionsConfig - displayOptions.ini
  • userInterfaceConfig - userInterfaceConfig.ini
  • helpTextConfig - helpTextConfig.ini

Note that serverurl in the app:main section should not be needed for the SVSeo client.

The video.converter.ffmpeg option must be set if the FFmpeg executable is not in the path with which the server is running.

Some options are used when customising the interface for a particular use:

  • custom_css_file - URL of a CSS file with additional rules (e.g., for the banner or logo regions)
  • omit_label_for_single_legend - false if a label image should be included next to the legend colour bar in a figure if there is only one layer in the figure, otherwise include the labels only if there is more than one layer.

Other customisation options are in the other configuration files referred to above.

Usage Logging

A dedicated logger logs requests for WMS capabilities data for layers to record which endpoints and layers have been accessed by users. The following is needed in the logging section of the configuration file (in addition to configuration for other loggers):

[loggers]
keys = usage, ...

[handlers]
keys = usage, ...

[formatters]
keys = usage, ...

...

# Setting the level to above INFO (e.g., WARNING) will suppress usage logging.
[logger_usage]
level = INFO
handlers = usage
qualname = usage
propagate = 0

[handler_usage]
class = logging.handlers.TimedRotatingFileHandler
# Arguments are file, when ('S', 'M', 'H', 'D', 'W'=Week day (0=Monday) or 'midnight') and interval.
# Rollover only occurs if the server is running at the rollover time.
args = ('/var/log/apache2/viewdata_usage.log', 'midnight', 1)
level = NOTSET
formatter = usage

[formatter_usage]
# The format key %(ip)s is replaced by the request.remote_addr value and %(user)s by request.remote_user.
format = %(ip)s %(user)s [%(asctime)s] %(message)s
datefmt = %Y-%m-%d:%H:%M:%S

This results in entries such as the following:

127.0.0.1 - [2011-04-11:18:47:52] Get WMS capabilities: endpoint "http://wmsserver/wms" layer "layername"

The columns contain:

  • The IP address of the request
  • The username of the logged on user if authentication had occurred, otherise "-"
  • Date/time stamp
  • Message containing the endpoint and layer name

outline_layers.ini

This is unchanged from the Wmsviz client. The outline option in the wmsviz section defines the outline layer to use. The parameters for this are set in a corresponding LayerConfig section: e.g.,

[wmsviz]
outline=ceda_pampero_outline_dark

[LayerConfig:ceda_pampero_outline_dark]
url=http://pampero.badc.rl.ac.uk/vmap0
params= layers:outline_dark,format:image/jpeg,version:1.1.1

endpoints_extended.ini

This defines the datasets and endpoints available in the dataset tree. A dataset may list child datasets within the tree or endpoints or both. Although both datasets and endpoints are optional, a useful entry will contain at least one of them. The section types are:

  • DEFAULT - Common values such as base URLs can be set here.
  • wmsviz - Defines the top level datasets using a keys option with a value of a comma-separated list of dataset names.
  • dataset:dataset_name - Defines a dataset using the following options:
    • datasets - (optional) comma-separated list of dataset names
    • endpoints - (optional) comma-separated list of endpoint names
    • title - (optional) A title to be used instead of the dataset name in the tree
    • abstract - (optional) An abstract for the dataset
    • metadataLink - (optional) A URL to a page giving information about the dataset
    • keywordData - (optional) A key name to be matched with a [key:''key_name''] section
  • endpoint:endpoint_name - Defines an endpoint using the following options:
    • wmsURL - URL of endpoint to be used in constructing a GetCapabilities request
    • name - (optional) A display name to be used instead of the endpoint name in the tree
    • metadataLink - (optional) A URL to a page giving information about the endpoint
    • newLayerNames - (optional) Mappings of layer names to display names to appear in the tree: one or more lines of the format layer_name:display_name
    • keywordData - (optional) A key name to be matched with a [key:''key_name''] section
  • key:key_name - Defines a set of key/value data. This is applied to all entities in the dataset/entity/layer hierarchy at and below the entity for which the keywordData value is set to key_name, but the values are overridden by assignments for the same key lower down the tree. The keys that can appear in the section are:
    • name - name of entity (applied to entity if no name key is present in the entity's own section)
    • title - title for entity (applied to entity if no title key is present in the entity's own section)
    • abstract - abstract for entity (applied to entity if no abstract key is present in the entity's own section)
    • metadataLink - metadata URL for entity (applied to entity if no metadataLink key is present in the entity's own section)
    • layerset - name of a layerset, a set of layers to which common values are to be applied
    • dimension_format - format string for dimension selector
    • dimension_reverse - comma separated list of dimensions for which the values in the selector are to have an order that is the reverse of that in the WMS capabilities document
    • keywords used in caption builders for figure and animation styles that use them (currently only ipcc-ddc)
  • layerset:layerset_name - a set of layers to which common values are to be applied; useful if more than one endpoint has the same layer types
    • layers - comma separated list of layer names to match [layer:''layer_name''] sections
  • layer:layer_name - Defines a layer in a layerset through a name expression to select applicable layers and keyword data to apply to those layers.
    • name - expression for name of WMS layer to which this layer data applies: it is interpreted as a regular expression to match against WMS layer names, and, before matching, the string "{endpoint}" is replaced with the endpoint name.
      • title - title for layer (applied to layer if no title key is present in the layer's own section)
      • abstract - abstract for layer (applied to layer if no abstract key is present in the layer's own section)
      • keywords used in caption builders for figure and animation styles that use them (currently only ipcc-ddc)

An example is shown below:

[DEFAULT]
baseurl=http://ceda.ac.uk/cows

[wmsviz]
keys=Model Data

[dataset:Model Data]
datasets = Slimcat-UTLS-OZONE
endpoints = demo_hadcm3

[dataset:Slimcat-UTLS-OZONE]
title = Slimcat Reference Atmosphere for UTLS-OZONE
metadataLink = http://badc.nerc.ac.uk/view/badc.nerc.ac.uk__ATOM__dataent_SLIMUTLS
endpoints = slimcat1, slimcat2

[endpoint:slimcat1]
wmsURL = %(baseurl)s/Slimcat_UTLS_Ozone_19970112/wms
name = Slimcat January 1997
newLayerNames = Slimcat_UTLS_Ozone_19970112_O3P:O(3P) Volume Mixing Ratio
                Slimcat_UTLS_Ozone_19970112_BrONO2:BrONO2 Volume Mixing Ratio

[endpoint:slimcat2]
wmsURL = %(baseurl)s/Slimcat_UTLS_Ozone_19970211/wms
name = Slimcat February 1997

[endpoint:demo_hadcm3]
name = HadCM3 (demo)
wmsURL = http://neptune.badc.rl.ac.uk/cows/demo_hadcm3/wms

Datasets may be nested to any depth. A given endpoint or dataset may appear in more than one place in the tree (but the chain of references should not be circular).

Below is a more complex example showing the use of keyword data, layer sets and dimension formatting.

[DEFAULT]
baseurl=http://localhost/cows/

[wmsviz]
keys=obs_clim, ar4

# Collections

[dataset:obs_clim]
title = IPCC-DDC CRU TS-2.1 observation climatologies
abstract = Observation data created by the UEA Climatic Research Unit for a variety of phenomena climatologically averaged over 10 and 30 years
metadataLink = http://www.ipcc-data.org/obs/cru_climatologies.html
keywordData = obs_clim
endpoints = obs_clim_10

[dataset:ar4]
title = IPCC-DDC 4th Assessment Report
datasets = ar4_1PTO2X

# CRU TS-2.1 observation climatologies

[key:obs_clim]
dimension_format = time:'Period':'{b}';'{Y:-4}-{Y:+5}'
dimension_reverse = time

[endpoint:obs_clim_10]
wmsURL = %(baseurl)s/obs_clim_10/wms
keywordData = clim-clim_10
layerset = obs_clim_layers
name = 10 year climatology

[key:clim-clim_10]
title = 10 year climatology
period = 10
caption_style = observation
metadataLink = http://www.ipcc-data.org/obs/get_10yr_means.html

[layerset:obs_clim_layers]
layers = pre, tmp

[layer:pre]
name = {endpoint}_pre
title = Precipitation
abstract = Observed Precipitation

[layer:tmp]
name = {endpoint}_tmp
title = Mean Temperature
abstract = Observed Mean Temperature

# IPCC-DDC 4th Assessment Report

[dataset:ar4_1PTO2X]
title = Scenario 1PTO2X
keywordData = scenario-1PTO2X
datasets = ar4_1PTO2X_change_20, ar4_1PTO2X_clim_20

[key:scenario-1PTO2X]
title = 1PTO2X
short = 1PTO2X
abstract = Experiments run with greenhouse gasses increasing from pre-industrial levels at a rate of 1%% per year until the concentration has doubled and held constant thereafter.
ref =   IPCC 2007
caption_style = simulation

[dataset:ar4_1PTO2X_change_20]
keywordData = type_period-change_20
endpoints = ar4_BCM2_1PTO2X_change_20

[key:type_period-change_20]
title = 20 year mean anomalies
abstract = For scenarios 1PTO2X and 1PTO4X anomalies are relative to the pre-industrial control (PICTL) scenario. For SRES scenarios SRA1B, SRA2 and SRB1 the anomalies are relative to the 20th century control (20C3M) 1961-1990 30 year normal.
descrip = anomaly
period = 20
dimension_format = time:'time':'{b} {Y:-9}-{Y:+10}'

[endpoint:ar4_BCM2_1PTO2X_change_20]
wmsURL = %(baseurl)s/ar4_BCM2_1PTO2X_change_20/wms
keywordData = model-BCM2

[key:model-BCM2]
title = BCCR-BCM2.0
institute = Bjerknes Centre for Climate Research, Norway
caption = Bjerknes Centre for Climate Research, Norway
model = BCCR-BCM2.0
metadataLink = http://www.ipcc-data.org/ar4/model-BCCR-BCM2.html
layerset = ar4

[dataset:ar4_1PTO2X_clim_20]
keywordData = type_period-clim_20
endpoints = ar4_HADGEM_1PTO2X_clim_20

[key:type_period-clim_20]
title = 20 year mean climatologies
descrip = climatology
period = 20
dimension_format = time:'time':'{b} {Y:-9}-{Y:+10}'

[endpoint:ar4_HADGEM_1PTO2X_clim_20]
wmsURL = %(baseurl)s/ar4_HADGEM_1PTO2X_clim_20/wms
keywordData = model-HADGEM

[key:model-HADGEM]
title = UKMO-HadGEM1
institute = Hadley Centre for Climate Prediction and Research/Met Office, UK
caption = UK Met Office
model = UKMO-HadGEM1
metadataLink = http://www.ipcc-data.org/ar4/model-UKMO-HADGEM1.html
layerset = ar4

[layerset:ar4]
layers = air_temperature_anomaly, air_temperature

[layer:air_temperature_anomaly]
name = {endpoint}_air_temperature_anomaly
title = Temperature Anomaly
varcaption = Surface Air Temperature Anomaly
abstract = Surface Air Temperature Anomaly
cmap = ipcc_temperature_anomaly
max_value = 30
min_value = -10

[layer:air_temperature]
name = {endpoint}_air_temperature
title = Temperature
varcaption = Surface Air Temperature Climatology
abstract = Surface Air Temperature Climatology
max_value = 320
min_value = 220

Dimension Formatting

Currently, formatting of time dimensions only is supported. However, for other dimensions a label may be specified. The format string is as follows:

dimension_name:[dimension_label][:format_string[:format_label]][;format_string[:format_label]][;...]

  • dimension_name - name of dimension to which the format applies
  • dimension_label - (optional) label for dimension selector
  • format_string - (optional) time component format string as described below
  • format_label - (optional) label describing the time component

For each dimension there may be one or more format_strings. More than one dimension format specification of the above form may be present, each separated by a comma.

The format_string specification is in the format of text containing occurrences of: {component_specifier[:offset]} Each of these is replaced by a string value of a date/time component formatted according to the component specifier and optional offset. component_specifier is one of:

  • b Abbreviated month name.
  • B Full month name.
  • d Day of the month as a decimal number [01,31]
  • H Hour (24-hour clock) as a decimal number [00,23]
  • I Hour (12-hour clock) as a decimal number [01,12]
  • m Month as a decimal number [01,12]
  • M Minute as a decimal number [00,59]
  • p AM or PM
  • S Second as a decimal number [00,61]
  • y Year without century as a decimal number [00,99]
  • Y Year with century as a decimal number

The optional offset is a number which is added to the relevant component before formatting. Examples of time component formats are:

  • "{b}, {Y}" which results in a date of the form "Jul, 2011".
  • "{Y:-9}-{Y:+10}" which results in a date range of the form "2001-2020".

If more than one format_string is specified for a dimension, a selector will be created for each. The selectors allow selection from the distinct values of the part of the time specified by the format.

Examples of complete dimension_format strings are:

  • "time:Date" which just specifies a label for the time selector.
  • "time:Date:'{Y} {b} {d}',depth:Depth" which formats the dates on the time selector as in "2011 Jul 11" and specifies dimension labels for the time and depth dimensions.
  • "time::'{Y} {b} {d}'" which formats the dates on the time selector as in "2011 Jul 11"; no label is specified.
  • "time:'Date':'{Y}':'Year';'{b}':'Month'" which formats the dates on two time selectors, one for years and one for months.
  • "time:'Time':'{b} {Y:-9}-{Y:+10}'" which formats the dates on the time selector as in, e.g., "Jan 2001-2020"
  • "time:Date:'{Y}';'{b}';'{d}'" which formats the dates on three time selectors displaying years, months and days.

displayOptions.ini

This is unchanged from the Wmsviz client. The "hide_rules" keys are not used by the SVSeo client currently. An example is shown below:

[wmsviz]
default_rules=pml_scale, PML_Plankton
hide_rules=wms

#left here for example purposes:
[HideOption:wms]
endpoint=http://ice.badc.rl.ac.uk:5000/[^/]*/wms?
options=show_grid_lines,intervals,intervalNames,cbar_style,disable_subset,transparent,bgcolor

[DefaultOption:pml_scale]
endpoint=http://cedawms.badc.rl.ac.uk/cows/PML_\\d.*
layers=.*
values=cmap_scale|log

[DefaultOption:PML_Plankton]
endpoint=http://cedawms.badc.rl.ac.uk/cows/PML_Plankton[^/]*/wms?
layers=.*
values=styles|interval,intervals|-0.5%%2C0.5%%2C1.5%%2C2.5%%2C3.5%%2C4.5,intervalNames|Land%%2CNo%%2520Data%%2CPicoplankton%%2CNanoplankton%%2CMicroplankton

The endpoint and layers keys are used to define regular expressions that match endpoint URLs and layer names respectively. The values key is used to define a comma separated list of parameter/value pairs (in which the parameter name is separated from the value by | and values should be URL encoded). The parameters are passed to the WMS server in GetMap requests.

userInterfaceConfig.ini

This contains various options for configuring the user interface. The sections are:

  • customtext - Defines the text to be used in parts of the interface using the options:
    • abouttext - HTML for the "about" tab.
    • maptitle - Title for the map region (also used as the title in the HTML head section)
    • figuretitle - Title for figures (may contain <datetime> or <date>, which will be replaced by the date/time or date at which the figure is created.
    • animationtitle - Title for animations (may contain <datetime> or <date>, as above, and <animationlayer> (replaced by the name of the layer over which animation is occurring) and <animationdimension> (replaced by the name of the dimension over which animation is occurring).
  • banner - Defines the banner (displayed above the map) using the options:
    • height - optional - Defines the height of the banner region.
    • html - HTML for the banner region above the map.
    • style - optional - Sets a CSS style for the banner region.
  • logo - Defines the logo (displayed below the layer list) using the options:
    • height - optional - Defines the height of the logo region.
    • html - HTML for the logo region below the layer list.
    • style - optional - Sets a CSS style for the logo region.
  • animation - Defines limits and defaults for animation:
    • height.min - Minimum height allowed for animations in pixels
    • height.max - Maximum height allowed for animations in pixels
    • height.default - Default height allowed for animations in pixels
    • width.min - Minimum width allowed for animations in pixels
    • width.max - Maximum width allowed for animations in pixels
    • width.default - Default width allowed for animations in pixels
    • numbersteps.max - Maximum number of steps that will be allowed for an animation.
    • numbersteps.default - Default number of steps for an animation.
    • browser.timeout - Timeout in seconds for which the browser will wait for a response from a make_export request.
    • style - Name of figure style - allowed values are viewdata, ipcc-ddc and wmsviz.
  • figure - Defines limits and defaults for figures. The options are height.min, height.max, height.default, width.min, width.max, width.default, browser.timeout and style as in the animation section.
  • data - Defines limits and defaults for data download using WCS. The options are numbersteps.max, numbersteps.default and browser.timeout as in the animation section.
  • map - Defines parameters for the OpenLayers maps:
    • tilesize - The height and width of the tiles requested from WMS servers
    • numberzoomlevels - The number of zoom levels enabled in the zoom bar. Each zoom level corresponds to a magnification of sqrt(2).
  • viewdata - Defines the features available in the viewdata user interface. It has a features option, with value a comma-separated list of features to be configured. For each of these there is a feature:feature_name section. This has a show option, with vaue "true" or "false". By default, features are shown, so they need only be reconfigured if not to be shown. The features which can be controlled are:
    • add_session_endpoint
    • boundingbox tab
    • dimensions tab
    • style tab
    • figure tab
    • export_animation tab
    • data tab
    • about tab
    • banner_region
    • logo_region

To hide the export tab, use the following:

[viewdata]
features=export_animation
[feature:export_animation]
show=false

helpTextConfig.ini

This contains the text for the various help panels. There is a single section, "helptext", and the options are of the form: vd-help-identification. The values are the corresponding sections of text to display.

Dataset Tree Cache

Preloading

As described above, responses to GetCapability requests are cached to speed up responses to requests from a user's browser to expand an endpoint node in the dataset tree. It may be useful to populate this cache for all the endpoints defined in the endpoints_extended.ini file, so that users should never see the delay resulting from GetCapability requests. To do this, the script stored in Subversion at cowsclient/scripts/load_endpoints.py can be run:

python load_endpoints.py endpoint_file cache_type cache_data_dir

  • endpoint_file - the endpoint configuration file containing the endpoints to be loaded
  • cache_type - the Beaker cache type as set in the server configuration file with the wmscapabilitycache.type option
  • cache_data_dir - the Beaker cache data directory as set in the server configuration file with the wmscapabilitycache.data_dir option

The Python path must include the cowsclient egg and its dependencies.

Emptying

To remove the existing cache entries, it is necessary to delete the cache files. With the server stopped, the cache directory tree (as defined by the wmscapabilitycache.data_dir option in the server configuration file) should be deleted.

URLs

There is a URL with which to invoke the application user interface and some other URLs for special purpose actions.

Default Application URL

The default action for the application is

server/base_path/viewdata/

or server/base_path/viewdata/index

For example:

 http://isicvis.badc.rl.ac.uk/viewdata/

server/base_path/viewdata is redirected to server/base_path/viewdata/ so that the application sees a consistent controller URL.

Get Figure

server/base_path/viewdata/get_figure

This causes a figure to be created and returned. It would normally be invoked using the "Make figure" button, but can be used directly. The request must include parametes for all the layers to be included, e.g.:

 http://isicvis.badc.rl.ac.uk/viewdata/get_figure?1_CRS=CRS%3A84&1_ENDPOINT=http%3A%2F%2Fpampero.badc.rl.ac.uk%2Fvmap0&1_EXCEPTIONS=application%2Fvnd.ogc.se_inimage&1_FORMAT=image%2Fpng&1_LAYERS=outline_dark&1_REQUEST=GetMap&1_SERVICE=WMS&1_SRS=EPSG%3A4326&1_STYLES=&1_TRANSPARENT=TRUE&1_VERSION=1.1.1&2_CRS=CRS%3A84&2_ENDPOINT=http%3A%2F%2Fcedawms.badc.rl.ac.uk%2Fgrape_level_3%2Fwms&2_EXCEPTIONS=application%2Fvnd.ogc.se_inimage&2_FORMAT=image%2Fpng&2_LAYERS=grape_level_3_grape_l3_CP_s_CP&2_REQUEST=GetMap&2_SERVICE=WMS&2_SRS=EPSG%3A4326&2_STYLES=grid&2_TIME=1995-06-01T00%3A00%3A00.0&2_TRANSPARENT=TRUE&2_VERSION=1.3.0&BBOX=-180%2C-90%2C180%2C90&HEIGHT=900&WIDTH=1200&figFormat=image%2Fpng&figure-legend-show-bounding-box=on&figure-legend-show-dimensions=on&figure-legend-show-layer-names=on&figure-legend-show-style-names=on

or, with several optional parameters omitted

 http://isicvis.badc.rl.ac.uk/viewdata/get_figure?1_CRS=CRS%3A84&1_ENDPOINT=http%3A%2F%2Fpampero.badc.rl.ac.uk%2Fvmap0&1_LAYERS=outline_dark&1_STYLES=&1_VERSION=1.1.1&2_CRS=CRS%3A84&2_ENDPOINT=http%3A%2F%2Fcedawms.badc.rl.ac.uk%2Fgrape_level_3%2Fwms&2_LAYERS=grape_level_3_grape_l3_CP_s_CP&2_STYLES=grid&2_TIME=1995-06-01T00%3A00%3A00.0&2_VERSION=1.3.0&BBOX=-180%2C-90%2C180%2C90&HEIGHT=900&WIDTH=1200&figure-legend-show-bounding-box=on&figure-legend-show-dimensions=on&figure-legend-show-layer-names=on&figure-legend-show-style-names=on

The layers have number n = 1, 2, 3, ... For each layer the following parameters can be set:

  • n_CRS - WMS CRS parameter
  • n_ENDPOINT - endpoint URL for the WMS
  • n_EXCEPTIONS - WMS exception parameter (optional)
  • n_FORMAT - WMS format parameter with a MIME type value, defaults to image/png
  • n_LAYERS - WMS layers parameter - comma-separated list of layers
  • n_REQUEST - WMS request parameter, defaults to GetMap
  • n_SERVICE - WMS service parameter - must be WMS and defaults to this
  • n_SRS - WMS SRS parameter - not valid for WMS 1.3.0, defaults to EPSG:4326
  • n_STYLES - WMS styles parameter - comma-separated list of styles, one for each layer
  • n_TRANSPARENT - WMS transparent parameter, defaults to TRUE
  • n_VERSION - WMS version parameter

Dimension values may be included, such as:

  • n_TIME - time value

The other paramaters apply to the entire figure:

  • BBOX - bounding box, defaults to (-180, -90, 180, 90)
  • HEIGHT - figure height in pixels, defaults to 600
  • WIDTH - figure widthin pixels, defaults to 900
  • figFormat - figure format as a MIME type
  • figure-legend-show-bounding-box - set value to "on" or omit parameter, determines whether the figure legend contains the bounding box values, not present by default
  • figure-legend-show-dimensions - set value to "on" or omit parameter, determines whether the figure legend contains the values of the additional dimensions, not present by default
  • figure-legend-show-layer-names - set value to "on" or omit parameter, determines whether the figure legend contains the names of the layers (including the endpoint URL), not present by default
  • figure-legend-show-style-names - set value to "on" or omit parameter, determines whether the figure legend contains the names of the styles used to display the layers, not present by default

Get Export

server/base_path/viewdata/get_export

This causes an export to be created and returned. The request parameters are those of get_figure with some additional ones:

  • animation-dimension - name of dimension over which to animate, e.g,. time (this replaces the n_dimension parameter for the animation layer)
  • animation-end - final dimension value over which animation should occur
  • animation-format - possible values are: AVI_MJPEG (AVI / MJPEG Video), FLV (Flash Video), MOV (Quicktime Video), MPEG2 (MPEG-2 Video), KML, SVSX (SVS Export), WMS (WMS Details)
  • animation-framerate - number of frames per second for animation (some formats have restricted values - a different rate will be used in these cases)
  • animation-layer-number - the number of the layer over which animation should occur
  • animation-start - initial dimension value over which animation should occur

An example is:

 http://isicvis.badc.rl.ac.uk/viewdata/get_export?1_CRS=CRS%3A84&1_ENDPOINT=http%3A%2F%2Fpampero.badc.rl.ac.uk%2Fvmap0&1_LAYERS=outline_dark&1_STYLES=&1_VERSION=1.1.1&2_CRS=CRS%3A84&2_ENDPOINT=http%3A%2F%2Fcedawms.badc.rl.ac.uk%2Fgrape_level_3%2Fwms&2_EXCEPTIONS=application%2Fvnd.ogc.se_inimage&2_LAYERS=grape_level_3_grape_l3_CP_s_CP&2_STYLES=grid&2_VERSION=1.3.0&BBOX=-180%2C-90%2C180%2C90&HEIGHT=900&WIDTH=1200&animation-dimension=time&animation-end=1997-08-01T00%3A00%3A00.0&animation-format=AVI_MJPEG&animation-framerate=2&animation-layer-number=2&animation-prefix=&animation-start=1997-06-01T00%3A00%3A00.0&figure-legend-show-bounding-box=on&figure-legend-show-dimensions=on&figure-legend-show-layer-names=on

Make Export

server/base_path/viewdata/make_export

This causes an export to be created and details for its retrieval to be returned. It would normally be invoked using the "Make export" button, but can be used directly. The request parameters those of get_export with an additional one:

  • animation-prefix - prefix for file name to aid with identification (a random part is added)

The returned value is a JSON string of the form:

{"url": "URL from which to retrieve export", "success": true}

or

{"errorMessage": "error message", "success": false}

Download Export

server/base_path/viewdata/download

This returns the content of an export file specified using the "file" request parameter. The complete URL will have been returned by a make_export request.

  • file - name of a file returned by a make_export request

For example:

 http://isicvis.badc.rl.ac.uk/viewdata/download?file=viewdataExportbegi0Y.avi

Attachments