diff --git a/grid_models.md b/grid_models.md index fc75d5ef4b2324d24f873c0e8e462e849e5ebb86..3c62bc0c1e10309231882a512c0a61b09b20ca43 100644 --- a/grid_models.md +++ b/grid_models.md @@ -7,22 +7,51 @@ Tor-Einar Skog, Senior developer, NIBIO Updated: 2023-11-17 ## What you will learn -This document describes how to set up a VIPS compatible DSS model displaying results in a grid, such as in the screenshot below: +This document describes how to set up a VIPS compatible gridded DSS model, such as in the screenshot below. It also describes [how to set up a client to a VIPS compatible DSS gridded model](#gridClient). + +The gridded models are using the same "traffic light" color pattern for indicating risk as the location based models. In addition, any other numeric parameter can be displayed as a separate layer, with its own legend and colour scheme. <img src="illustrations/grid_models_01.png" alt="Grid models example" width="1024"/> ## Prerequisites * You should be familiar with web maps and WMS services -* You should be familiar with using and manipulating gridded weatherdata files, e.g. NetCDF files or GRIB files +* You should be familiar with using and manipulating gridded weatherdata files, e.g. NetCDF files or GRIB files. ## Architecture of the VIPS gridded model system **TODO**: Architecture overview illustration -## Structure of the WMS Service +## Get started +### Get gridded weather data +Gridded weather data typically comes in [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) or [GRIB](https://en.wikipedia.org/wiki/GRIB) format. In VIPS, we have been using NetCDF files, which can be inspected with command-line tools like [`ncdump`](https://www.unidata.ucar.edu/software/netcdf/workshops/2011/utilities/Ncdump.html) and [`ncview`](https://cirrus.ucsd.edu/ncview/). + +<img src="illustrations/grid_models_02.png" alt="VIPS Logo" /> + +*`ncview` is a great tool to familiarize yourself with a NetCDF file* + +### Manipulate data, perform calculations +Performing calculations on gridded data are typically done using tools like [R](https://www.r-project.org/), [numPy](https://numpy.org/)/[netCDF4](https://pypi.org/project/netCDF4/) or [CDO](https://code.mpimet.mpg.de/projects/cdo). The latter is by far the quickest, but - depending on the problem - could be cumbersome to work with from a programmer's point of view. + +```bash +$ cdo -selname,TM -seldate,2023-04-01T00:00:00,2023-12-31T00:00:00 met_1_0km_nordic-2023.nc TM_from_april.nc +``` +*The above example extracts one variable (`TM` - mean temperature) for the period starting with April 1st 2023 and outputs this to a new NetCDF file. To see all CDO operators, run `cdo --operators`* + + +### Create output files +The output files must be data files for a WMS service. A common format for this purpose is [GeoTIFF](https://en.wikipedia.org/wiki/GeoTIFF). To convert data from NetCDF to GeoTIFF, we use [GDAL](https://gdal.org/), for example: + +```bash +$ gdal_translate -ot Int16 -of GTiff -b 1 NETCDF:"tmp/result.nc":WARNING_STATUS out/result_WARNING_STATUS_2023-04-01.tif +``` +*This selects the first timestep (`-b 1`) of result.nc, specifically the WARNING_STATUS variable, and creates a GeoTIFF file from this.* + +### Set up a WMS Service + +## The structure of the WMS Service VIPS expects the WMS Service to follow certain patterns in order to display it in a map. ### Model metadata -You need at least these metadata set: +You need at least these metadata: * `wms_title` - Used to display the model's name (see illustration above) * `wms_abstract` - This is used to display the model's description (see illustration above) @@ -32,6 +61,8 @@ In order for VIPS to be able to utilize your WMS, you need to structure the laye * `PSILARTEMP.WARNING_STATUS.2023-04-01` * `PSILARTEMP.DD.2023-04-01` +**There is one mandatory layer, and that is of course the `WARNING_STATUS` layer. It must have an integer data type - at least if you're using [Mapserver](https://mapserver.org/) for the WMS** + For each layer, you need to specify metadata for classification and legend building, e.g. like in this mapfile excerpt: ```mapfile @@ -93,4 +124,13 @@ For your reference, please see the file `examples/PSILARTEMP.map` in this reposi * [In action](https://testvips.nibio.no/spatial/gridmap/PSILARTEMP/) * Septoria Reference Humidity Model * [Source code](https://gitlab.nibio.no/VIPS/models/grid/SEPTREFHUM) - * [In action](https://testvips.nibio.no/spatial/gridmap/SEPTREFHUM/) \ No newline at end of file + * [In action](https://testvips.nibio.no/spatial/gridmap/SEPTREFHUM/) + +<h2 id="gridClient">VIPS grid model client</h2> + +### Reference implementation +The reference implementation for a VIPS grid model client is found in the [VIPSWeb repository](https://gitlab.nibio.no/VIPS/VIPSWeb/-/tree/develop/spatial). These two files are the most important: +* [gridmap.html](https://gitlab.nibio.no/VIPS/VIPSWeb/-/blob/develop/spatial/templates/spatial/gridmap.html) +* [gridmap.js](https://gitlab.nibio.no/VIPS/VIPSWeb/-/blob/develop/spatial/static/spatial/js/gridmap.js) + +The map API is an [old version of OpenLayers](https://openlayers.org/en/v4.6.5/apidoc/index.html). We strongly encourage to use the latest stable version! \ No newline at end of file diff --git a/illustrations/grid_models_02.png b/illustrations/grid_models_02.png new file mode 100644 index 0000000000000000000000000000000000000000..c2b0627766684a51a5097f5475dd43bfa98e598f Binary files /dev/null and b/illustrations/grid_models_02.png differ