WSL/SLF GitLab Repository

IOManager.h 10.9 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/***********************************************************************************/
/*  Copyright 2009 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/>.
*/
18
19
#ifndef IOMANAGER_H
#define IOMANAGER_H
20

21
#include <meteoio/DataGenerator.h>
22
#include <meteoio/Meteo2DInterpolator.h>
23
#include <meteoio/MeteoProcessor.h>
24
#include <meteoio/dataClasses/MeteoData.h>
25
26
#include <meteoio/TimeSeriesManager.h>
#include <meteoio/GridsManager.h>
27
28
29

namespace mio {

30
31
32
33
class TimeSeriesManager;
class GridsManager;
class Meteo2DInterpolator;

34
35
36
class IOManager {

	public:
37
		IOManager(const std::string& filename_in);
38
39
		IOManager(const Config& i_cfg);

40
41
		//Legacy support to support functionality of the IOInterface superclass:
		void read2DGrid(Grid2DObject& grid_out, const std::string& parameter="");
42
		void read2DGrid(Grid2DObject& grid_out, const MeteoGrids::Parameters& parameter, const Date& date);
43
44
		void read3DGrid(Grid3DObject& grid_out, const std::string& i_filename="");
		void read3DGrid(Grid3DObject& grid_out, const MeteoGrids::Parameters& parameter, const Date& date);
45
46
47
		void readDEM(DEMObject& dem_out);
		void readAssimilationData(const Date& date_in, Grid2DObject& da_out);
		void readLanduse(Grid2DObject& landuse_out);
48
		void readPOI(std::vector<Coords>& pts);
49
		void write2DGrid(const Grid2DObject& grid_in, const std::string& options="");
50
		void write2DGrid(const Grid2DObject& grid_in, const MeteoGrids::Parameters& parameter, const Date& date);
51
52
		void write3DGrid(const Grid3DObject& grid_out, const std::string& options="");
		void write3DGrid(const Grid3DObject& grid_out, const MeteoGrids::Parameters& parameter, const Date& date);
53
54
		//end legacy support

55
		size_t getStationData(const Date& date, STATIONS_SET& vecStation);
56

57
58
59
60
61
		/**
		* @brief Fill vecMeteo with a time series of objects
		* corresponding to the interval indicated by dateStart and dateEnd.
		* Depending on the ProcessingLevel for the instance of the IOManager
		* the data returned will be either raw (read directly from the IOHandler)
62
		* or processed (read from a buffer and filtered through the MeteoProcessor)
63
64
65
		*
		* vecMeteo will be empty if no datasets were retrieved in the interval defined
		* by dateStart and dateEnd
66
		*
67
68
69
70
71
		* Example Usage:
		* @code
		* vector< vector<MeteoData> > vecMeteo;      //empty vector
		* Date d1(2008,06,21,11,00);       //21.6.2008 11:00
		* Date d2(2008,07,21,11,00);       //21.7.2008 11:00
72
		* IOManager iom("io.ini");
73
74
75
76
		* unsigned int nstations = iom.getMeteoData(d1, d2, vecMeteo);
		* @endcode
		* @param dateStart   A Date object representing the beginning of an interval (inclusive)
		* @param dateEnd     A Date object representing the end of an interval (inclusive)
77
		* @param vecVecMeteo A vector of vector<MeteoData> objects to be filled with data
78
79
		* @return            Number of stations for which data has been found in the interval
		*/
80
		size_t getMeteoData(const Date& dateStart, const Date& dateEnd,
81
		                    std::vector< METEO_SET >& vecVecMeteo);
82

83
		/**
84
85
		 * @brief Fill vector<MeteoData> object with multiple instances of MeteoData
		 * corresponding to the instant indicated by a Date object. Each MeteoData
86
87
		 * instance within the vector represents the data for one station at the given
		 * instant. Depending on the ProcessingLevel configured data will be either
88
		 * raw (read directly from the IOHandler)
89
		 * or processed (read from a buffer, filtered and resampled).
90
91
		 *
		 * NOTE:
92
		 * - vecMeteo will be empty if there is no data found for any station
93
94
95
96
		 *
		 * Example Usage:
		 * @code
		 * vector<MeteoData> vecMeteo;      //empty vector
97
		 * IOManager iomanager("io.ini");
98
99
100
101
		 * iomanager.getMeteoData(Date(2008,06,21,11,00), vecMeteo); //21.6.2008 11:00
		 * @endcode
		 * @param i_date      A Date object representing the date/time for the sought MeteoData objects
		 * @param vecMeteo    A vector of MeteoData objects to be filled with data
102
		 * @return            Number of stations for which data has been found in the interval
103
		 */
104
		size_t getMeteoData(const Date& i_date, METEO_SET& vecMeteo);
105

106
107
108
109
		/**
		 * @brief Push a vector of time series of MeteoData objects into the IOManager. This overwrites
		 *        any internal buffers that are used and subsequent calls to getMeteoData or interpolate
		 *        will be performed upon this data. This method is a way to bypass the internal reading
110
111
		 *        of MeteoData from a certain source and is useful in case the user is only interested
		 *        in data processing and interpolation performed by the IOManager object.
112
113
114
115
116
		 * @param level Level of processing that has already been performed on the data (raw XOR filtered)
		 * @param date_start Representing the beginning of the data
		 * @param date_end Representing the end of the data
		 * @param vecMeteo The actual data being pushed into the IOManager object
		 */
117
		void push_meteo_data(const IOUtils::ProcessingLevel& level, const Date& date_start, const Date& date_end,
118
		                     const std::vector< METEO_SET >& vecMeteo);
119

120
121
122
123
124
125
		/**
		 * @brief Fill Grid2DObject with spatial data.
		 * Depending on which meteo plugin is in use, this might be spatially interpolated
		 * point measurements or grids as provided by the data source itself.
		 * Depending on the ProcessingLevel configured data will be either
		 * raw (read directly from the IOHandler)
126
		 * or processed (read from a buffer, filtered and resampled).
127
128
129
130
131
132
133
		 *
		 * NOTE:
		 * - grid will be empty if there is no data found
		 *
		 * Example Usage:
		 * @code
		 * Grid2DObject grid;      //empty grid
134
		 * IOManager iomanager("io.ini");
135
136
137
138
139
140
141
142
143
144
		 * iomanager.getMeteoData(Date(2008,06,21,11,00), MeteoData::TA, grid); //21.6.2008 11:00
		 * @endcode
		 * @param date A Date object representing the date/time for the sought MeteoData objects
		 * @param dem Digital Elevation Model data
		 * @param meteoparam which meteo parameter to return
		 * @param result grid returned filled with the requested data
		 * @return true if the grid got filled
		 */

		bool getMeteoData(const Date& date, const DEMObject& dem, const MeteoData::Parameters& meteoparam,
145
		                 Grid2DObject& result);
146

147
		bool getMeteoData(const Date& date, const DEMObject& dem, const MeteoData::Parameters& meteoparam,
148
149
		                 Grid2DObject& result, std::string& info_string);

150
		void interpolate(const Date& date, const DEMObject& dem, const MeteoData::Parameters& meteoparam,
151
152
153
154
				 const std::vector<Coords>& in_coords, std::vector<double>& result);

		void interpolate(const Date& date, const DEMObject& dem, const MeteoData::Parameters& meteoparam,
				 const std::vector<Coords>& in_coords, std::vector<double>& result, std::string& info_string);
155

156
157
158
159
		/**
		 * @brief Set the desired ProcessingLevel of the IOManager instance
		 *        The processing level affects the way meteo data is read and processed
		 *        Three values are possible:
160
161
162
		 *        - IOUtils::raw data shall be read directly from the buffer
		 *        - IOUtils::filtered data shall be filtered before returned to the user
		 *        - IOUtils::resampled data shall be resampled before returned to the user
163
164
		 *          this only affects the function getMeteoData(const Date&, METEO_DATASET&);
		 *
165
		 *        The three values can be combined: e.g. IOUtils::filtered | IOUtils:resampled
166
167
		 * @param i_level The ProcessingLevel values that shall be used to process data
		 */
168
169
		void setProcessingLevel(const unsigned int& i_level);

170
171
172
173
174
175
176
177
178
179
		/**
		 * @brief Set buffer window properties requirements as known to the application itself.
		 * This will compare these requirements with the ones expressed by the end user and keep the max between them.
		 * The method can be called several times, it will NOT reset the calculated buffer's requirements but keep
		 * on merging with new submissions. Any parameter given as IOUtils::nodata will be ignored.
		 * @param buffer_size buffer size in days
		 * @param buff_before buffer centering in days
		 */
		void setMinBufferRequirements(const double& buffer_size, const double& buff_before);

180
181
		/**
		 * @brief Returns the average sampling rate in the data.
182
183
184
185
186
187
		 * This computes the average sampling rate of the data that is contained in the buffer. This is a quick
		 * estimate, centered on how often a station measures "something" (ie, how many timestamps do we have
		 * for this station in the buffer). if the station measures TA at h+0 and h+30 and
		 * RH at h+15 and h+45, it would return 4 measurements per hour. If the station measures TA and RH at h+0 and h+30,
		 * it would return 2 measurements per hour.
		 * @return average sampling rate in Hz, nodata if the buffer is empty
188
		 */
189
		double getAvgSamplingRate() const;
190

191
		void writeMeteoData(const std::vector< METEO_SET >& vecMeteo, const std::string& name="");
192

193
194
195
196
197
		/**
		 * @brief Returns a copy of the internal Config object.
		 * This is convenient to clone an iomanager
		 * @return new Config object as a copy of the internal Config
		 */
198
		const Config getConfig() const {return cfg;}
199

200
		const std::string toString() const;
201

202
203
		/**
		 * @brief Add a METEO_SET for a specific instance to the point cache. This is a way to manipulate
204
		 * MeteoData variables and be sure that the manipulated values are later used for requests
205
206
207
208
209
		 * regarding that specific date (e.g. 2D interpolations)
		 *
		 * @param i_date Representing a point in time
		 * @param vecMeteo A vector of MeteoData objects to be copied into the point cache
		 */
210
		void add_to_points_cache(const Date& i_date, const METEO_SET& vecMeteo);
211

212
		/**
213
		 * @brief Clear the all cache. All raw, filtered and resampled values are dismissed, will need to be re-read and/or recalculated.
214
		 */
215
216
		void clear_cache();

217
	private:
218
		void initIOManager();
219
		void load_virtual_meteo(const Date& i_date, METEO_SET& vecMeteo);
220

221
		const Config cfg; ///< we keep this Config object as full copy, so the original one can get out of scope/be destroyed
222
223
224
		IOHandler iohandler;
		TimeSeriesManager tsmanager;
		GridsManager gridsmanager;
225
		Meteo2DInterpolator interpolator;
226
		unsigned int vstations_refresh_rate; ///< when using virtual stations, how often should the data be spatially re-interpolated?
227
		bool downscaling; ///< Are we downscaling meteo grids instead of interpolating stations' data?
228
		bool virtual_stations; ///< compute the meteo values at virtual stations
229
230
231
};
} //end namespace
#endif