WSL/SLF GitLab Repository

MainPage.h 31.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/***********************************************************************************/
/*  Copyright 2009-2010 WSL Institute for Snow and Avalanche Research    SLF-DAVOS */
/***********************************************************************************/
/* This file is part of MeteoIO.
    MeteoIO is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    MeteoIO is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with MeteoIO.  If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __MAINPAGE_H__
#define __MAINPAGE_H__

namespace mio {
22
//groups
23
/*! \defgroup meteoLaws Meteorological Laws
24
25
26
27
   Documentation for meteorological laws and constants.
*/

/*! \defgroup plugins IO plugins
28
   Documentation for available IO plugins. Please consider having a look at the \ref plugins "Available plugins and usage" page and the \ref dev_plugins "How to write a Plugin" page.
29
30
31
*/

/*! \defgroup stats Statistical calculations
32
   Documentation for available statistical calculations. This is heavily used by the \ref processing "Available data processing elements" as well as the \ref resampling "1D interpolations" and \ref interpol2d "2D interpolations".
33
34
35
*/

/*! \defgroup processing Data processing elements
36
   Documentation for available data processing components. These can be used on incoming meteorological data. See \ref processing "Available data processing elements".
37
38
*/

39
40
/*! \defgroup data_str Data classes
   Documentation for available data classes.
41
42
*/

43
44
45
46
/*! \defgroup graphics Graphical elements and operations
   Documentation for available classes and methods for dealing with graphical elements, color conversions, etc
*/

47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 /**
 * @mainpage Welcome to MeteoIO
 * @section intro_sec Introduction
 * This library aims at making data access easy and safe for numerical simulations in environmental sciences requiring general meteorological data. It's main design goals are:
 * - providing data format/protocol independent data access
 * - providing safe and robust I/O
 * - making I/O code as unobtrusive and simple as possible for the user
 * - providing ready to use data to the user, which means transparent caching, filtering, resampling, spatial interpolation.
 * - enabling unattended use from an IO point of view
 * - offering high modularity so that individual elements of the library can easily be replaced/expanded/added
 * - by its modularity, help interdisciplinary development, each module being targeted at a specific developer profile
 *
 * This library is available under LPGL version 3 or above, see <a href="http://www.gnu.org/licenses/lgpl.txt">www.gnu.org</a>.
 *
 * @section table_of_content Table of content
62
63
64
65
66
 * -# External Links
 *    -# <A HREF="https://models.slf.ch/p/meteoio/">MeteoIO's home page</A>
 *          -# <A HREF="https://models.slf.ch/p/meteoio/page/Getting-started/">Installation, compilation</A>
 *          -# <A HREF="https://models.slf.ch/p/meteoio/page/GettingHelp/">Getting help</A>
 *    -# subscribe to <A HREF="https://freecode.com/projects/meteoio">MeteoIO's release announcements</A>
67
68
 * -# End User documentation
 *    -# \subpage general "General concepts"
69
 *    -# \subpage configuration "Configuration file"
70
71
 *    -# \subpage plugins "Available plugins" and usage
 *    -# \subpage coords "Available coordinate systems" and usage
72
 *    -# \subpage processing "Available processing elements" and usage
73
 *    -# \subpage resampling "Available temporal interpolations" and usage
74
 *    -# \subpage generators "Available data generators" and usage
75
 *    -# \subpage interpol2d "Available spatial interpolations" and usage
76
 *    -# \subpage build_io "How to build your io.ini configuration file"
77
 * -# Programing using MeteoIO
78
 *    -# \subpage workflow "Example Workflow"
79
 *    -# \subpage quick_overview "Quick overview" of the functionnality provided by MeteoIO
80
 *    -# <A HREF="modules.html">Modules list</a>
81
82
83
 *    -# \subpage examples "Usage examples"
 * -# Expanding MeteoIO
 *    -# How to \subpage dev_plugins "write a Plugin"
84
 *    -# How to \subpage dev_processing "write a processing element"
85
 *    -# How to \subpage dev_DataGenerator "Write a data generator"
86
 *    -# How to \subpage dev_2Dinterpol "write a spatial interpolation algorithm"
87
88
89
90
 */

 /**
 * @page general General concepts
91
92
93
94
95
96
97
 * A large number of the problems encountered by users of numerical models working on large meteorological data sets can be traced back to the Input/Output functionality.
 * This comes from the focus of the model developers on the core modeling issues at the expanse of the I/O routines that are costly to properly implement. Therefore
 * the I/O routines often lack flexibility and robustness. When using numerical models in operational applications, this becomes a major drawback and a regular
 * source of problems.
 *
 * The MeteoIO library has been designed to address this issue. It is an additional layer between the data and the numerical model, handling the retrieval of data
 * from various data sources as well as the data pre-processing.
98
 *
99
100
101
102
103
104
105
106
107
108
109
110
111
 * @section typical_setup Typical setup
 * \image html typical_setup.png "typical setup of MeteoIO for operational applications"
 * \image latex typical_setup.eps "typical setup of MeteoIO for operational applications" width=0.9\textwidth
 * MeteoIO has been designed to accomodate both the needs of carefully crafted simulations for a specific purpose/study and for the needs of operational
 * simulations that run automatically and unattended. A typical setup for such operational applications consists of a data acquisition system
 * (made of various sensors, usually mounted on a common mast, thus seen as belonging to a station and some system to bring the data back to some sort
 * of data repository), a data storage system that usually has some way of also distributing the data (often a database but sometimes only data files on a disk)
 * and is mostly seen as the data source by the application, some applications using the data and producing results that are published to
 * their end users (either to an automated system that one can connect to or to some visualization tool that one can use to explore the results).
 *
 * In this setup, MeteoIO is the "glue" between the numerical model at the core of the application and the data sources on one hand and the
 * publication system on the other hand.
 *
112
 * @section MeteoIO_structure General MeteoIO structure
113
114
115
 * @anchor general_structure
 * \image html meteoio_workflow.png "MeteoIO workflow"
 * \image latex meteoio_workflow.eps "MeteoIO workflow" width=0.9\textwidth
116
117
118
 * MeteoIO can be seen as a set of modules that is focused on the handling of input/output operations (including data preparation) for numerical simulations in the realm of earth sciences. On the visible side, it offers the following modules, working on a pre-determined set of \ref meteoparam "meteorological parameters" or on parameters added by the developer:
 * - a set of \ref plugins "plugins" for accessing the data (for example, a plugin might be responsible for fetching the raw data from a given database)
 * - a set of \ref processing "filters and processing elements" for applying transformations to the data (for example, a filter might remove all data that is out of range)
119
120
 * - a set of \ref resampling "resampling" algorithms to temporally interpolate the data at the required timestamp
 * - a set of \ref generators "parametrizations" to generate data/meteorological parameters when they could not be interpolated
121
 * - a set of \ref interpol2d "spatial interpolation algorithms" (for example, such an algorithm might perform Inverse Distance Weighting for filling a grid with spatially interpolated data)
122
 *
123
124
 * Each of these steps can be configured and fine tuned according to the needs of the model and the wishes of the user.
 *
125
 * Moreover, a few assumptions are made about the data that you are using: each data point has to be associated with a geographic location (defined by some sort of coordinates) and very often you will also need to provide a Digital Elevation Model. Therefore, you will also notice a few extra modules that come to play on the visible side:
126
127
128
 * - a module to deal with \ref DEMObject "Digital Elevation Models". Such module will for example interpret a grid of data as a grid of elevations and compute a grid of slopes.
 * - a module to deal with \ref coords "coordinate systems". Such module will require you to define which coordinate system are your data in and transparently handle potential coordinate conversions in the program that you are using.
 * - a module to deal with \ref mio::Config "configuration files". The program that you are using might be using this module for other configuration files.
129
 *
130
131
132
133
 */

 /**
 * @page configuration Configuration file
134
 * @anchor config_doc
135
136
137
138
139
140
141
142
 * Since MeteoIO is a library, you, as an end user, will not be directly exposed to it: the library is called by the program that you are using,
 * not directly by yourself. You will basically have to set some parameters in a configuration file that defines how MeteoIO has to behave.
 * This configuration file is often named "io.ini" and follows the <A HREF="http://en.wikipedia.org/wiki/INI_file">INI file format</A> standard.
 *
 * It is highly recommended that you first understand the \ref general_structure "general structure" of MeteoIO before moving forward. We will then show the
 * configuration file syntax and then the configuration file structure.
 *
 * @section Config_syntax Configuration file syntax
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 * The configuration inputs/outputs file is divided in sections. Each section name is enclosed in brackets.
 * @code
 * [My_section]
 * bla bla bla
 * @endcode
 *
 * Within each section, you might have comments and/or key/value pairs. The comments start with a "#" or a ";" sign and run until the end of the line. A whole line might be commented out, or only a fraction of it. A key/value pair is a keyword, followed by a "=" sign, followed by the value to associate with this key.
 * @code
 * #This is a commented out line
 * PI = 3.14159   #key/value pair and a comment
 * @endcode
 *
 * A valid value can be an integer, a float, or string, a list of keywords, a mixed list of keywords and numbers...
 * @code
 * TA::algorithms = IDW_LAPSE CST_LAPSE
 * @endcode
 *
160
 * @section Config_structure Configuration file structure
161
 * MeteoIO imposes a minimum structure to the configuration %file: It must contain the [General], [Input] and [Output] sections. If any filter is to be used, a [Filters] section has to be present and if any spatial interpolation is to be used, an [Interpolations2D] section has to be present. A minimal set of keys has to be there, an potentially a number of optional keys. Moreover, the program that you are using might also impose you some specific keys or sections.
162
163
164
165
166
167
168
 * The keys and their location in the configuration file (ie: to which section they belong) depends on the module that is actually using them. The optional keys depend on the specific options handled by each specific module (or plugin, or algorithm). Therefore, we can draw the following skeleton:
 * @code
 * [General]
 *
 * [Input]
 * COORDSYS	= CH1903	#mandatory: which coordinate system is used for the geographic coordinates
 * COORDPARAM	= -999		#extra arguments for the chosen coordinate system (often, none)
169
 * TIME_ZONE    = +1		#default time zone for inputs
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 *
 * DEM		= ARC		#plugin to use for reading DEM information
 * #this might be followed by any number of arguments that are specific to this plugin
 *
 * METEO	= A3D		#plugin to use for reading meteorological data
 * #this might be followed by any number of arguments that are specific to this plugin
 *
 * [Output]
 * COORDSYS	= CH1903
 *
 * GRID2D	= ARC		#plugin to use for writing 2D grids
 *
 * [Filters]
 * TA::filter1	= min_max	#first filter to use on the parameter TA
 * TA::arg1	= 230 330	#arguments for this first filter
 * TA::filter2	= rate		#second filter to use (in chronological order)
 * TA::arg2	= 0.01		#arguments for this second filter
 * #add any extra filter that you want to use. They will be applied serially
 *
 * [Interpolations2D]
 * TA::algorithms = IDW_LAPSE CST_LAPSE	#list of algorithms to consider for use for spatially interpolating parameter TA
 * TA::cst_lapse = -0.008 		#parameter for a specific interpolation algorithm for parameter TA
 *
 * @endcode
 *
195
196
 * It is also possible (for advanced use) to import another configuration file, see in the \ref config_import "Config class" documentation.
 *
197
198
199
200
 * @section Finding_docs Where to find the proper documentation
 * As can be seen from the previous example, each plugin, each filter or each interpolation algorithm might have its own parameters. Therefore,
 * this is the documentation of each specific plugin/filter/algorithm that has to be used in order to figure out what can be configured when it is used
 * (see the next sections in the welcome page).
201
 *
202
203
 */

204
/**
Mathias Bavay's avatar
Mathias Bavay committed
205
 * @page build_io How to build your io.ini configuration file
206
207
208
209
210
211
 * As shown in \ref config_doc , the operation of MeteoIO is driven by a configuration file. Please note that
 * <b>it is highly recommended to use <a href="https://models.slf.ch/p/inishell">inishell</a></b> to build your io.ini configuration file, since this significantly
 * reduces the number of errors and provides help text for each keys.
 *
 * Anyway, this section will show you how to manually set up a configuration file. Please read
 * \ref general documentation page before starting!
212
213
 *
 * You first need to create the various sections:
214
 * - [General] : The documentation about this section is found in ??. It currently contains the PLUGIN_PATH key that
215
 *               points to the place where to find the plugins as well as some buffering keys (see BufferedIOHandler).
216
 * - [Input] : This section contains the list of all the plugins that you want to use as well as their parameters. You can
217
218
 *             use one plugin for the meteorological data (key=METEO), one for grids (key=GRID2D), one for the Points Of Interest
 *             (key=POI), one for data assimilation (key=DA), one for landuse (key=LANDUSE) and one for Digital
219
220
 *             Elevation Model (key=DEM). Please see \ref plugins for the available plugins. Afterwards, each plugin comes
 *             with its own set of keys, as specified in the plugin's documentation. Morevover, the geographic coordinate
Mathias Bavay's avatar
Mathias Bavay committed
221
222
 *             system should often be specified, as explained in \ref coords. For the meteorological parameters, it is also
 *             possible to copy one parameter into a new one, as shown in \ref data_generators.
223
224
 *
 *  - [Output] : This section is very similar to the [Input] section, but (obviously) for outputing the data.
225
 *
226
227
 *  - [Filters] : This section lists the pre-processing that has to be performed on the incoming meteorological data.
 *                It builds a stack of processing elements one after the other one, for each meteorological parameter.
228
 *                See \ref processing for more information. It also contains
229
 *
230
231
232
233
 *  - [Interpolations1D] : This section deals with temporal resampling of the incoming meteorological data. The goal is
 *                         to be able to take in data at any sampling rate and to extract values at any user given time step
 *                         according to the resampling specifications of the user. The search window size can be given with
 *                         key WINDOW_SIZE that expresses (in seconds) how far a valid point can be searched for when
234
 *                         re-interpolating a missing value (up to WINDOW_SIZE/2 before and after the requested point).
235
236
237
 *                         See \ref resampling .
 *
 *  - [Interpolations2D] : This section deals with the spatial interpolation of meteorological data, based on a provided
238
239
240
 *                         Digital Elevation Model. The goal is to populate two dimensional grids with meteorological
 *                         parameters from point measurements, according to the specifications of the user.
 *                         See \ref interpol2d .
241
242
 *
 * The application that you are using might also need its own section(s), check this with your application.
243
 *
244
245
 */

246
247
248
249
250
251
252
 /**
 * @page workflow Workflow
 * Here is a workflow example showing how meteorological data is requested by the user's application and delivered. This is a simplified view, in order to show the general structure. Requesting grids (2D grids, DEM, etc) is very similar but does not perfom filtering or resampling.
 * \image html workflow_meteoreading.png "simplified meteo reading workflow"
 * \image latex workflow_meteoreading.eps "simplified meteo reading workflow" width=0.9\textwidth
 */

253
254
255
256
 /**
 * @page quick_overview Quick overview
 * This library contains various classes that have been designed to deal with various sets of problems. This page shows the different sets of problems and what kind of functionnality the library offers to tackle them.
 *
257
258
259
 * @section class_structure Class structure
 * \image html structure.png "simplified class structure"
 * \image latex structure.eps "simplified class structure" width=0.9\textwidth
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 *
 * @section iohandler_sec Data reading
 * The class IOHandler provides the meteorological data from the sources selected by the user in its configuration file. This class inherits from IOInterface and is implemented through plugins that are responsible for implementing a given data access (see \ref dev_plugins "Plugins developer's guide" for more information). It therefore proposes a uniform, standardized access to the data that can be meteorological data, gridded data (including Digital Elevation Model (DEM) data or variations like for landuse codes) and tables of coordinates (for special processing at users selected locations). A buffered version of this class exists: BufferedIOHandler that should be prefered. The description of the plugins and their usage can be found in \ref plugins "Available plugins".
 * This class also transparently calls the filtering class, FilterAlgorithms in order to filter the data according to the configuration of the user.
 *
 *
 * @section meteo Meteorological data
 * The data structures designed for storing meteorological data have been split into two classes: MeteoData and StationData.
 * @subsection meteodata MeteoData
 * The class MeteoData stores the measurement data coming from some idealized station. It contains the widest set of meteorological measurements. It can be compared, assigned and set (either using a constructor or by calling a set method). Its meteorological parameters can be directly accessed or using a param() method that takes a enum in order to be able to cycle through the parameters.
 * @subsection stationdata StationData
 * The class StationData contains the metadata of a weather station, that is mostly its location. It supports the comparison operators.
 * @subsection getmeteo_sec Getting the data
 * The getMeteoData method defined in the IOHandler class provides a vector of MeteoData and StationData for the requested time step. More details are given in \ref iohandler_sec .
 *
 *
 * @section arrays Arrays related functionnalities
 * @subsection arrays_sec Arrays
 * The classes Array, Array2D and Array3D are designed for the storage and handling of 1D, 2D, 3D arrays in memory. These classes provide access to a given element (read/write), sizing or resizing of an existing array as well as clearing an array. They also provide the minimum and the maximum of the values that are stored in the array. Finally, a subset of an array can be extracted.
 * @subsection grids_sec Grids
 * Built on top of the arrays, defined as classes Grid2DObject and Grid3DObject, the grids add the geolocalization. This means that the coordinates of the lower-left corner of the array are stored as well as the cellsize. They can be built manually, or by providing an array. A subset constructor is available, allowing to extract a subset of the grid. It is also possible to get the lat/long (in WGS84) coordinates matching an (i,j) coordinate in the grid. Finally, It is possible to test for geolocalization equality (ie: do two grids have the same geolocalization).
 * @subsection dem_sec Digital Elevation Models
 * The last layer for gridded data is class DEMObject. Various parameters that are specific to Digital Elevation Models (DEM) are added: for each grid point, the slope, the azimuth, the curvature as well as the normal vector are defined (an optional parameter can be used to select the algorithm to be used). The minimums and maximums (over the grid) for each of these parameters are available. A subset of the DEM can be extracted using the subset constructor.
 *
 *
 * @section proj_sec Geographic projections
 * The class Coords is dedicated to geographic projections. It can use both internal algorithms and projections provided by <a href="http://trac.osgeo.org/proj/">libproj4</a>.
 * @subsection coord_conv Coordinate conversion
 * The class Coords takes one or two arguments describing the coordinate system of the input data and then converts back and forth with lat/long WGS84. It can be used to construct a local coordinate system, that is to say a metric grid whose origin is chosen by the user (through the lat/long parameters provided to the constructor). This is useful when working with multiple gridded coordinate system in order to get a common system that would still allow easy distances calculations. See the supported \ref Coordinate_types "projections".
 * @subsection dist_sec Distances
 * A few method used internally to work with custom, local grids are exposed to the user in order to easily compute distances beetwen points (using their lat/long). The algorithms can optionnaly be chosen (otherwise a default choice is used).
 *
 *
 * @section interpol_sec Interpolations
 * @subsection interpol2d_sec Spatial interpolations
 * The class Meteo2DInterpolator receives a Digital Elevation Model (DEM) in its constructor as well as two vectors, one of MeteoData the other one of StationData. Then it allows filling 2D grid (as Grid2DObject) with spatially interpolated meteorological parameters.
 * @subsection interpol1d_sec 1D interpolations
297
 * The ResamplingAlgorithms class uses the Interpol1D class to perform temporal interpolations (for resampling).
298
299
 *
 * @section config_sec Configuration files handling
300
 * In order to offer a consistent interface to the user as well as make it easy to read configuration parameters, the class Config is exposed. Once constructed with a configuration file name, each key's parameter can be retrieved with a call to the templatized getValue() method.
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 *
 *
 * @section date_sec Dates handling
 * Dates should be constructed as a Date object. Then, it is easy to built a new date from a julian date, from an ISO formatted date string, from a date split in fields or from a UNIX date (number of seconds since epoch). Then the various representation of the date can be retrieved, the date arithmetics can be done (for example, get the date that is 1 year, 3 months, 15 hours after 2008-12-01T11:54:00) as well as comparisons. The date printing can be controlled by keywords.
 *
 *
 * @section exceptions_sec Exceptions
 * A few customized exceptions have been defined in IOException : these exceptions have to do with I/O, parameter parsing, argument validity, etc and consistently print usefull debuging information when thrown.
 *
 *
 * @section misc_sec Miscellaneous
 * The IOUtils class is a static class that contains a few helper functions, in order to deal with things as diverse as units conversions, checking for file presence, equality within a given epsilon, string parsing.
 *
 */

//Plugins overview given in IOHandler.cc
317
//Filters overview given in ProcessingBlock.cc
318
//Plugin development given in IOInterface.h
319
//2D interpolation development given in Meteo2DInterpolator.h
320
321

 /**
322
 * @page dev_processing Processing elements developer's guide
323
 *
324
 * In order to add a new filter/processing element to the already existing set of components, the developer only needs to
325
326
 * add a class derived from either ProcessingBlock, FilterBlock or WindowedFilter in meteoio/meteoFilters (depending on the kind of filter
 * that is developed). Templates header and code files are available to get you started, look into the "meteoFilters" subdirectory of the source directory (files "template.cc" and "template.h").
327
 *
328
 * It is important to understand that the processing elements operate on a "per parameter" basis.
329
 * This means that an element might be executed for the parameter TA and another one for the parameter HNW, so the
330
 * algorithm only has to deal with a generic processing method based on double values.
331
 *
332
 * To implement a new processing element, the following steps are necessary:
333
 *
334
 * -# Implementing the element, as a derived class of ProcessingBlock or FilterBlock or WindowedFilter, by creating
335
 *    two files: the header file and its implementation file, in the meteoFilters subdirectory of the source code.
336
337
338
339
340
341
342
343
344
345
346
347
348
 *    The class will contain two public methods: a constructor and a "process" method and at least one private method,
 *    "parse_args" to read the arguments from a provided vector of strings.
 *    -# The <b>constructor</b> takes a vector of strings containing the element's arguments and a constant string (that contains
 *    the block name, for example for printing in an error message from which filter/block it comes). The constructor
 *    would therefore have a declaration similar to:
 *    @code
 *    FilterMax::FilterMax(const std::vector<std::string>& vec_args, const std::string& name)
 *    @endcode
 *    -# The <b>process</b> method applies the element to the provided vector of values, for a meteo parameter pointed to by index.
 *    This index is the MeteoData parameter that this filter shall be run upon (see MeteoData for the enumeration of
 *    parameters). The constructor must set up porcessing.stage to mark if the filter should be applied only during the
 *    first pass (ie before the resampling), or both at the first and second pass (ie before and after resampling).
 *    Its declaration is such as:
349
 *    @code
350
 *    process(const unsigned int& index, const std::vector<MeteoData>& ivec, std::vector<MeteoData>& ovec)
351
 *    @endcode
352
 *    -# The private <b>parse_args</b> method reads the arguments from a vector of strings, with the following declaration:
353
 *    @code
354
 *    parse_args(std::vector<std::string> vec_args)
355
 *    @endcode
356
 * -# Adding the created implementation file to meteoFilters/CMakeLists.txt in a similar way as for the other
357
 *    filters
358
359
 * -# Adding the filter in the processing loop, in meteoFilters/ProcessingBlock.cc in the BlockFactory::getBlock()
 * method by adding three lines similar to:
360
361
 *    @code
 *     else if (blockname == "MIN_MAX"){
362
 *     		return new FilterMinMax(vec_args, blockname);
363
364
 * 	}
 *    @endcode
365
 *    The key (here the string "MIN_MAX") is the key that the user will put in his io.ini to select the processing block.
366
 * -# Including the filter's header file in meteoFilters/ProcessingBlocks.cc
367
 *
368
 * Although you are encouraged to use the provided templates (files "template.cc" and "template.h" in the meteoFilters subdirectory),
369
 * the class FilterMax can be used as an example of implementation of a basic filter that will check whether a
370
 * value is greater than an argument
371
372
 * supplied to the filter and if so changes the value either to IOUtils::nodata (normal operation) or to the
 * maximum value supplied in the argument (soft mode of operation). An example section in the io.ini file supplied
373
 * to the Config could look like this:
374
375
376
377
378
379
380
 * @code
 * [Filters]
 * TA::filter1 = max
 * TA::arg1    = soft 280
 * @endcode
 * Which has the following interpretation: Apply filter max (max-value-filter) to the parameter TA (air temperature)
 * in case that a value is greater than 280 degrees Kelvin change that value to 280.
381
 * A more customized operation could be:
382
 * @code
383
384
385
 * [Filters]
 * TA::filter1 = max
 * TA::arg1    = soft 280 260
386
 * @endcode
387
 * Which will replace any value greater than 280 Kelvin by 260 Kelvin.
388
 *
389
390
 * Another good example is the FilterUnheatedHNW that uses a combination of several meteorological parameters to filter the
 * precipitation.
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 */

/**
 * @page examples Examples
 * Here is a simple exmaple showing how to get some meteorological data into the MeteoData and StationData vectors.
 * \code
 * #include <iostream>
 * #include "MeteoIO.h"
 *
 * int main(int argc, char** argv) {
 * 	(void)argc;
 * 	//provide date as ISO formatted, for example 2008-12-01T15:35:00
 * 	Date d1;
 * 	std::vector<mio::MeteoData> vecMeteo;
 *
406
 * 	mio::IOManager *io = NULL;
407
408
 *
 * 	try {
409
 * 		mio::Config cfg("io.ini");
410
 * 		io = new mio::IOManager(cfg);
411
 * 	} catch (const IOException& e){
412
 * 		std::cout << "Problem with IOManager creation, cause: " << e.what() << std::endl;
413
414
415
 * 	}
 *
 * 	try {
416
 * 		mio::IOUtils::convertString(d1,argv[1]);
417
 * 		io->readMeteoData(d1, vecMeteo);
418
 * 	} catch (const IOException& e){
419
420
421
422
423
 * 		std::cout << "Problem when reading data, cause: " << e.what() << std::endl;
 * 	}
 *
 * 	//writing some data out in order to prove that it really worked!
 * 	for (unsigned int ii=0; ii < vecMeteo.size(); ii++) {
424
 * 		std::cout << "---------- Station: " << (ii+1) << " / " << vecMeteo.size() << std::endl;
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 * 		std::cout << vecMeteo[ii] << std::endl;
 * 	}
 *
 * 	delete io;
 *
 * 	return 0;
 * }
 * \endcode
 *
 * Now, we can also read a Digital Elevation Model, extract a sub set as defined by some geographical coordinates and distances and write it back to disk:
 * \code
 * #include "MeteoIO.h"
 *
 * int main(void) {
 * 	const double dist_x=700, dist_y=1200;
 * 	mio::DEMObject dem;
441
 * 	mio::IOManager *io = NULL;
442
 * 	mio::Config *cfg = NULL;
443
444
445
 * 	int i,j;
 *
 * 	try {
446
 * 		cfg = new mio::Config("io.ini");
447
 * 		io = new mio::IOManager(cfg);
448
 * 	} catch (const IOException& e){
449
450
451
 * 		std::cout << "Problem with IOHandler creation, cause: " << e.what() << std::endl;
 * 	}
 *
452
453
454
455
456
457
458
459
 * 	try {
 * 		io->readDEM(dem);
 * 		mio::Coords point(*cfg);
 * 		point.setLatLon(46.1592, 8.12993);
 * 		dem.WGS84_to_grid(point, i,j);
 *
 * 		const int ncols = (int)ceil(dist_x/dem.cellsize);
 * 		const int nrows = (int)ceil(dist_y/dem.cellsize);
460
 *
461
462
463
464
465
 * 		mio::DEMObject sub_dem(dem, i, j, ncols, nrows);
 * 		io->write2DGrid(sub_dem,"sub_dem.dem");
 * 	} catch (const IOException& e){
 * 		std::cout << "Problem processing DEM: " << e.what() << std::endl;
 * 	}
466
467
468
469
470
 *
 * 	return 0;
 * }
 * \endcode
 *
471
 * The next example shows how to compute and output spatial interpolations.
472
 * \code
473
 * #include "MeteoIO.h"
474
 *
475
 * void real_main(void) {
476
 * 	mio::Date d1;
477
 *
478
479
480
 * 	//initializing the io handlers according to the config file
 * 	mio::Config cfg("io.ini");
 * 	mio::IOManager io(cfg);
481
 *
482
483
484
 * 	//reading the dem (necessary for several spatial interpolations algoritms)
 * 	mio::DEMObject dem;
 * 	io.readDEM(dem);
485
 *
486
487
488
 * 	//we assume that the time given on the command line is in TZ=+1
 * 	d1.setTimeZone(1.);
 * 	mio::IOUtils::convertString(d1,argv[1]);
489
 *
490
491
492
493
 * 	//performing spatial interpolations
 * 	mio::Grid2DObject ta_grid;
 * 	io.interpolate(d1, dem, MeteoData::TA, ta_grid);
 * 	io.write2DGrid(param,"ta.asc");
494
495
496
497
498
499
500
501
 * }
 *
 * int main(void) {
 * 	try {
 * 		real_main();
 * 	} catch (const IOException& e){
 * 		std::cout << e.what() << std::endl;
 * 	}
502
 *
503
 * 	return 0;
504
505
 * }
 * \endcode
506
507
508
 *
 * Do not forget to have a look at the examples provided in doc/examples! An example io.ini is provided as well as some data sets
 * (7 weather stations as well as one DEM).
509
510
511
512
 */

} //end namespace mio
#endif