QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 "qgsprocessingutils.h"
27 #include <QString>
28 #include <QVariant>
29 #include <QIcon>
30 
33 class QgsFeatureSink;
34 class QgsProcessingModelAlgorithm;
36 class QgsMeshLayer;
37 class QgsPointCloudLayer;
38 
39 #ifdef SIP_RUN
40 % ModuleHeaderCode
42 % End
43 #endif
44 
50 class CORE_EXPORT QgsProcessingAlgorithm
51 {
52 
53 #ifdef SIP_RUN
55  if ( dynamic_cast< QgsProcessingModelAlgorithm * >( sipCpp ) != NULL )
56  sipType = sipType_QgsProcessingModelAlgorithm;
57  else if ( dynamic_cast< QgsProcessingFeatureBasedAlgorithm * >( sipCpp ) != NULL )
58  sipType = sipType_QgsProcessingFeatureBasedAlgorithm;
59  else
60  sipType = sipType_QgsProcessingAlgorithm;
61  SIP_END
62 #endif
63 
64  public:
65 
74 
75  virtual ~QgsProcessingAlgorithm();
76 
81 
82  /*
83  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
84  * the case.
85  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
86  *
87  * "
88  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
89  * In this case it isn't because it has already been seen when being returned by createInstance()
90  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
91  * by Python so the /Factory/ on create() would be correct.)
92  *
93  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
94  * "
95  */
96 
114  QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
115 
125  virtual QString name() const = 0 SIP_HOLDGIL;
126 
133  QString id() const SIP_HOLDGIL;
134 
145  virtual QString displayName() const = 0 SIP_HOLDGIL;
146 
152  virtual QString shortDescription() const SIP_HOLDGIL;
153 
158  virtual QStringList tags() const SIP_HOLDGIL { return QStringList(); }
159 
166  virtual QString shortHelpString() const SIP_HOLDGIL;
167 
175  Q_DECL_DEPRECATED virtual QString helpString() const SIP_HOLDGIL SIP_DEPRECATED;
176 
182  virtual QString helpUrl() const SIP_HOLDGIL;
183 
188  virtual QIcon icon() const SIP_HOLDGIL;
189 
194  virtual QString svgIconPath() const SIP_HOLDGIL;
195 
202  virtual QString group() const SIP_HOLDGIL { return QString(); }
203 
211  virtual QString groupId() const SIP_HOLDGIL { return QString(); }
212 
217  virtual Qgis::ProcessingAlgorithmFlags flags() const SIP_HOLDGIL;
218 
225  virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
226 
234  virtual bool checkParameterValues( const QVariantMap &parameters,
235  QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
236 
244  virtual QVariantMap preprocessParameters( const QVariantMap &parameters );
245 
249  QgsProcessingProvider *provider() const SIP_HOLDGIL;
250 
257  QgsProcessingParameterDefinitions parameterDefinitions() const SIP_HOLDGIL { return mParameters; }
258 
264  const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const SIP_HOLDGIL;
265 
270  int countVisibleParameters() const SIP_HOLDGIL;
271 
277  QgsProcessingParameterDefinitions destinationParameterDefinitions() const SIP_HOLDGIL;
278 
284  QgsProcessingOutputDefinitions outputDefinitions() const SIP_HOLDGIL { return mOutputs; }
285 
291  const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const SIP_HOLDGIL;
292 
296  bool hasHtmlOutputs() const SIP_HOLDGIL;
297 
298 
305  {
308 
311 
314 
317  };
318 
334  virtual QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
335  const QVariantMap &parameters,
336  QgsProcessingContext &context,
337  const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const;
338 
359  QVariantMap run( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap(),
360  bool catchExceptions = true ) const SIP_THROW( QgsProcessingException );
361 
372  bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
373 
385  QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );
386 
395  QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
396 
403  virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
404 
411  virtual QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
412  QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
413 
420  virtual bool validateInputCrs( const QVariantMap &parameters,
421  QgsProcessingContext &context ) const;
422 
430  virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;
431 
446  virtual QString asQgisProcessCommand( const QVariantMap &parameters, QgsProcessingContext &context, bool &ok SIP_OUT ) const;
447 
453  virtual QVariantMap asMap( const QVariantMap &parameters, QgsProcessingContext &context ) const;
454 
458  void setProvider( QgsProcessingProvider *provider ) SIP_HOLDGIL;
459 
460  protected:
461 
467  virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );
468 
487  virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
488 
506  bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true ) SIP_HOLDGIL;
507 
512  void removeParameter( const QString &name ) SIP_HOLDGIL;
513 
527  bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER ) SIP_HOLDGIL;
528 
559  virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
560 
590  virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
591 
619  virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
620 
624  QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
625 
629  QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
630 
634  double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
635 
639  int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
640 
645  QList<int> parameterAsInts( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
646 
650  int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
651 
655  QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
656 
661  QString parameterAsEnumString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
662 
667  QStringList parameterAsEnumStrings( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
668 
672  bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
673 
678  bool parameterAsBoolean( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
679 
700  QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
701  const QgsFields &fields, Qgis::WkbType geometryType = Qgis::WkbType::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;
702 
711  QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
712 
728  QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
729  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr ) const;
730 
760  QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap &parameters, const QString &name,
761  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr ) const;
762 
770  QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
771 
779  QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
780 
790  QgsMeshLayer *parameterAsMeshLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
791 
795  QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
796 
800  QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
801 
809  QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
810 
814  QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
815 
824  QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
826 
837  QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
839 
845  QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
846 
855  QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
857 
863  QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
864 
873  QgsGeometry parameterAsGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
875 
881  QgsCoordinateReferenceSystem parameterAsGeometryCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
882 
886  QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
887 
892  QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
893 
898  QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsProcessing::LayerOptionsFlags flags = QgsProcessing::LayerOptionsFlags() ) const;
899 
905  QStringList parameterAsFileList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
906 
910  QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
911 
917  Q_DECL_DEPRECATED QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_DEPRECATED;
918 
924  QStringList parameterAsStrings( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
925 
934  QgsPrintLayout *parameterAsLayout( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
935 
944  QgsLayoutItem *parameterAsLayoutItem( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );
945 
951  QColor parameterAsColor( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
952 
958  QString parameterAsConnectionName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
959 
965  QString parameterAsSchema( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
966 
972  QString parameterAsDatabaseTableName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
973 
979  QDateTime parameterAsDateTime( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
980 
991  QgsPointCloudLayer *parameterAsPointCloudLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsProcessing::LayerOptionsFlags flags = QgsProcessing::LayerOptionsFlags() ) const;
992 
1006  QgsAnnotationLayer *parameterAsAnnotationLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
1007 
1021  static QString invalidSourceError( const QVariantMap &parameters, const QString &name );
1022 
1036  static QString invalidRasterError( const QVariantMap &parameters, const QString &name );
1037 
1051  static QString invalidSinkError( const QVariantMap &parameters, const QString &name );
1052 
1066  static QString invalidPointCloudError( const QVariantMap &parameters, const QString &name );
1067 
1079  static QString writeFeatureError( QgsFeatureSink *sink, const QVariantMap &parameters, const QString &name );
1080 
1088  virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
1089 
1090  private:
1091 
1092  QgsProcessingProvider *mProvider = nullptr;
1095  bool mHasPrepared = false;
1096  bool mHasExecuted = false;
1097  bool mHasPostProcessed = false;
1098  std::unique_ptr< QgsProcessingContext > mLocalContext;
1099 
1100  bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
1101 
1102 
1104  friend class TestQgsProcessing;
1105  friend class QgsProcessingModelAlgorithm;
1107 
1108 #ifdef SIP_RUN
1110 #endif
1111 
1112 };
1113 
1114 
1138 {
1139  public:
1140 
1145 
1146  Qgis::ProcessingAlgorithmFlags flags() const override SIP_HOLDGIL;
1147 
1171  virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
1172 
1173  protected:
1174 
1175  void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;
1176 
1184  virtual QString inputParameterName() const SIP_HOLDGIL;
1185 
1193  virtual QString inputParameterDescription() const SIP_HOLDGIL;
1194 
1200  virtual QString outputName() const = 0 SIP_HOLDGIL;
1201 
1207  virtual QList<int> inputLayerTypes() const SIP_HOLDGIL;
1208 
1213  virtual Qgis::ProcessingSourceType outputLayerType() const SIP_HOLDGIL;
1214 
1218  virtual Qgis::ProcessingFeatureSourceFlags sourceFlags() const SIP_HOLDGIL;
1219 
1225  virtual QgsFeatureSink::SinkFlags sinkFlags() const SIP_HOLDGIL;
1226 
1234  virtual Qgis::WkbType outputWkbType( Qgis::WkbType inputWkbType ) const SIP_HOLDGIL;
1235 
1246  virtual QgsFields outputFields( const QgsFields &inputFields ) const SIP_HOLDGIL;
1247 
1257 
1263  virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
1264 
1269  QgsCoordinateReferenceSystem sourceCrs() const SIP_HOLDGIL;
1270 
1271 
1272  QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
1273 
1278  virtual QgsFeatureRequest request() const;
1279 
1288  bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;
1289 
1295  void prepareSource( const QVariantMap &parameters, QgsProcessingContext &context );
1296 
1297  QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
1298  const QVariantMap &parameters,
1299  QgsProcessingContext &context,
1300  const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const override;
1301 
1302  private:
1303 
1304  std::unique_ptr< QgsProcessingFeatureSource > mSource;
1305 
1306 };
1307 
1308 // clazy:excludeall=qstring-allocations
1309 
1310 #endif // QGSPROCESSINGALGORITHM_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:54
ProcessingPropertyAvailability
Property availability, used for QgsProcessingAlgorithm::VectorProperties in order to determine if pro...
Definition: qgis.h:2926
@ NotAvailable
Properties are not available.
QFlags< ProcessingAlgorithmFlag > ProcessingAlgorithmFlags
Flags indicating how and when an algorithm operates and should be exposed to users.
Definition: qgis.h:2914
WkbType
The WKB type describes the number of dimensions a geometry has.
Definition: qgis.h:182
@ Unknown
Unknown.
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:162
Base class for graphical items within a QgsLayout.
Base class for all map layer types.
Definition: qgsmaplayer.h:75
Represents a mesh layer supporting display of data on structured or unstructured meshes.
Definition: qgsmeshlayer.h:101
Represents a map layer supporting display of point clouds.
A class to represent a 2D point.
Definition: qgspointxy.h:60
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.
virtual QString groupId() const
Returns the unique ID of the group this algorithm belongs to.
QgsProcessingAlgorithm(const QgsProcessingAlgorithm &other)=delete
Algorithms cannot be copied - create() should be used instead.
QgsProcessingAlgorithm & operator=(const QgsProcessingAlgorithm &other)=delete
Algorithms cannot be copied- create() should be used instead.
QgsProcessingAlgorithm()=default
Constructor for QgsProcessingAlgorithm.
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.
QgsFeatureSource subclass which proxies methods to an underlying QgsFeatureSource,...
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,...
Contains enumerations and other constants for use in processing algorithms and parameters.
Definition: qgsprocessing.h:41
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.
std::unique_ptr< GEOSGeometry, GeosDeleter > unique_ptr
Scoped GEOS pointer.
Definition: qgsgeos.h:73
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:191
#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_HOLDGIL
Definition: qgis_sip.h:171
#define SIP_FACTORY
Definition: qgis_sip.h:76
#define SIP_VIRTUALERRORHANDLER(name)
Definition: qgis_sip.h:196
#define SIP_THROW(name,...)
Definition: qgis_sip.h:203
#define SIP_END
Definition: qgis_sip.h:208
QList< QgsFeature > QgsFeatureList
Definition: qgsfeature.h:917
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.