Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgsprocessingalgorithm.h
3 : : ------------------------
4 : : begin : December 2016
5 : : copyright : (C) 2016 by Nyall Dawson
6 : : email : nyall dot dawson 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 QGSPROCESSINGALGORITHM_H
19 : : #define QGSPROCESSINGALGORITHM_H
20 : :
21 : : #include "qgis_core.h"
22 : : #include "qgis.h"
23 : : #include "qgsprocessingparameters.h"
24 : : #include "qgsprocessingoutputs.h"
25 : : #include "qgsprocessingcontext.h"
26 : : #include "qgsfeaturesource.h"
27 : : #include "qgsprocessingutils.h"
28 : : #include <QString>
29 : : #include <QVariant>
30 : : #include <QIcon>
31 : :
32 : : class QgsProcessingProvider;
33 : : class QgsProcessingFeedback;
34 : : class QgsFeatureSink;
35 : : class QgsProcessingModelAlgorithm;
36 : : class QgsProcessingAlgorithmConfigurationWidget;
37 : : class QgsMeshLayer;
38 : :
39 : : #ifdef SIP_RUN
40 : : % ModuleHeaderCode
41 : : #include <qgsprocessingmodelalgorithm.h>
42 : : % End
43 : : #endif
44 : :
45 : : /**
46 : : * \class QgsProcessingAlgorithm
47 : : * \ingroup core
48 : : * \brief Abstract base class for processing algorithms.
49 : : * \since QGIS 3.0
50 : : */
51 : : class CORE_EXPORT QgsProcessingAlgorithm
52 : : {
53 : :
54 : : #ifdef SIP_RUN
55 : : SIP_CONVERT_TO_SUBCLASS_CODE
56 : : if ( dynamic_cast< QgsProcessingModelAlgorithm * >( sipCpp ) != NULL )
57 : : sipType = sipType_QgsProcessingModelAlgorithm;
58 : : else if ( dynamic_cast< QgsProcessingFeatureBasedAlgorithm * >( sipCpp ) != NULL )
59 : : sipType = sipType_QgsProcessingFeatureBasedAlgorithm;
60 : : else
61 : : sipType = sipType_QgsProcessingAlgorithm;
62 : : SIP_END
63 : : #endif
64 : :
65 : : public:
66 : :
67 : : //! Flags indicating how and when an algorithm operates and should be exposed to users
68 : : enum Flag
69 : : {
70 : : FlagHideFromToolbox = 1 << 1, //!< Algorithm should be hidden from the toolbox
71 : : FlagHideFromModeler = 1 << 2, //!< Algorithm should be hidden from the modeler
72 : : FlagSupportsBatch = 1 << 3, //!< Algorithm supports batch mode
73 : : FlagCanCancel = 1 << 4, //!< Algorithm can be canceled
74 : : FlagRequiresMatchingCrs = 1 << 5, //!< Algorithm requires that all input layers have matching coordinate reference systems
75 : : FlagNoThreading = 1 << 6, //!< Algorithm is not thread safe and cannot be run in a background thread, e.g. for algorithms which manipulate the current project, layer selections, or with external dependencies which are not thread-safe.
76 : : FlagDisplayNameIsLiteral = 1 << 7, //!< Algorithm's display name is a static literal string, and should not be translated or automatically formatted. For use with algorithms named after commands, e.g. GRASS 'v.in.ogr'.
77 : : FlagSupportsInPlaceEdits = 1 << 8, //!< Algorithm supports in-place editing
78 : : FlagKnownIssues = 1 << 9, //!< Algorithm has known issues
79 : : FlagCustomException = 1 << 10, //!< Algorithm raises custom exception notices, don't use the standard ones
80 : : FlagPruneModelBranchesBasedOnAlgorithmResults = 1 << 11, //!< Algorithm results will cause remaining model branches to be pruned based on the results of running the algorithm
81 : : FlagSkipGenericModelLogging = 1 << 12, //!< When running as part of a model, the generic algorithm setup and results logging should be skipped
82 : : FlagNotAvailableInStandaloneTool = 1 << 13, //!< Algorithm should not be available from the standalone "qgis_process" tool. Used to flag algorithms which make no sense outside of the QGIS application, such as "select by..." style algorithms.
83 : : FlagRequiresProject = 1 << 14, //!< The algorithm requires that a valid QgsProject is available from the processing context in order to execute
84 : : FlagDeprecated = FlagHideFromToolbox | FlagHideFromModeler, //!< Algorithm is deprecated
85 : : };
86 : : Q_DECLARE_FLAGS( Flags, Flag )
87 : :
88 : : /**
89 : : * Constructor for QgsProcessingAlgorithm.
90 : : *
91 : : * initAlgorithm() should be called after creating an algorithm to ensure it can correctly configure
92 : : * its parameterDefinitions() and outputDefinitions(). Alternatively, calling create() will return
93 : : * a pre-initialized copy of the algorithm.
94 : : */
95 : 0 : QgsProcessingAlgorithm() = default;
96 : :
97 : : virtual ~QgsProcessingAlgorithm();
98 : :
99 : : //! Algorithms cannot be copied - create() should be used instead
100 : : QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other ) = delete;
101 : : //! Algorithms cannot be copied- create() should be used instead
102 : : QgsProcessingAlgorithm &operator=( const QgsProcessingAlgorithm &other ) = delete;
103 : :
104 : : /*
105 : : * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
106 : : * the case.
107 : : * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
108 : : *
109 : : * "
110 : : * /Factory/ is used when the instance returned is guaranteed to be new to Python.
111 : : * In this case it isn't because it has already been seen when being returned by createInstance()
112 : : * (However for a different sub-class implemented in C++ then it would be the first time it was seen
113 : : * by Python so the /Factory/ on create() would be correct.)
114 : : *
115 : : * You might try using /TransferBack/ on create() instead - that might be the best compromise.
116 : : * "
117 : : */
118 : :
119 : : /**
120 : : * Creates a copy of the algorithm, ready for execution.
121 : : *
122 : : * This method returns a new, preinitialized copy of the algorithm, ready for
123 : : * executing.
124 : : *
125 : : * The \a configuration argument allows passing of a map of configuration settings
126 : : * to the algorithm, allowing it to dynamically adjust its initialized parameters
127 : : * and outputs according to this configuration. This is generally used only for
128 : : * algorithms in a model, allowing them to adjust their behavior at run time
129 : : * according to some user configuration.
130 : : *
131 : : * Raises a QgsProcessingException if a new algorithm instance could not be created,
132 : : * e.g. if there is an issue with the subclass' createInstance() method.
133 : : *
134 : : * \see initAlgorithm()
135 : : */
136 : : QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
137 : :
138 : : /**
139 : : * Returns the algorithm name, used for identifying the algorithm. This string
140 : : * should be fixed for the algorithm, and must not be localised. The name should
141 : : * be unique within each provider. Names should contain lowercase alphanumeric characters
142 : : * only and no spaces or other formatting characters.
143 : : * \see displayName()
144 : : * \see group()
145 : : * \see tags()
146 : : */
147 : : virtual QString name() const = 0;
148 : :
149 : : /**
150 : : * Returns the unique ID for the algorithm, which is a combination of the algorithm
151 : : * provider's ID and the algorithms unique name (e.g. "qgis:mergelayers" ).
152 : : * \see name()
153 : : * \see provider()
154 : : */
155 : : QString id() const;
156 : :
157 : : /**
158 : : * Returns the translated algorithm name, which should be used for any user-visible display
159 : : * of the algorithm name.
160 : : *
161 : : * Algorithm display names should be short, e.g. ideally no more than 3 or 4 words.
162 : : * The name should use sentence case (e.g. "Raster layer statistics", not "Raster Layer Statistics").
163 : : *
164 : : * \see name()
165 : : * \see shortDescription()
166 : : */
167 : : virtual QString displayName() const = 0;
168 : :
169 : : /**
170 : : * Returns an optional translated short description of the algorithm. This should be
171 : : * at most a single sentence, e.g. "Converts 2D features to 3D by sampling a DEM raster."
172 : : * \since QGIS 3.2
173 : : */
174 : : virtual QString shortDescription() const;
175 : :
176 : : /**
177 : : * Returns a list of tags which relate to the algorithm, and are used to assist users in searching
178 : : * for suitable algorithms. These tags should be localised.
179 : : */
180 : 0 : virtual QStringList tags() const { return QStringList(); }
181 : :
182 : : /**
183 : : * Returns a localised short helper string for the algorithm. This string should provide a basic description
184 : : * about what the algorithm does and the parameters and outputs associated with it.
185 : : * \see helpString()
186 : : * \see helpUrl()
187 : : */
188 : : virtual QString shortHelpString() const;
189 : :
190 : : /**
191 : : * Returns a localised help string for the algorithm. Algorithm subclasses should implement either
192 : : * helpString() or helpUrl().
193 : : * \see helpUrl()
194 : : * \see shortHelpString()
195 : : * \deprecated Unused, will be removed in QGIS 4.0
196 : : */
197 : : Q_DECL_DEPRECATED virtual QString helpString() const SIP_DEPRECATED;
198 : :
199 : : /**
200 : : * Returns a url pointing to the algorithm's help page.
201 : : * \see helpString()
202 : : * \see shortHelpString()
203 : : */
204 : : virtual QString helpUrl() const;
205 : :
206 : : /**
207 : : * Returns an icon for the algorithm.
208 : : * \see svgIconPath()
209 : : */
210 : : virtual QIcon icon() const;
211 : :
212 : : /**
213 : : * Returns a path to an SVG version of the algorithm's icon.
214 : : * \see icon()
215 : : */
216 : : virtual QString svgIconPath() const;
217 : :
218 : : /**
219 : : * Returns the name of the group this algorithm belongs to. This string
220 : : * should be localised.
221 : : * \see groupId()
222 : : * \see tags()
223 : : */
224 : 0 : virtual QString group() const { return QString(); }
225 : :
226 : : /**
227 : : * Returns the unique ID of the group this algorithm belongs to. This string
228 : : * should be fixed for the algorithm, and must not be localised. The group id
229 : : * should be unique within each provider. Group id should contain lowercase
230 : : * alphanumeric characters only and no spaces or other formatting characters.
231 : : * \see group()
232 : : */
233 : 0 : virtual QString groupId() const { return QString(); }
234 : :
235 : : /**
236 : : * Returns the flags indicating how and when the algorithm operates and should be exposed to users.
237 : : * Default flags are FlagSupportsBatch and FlagCanCancel.
238 : : */
239 : : virtual Flags flags() const;
240 : :
241 : : /**
242 : : * Returns TRUE if the algorithm can execute. Algorithm subclasses can return FALSE
243 : : * here to indicate that they are not able to execute, e.g. as a result of unmet
244 : : * external dependencies. If specified, the \a errorMessage argument will be filled
245 : : * with a localised error message describing why the algorithm cannot execute.
246 : : */
247 : : virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
248 : :
249 : : /**
250 : : * Checks the supplied \a parameter values to verify that they satisfy the requirements
251 : : * of this algorithm in the supplied \a context. The \a message parameter will be
252 : : * filled with explanatory text if validation fails.
253 : : * Overridden implementations should also check this base class implementation.
254 : : * \returns TRUE if parameters are acceptable for the algorithm.
255 : : */
256 : : virtual bool checkParameterValues( const QVariantMap ¶meters,
257 : : QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
258 : :
259 : : /**
260 : : * Pre-processes a set of \a parameters, allowing the algorithm to clean their
261 : : * values.
262 : : *
263 : : * This method is automatically called after users enter parameters, e.g. via the algorithm
264 : : * dialog. This method should NOT be called manually by algorithms.
265 : : */
266 : : virtual QVariantMap preprocessParameters( const QVariantMap ¶meters );
267 : :
268 : : /**
269 : : * Returns the provider to which this algorithm belongs.
270 : : */
271 : : QgsProcessingProvider *provider() const;
272 : :
273 : : /**
274 : : * Returns an ordered list of parameter definitions utilized by the algorithm.
275 : : * \see addParameter()
276 : : * \see parameterDefinition()
277 : : * \see destinationParameterDefinitions()
278 : : */
279 : 0 : QgsProcessingParameterDefinitions parameterDefinitions() const { return mParameters; }
280 : :
281 : : /**
282 : : * Returns a matching parameter by \a name. Matching is done in a case-insensitive
283 : : * manner, but exact case matches will be preferred.
284 : : * \see parameterDefinitions()
285 : : */
286 : : const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
287 : :
288 : : /**
289 : : * Returns the number of visible (non-hidden) parameters defined by this
290 : : * algorithm.
291 : : */
292 : : int countVisibleParameters() const;
293 : :
294 : : /**
295 : : * Returns a list of destination parameters definitions utilized by the algorithm.
296 : : * \see QgsProcessingParameterDefinition::isDestination()
297 : : * \see parameterDefinitions()
298 : : */
299 : : QgsProcessingParameterDefinitions destinationParameterDefinitions() const;
300 : :
301 : : /**
302 : : * Returns an ordered list of output definitions utilized by the algorithm.
303 : : * \see addOutput()
304 : : * \see outputDefinition()
305 : : */
306 : 0 : QgsProcessingOutputDefinitions outputDefinitions() const { return mOutputs; }
307 : :
308 : : /**
309 : : * Returns a matching output by \a name. Matching is done in a case-insensitive
310 : : * manner.
311 : : * \see outputDefinitions()
312 : : */
313 : : const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const;
314 : :
315 : : /**
316 : : * Returns TRUE if this algorithm generates HTML outputs.
317 : : */
318 : : bool hasHtmlOutputs() const;
319 : :
320 : : /**
321 : : * Property availability, used for QgsProcessingAlgorithm::VectorProperties
322 : : * in order to determine if properties are available or not
323 : : */
324 : : enum PropertyAvailability
325 : : {
326 : : NotAvailable, //!< Properties are not available
327 : : Available, //!< Properties are available
328 : : };
329 : :
330 : : /**
331 : : * Properties of a vector source or sink used in an algorithm.
332 : : *
333 : : * \since QGIS 3.14
334 : : */
335 : 0 : struct VectorProperties
336 : : {
337 : : //! Fields
338 : : QgsFields fields;
339 : :
340 : : //! Geometry (WKB) type
341 : 0 : QgsWkbTypes::Type wkbType = QgsWkbTypes::Unknown;
342 : :
343 : : //! Coordinate Reference System
344 : : QgsCoordinateReferenceSystem crs;
345 : :
346 : : //! Availability of the properties. By default properties are not available.
347 : 0 : QgsProcessingAlgorithm::PropertyAvailability availability = QgsProcessingAlgorithm::NotAvailable;
348 : : };
349 : :
350 : : /**
351 : : * Returns the vector properties which will be used for the \a sink with matching name.
352 : : *
353 : : * The \a parameters argument specifies the values of all parameters which would be used to generate
354 : : * the sink. These can be used alongside the provided \a context in order to pre-evaluate inputs
355 : : * when required in order to determine the sink's properties.
356 : : *
357 : : * The \a sourceProperties map will contain the vector properties of the various sources used
358 : : * as inputs to the algorithm. These will only be available in certain circumstances (e.g. when the
359 : : * algorithm is used within a model), so implementations will need to be adaptable to circumstances
360 : : * when either \a sourceParameters is empty or \a parameters is empty, and use whatever information
361 : : * is passed in order to make a best guess determination of the output properties.
362 : : *
363 : : * \since QGIS 3.14
364 : : */
365 : : virtual QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
366 : : const QVariantMap ¶meters,
367 : : QgsProcessingContext &context,
368 : : const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const;
369 : :
370 : : /**
371 : : * Executes the algorithm using the specified \a parameters. This method internally
372 : : * creates a copy of the algorithm before running it, so it is safe to call
373 : : * on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider.
374 : : *
375 : : * The \a context argument specifies the context in which the algorithm is being run.
376 : : *
377 : : * Algorithm progress should be reported using the supplied \a feedback object.
378 : : *
379 : : * If specified, \a ok will be set to TRUE if algorithm was successfully run.
380 : : *
381 : : * If \a catchExceptions is set to FALSE, then QgsProcessingException raised during
382 : : * the algorithm run will not be automatically caught and will be raised instead.
383 : : *
384 : : * \returns A map of algorithm outputs. These may be output layer references, or calculated
385 : : * values such as statistical calculations.
386 : : *
387 : : * \note this method can only be called from the main thread. Use prepare(), runPrepared() and postProcess()
388 : : * if you need to run algorithms from a background thread, or use the QgsProcessingAlgRunnerTask class.
389 : : */
390 : : QVariantMap run( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap(),
391 : : bool catchExceptions = true ) const SIP_THROW( QgsProcessingException );
392 : :
393 : : /**
394 : : * Prepares the algorithm for execution. This must be run in the main thread, and allows the algorithm
395 : : * to pre-evaluate input parameters in a thread-safe manner. This must be called before
396 : : * calling runPrepared() (which is safe to do in any thread).
397 : : * \see runPrepared()
398 : : * \see postProcess()
399 : : * \note This method modifies the algorithm instance, so it is not safe to call
400 : : * on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
401 : : * of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
402 : : */
403 : : bool prepare( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
404 : :
405 : : /**
406 : : * Runs the algorithm, which has been prepared by an earlier call to prepare().
407 : : * This method is safe to call from any thread. Returns TRUE if the algorithm was successfully executed.
408 : : * After runPrepared() has finished, the postProcess() method should be called from the main thread
409 : : * to allow the algorithm to perform any required cleanup tasks and return its final result.
410 : : * \see prepare()
411 : : * \see postProcess()
412 : : * \note This method modifies the algorithm instance, so it is not safe to call
413 : : * on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
414 : : * of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
415 : : */
416 : : QVariantMap runPrepared( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );
417 : :
418 : : /**
419 : : * Should be called in the main thread following the completion of runPrepared(). This method
420 : : * allows the algorithm to perform any required cleanup tasks. The returned variant map
421 : : * includes the results evaluated by the algorithm.
422 : : * \note This method modifies the algorithm instance, so it is not safe to call
423 : : * on algorithms directly retrieved from QgsProcessingRegistry and QgsProcessingProvider. Instead, a copy
424 : : * of the algorithm should be created with clone() and prepare()/runPrepared() called on the copy.
425 : : */
426 : : QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
427 : :
428 : : /**
429 : : * If an algorithm subclass implements a custom parameters widget, a copy of this widget
430 : : * should be constructed and returned by this method.
431 : : * The base class implementation returns NULLPTR, which indicates that an autogenerated
432 : : * parameters widget should be used.
433 : : */
434 : : virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
435 : :
436 : : /**
437 : : * Creates an expression context relating to the algorithm. This can be called by algorithms
438 : : * to create a new expression context ready for evaluating expressions within the algorithm.
439 : : * Optionally, a \a source can be specified which will be used to populate the context if it
440 : : * implements the QgsExpressionContextGenerator interface.
441 : : */
442 : : virtual QgsExpressionContext createExpressionContext( const QVariantMap ¶meters,
443 : : QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
444 : :
445 : : /**
446 : : * Checks whether the coordinate reference systems for the specified set of \a parameters
447 : : * are valid for the algorithm. For instance, the base implementation performs
448 : : * checks to ensure that all input CRS are equal
449 : : * Returns TRUE if \a parameters have passed the CRS check.
450 : : */
451 : : virtual bool validateInputCrs( const QVariantMap ¶meters,
452 : : QgsProcessingContext &context ) const;
453 : :
454 : : /**
455 : : * Returns a Python command string which can be executed to run the algorithm
456 : : * using the specified \a parameters.
457 : : *
458 : : * Algorithms which cannot be run from a Python command should return an empty
459 : : * string.
460 : : */
461 : : virtual QString asPythonCommand( const QVariantMap ¶meters, QgsProcessingContext &context ) const;
462 : :
463 : : /**
464 : : * Associates this algorithm with its provider. No transfer of ownership is involved.
465 : : */
466 : : void setProvider( QgsProcessingProvider *provider );
467 : :
468 : : protected:
469 : :
470 : : /**
471 : : * Creates a new instance of the algorithm class.
472 : : *
473 : : * This method should return a 'pristine' instance of the algorithm class.
474 : : */
475 : : virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );
476 : :
477 : : /**
478 : : * Initializes the algorithm using the specified \a configuration.
479 : : *
480 : : * This should be called directly after creating algorithms and before retrieving
481 : : * any parameterDefinitions() or outputDefinitions().
482 : : *
483 : : * Subclasses should use their implementations to add all required input parameter and output
484 : : * definitions (which can be dynamically adjusted according to \a configuration).
485 : : *
486 : : * Dynamic configuration can be used by algorithms which alter their behavior
487 : : * when used inside processing models. For instance, a "feature router" type
488 : : * algorithm which sends input features to one of any number of outputs sinks
489 : : * based on some preconfigured filter parameters can use the init method to
490 : : * create these outputs based on the specified \a configuration.
491 : : *
492 : : * \see addParameter()
493 : : * \see addOutput()
494 : : */
495 : : virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
496 : :
497 : : /**
498 : : * Adds a parameter \a definition to the algorithm. Ownership of the definition is transferred to the algorithm.
499 : : * Returns TRUE if parameter could be successfully added, or FALSE if the parameter could not be added (e.g.
500 : : * as a result of a duplicate name).
501 : : *
502 : : * This should usually be called from a subclass' initAlgorithm() implementation.
503 : : *
504 : : * If the \a createOutput argument is TRUE, then a corresponding output definition will also be created
505 : : * (and added to the algorithm) where appropriate. E.g. when adding a QgsProcessingParameterVectorDestination
506 : : * and \a createOutput is TRUE, then a QgsProcessingOutputVectorLayer output will be created and
507 : : * added to the algorithm. There is no need to call addOutput() to manually add a corresponding output
508 : : * for this vector. If \a createOutput is FALSE then this automatic output creation will not
509 : : * occur.
510 : : *
511 : : * \see initAlgorithm()
512 : : * \see addOutput()
513 : : */
514 : : bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true );
515 : :
516 : : /**
517 : : * Removes the parameter with matching \a name from the algorithm, and deletes any existing
518 : : * definition.
519 : : */
520 : : void removeParameter( const QString &name );
521 : :
522 : : /**
523 : : * Adds an output \a definition to the algorithm. Ownership of the definition is transferred to the algorithm.
524 : : * Returns TRUE if the output could be successfully added, or FALSE if the output could not be added (e.g.
525 : : * as a result of a duplicate name).
526 : : *
527 : : * This should usually be called from a subclass' initAlgorithm() implementation.
528 : : *
529 : : * Note that in some cases output creation can be automatically performed when calling addParameter().
530 : : * See the notes in addParameter() for a description of when this occurs.
531 : : *
532 : : * \see addParameter()
533 : : * \see initAlgorithm()
534 : : */
535 : : bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER );
536 : :
537 : : /**
538 : : * Prepares the algorithm to run using the specified \a parameters. Algorithms should implement
539 : : * their logic for evaluating parameter values here. The evaluated parameter results should
540 : : * be stored in member variables ready for a call to processAlgorithm().
541 : : *
542 : : * The \a context argument specifies the context in which the algorithm is being run.
543 : : *
544 : : * prepareAlgorithm should be used to handle any thread-sensitive preparation which is required
545 : : * by the algorithm. It will always be called from the same thread that \a context has thread
546 : : * affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
547 : : * algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
548 : : * will call prepareAlgorithm from the same thread as that model/script it being executed in.
549 : : *
550 : : * Note that the processAlgorithm step uses a temporary context with affinity for the thread in
551 : : * which the algorithm is executed, making it safe for processAlgorithm implementations to load
552 : : * sources and sinks without issue. Implementing prepareAlgorithm is only required if special
553 : : * thread safe handling is required by the algorithm.
554 : : *
555 : : * Algorithm preparation progress should be reported using the supplied \a feedback object. Additionally,
556 : : * well-behaved algorithms should periodically check \a feedback to determine whether the
557 : : * algorithm should be canceled and exited early.
558 : : *
559 : : * If the preparation was successful algorithms must return TRUE. If a FALSE value is returned
560 : : * this indicates that the preparation could not be completed, and the algorithm execution
561 : : * will be canceled.
562 : : *
563 : : * \returns TRUE if preparation was successful.
564 : : * \see processAlgorithm()
565 : : * \see postProcessAlgorithm()
566 : : */
567 : : virtual bool prepareAlgorithm( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
568 : :
569 : : /**
570 : : * Runs the algorithm using the specified \a parameters. Algorithms should implement
571 : : * their custom processing logic here.
572 : : *
573 : : * The \a context argument gives a temporary context with thread affinity matching the thread
574 : : * in which the algorithm is being run. This is a cut-back copy of the context passed to
575 : : * the prepareAlgorithm() and postProcessAlgorithm() steps, but it is generally safe
576 : : * for most algorithms to utilize this context for loading layers and creating sinks.
577 : : * Any loaded layers or sinks created within this temporary context will be transferred
578 : : * back to the main execution context upon successful completion of the processAlgorithm()
579 : : * step.
580 : : *
581 : : * Algorithm progress should be reported using the supplied \a feedback object. Additionally,
582 : : * well-behaved algorithms should periodically check \a feedback to determine whether the
583 : : * algorithm should be canceled and exited early.
584 : : *
585 : : * This method will not be called if the prepareAlgorithm() step failed (returned FALSE).
586 : : *
587 : : * Implementations of processAlgorithm can throw the QgsProcessingException exception
588 : : * to indicate that a fatal error occurred within the execution.
589 : : *
590 : : * \returns A map of algorithm outputs. These may be output layer references, or calculated
591 : : * values such as statistical calculations. Unless the algorithm subclass overrides
592 : : * the postProcessAlgorithm() step this returned map will be used as the output for the
593 : : * algorithm.
594 : : *
595 : : * \see prepareAlgorithm()
596 : : * \see postProcessAlgorithm()
597 : : */
598 : : virtual QVariantMap processAlgorithm( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
599 : :
600 : : /**
601 : : * Allows the algorithm to perform any required cleanup tasks. The returned variant map
602 : : * includes the results evaluated by the algorithm. These may be output layer references, or calculated
603 : : * values such as statistical calculations.
604 : : *
605 : : * The \a context argument specifies the context in which the algorithm was run.
606 : : *
607 : : * Postprocess progress should be reported using the supplied \a feedback object. Additionally,
608 : : * well-behaved algorithms should periodically check \a feedback to determine whether the
609 : : * post processing should be canceled and exited early.
610 : : *
611 : : * postProcessAlgorithm should be used to handle any thread-sensitive cleanup which is required
612 : : * by the algorithm. It will always be called from the same thread that \a context has thread
613 : : * affinity with. While this will generally be the main thread, it is not guaranteed. For instance,
614 : : * algorithms which are run as a step in a larger model or as a subcomponent of a script-based algorithm
615 : : * will call postProcessAlgorithm from the same thread as that model/script it being executed in.
616 : : *
617 : : * postProcessAlgorithm will not be called if the prepareAlgorithm() step failed (returned FALSE),
618 : : * or if an exception was raised by the processAlgorithm() step.
619 : : *
620 : : * \returns A map of algorithm outputs. These may be output layer references, or calculated
621 : : * values such as statistical calculations. Implementations which return a non-empty
622 : : * map will override any results returned by processAlgorithm().
623 : : *
624 : : * \see prepareAlgorithm()
625 : : * \see processAlgorithm()
626 : : */
627 : : virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
628 : :
629 : : /**
630 : : * Evaluates the parameter with matching \a name to a static string value.
631 : : */
632 : : QString parameterAsString( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
633 : :
634 : : /**
635 : : * Evaluates the parameter with matching \a name to an expression.
636 : : */
637 : : QString parameterAsExpression( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
638 : :
639 : : /**
640 : : * Evaluates the parameter with matching \a name to a static double value.
641 : : */
642 : : double parameterAsDouble( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
643 : :
644 : : /**
645 : : * Evaluates the parameter with matching \a name to a static integer value.
646 : : */
647 : : int parameterAsInt( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
648 : :
649 : : /**
650 : : * Evaluates the parameter with matching \a name to a list of integer values.
651 : : * \since QGIS 3.4
652 : : */
653 : : QList<int> parameterAsInts( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
654 : :
655 : : /**
656 : : * Evaluates the parameter with matching \a name to a enum value.
657 : : */
658 : : int parameterAsEnum( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
659 : :
660 : : /**
661 : : * Evaluates the parameter with matching \a name to list of enum values.
662 : : */
663 : : QList<int> parameterAsEnums( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
664 : :
665 : : /**
666 : : * Evaluates the parameter with matching \a name to a static enum string.
667 : : * \since QGIS 3.18
668 : : */
669 : : QString parameterAsEnumString( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
670 : :
671 : : /**
672 : : * Evaluates the parameter with matching \a name to list of static enum strings.
673 : : * \since QGIS 3.18
674 : : */
675 : : QStringList parameterAsEnumStrings( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
676 : :
677 : : /**
678 : : * Evaluates the parameter with matching \a name to a static boolean value.
679 : : */
680 : : bool parameterAsBool( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
681 : :
682 : : /**
683 : : * Evaluates the parameter with matching \a name to a static boolean value.
684 : : * \since QGIS 3.8
685 : : */
686 : : bool parameterAsBoolean( const QVariantMap ¶meters, const QString &name, const QgsProcessingContext &context ) const;
687 : :
688 : : /**
689 : : * Evaluates the parameter with matching \a name to a feature sink.
690 : : *
691 : : * Sinks will either be taken from \a context's active project, or created from external
692 : : * providers and stored temporarily in the \a context.
693 : : *
694 : : * The \a fields, \a geometryType and \a crs parameters dictate the properties
695 : : * of the resulting feature sink.
696 : : *
697 : : * The \a destinationIdentifier argument will be set to a string which can be used to retrieve the layer corresponding
698 : : * to the sink, e.g. via calling QgsProcessingUtils::mapLayerFromString().
699 : : *
700 : : * The \a createOptions argument is used to pass on creation options such as layer name.
701 : : *
702 : : * The \a datasourceOptions and \a layerOptions arguments is used to pass on GDAL-specific format driver options.
703 : : *
704 : : * This function creates a new object and the caller takes responsibility for deleting the returned object.
705 : : *
706 : : * \throws QgsProcessingException
707 : : */
708 : : QgsFeatureSink *parameterAsSink( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
709 : : const QgsFields &fields, QgsWkbTypes::Type geometryType = QgsWkbTypes::NoGeometry, const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem(), QgsFeatureSink::SinkFlags sinkFlags = QgsFeatureSink::SinkFlags(), const QVariantMap &createOptions = QVariantMap(), const QStringList &datasourceOptions = QStringList(), const QStringList &layerOptions = QStringList() ) const SIP_THROW( QgsProcessingException ) SIP_FACTORY;
710 : :
711 : : /**
712 : : * Evaluates the parameter with matching \a name to a feature source.
713 : : *
714 : : * Sources will either be taken from \a context's active project, or loaded from external
715 : : * sources and stored temporarily in the \a context.
716 : : *
717 : : * This function creates a new object and the caller takes responsibility for deleting the returned object.
718 : : */
719 : : QgsProcessingFeatureSource *parameterAsSource( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
720 : :
721 : : /**
722 : : * Evaluates the parameter with matching \a name to a source vector layer file path of compatible format.
723 : : *
724 : : * If the parameter is evaluated to an existing layer, and that layer is not of the format listed in the
725 : : * \a compatibleFormats argument, then the layer will first be exported to a compatible format
726 : : * in a temporary location. The function will then return the path to that temporary file.
727 : : *
728 : : * \a compatibleFormats should consist entirely of lowercase file extensions, e.g. 'shp'.
729 : : *
730 : : * The \a preferredFormat argument is used to specify to desired file extension to use when a temporary
731 : : * layer export is required.
732 : : *
733 : : * When an algorithm is capable of handling multi-layer input files (such as Geopackage), it is preferable
734 : : * to use parameterAsCompatibleSourceLayerPathAndLayerName() which may avoid conversion in more situations.
735 : : */
736 : : QString parameterAsCompatibleSourceLayerPath( const QVariantMap ¶meters, const QString &name,
737 : : QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr );
738 : :
739 : : /**
740 : : * Evaluates the parameter with matching \a name to a source vector layer file path and layer name of compatible format.
741 : : *
742 : : * If the parameter is evaluated to an existing layer, and that layer is not of the format listed in the
743 : : * \a compatibleFormats argument, then the layer will first be exported to a compatible format
744 : : * in a temporary location. The function will then return the path to that temporary file.
745 : : *
746 : : * \a compatibleFormats should consist entirely of lowercase file extensions, e.g. 'shp'.
747 : : *
748 : : * The \a preferredFormat argument is used to specify to desired file extension to use when a temporary
749 : : * layer export is required. This defaults to shapefiles, because shapefiles are the future (don't believe the geopackage hype!).
750 : : *
751 : : * This method should be preferred over parameterAsCompatibleSourceLayerPath() when an algorithm is able
752 : : * to correctly handle files with multiple layers. Unlike parameterAsCompatibleSourceLayerPath(), it will not force
753 : : * a conversion in this case and will return the target layer name in the \a layerName argument.
754 : : *
755 : : * \param parameters input parameter value map
756 : : * \param name name of target parameter
757 : : * \param context processing context
758 : : * \param compatibleFormats a list of lowercase file extensions compatible with the algorithm
759 : : * \param preferredFormat preferred format extension to use if conversion if required
760 : : * \param feedback feedback object
761 : : * \param layerName will be set to the target layer name for multi-layer sources (e.g. Geopackage)
762 : : *
763 : : * \returns path to source layer, or nearly converted compatible layer
764 : : *
765 : : * \see parameterAsCompatibleSourceLayerPath()
766 : : * \since QGIS 3.10
767 : : */
768 : : QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap ¶meters, const QString &name,
769 : : QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr );
770 : :
771 : : /**
772 : : * Evaluates the parameter with matching \a name to a map layer.
773 : : *
774 : : * Layers will either be taken from \a context's active project, or loaded from external
775 : : * sources and stored temporarily in the \a context. In either case, callers do not
776 : : * need to handle deletion of the returned layer.
777 : : */
778 : : QgsMapLayer *parameterAsLayer( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
779 : :
780 : : /**
781 : : * Evaluates the parameter with matching \a name to a raster layer.
782 : : *
783 : : * Layers will either be taken from \a context's active project, or loaded from external
784 : : * sources and stored temporarily in the \a context. In either case, callers do not
785 : : * need to handle deletion of the returned layer.
786 : : */
787 : : QgsRasterLayer *parameterAsRasterLayer( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
788 : :
789 : : /**
790 : : * Evaluates the parameter with matching \a name to a mesh layer.
791 : : *
792 : : * Layers will either be taken from \a context's active project, or loaded from external
793 : : * sources and stored temporarily in the \a context. In either case, callers do not
794 : : * need to handle deletion of the returned layer.
795 : : *
796 : : * \since QGIS 3.6
797 : : */
798 : : QgsMeshLayer *parameterAsMeshLayer( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
799 : :
800 : :
801 : : /**
802 : : * Evaluates the parameter with matching \a name to a output layer destination.
803 : : */
804 : : QString parameterAsOutputLayer( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
805 : :
806 : : /**
807 : : * Evaluates the parameter with matching \a name to a file based output destination.
808 : : */
809 : : QString parameterAsFileOutput( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
810 : :
811 : : /**
812 : : * Evaluates the parameter with matching \a name to a vector layer.
813 : : *
814 : : * Layers will either be taken from \a context's active project, or loaded from external
815 : : * sources and stored temporarily in the \a context. In either case, callers do not
816 : : * need to handle deletion of the returned layer.
817 : : */
818 : : QgsVectorLayer *parameterAsVectorLayer( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
819 : :
820 : : /**
821 : : * Evaluates the parameter with matching \a name to a coordinate reference system.
822 : : */
823 : : QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
824 : :
825 : : /**
826 : : * Evaluates the parameter with matching \a name to a rectangular extent.
827 : : *
828 : : * If \a crs is set, and the original coordinate reference system of the parameter can be determined, then the extent will be automatically
829 : : * reprojected so that it is in the specified \a crs. In this case the extent of the reproject rectangle will be returned.
830 : : *
831 : : * \see parameterAsExtentGeometry()
832 : : */
833 : : QgsRectangle parameterAsExtent( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context,
834 : : const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
835 : :
836 : : /**
837 : : * Evaluates the parameter with matching \a name to a rectangular extent, and returns a geometry covering this extent.
838 : : *
839 : : * If \a crs is set, and the original coordinate reference system of the parameter can be determined, then the extent will be automatically
840 : : * reprojected so that it is in the specified \a crs. Unlike parameterAsExtent(), the reprojected rectangle returned by this function
841 : : * will no longer be a rectangle itself (i.e. this method returns the geometry of the actual reprojected rectangle, while parameterAsExtent() returns
842 : : * just the extent of the reprojected rectangle).
843 : : *
844 : : * \see parameterAsExtent()
845 : : */
846 : : QgsGeometry parameterAsExtentGeometry( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context,
847 : : const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() );
848 : :
849 : : /**
850 : : * Returns the coordinate reference system associated with an extent parameter value.
851 : : *
852 : : * \see parameterAsExtent()
853 : : */
854 : : QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
855 : :
856 : : /**
857 : : * Evaluates the parameter with matching \a name to a point.
858 : : *
859 : : * If \a crs is set then the point will be automatically
860 : : * reprojected so that it is in the specified \a crs.
861 : : *
862 : : * \see parameterAsPointCrs()
863 : : */
864 : : QgsPointXY parameterAsPoint( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context,
865 : : const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
866 : :
867 : : /**
868 : : * Returns the coordinate reference system associated with an point parameter value.
869 : : *
870 : : * \see parameterAsPoint()
871 : : */
872 : : QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
873 : :
874 : : /**
875 : : * Evaluates the parameter with matching \a name to a geometry.
876 : : *
877 : : * If \a crs is set then the geometry will be automatically
878 : : * reprojected so that it is in the specified \a crs.
879 : : *
880 : : * \see parameterAsGeometryCrs()
881 : : */
882 : : QgsGeometry parameterAsGeometry( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context,
883 : : const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
884 : :
885 : : /**
886 : : * Returns the coordinate reference system associated with a geometry parameter value.
887 : : *
888 : : * \see parameterAsGeometry()
889 : : */
890 : : QgsCoordinateReferenceSystem parameterAsGeometryCrs( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
891 : :
892 : :
893 : :
894 : : /**
895 : : * Evaluates the parameter with matching \a name to a file/folder name.
896 : : */
897 : : QString parameterAsFile( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
898 : :
899 : : /**
900 : : * Evaluates the parameter with matching \a name to a matrix/table of values.
901 : : * Tables are collapsed to a 1 dimensional list.
902 : : */
903 : : QVariantList parameterAsMatrix( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
904 : :
905 : : /**
906 : : * Evaluates the parameter with matching \a name to a list of map layers.
907 : : */
908 : : QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
909 : :
910 : : /**
911 : : * Evaluates the parameter with matching \a name to a list of files (for QgsProcessingParameterMultipleLayers in QgsProcessing:TypeFile mode).
912 : : *
913 : : * \since QGIS 3.10
914 : : */
915 : : QStringList parameterAsFileList( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
916 : :
917 : : /**
918 : : * Evaluates the parameter with matching \a name to a range of values.
919 : : */
920 : : QList<double> parameterAsRange( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
921 : :
922 : : /**
923 : : * Evaluates the parameter with matching \a name to a list of fields.
924 : : */
925 : : QStringList parameterAsFields( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context ) const;
926 : :
927 : : /**
928 : : * Evaluates the parameter with matching \a name to a print layout.
929 : : *
930 : : * \warning This method is not safe to run in a background thread, so it must either be used within a prepareAlgorithm
931 : : * implementation (which runs in the main thread), or the algorithm must return the FlagNoThreading flag.
932 : : *
933 : : * \since QGIS 3.8
934 : : */
935 : : QgsPrintLayout *parameterAsLayout( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
936 : :
937 : : /**
938 : : * Evaluates the parameter with matching \a name to a print layout item, taken from the specified \a layout.
939 : : *
940 : : * \warning This method is not safe to run in a background thread, so it must either be used within a prepareAlgorithm
941 : : * implementation (which runs in the main thread), or the algorithm must return the FlagNoThreading flag.
942 : : *
943 : : * \since QGIS 3.8
944 : : */
945 : : QgsLayoutItem *parameterAsLayoutItem( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );
946 : :
947 : : /**
948 : : * Evaluates the parameter with matching \a name to a color, or returns an invalid color if the parameter was not set.
949 : : *
950 : : * \since QGIS 3.10
951 : : */
952 : : QColor parameterAsColor( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
953 : :
954 : : /**
955 : : * Evaluates the parameter with matching \a name to a connection name string.
956 : : *
957 : : * \since QGIS 3.14
958 : : */
959 : : QString parameterAsConnectionName( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
960 : :
961 : : /**
962 : : * Evaluates the parameter with matching \a name to a database schema name string.
963 : : *
964 : : * \since QGIS 3.14
965 : : */
966 : : QString parameterAsSchema( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
967 : :
968 : : /**
969 : : * Evaluates the parameter with matching \a name to a database table name string.
970 : : *
971 : : * \since QGIS 3.14
972 : : */
973 : : QString parameterAsDatabaseTableName( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
974 : :
975 : : /**
976 : : * Evaluates the parameter with matching \a name to a DateTime, or returns an invalid date time if the parameter was not set.
977 : : *
978 : : * \since QGIS 3.14
979 : : */
980 : : QDateTime parameterAsDateTime( const QVariantMap ¶meters, const QString &name, QgsProcessingContext &context );
981 : :
982 : :
983 : : /**
984 : : * Returns a user-friendly string to use as an error when a source parameter could
985 : : * not be loaded.
986 : : *
987 : : * The \a parameters argument should give the algorithms parameter map, and the \a name
988 : : * should correspond to the invalid source parameter name.
989 : : *
990 : : *
991 : : * \see invalidRasterError()
992 : : * \see invalidSinkError()
993 : : * \since QGIS 3.2
994 : : */
995 : : static QString invalidSourceError( const QVariantMap ¶meters, const QString &name );
996 : :
997 : : /**
998 : : * Returns a user-friendly string to use as an error when a raster layer input could
999 : : * not be loaded.
1000 : : *
1001 : : * The \a parameters argument should give the algorithms parameter map, and the \a name
1002 : : * should correspond to the invalid source parameter name.
1003 : : *
1004 : : *
1005 : : * \see invalidSourceError()
1006 : : * \see invalidSinkError()
1007 : : * \since QGIS 3.2
1008 : : */
1009 : : static QString invalidRasterError( const QVariantMap ¶meters, const QString &name );
1010 : :
1011 : : /**
1012 : : * Returns a user-friendly string to use as an error when a sink parameter could
1013 : : * not be created.
1014 : : *
1015 : : * The \a parameters argument should give the algorithms parameter map, and the \a name
1016 : : * should correspond to the invalid source parameter name.
1017 : : *
1018 : : *
1019 : : * \see invalidSourceError()
1020 : : * \see invalidRasterError()
1021 : : * \since QGIS 3.2
1022 : : */
1023 : : static QString invalidSinkError( const QVariantMap ¶meters, const QString &name );
1024 : :
1025 : : /**
1026 : : * Checks whether this algorithm supports in-place editing on the given \a layer
1027 : : * Default implementation returns FALSE.
1028 : : *
1029 : : * \return TRUE if the algorithm supports in-place editing
1030 : : * \since QGIS 3.4
1031 : : */
1032 : : virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
1033 : :
1034 : : private:
1035 : :
1036 : 0 : QgsProcessingProvider *mProvider = nullptr;
1037 : : QgsProcessingParameterDefinitions mParameters;
1038 : : QgsProcessingOutputDefinitions mOutputs;
1039 : 0 : bool mHasPrepared = false;
1040 : 0 : bool mHasExecuted = false;
1041 : 0 : bool mHasPostProcessed = false;
1042 : : std::unique_ptr< QgsProcessingContext > mLocalContext;
1043 : :
1044 : : bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
1045 : :
1046 : :
1047 : : friend class QgsProcessingProvider;
1048 : : friend class TestQgsProcessing;
1049 : : friend class QgsProcessingModelAlgorithm;
1050 : : friend class QgsProcessingToolboxProxyModel;
1051 : :
1052 : : #ifdef SIP_RUN
1053 : : QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other );
1054 : : #endif
1055 : :
1056 : : };
1057 : 0 : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProcessingAlgorithm::Flags )
1058 : :
1059 : :
1060 : :
1061 : : /**
1062 : : * \class QgsProcessingFeatureBasedAlgorithm
1063 : : * \ingroup core
1064 : : * \brief An abstract QgsProcessingAlgorithm base class for processing algorithms which operate "feature-by-feature".
1065 : : *
1066 : : * Feature based algorithms are algorithms which operate on individual features in isolation. These
1067 : : * are algorithms where one feature is output for each input feature, and the output feature result
1068 : : * for each input feature is not dependent on any other features present in the source.
1069 : : *
1070 : : * For instance, algorithms like "centroids" and "buffers" are feature based algorithms since the centroid
1071 : : * or buffer of a feature is calculated for each feature in isolation. An algorithm like "dissolve"
1072 : : * is NOT suitable for a feature based algorithm as the dissolved output depends on multiple input features
1073 : : * and these features cannot be processed in isolation.
1074 : : *
1075 : : * Using QgsProcessingFeatureBasedAlgorithm as the base class for feature based algorithms allows
1076 : : * shortcutting much of the common algorithm code for handling iterating over sources and pushing
1077 : : * features to output sinks. It also allows the algorithm execution to be optimised in future
1078 : : * (for instance allowing automatic multi-thread processing of the algorithm, or use of the
1079 : : * algorithm in "chains", avoiding the need for temporary outputs in multi-step models).
1080 : : *
1081 : : * \since QGIS 3.0
1082 : : */
1083 : :
1084 : 0 : class CORE_EXPORT QgsProcessingFeatureBasedAlgorithm : public QgsProcessingAlgorithm
1085 : : {
1086 : : public:
1087 : :
1088 : : /**
1089 : : * Constructor for QgsProcessingFeatureBasedAlgorithm.
1090 : : */
1091 : 0 : QgsProcessingFeatureBasedAlgorithm() = default;
1092 : :
1093 : : QgsProcessingAlgorithm::Flags flags() const override;
1094 : :
1095 : : /**
1096 : : * Processes an individual input \a feature from the source. Algorithms should implement their
1097 : : * logic in this method for performing the algorithm's operation (e.g. replacing the feature's
1098 : : * geometry with the centroid of the original feature geometry for a 'centroid' type
1099 : : * algorithm).
1100 : : *
1101 : : * Implementations should return a list containing the modified feature. Returning an empty an list
1102 : : * will indicate that this feature should be 'skipped', and will not be added to the algorithm's output.
1103 : : * Subclasses can use this approach to filter the incoming features as desired.
1104 : : *
1105 : : * Additionally, multiple features can be returned for a single input feature. Each returned feature
1106 : : * will be added to the algorithm's output. This allows for "explode" type algorithms where a single
1107 : : * input feature results in multiple output features.
1108 : : *
1109 : : * The provided \a feedback object can be used to push messages to the log and for giving feedback
1110 : : * to users. Note that handling of progress reports and algorithm cancellation is handled by
1111 : : * the base class and subclasses do not need to reimplement this logic.
1112 : : *
1113 : : * Algorithms can throw a QgsProcessingException if a fatal error occurred which should
1114 : : * prevent the algorithm execution from continuing. This can be annoying for users though as it
1115 : : * can break valid model execution - so use with extreme caution, and consider using
1116 : : * \a feedback to instead report non-fatal processing failures for features instead.
1117 : : */
1118 : : virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
1119 : :
1120 : : protected:
1121 : :
1122 : : void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;
1123 : :
1124 : : /**
1125 : : * Returns the name of the parameter corresponding to the input layer.
1126 : : *
1127 : : * By default this is the standard "INPUT" parameter name.
1128 : : *
1129 : : * \since QGIS 3.12
1130 : : */
1131 : : virtual QString inputParameterName() const;
1132 : :
1133 : : /**
1134 : : * Returns the translated description of the parameter corresponding to the input layer.
1135 : : *
1136 : : * By default this is a translated "Input layer" string.
1137 : : *
1138 : : * \since QGIS 3.12
1139 : : */
1140 : : virtual QString inputParameterDescription() const;
1141 : :
1142 : : /**
1143 : : * Returns the translated, user visible name for any layers created by this algorithm.
1144 : : * This name will be used as the default name when loading the resultant layer into a
1145 : : * QGIS project.
1146 : : */
1147 : : virtual QString outputName() const = 0;
1148 : :
1149 : : /**
1150 : : * Returns the valid input layer types for the source layer for this algorithm.
1151 : : * By default vector layers with any geometry types (excluding non-spatial, geometryless layers)
1152 : : * are accepted.
1153 : : */
1154 : : virtual QList<int> inputLayerTypes() const;
1155 : :
1156 : : /**
1157 : : * Returns the layer type for layers generated by this algorithm, if
1158 : : * this is possible to determine in advance.
1159 : : */
1160 : : virtual QgsProcessing::SourceType outputLayerType() const;
1161 : :
1162 : : /**
1163 : : * Returns the processing feature source flags to be used in the algorithm.
1164 : : */
1165 : : virtual QgsProcessingFeatureSource::Flag sourceFlags() const;
1166 : :
1167 : : /**
1168 : : * Returns the feature sink flags to be used for the output.
1169 : : *
1170 : : * \since QGIS 3.4.1
1171 : : */
1172 : : virtual QgsFeatureSink::SinkFlags sinkFlags() const;
1173 : :
1174 : : /**
1175 : : * Maps the input WKB geometry type (\a inputWkbType) to the corresponding
1176 : : * output WKB type generated by the algorithm. The default behavior is that the algorithm maintains
1177 : : * the same WKB type.
1178 : : * This is called once by the base class when creating the output sink for the algorithm (i.e. it is
1179 : : * not called once per feature processed).
1180 : : */
1181 : : virtual QgsWkbTypes::Type outputWkbType( QgsWkbTypes::Type inputWkbType ) const;
1182 : :
1183 : : /**
1184 : : * Maps the input source fields (\a inputFields) to corresponding
1185 : : * output fields generated by the algorithm. The default behavior is that the algorithm maintains
1186 : : * the same fields as are input.
1187 : : * Algorithms which add, remove or modify existing fields should override this method and
1188 : : * implement logic here to indicate which fields are output by the algorithm.
1189 : : *
1190 : : * This is called once by the base class when creating the output sink for the algorithm (i.e. it is
1191 : : * not called once per feature processed).
1192 : : */
1193 : : virtual QgsFields outputFields( const QgsFields &inputFields ) const;
1194 : :
1195 : : /**
1196 : : * Maps the input source coordinate reference system (\a inputCrs) to a corresponding
1197 : : * output CRS generated by the algorithm. The default behavior is that the algorithm maintains
1198 : : * the same CRS as the input source.
1199 : : *
1200 : : * This is called once by the base class when creating the output sink for the algorithm (i.e. it is
1201 : : * not called once per feature processed).
1202 : : */
1203 : : virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const;
1204 : :
1205 : : /**
1206 : : * Initializes any extra parameters added by the algorithm subclass. There is no need
1207 : : * to declare the input source or output sink, as these are automatically created by
1208 : : * QgsProcessingFeatureBasedAlgorithm.
1209 : : */
1210 : : virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
1211 : :
1212 : : /**
1213 : : * Returns the source's coordinate reference system. This will only return a valid CRS when
1214 : : * called from a subclasses' processFeature() implementation.
1215 : : */
1216 : : QgsCoordinateReferenceSystem sourceCrs() const;
1217 : :
1218 : :
1219 : : QVariantMap processAlgorithm( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
1220 : :
1221 : : /**
1222 : : * Returns the feature request used for fetching features to process from the
1223 : : * source layer. The default implementation requests all attributes and geometry.
1224 : : */
1225 : : virtual QgsFeatureRequest request() const;
1226 : :
1227 : : /**
1228 : : * Checks whether this algorithm supports in-place editing on the given \a layer
1229 : : * Default implementation for feature based algorithms run some basic compatibility
1230 : : * checks based on the geometry type of the layer.
1231 : : *
1232 : : * \return TRUE if the algorithm supports in-place editing
1233 : : * \since QGIS 3.4
1234 : : */
1235 : : bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;
1236 : :
1237 : : /**
1238 : : * Read the source from \a parameters and \a context and set it
1239 : : *
1240 : : * \since QGIS 3.4
1241 : : */
1242 : : void prepareSource( const QVariantMap ¶meters, QgsProcessingContext &context );
1243 : :
1244 : : QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
1245 : : const QVariantMap ¶meters,
1246 : : QgsProcessingContext &context,
1247 : : const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const override;
1248 : :
1249 : : private:
1250 : :
1251 : : std::unique_ptr< QgsProcessingFeatureSource > mSource;
1252 : :
1253 : : };
1254 : :
1255 : : // clazy:excludeall=qstring-allocations
1256 : :
1257 : : #endif // QGSPROCESSINGALGORITHM_H
1258 : :
1259 : :
|
