QGIS API Documentation  3.0.2-Girona (307d082)
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 "qgsfeaturesource.h"
28 #include <QString>
29 #include <QVariant>
30 #include <QIcon>
31 
34 class QgsFeatureSink;
36 
37 
38 #ifdef SIP_RUN
39 % ModuleHeaderCode
40 #include <qgsprocessingmodelalgorithm.h>
41 % End
42 #endif
43 
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  FlagDeprecated = FlagHideFromToolbox | FlagHideFromModeler,
77  };
78  Q_DECLARE_FLAGS( Flags, Flag )
79 
80 
87  QgsProcessingAlgorithm() = default;
88 
89  virtual ~QgsProcessingAlgorithm();
90 
92  QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other ) = delete;
94  QgsProcessingAlgorithm &operator=( const QgsProcessingAlgorithm &other ) = delete;
95 
96  /*
97  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
98  * the case.
99  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
100  *
101  * "
102  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
103  * In this case it isn't because it has already been seen when being returned by createInstance()
104  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
105  * by Python so the /Factory/ on create() would be correct.)
106  *
107  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
108  * "
109  */
110 
125  QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_TRANSFERBACK;
126 
136  virtual QString name() const = 0;
137 
144  QString id() const;
145 
151  virtual QString displayName() const = 0;
152 
157  virtual QStringList tags() const { return QStringList(); }
158 
165  virtual QString shortHelpString() const;
166 
173  virtual QString helpString() const;
174 
180  virtual QString helpUrl() const;
181 
186  virtual QIcon icon() const;
187 
192  virtual QString svgIconPath() const;
193 
200  virtual QString group() const { return QString(); }
201 
209  virtual QString groupId() const { return QString(); }
210 
215  virtual Flags flags() const;
216 
223  virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;
224 
232  virtual bool checkParameterValues( const QVariantMap &parameters,
233  QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;
234 
242  virtual QVariantMap preprocessParameters( const QVariantMap &parameters );
243 
247  QgsProcessingProvider *provider() const;
248 
256 
262  const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
263 
268  int countVisibleParameters() const;
269 
275  QgsProcessingParameterDefinitions destinationParameterDefinitions() const;
276 
283 
289  const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const;
290 
294  bool hasHtmlOutputs() const;
295 
313  QVariantMap run( const QVariantMap &parameters,
314  QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr ) const;
315 
326  bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
327 
339  QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );
340 
349  QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback );
350 
357  virtual QWidget *createCustomParametersWidget( QWidget *parent = nullptr ) const SIP_FACTORY;
358 
365  QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
366  QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;
367 
374  virtual bool validateInputCrs( const QVariantMap &parameters,
375  QgsProcessingContext &context ) const;
376 
384  virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;
385 
389  void setProvider( QgsProcessingProvider *provider );
390 
391  protected:
392 
398  virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY;
399 
418  virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;
419 
437  bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true );
438 
443  void removeParameter( const QString &name );
444 
458  bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER );
459 
490  virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
491 
522  virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
523 
551  virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );
552 
556  QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
557 
561  QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
562 
566  double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
567 
571  int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
572 
576  int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
577 
581  QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
582 
586  bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
587 
602  QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
604 
613  QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;
614 
627  QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
628  QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr );
629 
637  QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
638 
646  QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
647 
651  QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
652 
656  QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
657 
665  QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
666 
670  QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
671 
680  QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
682 
693  QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
695 
701  QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
702 
711  QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
713 
719  QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );
720 
724  QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
725 
730  QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
731 
735  QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
736 
740  QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
741 
745  QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
746 
747  private:
748 
749  QgsProcessingProvider *mProvider = nullptr;
752  bool mHasPrepared = false;
753  bool mHasExecuted = false;
754  bool mHasPostProcessed = false;
755  std::unique_ptr< QgsProcessingContext > mLocalContext;
756 
757  bool createAutoOutputForParameter( QgsProcessingParameterDefinition *parameter );
758 
759  friend class QgsProcessingProvider;
760  friend class TestQgsProcessing;
761  friend class QgsProcessingModelAlgorithm;
762 
763 #ifdef SIP_RUN
765 #endif
766 
767 };
768 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProcessingAlgorithm::Flags )
769 
770 
771 
772 
796 {
797  public:
798 
803 
804  protected:
805 
806  void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;
807 
813  virtual QString outputName() const = 0;
814 
820  virtual QList<int> inputLayerTypes() const;
821 
826  virtual QgsProcessing::SourceType outputLayerType() const;
827 
831  virtual QgsProcessingFeatureSource::Flag sourceFlags() const;
832 
840  virtual QgsWkbTypes::Type outputWkbType( QgsWkbTypes::Type inputWkbType ) const;
841 
852  virtual QgsFields outputFields( const QgsFields &inputFields ) const;
853 
862  virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const;
863 
869  virtual void initParameters( const QVariantMap &configuration = QVariantMap() );
870 
875  QgsCoordinateReferenceSystem sourceCrs() const;
876 
900  virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );
901 
902  QVariantMap processAlgorithm( const QVariantMap &parameters,
903  QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override;
904 
909  virtual QgsFeatureRequest request() const;
910 
911  private:
912 
913  std::unique_ptr< QgsProcessingFeatureSource > mSource;
914 
915 };
916 
917 // clazy:excludeall=qstring-allocations
918 
919 #endif // QGSPROCESSINGALGORITHM_H
920 
921 
#define SIP_VIRTUALERRORHANDLER(name)
Definition: qgis_sip.h:170
QList< const QgsProcessingParameterDefinition *> QgsProcessingParameterDefinitions
List of processing parameters.
A rectangle specified with double values.
Definition: qgsrectangle.h:39
Base class for all map layer types.
Definition: qgsmaplayer.h:56
Base class for providing feedback from a processing algorithm.
QgsProcessingParameterDefinitions parameterDefinitions() const
Returns an ordered list of parameter definitions utilized by the algorithm.
This class provides qgis with the ability to render raster datasets onto the mapcanvas.
QList< QgsFeature > QgsFeatureList
Definition: qgsfeature.h:549
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.
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:42
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:111
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:62
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:41
Abstract base class for processing algorithms.
Type
The WKB type describes the number of dimensions a geometry has.
Definition: qgswkbtypes.h:67
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
#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)...
#define SIP_END
Definition: qgis_sip.h:175
#define SIP_FACTORY
Definition: qgis_sip.h:69
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.
#define SIP_OUT
Definition: qgis_sip.h:51
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:165
SourceType
Data source types enum.
Definition: qgsprocessing.h:45
virtual QString groupId() const
Returns the unique ID of the group this algorithm belongs to.
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.