QGIS API Documentation  3.23.0-Master (4fd2f04bd0)
qgsprocessingalgorithm.h
Go to the documentation of this file.
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"
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 
34 class QgsFeatureSink;
35 class QgsProcessingModelAlgorithm;
37 class QgsMeshLayer;
38 class QgsPointCloudLayer;
39 
40 #ifdef SIP_RUN
41 % ModuleHeaderCode
43 % End
44 #endif
45 
52 class CORE_EXPORT QgsProcessingAlgorithm
53 {
54 
55 #ifdef SIP_RUN
57  if ( dynamic_cast< QgsProcessingModelAlgorithm * >( sipCpp ) != NULL )
58  sipType = sipType_QgsProcessingModelAlgorithm;
59  else if ( dynamic_cast< QgsProcessingFeatureBasedAlgorithm * >( sipCpp ) != NULL )
60  sipType = sipType_QgsProcessingFeatureBasedAlgorithm;
61  else
62  sipType = sipType_QgsProcessingAlgorithm;
63  SIP_END
64 #endif
65 
66  public:
67 
69  enum Flag
70  {
71  FlagHideFromToolbox = 1 << 1,
72  FlagHideFromModeler = 1 << 2,
73  FlagSupportsBatch = 1 << 3,
74  FlagCanCancel = 1 << 4,
75  FlagRequiresMatchingCrs = 1 << 5,
76  FlagNoThreading = 1 << 6,
77  FlagDisplayNameIsLiteral = 1 << 7,
78  FlagSupportsInPlaceEdits = 1 << 8,
79  FlagKnownIssues = 1 << 9,
80  FlagCustomException = 1 << 10,
81  FlagPruneModelBranchesBasedOnAlgorithmResults = 1 << 11,
82  FlagSkipGenericModelLogging = 1 << 12,
83  FlagNotAvailableInStandaloneTool = 1 << 13,
84  FlagRequiresProject = 1 << 14,
85  FlagDeprecated = FlagHideFromToolbox | FlagHideFromModeler,
86  };
87  Q_DECLARE_FLAGS( Flags, Flag )
88 
89 
97 
98  virtual ~QgsProcessingAlgorithm();
99 
103  QgsProcessingAlgorithm &operator=( const QgsProcessingAlgorithm &other ) = delete;
104 
105  /*
106  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
107  * the case.
108  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
109  *
110  * "
111  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
112  * In this case it isn't because it has already been seen when being returned by createInstance()
113  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
114  * by Python so the /Factory/ on create() would be correct.)
115  *
116  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
117  * "
118  */
119 
137  QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
138 
148  virtual QString name() const = 0;
149 
156  QString id() const;
157 
168  virtual QString displayName() const = 0;
169 
175  virtual QString shortDescription() const;
176 
181  virtual QStringList tags() const { return QStringList(); }
182 
189  virtual QString shortHelpString() const;
190 
198  Q_DECL_DEPRECATED virtual QString helpString() const SIP_DEPRECATED;
199 
205  virtual QString helpUrl() const;
206 
211  virtual QIcon icon() const;
212 
217  virtual QString svgIconPath() const;
218 
225  virtual QString group() const { return QString(); }
226 
234  virtual QString groupId() const { return QString(); }
235 
240  virtual Flags flags() const;
241 
248  virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
249 
257  virtual bool checkParameterValues( const QVariantMap &parameters,
258  QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
259 
267  virtual QVariantMap preprocessParameters( const QVariantMap &parameters );
268 
272  QgsProcessingProvider *provider() const;
273 
281 
287  const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
288 
293  int countVisibleParameters() const;
294 
300  QgsProcessingParameterDefinitions destinationParameterDefinitions() const;
301 
308 
314  const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const;
315 
319  bool hasHtmlOutputs() const;
320 
326  {
329  };
330 
337  {
340 
343 
346 
349  };
350 
366  virtual QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
367  const QVariantMap &parameters,
368  QgsProcessingContext &context,
369  const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const;
370 
391  QVariantMap run( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap(),
392  bool catchExceptions = true ) const SIP_THROW( QgsProcessingException );
393 
404  bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
405 
417  QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );
418 
427  QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
428 
435  virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
436 
443  virtual QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
444  QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
445 
452  virtual bool validateInputCrs( const QVariantMap &parameters,
453  QgsProcessingContext &context ) const;
454 
462  virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;
463 
478  virtual QString asQgisProcessCommand( const QVariantMap &parameters, QgsProcessingContext &context, bool &ok SIP_OUT ) const;
479 
485  virtual QVariantMap asMap( const QVariantMap &parameters, QgsProcessingContext &context ) const;
486 
490  void setProvider( QgsProcessingProvider *provider );
491 
492  protected:
493 
499  virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );
500 
519  virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
520 
538  bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true );
539 
544  void removeParameter( const QString &name );
545 
559  bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER );
560 
591  virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
592 
622  virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
623 
651  virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
652 
656  QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
657 
661  QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
662 
666  double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
667 
671  int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
672 
677  QList<int> parameterAsInts( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
678 
682  int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
683 
687  QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
688 
693  QString parameterAsEnumString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
694 
699  QStringList parameterAsEnumStrings( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
700 
704  bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
705 
710  bool parameterAsBoolean( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
711 
732  QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
733  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;
734 
743  QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
744 
760  QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
761  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr );
762 
792  QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap &parameters, const QString &name,
793  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr );
794 
802  QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
803 
811  QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
812 
822  QgsMeshLayer *parameterAsMeshLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
823 
827  QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
828 
832  QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
833 
841  QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
842 
846  QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
847 
856  QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
858 
869  QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
871 
877  QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
878 
887  QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
889 
895  QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
896 
905  QgsGeometry parameterAsGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
907 
913  QgsCoordinateReferenceSystem parameterAsGeometryCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
914 
918  QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
919 
924  QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
925 
929  QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
930 
936  QStringList parameterAsFileList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
937 
941  QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
942 
946  QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
947 
956  QgsPrintLayout *parameterAsLayout( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
957 
966  QgsLayoutItem *parameterAsLayoutItem( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );
967 
973  QColor parameterAsColor( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
974 
980  QString parameterAsConnectionName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
981 
987  QString parameterAsSchema( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
988 
994  QString parameterAsDatabaseTableName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
995 
1001  QDateTime parameterAsDateTime( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
1002 
1012  QgsPointCloudLayer *parameterAsPointCloudLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
1013 
1027  QgsAnnotationLayer *parameterAsAnnotationLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
1028 
1041  static QString invalidSourceError( const QVariantMap &parameters, const QString &name );
1042 
1055  static QString invalidRasterError( const QVariantMap &parameters, const QString &name );
1056 
1069  static QString invalidSinkError( const QVariantMap &parameters, const QString &name );
1070 
1082  static QString writeFeatureError( QgsFeatureSink *sink, const QVariantMap &parameters, const QString &name );
1083 
1091  virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
1092 
1093  private:
1094 
1095  QgsProcessingProvider *mProvider = nullptr;
1098  bool mHasPrepared = false;
1099  bool mHasExecuted = false;
1100  bool mHasPostProcessed = false;
1101  std::unique_ptr< QgsProcessingContext > mLocalContext;
1102 
1103  bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
1104 
1105 
1107  friend class TestQgsProcessing;
1108  friend class QgsProcessingModelAlgorithm;
1110 
1111 #ifdef SIP_RUN
1113 #endif
1114 
1115 };
1116 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProcessingAlgorithm::Flags )
1117 
1118 
1119 
1120 
1144 {
1145  public:
1146 
1151 
1152  QgsProcessingAlgorithm::Flags flags() const override;
1153 
1177  virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
1178 
1179  protected:
1180 
1181  void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;
1182 
1190  virtual QString inputParameterName() const;
1191 
1199  virtual QString inputParameterDescription() const;
1200 
1206  virtual QString outputName() const = 0;
1207 
1213  virtual QList<int> inputLayerTypes() const;
1214 
1219  virtual QgsProcessing::SourceType outputLayerType() const;
1220 
1224  virtual QgsProcessingFeatureSource::Flag sourceFlags() const;
1225 
1231  virtual QgsFeatureSink::SinkFlags sinkFlags() const;
1232 
1240  virtual QgsWkbTypes::Type outputWkbType( QgsWkbTypes::Type inputWkbType ) const;
1241 
1252  virtual QgsFields outputFields( const QgsFields &inputFields ) const;
1253 
1262  virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const;
1263 
1269  virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
1270 
1275  QgsCoordinateReferenceSystem sourceCrs() const;
1276 
1277 
1278  QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
1279 
1284  virtual QgsFeatureRequest request() const;
1285 
1294  bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;
1295 
1301  void prepareSource( const QVariantMap &parameters, QgsProcessingContext &context );
1302 
1303  QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
1304  const QVariantMap &parameters,
1305  QgsProcessingContext &context,
1306  const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const override;
1307 
1308  private:
1309 
1310  std::unique_ptr< QgsProcessingFeatureSource > mSource;
1311 
1312 };
1313 
1314 // clazy:excludeall=qstring-allocations
1315 
1316 #endif // QGSPROCESSINGALGORITHM_H
1317 
1318 
Represents a map layer containing a set of georeferenced annotations, e.g.
This class represents a coordinate reference system (CRS).
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
This class wraps a request for features to a vector layer (or directly its vector data provider).
An interface for objects which accept features via addFeature(s) methods.
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:125
Base class for graphical items within a QgsLayout.
Base class for all map layer types.
Definition: qgsmaplayer.h:73
Represents a mesh layer supporting display of data on structured or unstructured meshes.
Definition: qgsmeshlayer.h:97
Represents a map layer supporting display of point clouds.
A class to represent a 2D point.
Definition: qgspointxy.h:59
Print layout, a QgsLayout subclass for static or atlas-based layouts.
A configuration widget for processing algorithms allows providing additional configuration options di...
Abstract base class for processing algorithms.
QgsProcessingOutputDefinitions outputDefinitions() const
Returns an ordered list of output definitions utilized by the algorithm.
PropertyAvailability
Property availability, used for QgsProcessingAlgorithm::VectorProperties in order to determine if pro...
@ NotAvailable
Properties are not available.
@ Available
Properties are available.
virtual QString groupId() const
Returns the unique ID of the group this algorithm belongs to.
QgsProcessingParameterDefinitions parameterDefinitions() const
Returns an ordered list of parameter definitions utilized by the algorithm.
Flag
Flags indicating how and when an algorithm operates and should be exposed to users.
Contains information about the context in which a processing algorithm is executed.
Custom exception class for processing related exceptions.
Definition: qgsexception.h:83
An abstract QgsProcessingAlgorithm base class for processing algorithms which operate "feature-by-fea...
QgsProcessingFeatureBasedAlgorithm()=default
Constructor for QgsProcessingFeatureBasedAlgorithm.
virtual QString outputName() const =0
Returns the translated, user visible name for any layers created by this algorithm.
virtual QgsFeatureList processFeature(const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback) SIP_THROW(QgsProcessingException)=0
Processes an individual input feature from the source.
QgsFeatureSource subclass which proxies methods to an underlying QgsFeatureSource,...
Flag
Flags controlling how QgsProcessingFeatureSource fetches features.
Base class for providing feedback from a processing algorithm.
Base class for the definition of processing outputs.
Base class for the definition of processing parameters.
Abstract base class for processing providers.
A sort/filter proxy model for providers and algorithms shown within the Processing toolbox,...
SourceType
Data source types enum.
Definition: qgsprocessing.h:46
Represents a raster layer.
A rectangle specified with double values.
Definition: qgsrectangle.h:42
Represents a vector layer which manages a vector based data sets.
Handles storage of information regarding WKB types and their properties.
Definition: qgswkbtypes.h:42
Type
The WKB type describes the number of dimensions a geometry has.
Definition: qgswkbtypes.h:70
std::unique_ptr< GEOSGeometry, GeosDeleter > unique_ptr
Scoped GEOS pointer.
Definition: qgsgeos.h:79
#define SIP_THROW(name)
Definition: qgis_sip.h:189
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:177
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_OUT
Definition: qgis_sip.h:58
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
#define SIP_FACTORY
Definition: qgis_sip.h:76
#define SIP_VIRTUALERRORHANDLER(name)
Definition: qgis_sip.h:182
#define SIP_END
Definition: qgis_sip.h:194
QList< QgsFeature > QgsFeatureList
Definition: qgsfeature.h:882
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
QList< const QgsProcessingOutputDefinition * > QgsProcessingOutputDefinitions
List of processing parameters.
QList< const QgsProcessingParameterDefinition * > QgsProcessingParameterDefinitions
List of processing parameters.
const QgsCoordinateReferenceSystem & outputCrs
const QgsCoordinateReferenceSystem & crs
Properties of a vector source or sink used in an algorithm.
QgsCoordinateReferenceSystem crs
Coordinate Reference System.