WSL/SLF GitLab Repository

MainPage.h 32.8 KB
 Thomas Egger committed Jun 21, 2010 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 . */ #ifndef __MAINPAGE_H__ #define __MAINPAGE_H__ namespace mio {  Mathias Bavay committed Jan 26, 2011 22 //groups  23 /*! \defgroup meteoLaws Meteorological Laws  Mathias Bavay committed Jan 26, 2011 24 25 26 27  Documentation for meteorological laws and constants. */ /*! \defgroup plugins IO plugins  Mathias Bavay committed Feb 16, 2011 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.  Mathias Bavay committed Jan 26, 2011 29 30 31 */ /*! \defgroup stats Statistical calculations  Mathias Bavay committed Feb 16, 2011 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".  Mathias Bavay committed Feb 11, 2011 33 34 35 */ /*! \defgroup processing Data processing elements  Mathias Bavay committed Feb 16, 2011 36  Documentation for available data processing components. These can be used on incoming meteorological data. See \ref processing "Available data processing elements".  Mathias Bavay committed Jan 26, 2011 37 38 */  39 40 /*! \defgroup data_str Data classes Documentation for available data classes.  Mathias Bavay committed Jan 26, 2011 41 42 */  Mathias Bavay committed Jan 06, 2012 43 44 45 46 /*! \defgroup graphics Graphical elements and operations Documentation for available classes and methods for dealing with graphical elements, color conversions, etc */  Thomas Egger committed Jun 21, 2010 47  /**  Mathias Bavay committed Jan 30, 2015 48  * @mainpage Table of content  Mathias Bavay committed Dec 05, 2012 49 50 51 52 53  * -# External Links * -# MeteoIO's home page * -# Installation, compilation * -# Getting help * -# subscribe to MeteoIO's release announcements  Thomas Egger committed Jun 21, 2010 54 55  * -# End User documentation * -# \subpage general "General concepts"  Mathias Bavay committed Mar 14, 2014 56  * -# \subpage configuration "Configuration file"  Thomas Egger committed Jun 21, 2010 57 58  * -# \subpage plugins "Available plugins" and usage * -# \subpage coords "Available coordinate systems" and usage  Mathias Bavay committed Feb 11, 2011 59  * -# \subpage processing "Available processing elements" and usage  Mathias Bavay committed Jul 12, 2010 60  * -# \subpage resampling "Available temporal interpolations" and usage  61  * -# \subpage generators "Available data generators" and usage  Thomas Egger committed Jun 21, 2010 62  * -# \subpage interpol2d "Available spatial interpolations" and usage  Mathias Bavay committed Feb 11, 2011 63  * -# \subpage build_io "How to build your io.ini configuration file"  Thomas Egger committed Jun 21, 2010 64  * -# Programing using MeteoIO  Mathias Bavay committed Jul 13, 2010 65  * -# \subpage workflow "Example Workflow"  Thomas Egger committed Jun 21, 2010 66  * -# \subpage quick_overview "Quick overview" of the functionnality provided by MeteoIO  67  * -# Modules list  Thomas Egger committed Jun 21, 2010 68 69  * -# \subpage examples "Usage examples" * -# Expanding MeteoIO  70  * -# How to \subpage dev_coords "write a coordinate system support"  Thomas Egger committed Jun 21, 2010 71  * -# How to \subpage dev_plugins "write a Plugin"  Mathias Bavay committed Feb 11, 2011 72  * -# How to \subpage dev_processing "write a processing element"  73  * -# How to \subpage dev_DataGenerator "Write a data generator"  74  * -# How to \subpage dev_2Dinterpol "write a spatial interpolation algorithm"  Mathias Bavay committed Jan 30, 2015 75 76 77 78 79 80 81 82 83  * *
 Thomas Egger committed Jun 21, 2010 84 85 86 87  */ /** * @page general General concepts  Mathias Bavay committed Mar 14, 2014 88 89 90 91 92 93 94  * 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.  Thomas Egger committed Jun 21, 2010 95  *  Mathias Bavay committed Mar 11, 2014 96 97 98 99 100 101 102 103 104 105 106 107 108  * @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. *  Thomas Egger committed Jun 21, 2010 109  * @section MeteoIO_structure General MeteoIO structure  Mathias Bavay committed Mar 14, 2014 110 111 112  * @anchor general_structure * \image html meteoio_workflow.png "MeteoIO workflow" * \image latex meteoio_workflow.eps "MeteoIO workflow" width=0.9\textwidth  113 114 115  * 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)  Mathias Bavay committed Mar 14, 2014 116 117  * - 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  118  * - 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)  Thomas Egger committed Jun 21, 2010 119  *  Mathias Bavay committed Mar 14, 2014 120 121  * Each of these steps can be configured and fine tuned according to the needs of the model and the wishes of the user. *  Thomas Egger committed Jun 21, 2010 122  * 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:  123 124 125  * - 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.  Thomas Egger committed Jun 21, 2010 126  *  Mathias Bavay committed Mar 14, 2014 127 128 129 130  */ /** * @page configuration Configuration file  Mathias Bavay committed Feb 11, 2011 131  * @anchor config_doc  Mathias Bavay committed Mar 14, 2014 132 133 134 135 136 137 138 139  * 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 INI file format 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  Thomas Egger committed Jun 21, 2010 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156  * 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 *  Mathias Bavay committed Mar 14, 2014 157  * @section Config_structure Configuration file structure  Mathias Bavay committed Mar 11, 2014 158  * 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.  Thomas Egger committed Jun 21, 2010 159 160 161 162 163 164 165  * 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)  Mathias Bavay committed Feb 11, 2011 166  * TIME_ZONE = +1 #default time zone for inputs  Thomas Egger committed Jun 21, 2010 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191  * * 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 *  Mathias Bavay committed Jun 14, 2013 192 193  * It is also possible (for advanced use) to import another configuration file, see in the \ref config_import "Config class" documentation. *  Mathias Bavay committed Mar 14, 2014 194 195 196 197  * @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).  Mathias Bavay committed Mar 11, 2014 198  *  Thomas Egger committed Jun 21, 2010 199 200  */  Mathias Bavay committed Feb 11, 2011 201 /**  Mathias Bavay committed Jun 27, 2012 202  * @page build_io How to build your io.ini configuration file  Mathias Bavay committed Jul 24, 2013 203 204 205 206 207 208  * As shown in \ref config_doc , the operation of MeteoIO is driven by a configuration file. Please note that * it is highly recommended to use inishell 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!  Mathias Bavay committed Feb 11, 2011 209 210  * * You first need to create the various sections:  211  * - [General] : The documentation about this section is found in ??. It currently contains the PLUGIN_PATH key that  Mathias Bavay committed Aug 24, 2011 212  * points to the place where to find the plugins as well as some buffering keys (see BufferedIOHandler).  Mathias Bavay committed Feb 11, 2011 213  * - [Input] : This section contains the list of all the plugins that you want to use as well as their parameters. You can  Mathias Bavay committed Nov 02, 2013 214 215  * 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  Mathias Bavay committed Feb 11, 2011 216 217  * 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 committed Oct 06, 2011 218 219  * 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.  Mathias Bavay committed Feb 11, 2011 220 221  * * - [Output] : This section is very similar to the [Input] section, but (obviously) for outputing the data.  Mathias Bavay committed Aug 24, 2011 222  *  Mathias Bavay committed Feb 11, 2011 223 224  * - [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.  Mathias Bavay committed Aug 24, 2011 225  * See \ref processing for more information. It also contains  Mathias Bavay committed Feb 11, 2011 226  *  227 228 229 230  * - [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  Mathias Bavay committed Aug 24, 2011 231  * re-interpolating a missing value (up to WINDOW_SIZE/2 before and after the requested point).  Mathias Bavay committed Feb 11, 2011 232 233 234  * See \ref resampling . * * - [Interpolations2D] : This section deals with the spatial interpolation of meteorological data, based on a provided  235 236 237  * 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 .  Mathias Bavay committed Feb 11, 2011 238 239  * * The application that you are using might also need its own section(s), check this with your application.  Mathias Bavay committed Aug 24, 2011 240  *  Mathias Bavay committed Feb 11, 2011 241 242  */  Mathias Bavay committed Jul 13, 2010 243 244 245 246 247 248 249  /** * @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 */  Thomas Egger committed Jun 21, 2010 250 251 252 253  /** * @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. *  Mathias Bavay committed Jul 12, 2010 254 255 256  * @section class_structure Class structure * \image html structure.png "simplified class structure" * \image latex structure.eps "simplified class structure" width=0.9\textwidth  Thomas Egger committed Jun 21, 2010 257 258 259 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  * * @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 libproj4. * @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  Mathias Bavay committed Jul 12, 2010 294  * The ResamplingAlgorithms class uses the Interpol1D class to perform temporal interpolations (for resampling).  Thomas Egger committed Jun 21, 2010 295 296  * * @section config_sec Configuration files handling  Thomas Egger committed Jul 26, 2010 297  * 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.  Thomas Egger committed Jun 21, 2010 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313  * * * @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  Mathias Bavay committed Feb 15, 2011 314 //Filters overview given in ProcessingBlock.cc  Thomas Egger committed Jun 21, 2010 315 //Plugin development given in IOInterface.h  316 //2D interpolation development given in Meteo2DInterpolator.h  Thomas Egger committed Jun 21, 2010 317 318  /**  Mathias Bavay committed Feb 11, 2011 319  * @page dev_processing Processing elements developer's guide  Thomas Egger committed Jun 21, 2010 320  *  Mathias Bavay committed Feb 11, 2011 321  * In order to add a new filter/processing element to the already existing set of components, the developer only needs to  322 323  * 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").  Mathias Bavay committed Feb 19, 2014 324  *  Mathias Bavay committed Feb 11, 2011 325  * It is important to understand that the processing elements operate on a "per parameter" basis.  Mathias Bavay committed Aug 24, 2011 326  * This means that an element might be executed for the parameter TA and another one for the parameter HNW, so the  Mathias Bavay committed Feb 11, 2011 327  * algorithm only has to deal with a generic processing method based on double values.  Thomas Egger committed Jun 21, 2010 328  *  Mathias Bavay committed Feb 11, 2011 329  * To implement a new processing element, the following steps are necessary:  Thomas Egger committed Jun 21, 2010 330  *  Mathias Bavay committed Feb 11, 2011 331  * -# Implementing the element, as a derived class of ProcessingBlock or FilterBlock or WindowedFilter, by creating  332  * two files: the header file and its implementation file, in the meteoFilters subdirectory of the source code.  Mathias Bavay committed Nov 01, 2013 333 334 335 336 337 338 339 340 341 342 343 344 345  * 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 constructor 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& vec_args, const std::string& name) * @endcode * -# The process 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:  Thomas Egger committed Jun 21, 2010 346  * @code  Mathias Bavay committed Feb 01, 2011 347  * process(const unsigned int& index, const std::vector& ivec, std::vector& ovec)  Thomas Egger committed Jun 21, 2010 348  * @endcode  Mathias Bavay committed Nov 01, 2013 349  * -# The private parse_args method reads the arguments from a vector of strings, with the following declaration:  Thomas Egger committed Jun 21, 2010 350  * @code  Mathias Bavay committed Feb 01, 2011 351  * parse_args(std::vector vec_args)  Thomas Egger committed Jun 21, 2010 352  * @endcode  353  * -# Adding the created implementation file to meteoFilters/CMakeLists.txt in a similar way as for the other  Mathias Bavay committed Feb 01, 2011 354  * filters  355 356  * -# Adding the filter in the processing loop, in meteoFilters/ProcessingBlock.cc in the BlockFactory::getBlock() * method by adding three lines similar to:  Mathias Bavay committed Feb 01, 2011 357 358  * @code * else if (blockname == "MIN_MAX"){  359  * return new FilterMinMax(vec_args, blockname);  Mathias Bavay committed Feb 01, 2011 360 361  * } * @endcode  Mathias Bavay committed Nov 01, 2013 362  * The key (here the string "MIN_MAX") is the key that the user will put in his io.ini to select the processing block.  363  * -# Including the filter's header file in meteoFilters/ProcessingBlocks.cc  Mathias Bavay committed Feb 01, 2011 364  *  365  * Although you are encouraged to use the provided templates (files "template.cc" and "template.h" in the meteoFilters subdirectory),  Mathias Bavay committed Feb 19, 2014 366  * the class FilterMax can be used as an example of implementation of a basic filter that will check whether a  Mathias Bavay committed Feb 01, 2011 367  * value is greater than an argument  Thomas Egger committed Jun 21, 2010 368 369  * 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  Thomas Egger committed Jul 26, 2010 370  * to the Config could look like this:  Thomas Egger committed Jun 21, 2010 371 372 373 374 375 376 377  * @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.  Mathias Bavay committed Feb 01, 2011 378  * A more customized operation could be:  Thomas Egger committed Jun 21, 2010 379  * @code  Mathias Bavay committed Feb 01, 2011 380 381 382  * [Filters] * TA::filter1 = max * TA::arg1 = soft 280 260  Thomas Egger committed Jun 21, 2010 383  * @endcode  Mathias Bavay committed Feb 01, 2011 384  * Which will replace any value greater than 280 Kelvin by 260 Kelvin.  Mathias Bavay committed Aug 24, 2011 385  *  Mathias Bavay committed Oct 18, 2013 386 387  * Another good example is the FilterUnheatedHNW that uses a combination of several meteorological parameters to filter the * precipitation.  Thomas Egger committed Jun 21, 2010 388 389 390 391  */ /** * @page examples Examples  Mathias Bavay committed Jun 24, 2015 392 393 394 395 396 397 398 399  * This page shows you how to integrate MeteoIO within your own aplication. Several of the basics calls are shown * here below in the code examples. Finally, some tips are given in order to polish such integration. * * Please keep in mind that the given examples are very simple, in order to keep them compact. For a real application, * you will need to add some error checking code (as shown in the "tips" section). * * @section reading_meteo_data Reading meteorological time series * Here is a simple exmaple showing how to get some meteorological data into the MeteoData vectors.  Thomas Egger committed Jun 21, 2010 400 401  * \code * #include  Mathias Bavay committed Jun 24, 2015 402 403 404 405 406 407 408  * #include * * using namespace mio; //The MeteoIO namespace is called mio * * //This is the most basic example. It does not check any exceptions, it only tries to be as c-like as possible * //provide date as ISO formatted, for example 2008-12-01T15:35:00 and * //it will retrieve the data for this date according to the io.ini configuration file  Thomas Egger committed Jun 21, 2010 409 410  * int main(int argc, char** argv) { * Date d1;  Mathias Bavay committed Jun 24, 2015 411 412 413 414 415 416 417 418 419 420 421  * std::vector vecMeteo; * * Config cfg("io.ini"); * IOManager io(cfg); * * //we assume that the time given on the command line is in TZ=+1 * IOUtils::convertString(d1,argv[1], 1.); * //io.setProcessingLevel(IOManager::raw); //set the processing level: raw, filtered or resampled * io.getMeteoData(d1, vecMeteo); * * std::cout << vecMeteo.size() << " stations with an average sampling rate of " << io.getAvgSamplingRate() << " or 1 point every " << 1./(io.getAvgSamplingRate()*60.+1e-12) << " minutes\n";  Thomas Egger committed Jun 21, 2010 422 423  * //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;  Mathias Bavay committed Jun 24, 2015 425  * std::cout << vecMeteo[ii].toString() << std::endl;  Thomas Egger committed Jun 21, 2010 426  * }  Mathias Bavay committed Jun 24, 2015 427  *  Thomas Egger committed Jun 21, 2010 428 429 430 431  * return 0; * } * \endcode *  Mathias Bavay committed Jun 24, 2015 432 433  * @section reading_dem_example Reading Digital Elevation Models * Now, we can also read a Digital Elevation Model, print some information about it, write it back to disk with (potentially) another plugin as well as the slope and azimuth:  Thomas Egger committed Jun 21, 2010 434 435  * * \code  Mathias Bavay committed Jun 24, 2015 436 437 438 439 440 441  * #include * * using namespace mio; //The MeteoIO namespace is called mio * * //This is a basic example of using as dem: the dem is read, the grid coordinates of a point given by its (lat,long) are retrieved * //and a sub-dem is extracted starting at these coordinates and extending dist_x and dist_y and written out.  Mathias Bavay committed Sep 24, 2012 442  * int main(void) {  Mathias Bavay committed Jun 24, 2015 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464  * DEMObject dem; * Config cfg("io.ini"); * IOManager io(cfg); * * //reading dem * dem.setUpdatePpt(DEMObject::SLOPE); * io.readDEM(dem); * * //writing some statistics about this dem * //dem.grid2D.getMin() scans the DEM grid to get the min, while dem.min_altitude is cached and therefore very cheap * //The raw content of the 2D grids can also be accessed, for example dem.grid2D.getMin(IOUtils::RAW_NODATA). In this case, there would be no interpretation of some values as nodata. * std::cout << "DEM information: \n"; * std::cout << "\tmin=" << dem.grid2D.getMin() << " max=" << dem.grid2D.getMax() << " mean=" << dem.grid2D.getMean() << "\n"; * std::cout << "\tmin slope=" << dem.min_slope << " max slope=" << dem.max_slope << std::endl; * * io.write2DGrid(dem, MeteoGrids::DEM, Date(0.)); * * Grid2DObject slope(dem.cellsize, dem.llcorner, dem.slope); * io.write2DGrid(slope, MeteoGrids::SLOPE, Date(0.)); * Grid2DObject azi(dem.cellsize, dem.llcorner, dem.azi); * io.write2DGrid(azi,"azi.png"); *  Mathias Bavay committed Jan 26, 2011 465  * return 0;  Thomas Egger committed Jun 21, 2010 466 467  * } * \endcode  Mathias Bavay committed Dec 05, 2012 468  *  Mathias Bavay committed Jun 24, 2015 469 470  * @section examples_tips Programming Tips * First, more examples are provided in doc/examples (see the readme.txt file), alongside with an example io.ini as well as some data sets  Mathias Bavay committed Dec 05, 2012 471  * (7 weather stations as well as one DEM).  Mathias Bavay committed Jun 24, 2015 472 473 474 475 476 477 478  * * Then, for a real world application, the following would also be needed: * + wrapping up the MeteoIO calls in a try/catch block (at least for calls such as getMeteoData). This is particularly required for Windows and Mac platforms since uncaught exceptions on these plateforms won't print any error message on the screen. * + checking the data returned by getMeteoData against your application's minimum requirements. For example, you might want to check that there is at least one air temperature and one wind velocity at each time step. If your application's requirements are not fulfilled, then print an error message and exit (or thrown an exception with a proper error message). * + if your application is written in another language (for example C or Fortran), then you need a wrapper that will wrapp the call to MeteoIO and copy the returned data into your own data structures. * + finally, it might be a good idea to print the MeteoIO version information somewhere in your application's output. This could help with support and debugging. Such version information is returned by getLibVersion(). *  Thomas Egger committed Jun 21, 2010 479 480 481 482  */ } //end namespace mio #endif