Menu
▾
▴
Tree [ab3f19] master / History
Jesper Larsen
Jesper Baasch-Larsen
Johan Soederqvist
Read Me
Route Forecast Toolkit
----------------------
Route Forecast Toolkit (RFT) is a toolbox of useful scripts for providing
weather forecasts along sailing routes on request. RFT is distributed under
the GPL v.3 License, see COPYING for the full license. Installation instructions
can be found in the INSTALL file.
Usage instructions
------------------
To use RFT you will need some NetCDF files of a certain form. And you will
need to preprocess these files as discussed in the Preprocessing section below.
After that you can try to make some forecasts along sailing routes from the
command line. Thereafter you will need to run a server which provides internet
access to the METOC route forecasts. This is described in the Server section. In
the final section some utilities for masking out parts of NetCDF fields are
described.
Preprocessing
-------------
RFT assumes that your NetCDF files are Climate and Forecast (C/F) compliant. In
the current version of RFT there are some further limitations that may be lifted
in future versions. The most important is that it is assumed that the (lat, lon,
time) dimensions are one-dimensional and monotonic increasing. This means that
only regular non-rotated grids are currently supported. If your forecast files
have dimensions that are monotonic decreasing you can easily reverse them using
for example NetCDF Operators (NCO). So that is not really a limitation. Another
limitation is that you must collapse the vertical dimension of 3D fields. You
can either remove the vertical dimension entirely or just have a dimension of
size 1. This can also easily be achieved using NCO.
TODO: Insert NCO examples on how to process the files as discussed above.
Vector fields in C/F compliant NetCDF files can be represented both as vectors
and with a direction and magnitude field. It is recommended to use the latter
format. Otherwise the estimated uncertainties of the forecasts will not be
valid. RTF includes a script (ncvector.py) for preprocessing vector fields to
this format. It is run by typing:
$ ncvector.py cfgfile infile.nc outfile.nc
You can find example configuration files in the examples/ncvector directory.
Waves are special since they often have more than two components. This is fine.
There is only special handling of the direction components (identified by their
units).
Forecasts
---------
RTF supports multifile forecasts. In the route forecasts we have selected to
include the analysis time or epoch. This is deduced from the file name of the
last file in an alphanumerically sorted list of the forecast files. It is simply
found by searching for a string of 10 numbers like "2011090110" in the file name.
Your file names should therefore conform to this convention or you should modify
the get_epoch method in the forecasting.py file.
You can make a forecast along a route by typing:
$ metoc_route.py cfgfile inpfile
The configuration file is a fixed configuration files which determines where the
script should look for NetCDF files and some other information. You can find an
example in examples/metoc_route/metoc.cfg. Here is a snippet of this file:
[Parameters]
[[WI]]
[[[HIRLAM-S03]]]
file_tmpl = '/home/metoc/data/NETCDF/HIRLAM_S03_${epoch10}.nc'
ncvars = ['wd', 'ws']
WI is the name you must use in the input file to be described shortly to request
a wind forecast. HIRLAM-S03 is the name of the forecast. You can have multiple
forecasts for each parameter. Metoc_route will then try to use the forecasts in
the order they are written in the config file until a forecast value is found.
The file_tmpl variable is a template which will be globbed to produce a list of
forecast files. ${epoch10} and ${epoch12} will be substituted in the globbing
(with 10*[0-9] and 12*[0-9] respectively). The ncvars variable is a list of
NetCDF variables that this forecast will provide. In the above examples we have
wind direction (wd) and wind speed (ws).
The input file to metoc_route.py is an XML file which contains a description of
the route along which a forecast is required. You can find an example file in
examples/metoc_route/route.inp. This is the contents of the XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metocForecastRequest>
<mmsi>999999999</mmsi>
<dataTypes>WI</dataTypes>
<dataTypes>CU</dataTypes>
<dt>15</dt>
<waypoints>
<eta>2010-04-04T12:01:00.000000</eta>
<heading>RL</heading>
<lat>55.50000</lat>
<lon>10.33333</lon>
</waypoints>
<waypoints>
<eta>2010-04-07T13:09:00.000000</eta>
<heading>RL</heading>
<lat>55.50000</lat>
<lon>10.66667</lon>
</waypoints>
</metocForecastRequest>
Maritime Mobile Service Identity (mmsi) is a unique 9 digit identification number
used for marine purposes. It is included in the request but is not used for
anything but logging. The dataTypes items corresponds to the Parameters in the
configuration file above. The requested time interval between forecast points is
given in the dt tag. A list of waypoints are also defined. The heading can be
either Rhumb Line (RL) meaning constant heading or Great Circle (GC) which is
the shortest distance.
You can now try to setup the system with your own data and try it out. When it
runs you can proceed to the next section.
There is also a version of the metoc_route.py script which supports the
Computer Gateway Interface (CGI). This script is called metoc_route_cgi.py.
But it has not yet been upgraded to support XML input and output. Eventually
a new CGI wrapper will be written to provide this support. Until then please
do not use it as it is considered obsolete.
Server
------
Hopefully the route_metoc.py script is now working. It is then time to make the
service available over the internet. At the Danish Maritime Safety
Administration we use a JBOSS web application server for this. This server is
quite complicated and also includes other components. I have therefore written
a server in Python which you can use. You can find a setup for it in the
examples/server directory. You will have to modify the configuration files so
that the paths in the file point to files on your system. You can then start
the server by typing:
$ metoc_server.py dev.cfg
When the server is started up you can test it using the test_server.py script.
Or you can use the web interface in web/html. To use the test_server.py script
you will need an XML input file as the one shown above.
Masking out values
------------------
If you do not want to present the entire forecast field to the users you can mask
out regions using the mask_create.py and mask_apply.py tools. The first tool
creates a mask while the other tool applies this mask to a NetCDF file.
The usage of these utilities can be seen by running:
$ mask_create.py --help
and
$ mask_apply.py --help
Example configuration files are located in examples/mask.