QGIS API Documentation  3.17.0-Master (8af46bc54f)
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 
39 #ifdef SIP_RUN
40 % ModuleHeaderCode
41 #include <qgsprocessingmodelalgorithm.h>
42 % End
43 #endif
44 
51 class CORE_EXPORT QgsProcessingAlgorithm
52 {
53 
54 #ifdef SIP_RUN
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 
68  enum Flag
69  {
70  FlagHideFromToolbox = 1 << 1,
71  FlagHideFromModeler = 1 << 2,
72  FlagSupportsBatch = 1 << 3,
73  FlagCanCancel = 1 << 4,
74  FlagRequiresMatchingCrs = 1 << 5,
75  FlagNoThreading = 1 << 6,
76  FlagDisplayNameIsLiteral = 1 << 7,
77  FlagSupportsInPlaceEdits = 1 << 8,
78  FlagKnownIssues = 1 << 9,
79  FlagCustomException = 1 << 10,
80  FlagPruneModelBranchesBasedOnAlgorithmResults = 1 << 11,
81  FlagSkipGenericModelLogging = 1 << 12,
82  FlagNotAvailableInStandaloneTool = 1 << 13,
83  FlagRequiresProject = 1 << 14,
84  FlagDeprecated = FlagHideFromToolbox | FlagHideFromModeler,
85  };
86  Q_DECLARE_FLAGS( Flags, Flag )
87 
88 
95  QgsProcessingAlgorithm() = default;
96 
97  virtual ~QgsProcessingAlgorithm();
98 
100  QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other ) = delete;
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 
136  QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
137 
147  virtual QString name() const = 0;
148 
155  QString id() const;
156 
167  virtual QString displayName() const = 0;
168 
174  virtual QString shortDescription() const;
175 
180  virtual QStringList tags() const { return QStringList(); }
181 
188  virtual QString shortHelpString() const;
189 
197  Q_DECL_DEPRECATED virtual QString helpString() const SIP_DEPRECATED;
198 
204  virtual QString helpUrl() const;
205 
210  virtual QIcon icon() const;
211 
216  virtual QString svgIconPath() const;
217 
224  virtual QString group() const { return QString(); }
225 
233  virtual QString groupId() const { return QString(); }
234 
239  virtual Flags flags() const;
240 
247  virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
248 
256  virtual bool checkParameterValues( const QVariantMap &parameters,
257  QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
258 
266  virtual QVariantMap preprocessParameters( const QVariantMap &parameters );
267 
271  QgsProcessingProvider *provider() const;
272 
280 
286  const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
287 
292  int countVisibleParameters() const;
293 
299  QgsProcessingParameterDefinitions destinationParameterDefinitions() const;
300 
307 
313  const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const;
314 
318  bool hasHtmlOutputs() const;
319 
325  {
328  };
329 
336  {
339 
342 
345 
348  };
349 
365  virtual QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
366  const QVariantMap &parameters,
367  QgsProcessingContext &context,
368  const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const;
369 
390  QVariantMap run( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap(),
391  bool catchExceptions = true ) const SIP_THROW( QgsProcessingException );
392 
403  bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
404 
416  QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );
417 
426  QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
427 
434  virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
435 
442  virtual QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
443  QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
444 
451  virtual bool validateInputCrs( const QVariantMap &parameters,
452  QgsProcessingContext &context ) const;
453 
461  virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;
462 
466  void setProvider( QgsProcessingProvider *provider );
467 
468  protected:
469 
475  virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );
476 
495  virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
496 
514  bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true );
515 
520  void removeParameter( const QString &name );
521 
535  bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER );
536 
567  virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
568 
598  virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
599 
627  virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
628 
632  QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
633 
637  QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
638 
642  double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
643 
647  int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
648 
653  QList<int> parameterAsInts( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
654 
658  int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
659 
663  QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
664 
669  QString parameterAsEnumString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
670 
675  QStringList parameterAsEnumStrings( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
676 
680  bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
681 
686  bool parameterAsBoolean( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
687 
708  QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, 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 
719  QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
720 
736  QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
737  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr );
738 
768  QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap &parameters, const QString &name,
769  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr );
770 
778  QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
779 
787  QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
788 
798  QgsMeshLayer *parameterAsMeshLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
799 
800 
804  QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
805 
809  QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
810 
818  QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
819 
823  QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
824 
833  QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
834  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
835 
846  QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
847  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() );
848 
854  QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
855 
864  QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
865  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
866 
872  QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
873 
882  QgsGeometry parameterAsGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
883  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
884 
890  QgsCoordinateReferenceSystem parameterAsGeometryCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
891 
892 
893 
897  QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
898 
903  QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
904 
908  QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
909 
915  QStringList parameterAsFileList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
916 
920  QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
921 
925  QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
926 
935  QgsPrintLayout *parameterAsLayout( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
936 
945  QgsLayoutItem *parameterAsLayoutItem( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );
946 
952  QColor parameterAsColor( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
953 
959  QString parameterAsConnectionName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
960 
966  QString parameterAsSchema( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
967 
973  QString parameterAsDatabaseTableName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
974 
980  QDateTime parameterAsDateTime( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
981 
982 
995  static QString invalidSourceError( const QVariantMap &parameters, const QString &name );
996 
1009  static QString invalidRasterError( const QVariantMap &parameters, const QString &name );
1010 
1023  static QString invalidSinkError( const QVariantMap &parameters, const QString &name );
1024 
1032  virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
1033 
1034  private:
1035 
1036  QgsProcessingProvider *mProvider = nullptr;
1039  bool mHasPrepared = false;
1040  bool mHasExecuted = false;
1041  bool mHasPostProcessed = false;
1042  std::unique_ptr< QgsProcessingContext > mLocalContext;
1043 
1044  bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
1045 
1046 
1048  friend class TestQgsProcessing;
1049  friend class QgsProcessingModelAlgorithm;
1051 
1052 #ifdef SIP_RUN
1054 #endif
1055 
1056 };
1057 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProcessingAlgorithm::Flags )
1058 
1059 
1060 
1061 
1085 {
1086  public:
1087 
1092 
1093  QgsProcessingAlgorithm::Flags flags() const override;
1094 
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 
1131  virtual QString inputParameterName() const;
1132 
1140  virtual QString inputParameterDescription() const;
1141 
1147  virtual QString outputName() const = 0;
1148 
1154  virtual QList<int> inputLayerTypes() const;
1155 
1160  virtual QgsProcessing::SourceType outputLayerType() const;
1161 
1165  virtual QgsProcessingFeatureSource::Flag sourceFlags() const;
1166 
1172  virtual QgsFeatureSink::SinkFlags sinkFlags() const;
1173 
1181  virtual QgsWkbTypes::Type outputWkbType( QgsWkbTypes::Type inputWkbType ) const;
1182 
1193  virtual QgsFields outputFields( const QgsFields &inputFields ) const;
1194 
1203  virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const;
1204 
1210  virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
1211 
1216  QgsCoordinateReferenceSystem sourceCrs() const;
1217 
1218 
1219  QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
1220 
1225  virtual QgsFeatureRequest request() const;
1226 
1235  bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;
1236 
1242  void prepareSource( const QVariantMap &parameters, QgsProcessingContext &context );
1243 
1244  QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
1245  const QVariantMap &parameters,
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 
#define SIP_VIRTUALERRORHANDLER(name)
Definition: qgis_sip.h:182
PropertyAvailability
Property availability, used for QgsProcessingAlgorithm::VectorProperties in order to determine if pro...
QList< const QgsProcessingParameterDefinition *> QgsProcessingParameterDefinitions
List of processing parameters.
A rectangle specified with double values.
Definition: qgsrectangle.h:41
Base class for all map layer types.
Definition: qgsmaplayer.h:83
Properties of a vector source or sink used in an algorithm.
Base class for providing feedback from a processing algorithm.
QgsProcessingParameterDefinitions parameterDefinitions() const
Returns an ordered list of parameter definitions utilized by the algorithm.
Base class for graphical items within a QgsLayout.
Represents a raster layer.
QList< QgsFeature > QgsFeatureList
Definition: qgsfeature.h:583
Handles storage of information regarding WKB types and their properties.
Definition: qgswkbtypes.h:41
virtual QString group() const
Returns the name of the group this algorithm belongs to.
A class to represent a 2D point.
Definition: qgspointxy.h:43
An interface for objects which accept features via addFeature(s) methods.
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.
QgsFeatureSource subclass which proxies methods to an underlying QgsFeatureSource, modifying results according to the settings in a QgsProcessingContext.
Container of fields for a vector layer.
Definition: qgsfields.h:44
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:123
Abstract base class for processing providers.
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:55
const QgsCoordinateReferenceSystem & crs
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
Abstract base class for processing algorithms.
Type
The WKB type describes the number of dimensions a geometry has.
Definition: qgswkbtypes.h:69
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
std::unique_ptr< GEOSGeometry, GeosDeleter > unique_ptr
Scoped GEOS pointer.
Definition: qgsgeos.h:79
#define SIP_TRANSFER
Definition: qgis_sip.h:36
This class wraps a request for features to a vector layer (or directly its vector data provider)...
Custom exception class for processing related exceptions.
Definition: qgsexception.h:82
#define SIP_END
Definition: qgis_sip.h:194
#define SIP_FACTORY
Definition: qgis_sip.h:76
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
Flag
Flags controlling how QgsProcessingFeatureSource fetches features.
QgsProcessingOutputDefinitions outputDefinitions() const
Returns an ordered list of output definitions utilized by the algorithm.
Base class for the definition of processing outputs.
QList< const QgsProcessingOutputDefinition *> QgsProcessingOutputDefinitions
List of processing parameters.
A configuration widget for processing algorithms allows providing additional configuration options di...
A sort/filter proxy model for providers and algorithms shown within the Processing toolbox...
#define SIP_OUT
Definition: qgis_sip.h:58
This class represents a coordinate reference system (CRS).
Base class for the definition of processing parameters.
Flag
Flags indicating how and when an algorithm operates and should be exposed to users.
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:177
SourceType
Data source types enum.
Definition: qgsprocessing.h:44
const QgsCoordinateReferenceSystem & outputCrs
#define SIP_THROW(name)
Definition: qgis_sip.h:189
Represents a mesh layer supporting display of data on structured or unstructured meshes.
Definition: qgsmeshlayer.h:94
virtual QString groupId() const
Returns the unique ID of the group this algorithm belongs to.
Print layout, a QgsLayout subclass for static or atlas-based layouts.
QgsCoordinateReferenceSystem crs
Coordinate Reference System.
An abstract QgsProcessingAlgorithm base class for processing algorithms which operate "feature-by-fea...
Represents a vector layer which manages a vector based data sets.
Contains information about the context in which a processing algorithm is executed.