QGIS API Documentation  3.12.1-București (121cc00ff0)
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"
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 
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 
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  FlagDeprecated = FlagHideFromToolbox | FlagHideFromModeler,
80  };
81  Q_DECLARE_FLAGS( Flags, Flag )
82 
83 
90  QgsProcessingAlgorithm() = default;
91 
92  virtual ~QgsProcessingAlgorithm();
93 
95  QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other ) = delete;
97  QgsProcessingAlgorithm &operator=( const QgsProcessingAlgorithm &other ) = delete;
98 
99  /*
100  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
101  * the case.
102  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
103  *
104  * "
105  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
106  * In this case it isn't because it has already been seen when being returned by createInstance()
107  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
108  * by Python so the /Factory/ on create() would be correct.)
109  *
110  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
111  * "
112  */
113 
131  QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
132 
142  virtual QString name() const = 0;
143 
150  QString id() const;
151 
162  virtual QString displayName() const = 0;
163 
169  virtual QString shortDescription() const;
170 
175  virtual QStringList tags() const { return QStringList(); }
176 
183  virtual QString shortHelpString() const;
184 
192  Q_DECL_DEPRECATED virtual QString helpString() const SIP_DEPRECATED;
193 
199  virtual QString helpUrl() const;
200 
205  virtual QIcon icon() const;
206 
211  virtual QString svgIconPath() const;
212 
219  virtual QString group() const { return QString(); }
220 
228  virtual QString groupId() const { return QString(); }
229 
234  virtual Flags flags() const;
235 
242  virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
243 
251  virtual bool checkParameterValues( const QVariantMap &parameters,
252  QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
253 
261  virtual QVariantMap preprocessParameters( const QVariantMap &parameters );
262 
266  QgsProcessingProvider *provider() const;
267 
274  QgsProcessingParameterDefinitions parameterDefinitions() const { return mParameters; }
275 
281  const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
282 
287  int countVisibleParameters() const;
288 
294  QgsProcessingParameterDefinitions destinationParameterDefinitions() const;
295 
301  QgsProcessingOutputDefinitions outputDefinitions() const { return mOutputs; }
302 
308  const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const;
309 
313  bool hasHtmlOutputs() const;
314 
332  QVariantMap run( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap() ) const;
333 
344  bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
345 
357  QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );
358 
367  QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
368 
375  virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
376 
383  virtual QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
384  QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
385 
392  virtual bool validateInputCrs( const QVariantMap &parameters,
393  QgsProcessingContext &context ) const;
394 
402  virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;
403 
407  void setProvider( QgsProcessingProvider *provider );
408 
409  protected:
410 
416  virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );
417 
436  virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
437 
455  bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true );
456 
461  void removeParameter( const QString &name );
462 
476  bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER );
477 
508  virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
509 
539  virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
540 
568  virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
569 
573  QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
574 
578  QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
579 
583  double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
584 
588  int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
589 
594  QList<int> parameterAsInts( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
595 
599  int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
600 
604  QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
605 
609  bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
610 
615  bool parameterAsBoolean( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
616 
633  QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
634  const QgsFields &fields, QgsWkbTypes::Type geometryType = QgsWkbTypes::NoGeometry, const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem(), QgsFeatureSink::SinkFlags sinkFlags = nullptr ) const SIP_THROW( QgsProcessingException ) SIP_FACTORY;
635 
644  QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
645 
661  QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
662  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr );
663 
693  QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap &parameters, const QString &name,
694  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr );
695 
703  QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
704 
712  QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
713 
723  QgsMeshLayer *parameterAsMeshLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
724 
725 
729  QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
730 
734  QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
735 
743  QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
744 
748  QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
749 
758  QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
759  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
760 
771  QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
772  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() );
773 
779  QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
780 
789  QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
790  const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;
791 
797  QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
798 
802  QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
803 
808  QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
809 
813  QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
814 
820  QStringList parameterAsFileList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
821 
825  QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
826 
830  QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
831 
840  QgsPrintLayout *parameterAsLayout( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
841 
850  QgsLayoutItem *parameterAsLayoutItem( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );
851 
857  QColor parameterAsColor( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
858 
871  static QString invalidSourceError( const QVariantMap &parameters, const QString &name );
872 
885  static QString invalidRasterError( const QVariantMap &parameters, const QString &name );
886 
899  static QString invalidSinkError( const QVariantMap &parameters, const QString &name );
900 
908  virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
909 
910  private:
911 
912  QgsProcessingProvider *mProvider = nullptr;
913  QgsProcessingParameterDefinitions mParameters;
914  QgsProcessingOutputDefinitions mOutputs;
915  bool mHasPrepared = false;
916  bool mHasExecuted = false;
917  bool mHasPostProcessed = false;
918  std::unique_ptr< QgsProcessingContext > mLocalContext;
919 
920  bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
921 
922 
923  friend class QgsProcessingProvider;
924  friend class TestQgsProcessing;
925  friend class QgsProcessingModelAlgorithm;
926  friend class QgsProcessingToolboxProxyModel;
927 
928 #ifdef SIP_RUN
929  QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other );
930 #endif
931 
932 };
933 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProcessingAlgorithm::Flags )
934 
935 
936 
937 
960 class CORE_EXPORT QgsProcessingFeatureBasedAlgorithm : public QgsProcessingAlgorithm
961 {
962  public:
963 
967  QgsProcessingFeatureBasedAlgorithm() = default;
968 
969  QgsProcessingAlgorithm::Flags flags() const override;
970 
994  virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
995 
996  protected:
997 
998  void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;
999 
1007  virtual QString inputParameterName() const;
1008 
1016  virtual QString inputParameterDescription() const;
1017 
1023  virtual QString outputName() const = 0;
1024 
1030  virtual QList<int> inputLayerTypes() const;
1031 
1036  virtual QgsProcessing::SourceType outputLayerType() const;
1037 
1041  virtual QgsProcessingFeatureSource::Flag sourceFlags() const;
1042 
1048  virtual QgsFeatureSink::SinkFlags sinkFlags() const;
1049 
1057  virtual QgsWkbTypes::Type outputWkbType( QgsWkbTypes::Type inputWkbType ) const;
1058 
1069  virtual QgsFields outputFields( const QgsFields &inputFields ) const;
1070 
1079  virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const;
1080 
1086  virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
1087 
1092  QgsCoordinateReferenceSystem sourceCrs() const;
1093 
1094 
1095  QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );
1096 
1101  virtual QgsFeatureRequest request() const;
1102 
1111  bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;
1112 
1118  void prepareSource( const QVariantMap &parameters, QgsProcessingContext &context );
1119 
1120  private:
1121 
1122  std::unique_ptr< QgsProcessingFeatureSource > mSource;
1123 
1124 };
1125 
1126 // clazy:excludeall=qstring-allocations
1127 
1128 #endif // QGSPROCESSINGALGORITHM_H
1129 
1130 
SIP_VIRTUALERRORHANDLER
#define SIP_VIRTUALERRORHANDLER(name)
Definition: qgis_sip.h:177
QgsProcessingParameterDefinitions
QList< const QgsProcessingParameterDefinition *> QgsProcessingParameterDefinitions
List of processing parameters.
Definition: qgsprocessingparameters.h:598
QgsRectangle
A rectangle specified with double values.
Definition: qgsrectangle.h:41
QgsMapLayer
Base class for all map layer types.
Definition: qgsmaplayer.h:79
QgsProcessingFeedback
Base class for providing feedback from a processing algorithm.
Definition: qgsprocessingfeedback.h:37
QgsProcessingAlgorithm::parameterDefinitions
QgsProcessingParameterDefinitions parameterDefinitions() const
Returns an ordered list of parameter definitions utilized by the algorithm.
Definition: qgsprocessingalgorithm.h:274
QgsLayoutItem
Base class for graphical items within a QgsLayout.
Definition: qgslayoutitem.h:112
QgsRasterLayer
Represents a raster layer.
Definition: qgsrasterlayer.h:70
QgsFeatureList
QList< QgsFeature > QgsFeatureList
Definition: qgsfeature.h:571
QgsProcessingAlgorithm::group
virtual QString group() const
Returns the name of the group this algorithm belongs to.
Definition: qgsprocessingalgorithm.h:219
QgsPointXY
A class to represent a 2D point.
Definition: qgspointxy.h:43
QgsFeatureSink
An interface for objects which accept features via addFeature(s) methods.
Definition: qgsfeaturesink.h:33
QgsProcessingFeatureSource
QgsFeatureSource subclass which proxies methods to an underlying QgsFeatureSource, modifying results according to the settings in a QgsProcessingContext.
Definition: qgsprocessingutils.h:437
QgsFields
Container of fields for a vector layer.
Definition: qgsfields.h:42
QgsGeometry
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:122
QgsProcessingProvider
Abstract base class for processing providers.
Definition: qgsprocessingprovider.h:34
QgsFeature
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:55
crs
const QgsCoordinateReferenceSystem & crs
Definition: qgswfsgetfeature.cpp:51
SIP_TRANSFERBACK
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
QgsProcessingAlgorithm
Abstract base class for processing algorithms.
Definition: qgsprocessingalgorithm.h:51
QgsWkbTypes::Type
Type
The WKB type describes the number of dimensions a geometry has.
Definition: qgswkbtypes.h:68
QgsExpressionContext
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Definition: qgsexpressioncontext.h:371
SIP_TRANSFER
#define SIP_TRANSFER
Definition: qgis_sip.h:36
QgsFeatureRequest
This class wraps a request for features to a vector layer (or directly its vector data provider)...
Definition: qgsfeaturerequest.h:72
QgsProcessingException
Custom exception class for processing related exceptions.
Definition: qgsexception.h:82
SIP_END
#define SIP_END
Definition: qgis_sip.h:189
SIP_FACTORY
#define SIP_FACTORY
Definition: qgis_sip.h:76
SIP_DEPRECATED
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
QgsProcessingFeatureSource::Flag
Flag
Flags controlling how QgsProcessingFeatureSource fetches features.
Definition: qgsprocessingutils.h:442
QgsProcessingAlgorithm::outputDefinitions
QgsProcessingOutputDefinitions outputDefinitions() const
Returns an ordered list of output definitions utilized by the algorithm.
Definition: qgsprocessingalgorithm.h:301
QgsProcessingOutputDefinition
Base class for the definition of processing outputs.
Definition: qgsprocessingoutputs.h:41
QgsProcessingOutputDefinitions
QList< const QgsProcessingOutputDefinition *> QgsProcessingOutputDefinitions
List of processing parameters.
Definition: qgsprocessingoutputs.h:124
QgsProcessingAlgorithmConfigurationWidget
A configuration widget for processing algorithms allows providing additional configuration options di...
Definition: qgsprocessingalgorithmconfigurationwidget.h:40
QgsProcessingToolboxProxyModel
A sort/filter proxy model for providers and algorithms shown within the Processing toolbox...
Definition: qgsprocessingtoolboxmodel.h:416
SIP_OUT
#define SIP_OUT
Definition: qgis_sip.h:58
QgsCoordinateReferenceSystem
This class represents a coordinate reference system (CRS).
Definition: qgscoordinatereferencesystem.h:202
QgsProcessingParameterDefinition
Base class for the definition of processing parameters.
Definition: qgsprocessingparameters.h:206
QgsProcessingAlgorithm::Flag
Flag
Flags indicating how and when an algorithm operates and should be exposed to users.
Definition: qgsprocessingalgorithm.h:68
SIP_CONVERT_TO_SUBCLASS_CODE
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:172
QgsProcessing::SourceType
SourceType
Data source types enum.
Definition: qgsprocessing.h:44
outputCrs
const QgsCoordinateReferenceSystem & outputCrs
Definition: qgswfsgetfeature.cpp:61
SIP_THROW
#define SIP_THROW(name)
Definition: qgis_sip.h:184
QgsMeshLayer
Represents a mesh layer supporting display of data on structured or unstructured meshes.
Definition: qgsmeshlayer.h:91
QgsProcessingAlgorithm::groupId
virtual QString groupId() const
Returns the unique ID of the group this algorithm belongs to.
Definition: qgsprocessingalgorithm.h:228
QgsPrintLayout
Print layout, a QgsLayout subclass for static or atlas-based layouts.
Definition: qgsprintlayout.h:30
QgsProcessingFeatureBasedAlgorithm
An abstract QgsProcessingAlgorithm base class for processing algorithms which operate "feature-by-fea...
Definition: qgsprocessingalgorithm.h:960
QgsVectorLayer
Represents a vector layer which manages a vector based data sets.
Definition: qgsvectorlayer.h:386
QgsProcessingContext
Contains information about the context in which a processing algorithm is executed.
Definition: qgsprocessingcontext.h:43
Generated on Sat Mar 21 2020 00:00:36 for QGIS API Documentation by   doxygen 1.8.13