1 /***************************************************************************
2                           qgsmeshcalculator.h
3                           -------------------
4     begin                : December 18th, 2018
5     copyright            : (C) 2018 by Peter Petrik
6     email                : zilolv at gmail dot com
7  ***************************************************************************/
8 
9 /***************************************************************************
10  *                                                                         *
11  *   This program is free software; you can redistribute it and/or modify  *
12  *   it under the terms of the GNU General Public License as published by  *
13  *   the Free Software Foundation; either version 2 of the License, or     *
14  *   (at your option) any later version.                                   *
15  *                                                                         *
16  ***************************************************************************/
17 
18 #ifndef QGSMESHCALCULATOR_H
19 #define QGSMESHCALCULATOR_H
20 
21 #include <QString>
22 #include <QVector>
23 #include <QStringList>
24 
25 #include "qgis_core.h"
26 #include "qgis_sip.h"
27 #include "qgsrectangle.h"
28 #include "qgsmeshlayer.h"
29 #include "qgsmeshdataprovider.h"
30 #include "qgsprovidermetadata.h"
31 #include "qgsfeedback.h"
32 
33 /**
34  * \ingroup core
35  * \class QgsMeshCalculator
36  * \brief Performs mesh layer calculations.
37  *
38  * Mesh calculator can do various mathematical operations
39  * between dataset groups from a single mesh layer.
40  * Resulting dataset group is added to the mesh layer.
41  * Result can be filtered by extent or a vector layer mask
42  * spatially and by selection of times.
43  *
44  * Resulting dataset is always scalar
45  *
46  * \since QGIS 3.6
47 */
48 class CORE_EXPORT QgsMeshCalculator
49 {
50   public:
51 
52     //! Result of the calculation
53     enum Result
54     {
55       Success = 0, //!< Calculation successful
56       Canceled, //!< Calculation canceled
57       CreateOutputError, //!< Error creating output data file
58       InputLayerError, //!< Error reading input layer
59       ParserError, //!< Error parsing formula
60       InvalidDatasets, //!< Datasets with different time outputs or not part of the mesh
61       EvaluateError, //!< Error during evaluation
62       MemoryError, //!< Error allocating memory for result
63     };
64 
65     /**
66      * Creates calculator with bounding box (rectangular) mask
67      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
68      * \param outputFile file to store the resulting dataset group data
69      * \param outputExtent spatial filter defined by rectangle
70      * \param startTime time filter defining the starting dataset
71      * \param endTime time filter defining the ending dataset
72      * \param layer mesh layer with dataset groups references in formulaString
73      *
74      * \deprecated QGIS 3.12
75      */
76     Q_DECL_DEPRECATED QgsMeshCalculator( const QString &formulaString,
77                                          const QString &outputFile,
78                                          const QgsRectangle &outputExtent,
79                                          double startTime,
80                                          double endTime,
81                                          QgsMeshLayer *layer ) SIP_DEPRECATED;
82 
83     /**
84      * Creates calculator with geometry mask
85      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
86      * \param outputFile file to store the resulting dataset group data
87      * \param outputMask spatial filter defined by geometry
88      * \param startTime time filter defining the starting dataset
89      * \param endTime time filter defining the ending dataset
90      * \param layer mesh layer with dataset groups references in formulaString
91      *
92      * \deprecated QGIS 3.12
93      */
94     Q_DECL_DEPRECATED QgsMeshCalculator( const QString &formulaString,
95                                          const QString &outputFile,
96                                          const QgsGeometry &outputMask,
97                                          double startTime,
98                                          double endTime,
99                                          QgsMeshLayer *layer ) SIP_DEPRECATED;
100 
101     /**
102      * Creates calculator with bounding box (rectangular) mask
103      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
104      * \param outputDriver output driver name
105      * \param outputGroupName output group name
106      * \param outputFile file to store the resulting dataset group data
107      * \param outputExtent spatial filter defined by rectangle
108      * \param startTime time filter defining the starting dataset
109      * \param endTime time filter defining the ending dataset
110      * \param layer mesh layer with dataset groups references in formulaString
111      *
112      * \since QGIS 3.12
113      */
114     QgsMeshCalculator( const QString &formulaString,
115                        const QString &outputDriver,
116                        const QString &outputGroupName,
117                        const QString &outputFile,
118                        const QgsRectangle &outputExtent,
119                        double startTime,
120                        double endTime,
121                        QgsMeshLayer *layer );
122 
123     /**
124      * Creates calculator with geometry mask
125      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
126      * \param outputDriver output driver name
127      * \param outputGroupName output group name
128      * \param outputFile file to store the resulting dataset group data
129      * \param outputMask spatial filter defined by geometry
130      * \param startTime time filter defining the starting dataset
131      * \param endTime time filter defining the ending dataset
132      * \param layer mesh layer with dataset groups references in formulaString
133      *
134      * \since QGIS 3.12
135      */
136     QgsMeshCalculator( const QString &formulaString,
137                        const QString &outputDriver,
138                        const QString &outputGroupName,
139                        const QString &outputFile,
140                        const QgsGeometry &outputMask,
141                        double startTime,
142                        double endTime,
143                        QgsMeshLayer *layer );
144 
145     /**
146      * Creates calculator with bounding box (rectangular) mask, store the result in \a destination (must be on memory or virtual),
147      * see QgsMeshCalculator::Destination
148      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
149      * \param outputGroupName output group name
150      * \param outputExtent spatial filter defined by rectangle
151      * \param destination destination of the calculation (memory or virtual)
152      * \param startTime time filter defining the starting dataset
153      * \param endTime time filter defining the ending dataset
154      * \param layer mesh layer with dataset groups references in formulaString
155      *
156      * \since QGIS 3.16
157      */
158     QgsMeshCalculator( const QString &formulaString,
159                        const QString &outputGroupName,
160                        const QgsRectangle &outputExtent,
161                        const QgsMeshDatasetGroup::Type &destination,
162                        QgsMeshLayer *layer,
163                        double startTime,
164                        double endTime );
165 
166     /**
167      * Creates calculator with with geometry mask, store the result in \a destination (must be on memory or virtual),
168      *  see QgsMeshCalculator::Destination
169      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
170      * \param outputGroupName output group name
171      * \param outputMask spatial filter defined by geometry
172      * \param destination destination of the calculation (memory or virtual)
173      * \param startTime time filter defining the starting dataset
174      * \param endTime time filter defining the ending dataset
175      * \param layer mesh layer with dataset groups references in formulaString
176      *
177      * \since QGIS 3.16
178      */
179     QgsMeshCalculator( const QString &formulaString,
180                        const QString &outputGroupName,
181                        const QgsGeometry &outputMask,
182                        const QgsMeshDatasetGroup::Type &destination,
183                        QgsMeshLayer *layer,
184                        double startTime,
185                        double endTime );
186 
187     /**
188      * Starts the calculation, creates new dataset group and adds it to the mesh layer
189      * \param feedback The optional feedback argument for progress reporting and cancellation support
190      * \returns QgsMeshCalculator::Success in case of success
191      */
192     Result processCalculation( QgsFeedback *feedback = nullptr );
193 
194     /**
195      * Returns whether formula is valid for particular mesh layer
196      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
197      * \param layer mesh layer with dataset groups references in formulaString
198      * \returns QgsMeshCalculator::Success in case of success
199      *
200      * \deprecated QGIS 3.12 - use expressionIsValid
201      */
202     Q_DECL_DEPRECATED static Result expression_valid( const QString &formulaString,
203         QgsMeshLayer *layer ) SIP_DEPRECATED;
204 
205     /**
206      * Returns whether formula is valid for particular mesh layer
207      * \param formulaString formula/expression to evaluate. Consists of dataset group names, operators and numbers
208      * \param layer mesh layer with dataset groups references in formulaString
209      * \param requiredCapability returns required capability of driver to store results of the calculation
210      * \returns QgsMeshCalculator::Success in case of success
211      *
212      * \since QGIS 3.12
213      */
214     static Result expressionIsValid( const QString &formulaString,
215                                      QgsMeshLayer *layer,
216                                      QgsMeshDriverMetadata::MeshDriverCapability &requiredCapability );
217 
218   private:
219     QgsMeshCalculator();
220 
221     QString mFormulaString;
222     QString mOutputDriver;
223     QString mOutputGroupName;
224     QString mOutputFile;
225     QgsRectangle mOutputExtent;
226     QgsGeometry mOutputMask;
227     bool mUseMask = false;
228     QgsMeshDatasetGroup::Type mDestination = QgsMeshDatasetGroup::Persistent;
229     double mStartTime = 0.0;
230     double mEndTime = 0.0;
231     QgsMeshLayer *mMeshLayer = nullptr;
232 };
233 
234 #endif // QGSMESHCALCULATOR_H
235