Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgsprocessingmodelalgorithm.h
3 : : -----------------------------
4 : : begin : June 2017
5 : : copyright : (C) 2017 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 QGSPROCESSINGMODELALGORITHM_H
19 : : #define QGSPROCESSINGMODELALGORITHM_H
20 : :
21 : : #include "qgis_core.h"
22 : : #include "qgis.h"
23 : : #include "qgsprocessingmodelchildalgorithm.h"
24 : : #include "qgsprocessingalgorithm.h"
25 : : #include "qgsprocessingmodelparameter.h"
26 : : #include "qgsprocessingmodelchildparametersource.h"
27 : : #include "qgsprocessingmodelgroupbox.h"
28 : : #include "qgsprocessingmodelchilddependency.h"
29 : :
30 : : ///@cond NOT_STABLE
31 : :
32 : : /**
33 : : * \class QgsProcessingModelAlgorithm
34 : : * \ingroup core
35 : : * \brief Model based algorithm with processing.
36 : : * \since QGIS 3.0
37 : : */
38 : 0 : class CORE_EXPORT QgsProcessingModelAlgorithm : public QgsProcessingAlgorithm
39 : : {
40 : : public:
41 : :
42 : : /**
43 : : * Constructor for QgsProcessingModelAlgorithm.
44 : : */
45 : : QgsProcessingModelAlgorithm( const QString &name = QString(), const QString &group = QString(), const QString &groupId = QString() );
46 : :
47 : : void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override; //#spellok
48 : :
49 : : QString name() const override;
50 : : QString displayName() const override;
51 : : QString group() const override;
52 : : QString groupId() const override;
53 : : QIcon icon() const override;
54 : : QString svgIconPath() const override;
55 : : QString shortHelpString() const override;
56 : : QString shortDescription() const override;
57 : : QString helpUrl() const override;
58 : : Flags flags() const override;
59 : :
60 : : bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const override;
61 : : QString asPythonCommand( const QVariantMap ¶meters, QgsProcessingContext &context ) const override;
62 : : QgsExpressionContext createExpressionContext( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const override;
63 : :
64 : : /**
65 : : * Sets the model \a name.
66 : : * \see name()
67 : : */
68 : : void setName( const QString &name );
69 : :
70 : : /**
71 : : * Sets the model \a group.
72 : : * \see group()
73 : : */
74 : : void setGroup( const QString &group );
75 : :
76 : : /**
77 : : * Validates the model, returning TRUE if all child algorithms in the model are valid.
78 : : *
79 : : * \param issues will be set to a list of issues encountered during the validation
80 : : * \returns TRUE if the child is valid
81 : : * \since QGIS 3.14
82 : : */
83 : : bool validate( QStringList &issues SIP_OUT ) const;
84 : :
85 : : /**
86 : : * Returns the map of child algorithms contained in the model. The keys
87 : : * are the child algorithm ids (see QgsProcessingModelAlgorithm::ChildAlgorithm::childId()).
88 : : * \see childAlgorithm()
89 : : * \see setChildAlgorithms()
90 : : * \see addChildAlgorithm()
91 : : */
92 : : QMap<QString, QgsProcessingModelChildAlgorithm> childAlgorithms() const;
93 : :
94 : : /**
95 : : * Sets the map of child algorithms contained in the model. The keys
96 : : * are the child algorithm ids (see QgsProcessingModelAlgorithm::ChildAlgorithm::childId()).
97 : : * All existing child algorithms will be replaced.
98 : : * \see childAlgorithms()
99 : : * \see childAlgorithm()
100 : : * \see setChildAlgorithm()
101 : : * \see addChildAlgorithm()
102 : : */
103 : : void setChildAlgorithms( const QMap<QString, QgsProcessingModelChildAlgorithm> &childAlgorithms );
104 : :
105 : : /**
106 : : * Sets the child \a algorithm within the model. If a child algorithm already
107 : : * exists in the model with the same child ID then that algorithm will be replaced.
108 : : * \see addChildAlgorithm()
109 : : * \see setChildAlgorithms()
110 : : */
111 : : void setChildAlgorithm( const QgsProcessingModelChildAlgorithm &algorithm );
112 : :
113 : : /**
114 : : * Adds a new child \a algorithm to the model. If a child algorithm already exists
115 : : * in the model with the same child ID then \a algorithm will be assigned a new
116 : : * autogenerated unique ID.
117 : : * The assigned child ID will be returned.
118 : : * \see childAlgorithms()
119 : : * \see childAlgorithm()
120 : : * \see setChildAlgorithm()
121 : : * \see setChildAlgorithms()
122 : : */
123 : : QString addChildAlgorithm( QgsProcessingModelChildAlgorithm &algorithm );
124 : :
125 : : /**
126 : : * Returns the child algorithm with matching \a id. If no child algorithm exists with
127 : : * this ID a new algorithm will be added to the model and returned.
128 : : * \see addChildAlgorithm()
129 : : * \see childAlgorithms()
130 : : */
131 : : QgsProcessingModelChildAlgorithm &childAlgorithm( const QString &id );
132 : :
133 : : /**
134 : : * Attempts to remove the child algorithm with matching \a id.
135 : : * Returns TRUE if the algorithm could be removed, or FALSE
136 : : * if the algorithm could not be removed (e.g. due to other
137 : : * child algorithms depending on it).
138 : : * \see deactivateChildAlgorithm()
139 : : */
140 : : bool removeChildAlgorithm( const QString &id );
141 : :
142 : : /**
143 : : * Deactivates the child algorithm with matching \a id.
144 : : * All other child algorithms which depend on the child
145 : : * algorithm will also be deactivated.
146 : : * \see removeChildAlgorithm()
147 : : * \see activateChildAlgorithm()
148 : : */
149 : : void deactivateChildAlgorithm( const QString &id );
150 : :
151 : : /**
152 : : * Attempts to activate the child algorithm with matching \a id.
153 : : * If any child algorithms on which the child depends are not active,
154 : : * then the child will not be activated and FALSE will be returned.
155 : : * \see deactivateChildAlgorithm()
156 : : */
157 : : bool activateChildAlgorithm( const QString &id );
158 : :
159 : : /**
160 : : * Returns a list of the child algorithm IDs depending on the child
161 : : * algorithm with the specified \a childId.
162 : : *
163 : : * Optionally, a specific conditional branch which is created by the child algorithm
164 : : * can be specified in order to restrict the returned list to algorithms which depend
165 : : * on this specific branch.
166 : : *
167 : : * \see dependsOnChildAlgorithms()
168 : : */
169 : : QSet< QString > dependentChildAlgorithms( const QString &childId, const QString &conditionalBranch = QString() ) const;
170 : :
171 : : /**
172 : : * Returns a list of the child algorithm IDs on which the child
173 : : * algorithm with the specified \a childId depends upon.
174 : : * \see dependentChildAlgorithms()
175 : : */
176 : : QSet< QString > dependsOnChildAlgorithms( const QString &childId ) const;
177 : :
178 : : /**
179 : : * Returns details of available dependencies for the child algorithm with matching id.
180 : : *
181 : : * \since QGIS 3.14
182 : : */
183 : : QList< QgsProcessingModelChildDependency > availableDependenciesForChildAlgorithm( const QString &childId ) const;
184 : :
185 : : /**
186 : : * Validates the child algorithm with matching ID, returning TRUE if
187 : : * all mandatory inputs to the algorithm have valid values.
188 : : *
189 : : * \param childId ID for child to validate
190 : : * \param issues will be set to a list of issues encountered during the validation
191 : : * \returns TRUE if the child is valid
192 : : * \since QGIS 3.14
193 : : */
194 : : bool validateChildAlgorithm( const QString &childId, QStringList &issues SIP_OUT ) const;
195 : :
196 : : /**
197 : : * Adds a new parameter to the model, with the specified \a definition and graphical \a component.
198 : : * Ownership of \a definition is transferred to the model.
199 : : * \see updateModelParameter()
200 : : * \see removeModelParameter()
201 : : */
202 : : void addModelParameter( QgsProcessingParameterDefinition *definition SIP_TRANSFER, const QgsProcessingModelParameter &component );
203 : :
204 : : /**
205 : : * Replaces the definition of an existing parameter (by parameter name) with a new \a definition. Ownership of
206 : : * \a definition is transferred to the model, and any existing parameter is deleted.
207 : : * \see addModelParameter()
208 : : * \see removeModelParameter()
209 : : */
210 : : void updateModelParameter( QgsProcessingParameterDefinition *definition SIP_TRANSFER );
211 : :
212 : : /**
213 : : * Removes an existing model parameter by \a name. The definition of the matching parameter
214 : : * is deleted.
215 : : * \see addModelParameter()
216 : : * \see updateModelParameter()
217 : : */
218 : : void removeModelParameter( const QString &name );
219 : :
220 : : /**
221 : : * Returns TRUE if any child algorithms depend on the model parameter
222 : : * with the specified \a name.
223 : : * \see otherParametersDependOnParameter()
224 : : */
225 : : bool childAlgorithmsDependOnParameter( const QString &name ) const;
226 : :
227 : : /**
228 : : * Returns TRUE if any other model parameters depend on the parameter
229 : : * with the specified \a name (e.g. field parameters where \a name
230 : : * is the parent layer parameter).
231 : : * \see childAlgorithmsDependOnParameter()
232 : : */
233 : : bool otherParametersDependOnParameter( const QString &name ) const;
234 : :
235 : : /**
236 : : * Returns the map of parameter components used by the model. The keys
237 : : * should match the algorithm's parameter names (see parameterDefinitions() ).
238 : : * \see setParameterComponent()
239 : : * \see parameterComponent()
240 : : */
241 : : QMap<QString, QgsProcessingModelParameter> parameterComponents() const;
242 : :
243 : : /**
244 : : * Sets the map of parameter components used by the model. The keys
245 : : * should match the algorithm's parameter names (see parameterDefinitions() ).
246 : : * All existing parameter components will be replaced.
247 : : * \see parameterComponents()
248 : : * \see setParameterComponent()
249 : : * \see parameterComponent()
250 : : */
251 : : void setParameterComponents( const QMap<QString, QgsProcessingModelParameter> ¶meterComponents );
252 : :
253 : : /**
254 : : * Sets a parameter \a component for the model. If a parameter component already
255 : : * exists in the model with the same parameter name then that component will be replaced.
256 : : * \see parameterComponents()
257 : : * \see setParameterComponents()
258 : : * \see parameterComponent()
259 : : */
260 : : void setParameterComponent( const QgsProcessingModelParameter &component );
261 : :
262 : : /**
263 : : * Returns the parameter component with matching \a name. If no parameter component exists with
264 : : * this name a new component will be added to the model and returned.
265 : : * \see parameterComponents()
266 : : * \see setParameterComponents()
267 : : * \see setParameterComponent()
268 : : */
269 : : QgsProcessingModelParameter ¶meterComponent( const QString &name );
270 : :
271 : : /**
272 : : * Returns an ordered list of parameters for the model.
273 : : *
274 : : * \see setParameterOrder()
275 : : * \since QGIS 3.14
276 : : */
277 : : QList< QgsProcessingModelParameter > orderedParameters() const;
278 : :
279 : : /**
280 : : * Sets the \a order for showing parameters for the model.
281 : : *
282 : : * The \a order list should consist of parameter names corresponding to existing
283 : : * model parameterComponents().
284 : : *
285 : : * \see orderedParameters()
286 : : * \since QGIS 3.14
287 : : */
288 : : void setParameterOrder( const QStringList &order );
289 : :
290 : : /**
291 : : * Updates the model's parameter definitions to include all relevant destination
292 : : * parameters as required by child algorithm ModelOutputs.
293 : : * Must be called whenever child algorithm ModelOutputs are altered.
294 : : */
295 : : void updateDestinationParameters();
296 : :
297 : : /**
298 : : * Adds a new group \a box to the model.
299 : : *
300 : : * If an existing group box with the same uuid already exists then its definition will be replaced.
301 : : *
302 : : * \see groupBoxes()
303 : : * \since QGIS 3.14
304 : : */
305 : : void addGroupBox( const QgsProcessingModelGroupBox &groupBox );
306 : :
307 : : /**
308 : : * Returns a list of the group boxes within the model.
309 : : *
310 : : * \see addGroupBox()
311 : : * \since QGIS 3.14
312 : : */
313 : : QList< QgsProcessingModelGroupBox > groupBoxes() const;
314 : :
315 : : /**
316 : : * Removes the group box with matching \a uuid from the model.
317 : : *
318 : : * \see addGroupBox()
319 : : * \see groupBoxes()
320 : : * \since QGIS 3.14
321 : : */
322 : : void removeGroupBox( const QString &uuid );
323 : :
324 : : /**
325 : : * Writes the model to a file, at the specified \a path.
326 : : * \see fromFile()
327 : : */
328 : : bool toFile( const QString &path ) const;
329 : :
330 : : /**
331 : : * Reads the model from a file, at the specified \a path.
332 : : * \see toFile()
333 : : */
334 : : bool fromFile( const QString &path );
335 : :
336 : : /**
337 : : * Saves this model to a QVariantMap, wrapped in a QVariant.
338 : : * You can use QgsXmlUtils::writeVariant to save it to an XML document.
339 : : *
340 : : * \see loadVariant()
341 : : * \since QGIS 3.4
342 : : */
343 : : QVariant toVariant() const;
344 : :
345 : : /**
346 : : * Loads this model from a QVariantMap, wrapped in a QVariant \a variant.
347 : : * You can use QgsXmlUtils::readVariant to load it from an XML document.
348 : : *
349 : : * \see toVariant()
350 : : * \since QGIS 3.4
351 : : */
352 : : bool loadVariant( const QVariant &variant );
353 : :
354 : : /**
355 : : * Returns the model's help contents (a free-form map of values describing the algorithm's
356 : : * use and metadata).
357 : : * \see setHelpContent()
358 : : */
359 : : QVariantMap &helpContent() { return mHelpContent; }
360 : :
361 : : /**
362 : : * Returns the model's help contents (a free-form map of values describing the algorithm's
363 : : * use and metadata).
364 : : * \see setHelpContent()
365 : : */
366 : : SIP_SKIP QVariantMap helpContent() const;
367 : :
368 : : /**
369 : : * Sets the model's help \a contents (a free-form map of values describing the algorithm's
370 : : * use and metadata).
371 : : * \see helpContent()
372 : : */
373 : : void setHelpContent( const QVariantMap &contents );
374 : :
375 : : /**
376 : : * Returns the source file path for the model, if available.
377 : : * \see setSourceFilePath()
378 : : */
379 : : QString sourceFilePath() const;
380 : :
381 : : /**
382 : : * Sets the source file \a path for the model, if available.
383 : : * \see sourceFilePath()
384 : : */
385 : : void setSourceFilePath( const QString &path );
386 : :
387 : : /**
388 : : * Attempts to convert the model to executable Python code, and returns the generated lines of code.
389 : : *
390 : : * The \a outputType argument dictates the desired script type.
391 : : *
392 : : * The \a indentSize arguments specifies the size of indented lines.
393 : : */
394 : : QStringList asPythonCode( QgsProcessing::PythonOutputType outputType, int indentSize ) const;
395 : :
396 : : /**
397 : : * Returns a list of possible sources which can be used for the parameters for a child
398 : : * algorithm in the model. Returned sources are those which match either one of the
399 : : * specified \a parameterTypes (see QgsProcessingParameterDefinition::type() ) or
400 : : * one of the specified \a outputTypes (see QgsProcessingOutputDefinition::type() ).
401 : : * If specified, an optional list of \a dataTypes can be used to filter the returned
402 : : * sources to those with compatible data types for the parameter/outputs.
403 : : */
404 : : QList< QgsProcessingModelChildParameterSource > availableSourcesForChild( const QString &childId, const QStringList ¶meterTypes = QStringList(),
405 : : const QStringList &outputTypes = QStringList(), const QList< int > &dataTypes = QList< int >() ) const;
406 : :
407 : : /**
408 : : * \brief Definition of a expression context variable available during model execution.
409 : : * \ingroup core
410 : : * \since QGIS 3.0
411 : : */
412 : 0 : class CORE_EXPORT VariableDefinition
413 : : {
414 : : public:
415 : :
416 : : /**
417 : : * Constructor for a new VariableDefinition with the specified \a value and original
418 : : * parameter \a source, and \a description.
419 : : */
420 : 0 : VariableDefinition( const QVariant &value = QVariant(), const QgsProcessingModelChildParameterSource &source = QgsProcessingModelChildParameterSource::fromStaticValue( QVariant() ), const QString &description = QString() )
421 : 0 : : value( value )
422 : 0 : , source( source )
423 : 0 : , description( description )
424 : 0 : {}
425 : :
426 : : //! Value of variable
427 : : QVariant value;
428 : :
429 : : //! Original source of variable's value
430 : : QgsProcessingModelChildParameterSource source;
431 : :
432 : : //! Translated description of variable
433 : : QString description;
434 : : };
435 : :
436 : : /**
437 : : * Returns a map of variable name to variable definition for expression context variables which are available
438 : : * for use by child algorithm during model execution.
439 : : *
440 : : * The child algorithm \a childId and processing \a context
441 : : * are manadatory. If \a modelParameters and \a results are not specified, then only the variable names and sources
442 : : * will be returned, but all variable values will be null. This can be used to determine in advance which variables
443 : : * will be available for a specific child algorithm, e.g. for use in expression builder widgets.
444 : : *
445 : : * In order to calculate the actual variable value, the input model \a modelParameters and already executed child
446 : : * algorithm \a results must be passed.
447 : : * \see createExpressionContextScopeForChildAlgorithm()
448 : : */
449 : : QMap< QString, QgsProcessingModelAlgorithm::VariableDefinition > variablesForChildAlgorithm( const QString &childId, QgsProcessingContext &context, const QVariantMap &modelParameters = QVariantMap(),
450 : : const QVariantMap &results = QVariantMap() ) const;
451 : :
452 : : /**
453 : : * Creates a new expression context scope for a child algorithm within the model.
454 : : * \see variablesForChildAlgorithm()
455 : : */
456 : : QgsExpressionContextScope *createExpressionContextScopeForChildAlgorithm( const QString &childId, QgsProcessingContext &context, const QVariantMap &modelParameters = QVariantMap(),
457 : : const QVariantMap &results = QVariantMap() ) const SIP_FACTORY;
458 : :
459 : : /**
460 : : * Returns the map of custom expression context variables defined for this model.
461 : : *
462 : : * These variables are added to the model's expression context scope, allowing for preset
463 : : * "constant" expression variables to be utilized within the model.
464 : : *
465 : : * \see setVariables()
466 : : * \since QGIS 3.8
467 : : */
468 : : QVariantMap variables() const;
469 : :
470 : : /**
471 : : * Sets the map of custom expression context \a variables for this model.
472 : : *
473 : : * These variables are added to the model's expression context scope, allowing for preset
474 : : * "constant" expression variables to be utilized within the model.
475 : : *
476 : : * \see variables()
477 : : * \since QGIS 3.8
478 : : */
479 : : void setVariables( const QVariantMap &variables );
480 : :
481 : : /**
482 : : * Returns the parameter values to use as default values when running this model through the
483 : : * designer dialog.
484 : : *
485 : : * This usually corresponds to the last set of parameter values used when the model was
486 : : * run through the designer.
487 : : *
488 : : * \see setDesignerParameterValues()
489 : : *
490 : : * \since QGIS 3.14
491 : : */
492 : : QVariantMap designerParameterValues() const;
493 : :
494 : : /**
495 : : * Sets the parameter \a values to use as default values when running this model through the
496 : : * designer dialog.
497 : : *
498 : : * This usually corresponds to the last set of parameter values used when the model was
499 : : * run through the designer.
500 : : *
501 : : * \see designerParameterValues()
502 : : *
503 : : * \since QGIS 3.14
504 : : */
505 : : void setDesignerParameterValues( const QVariantMap &values ) { mDesignerParameterValues = values; }
506 : :
507 : : protected:
508 : :
509 : : QgsProcessingAlgorithm *createInstance() const override SIP_FACTORY;
510 : :
511 : : QVariantMap processAlgorithm( const QVariantMap ¶meters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
512 : :
513 : : private:
514 : :
515 : : QString mModelName;
516 : : QString mModelGroup;
517 : : QString mModelGroupId;
518 : :
519 : : QMap< QString, QgsProcessingModelChildAlgorithm > mChildAlgorithms;
520 : :
521 : : //! Map of parameter name to model parameter component
522 : : QMap< QString, QgsProcessingModelParameter > mParameterComponents;
523 : :
524 : : QVariantMap mHelpContent;
525 : :
526 : : //! Model source file
527 : : QString mSourceFile;
528 : :
529 : : QVariantMap mResults;
530 : :
531 : : QVariantMap mVariables;
532 : :
533 : : QVariantMap mDesignerParameterValues;
534 : :
535 : : QMap< QString, QgsProcessingModelGroupBox > mGroupBoxes;
536 : :
537 : : QStringList mParameterOrder;
538 : :
539 : : void dependsOnChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends ) const;
540 : : void dependentChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends, const QString &branch ) const;
541 : :
542 : : QVariantMap parametersForChildAlgorithm( const QgsProcessingModelChildAlgorithm &child, const QVariantMap &modelParameters, const QVariantMap &results, const QgsExpressionContext &expressionContext ) const;
543 : :
544 : : /**
545 : : * Returns TRUE if an output from a child algorithm is required elsewhere in
546 : : * the model.
547 : : */
548 : : bool childOutputIsRequired( const QString &childId, const QString &outputName ) const;
549 : :
550 : : /**
551 : : * Checks whether the output vector type given by \a outputType is compatible
552 : : * with the list of acceptable data types specified by \a acceptableDataTypes.
553 : : * Returns TRUE if vector output is compatible.
554 : : *
555 : : * \note This method is intended to be "permissive" rather than "restrictive".
556 : : * I.e. we only reject outputs which we know can NEVER be acceptable, but
557 : : * if there's doubt then we default to returning TRUE.
558 : : */
559 : : static bool vectorOutputIsCompatibleType( const QList<int> &acceptableDataTypes, QgsProcessing::SourceType outputType );
560 : :
561 : : /**
562 : : * Tries to reattach all child algorithms to their linked algorithms.
563 : : */
564 : : void reattachAlgorithms() const;
565 : :
566 : : friend class TestQgsProcessing;
567 : : };
568 : :
569 : : ///@endcond
570 : :
571 : : #endif // QGSPROCESSINGMODELALGORITHM_H
|
