qgsprocessingalgorithm.h

Go to the documentation of this file.

/***************************************************************************
                         qgsprocessingalgorithm.h
                         ------------------------
    begin                : December 2016
    copyright            : (C) 2016 by Nyall Dawson
    email                : nyall dot dawson at gmail dot com
 ***************************************************************************/
 
/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#ifndef QGSPROCESSINGALGORITHM_H
#define QGSPROCESSINGALGORITHM_H
 
#include "qgis.h"
#include "qgis_core.h"
 
#define EXCLUDE_CPPCHECK
#ifdef EXCLUDE_CPPCHECK
#include "qgsprocessingalgorithm_p.h"
#endif
#include "qgsprocessingcontext.h"
#include "qgsprocessingoutputs.h"
#include "qgsprocessingparameters.h"
#include "qgsprocessingutils.h"
 
#include <QIcon>
#include <QString>
#include <QVariant>
 
class QgsProcessingProvider;
class QgsProcessingFeedback;
class QgsFeatureSink;
class QgsProcessingModelAlgorithm;
class QgsProcessingAlgorithmConfigurationWidget;
class QgsMeshLayer;
class QgsPointCloudLayer;
class QMainWindow;
class QgsAcademicReference;
 
#ifdef SIP_RUN
// clang-format off
% ModuleHeaderCode
#include <qgsprocessingmodelalgorithm.h>
% End
// clang-format on
#endif

  class CORE_EXPORT QgsProcessingAlgorithm
{
#ifdef SIP_RUN
    SIP_CONVERT_TO_SUBCLASS_CODE
    if ( dynamic_cast< QgsProcessingModelAlgorithm * >( sipCpp ) != NULL )
      sipType = sipType_QgsProcessingModelAlgorithm;
    else if ( dynamic_cast< QgsProcessingFeatureBasedAlgorithm * >( sipCpp ) != NULL )
      sipType = sipType_QgsProcessingFeatureBasedAlgorithm;
    else
      sipType = sipType_QgsProcessingAlgorithm;
  SIP_END
#endif
 
  public:

    QgsProcessingAlgorithm() = default;
 
    virtual ~QgsProcessingAlgorithm();

    QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other ) = delete;
    QgsProcessingAlgorithm &operator=( const QgsProcessingAlgorithm &other ) = delete;
 
    /*
     * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
     * the case.
     * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
     *
     * "
     * /Factory/ is used when the instance returned is guaranteed to be new to Python.
     * In this case it isn't because it has already been seen when being returned by createInstance()
     * (However for a different sub-class implemented in C++ then it would be the first time it was seen
     * by Python so the /Factory/ on create() would be correct.)
     *
     * You might try using /TransferBack/ on create() instead - that might be the best compromise.
     * "
     */

    QgsProcessingAlgorithm *create( const QVariantMap &configuration = QVariantMap() ) const SIP_THROW( QgsProcessingException ) SIP_TRANSFERBACK;
 
    // clang-format off
    virtual QString name() const = 0 SIP_HOLDGIL;
    // clang-format on

    QString id() const SIP_HOLDGIL;

    virtual QString displayName() const = 0 SIP_HOLDGIL;

    virtual QString shortDescription() const SIP_HOLDGIL;

    virtual QStringList tags() const SIP_HOLDGIL { return QStringList(); }

    virtual QString shortHelpString() const SIP_HOLDGIL;

    Q_DECL_DEPRECATED virtual QString helpString() const SIP_HOLDGIL SIP_DEPRECATED;

    virtual QString helpUrl() const SIP_HOLDGIL;

    virtual Qgis::ProcessingAlgorithmDocumentationFlags documentationFlags() const SIP_HOLDGIL;

    virtual QList<QgsAcademicReference> academicReferences() const;

    struct ExternalLink
    {
      QString description;
      QString url;
    };

    virtual QList< QgsProcessingAlgorithm::ExternalLink > externalLinks() const;

    virtual QString implementationSourceUri() const;

    virtual QIcon icon() const SIP_HOLDGIL;

    virtual QString svgIconPath() const SIP_HOLDGIL;

    virtual QString group() const SIP_HOLDGIL { return QString(); }

    virtual QString groupId() const SIP_HOLDGIL { return QString(); }

    virtual Qgis::ProcessingAlgorithmFlags flags() const SIP_HOLDGIL;

    virtual bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const;

    virtual bool checkParameterValues( const QVariantMap &parameters,
                                       QgsProcessingContext &context, QString *message SIP_OUT = nullptr ) const;

    virtual QVariantMap preprocessParameters( const QVariantMap &parameters );

    virtual QVariantMap autogenerateParameterValues( const QVariantMap &existingParameters, const QString &changedParameter, Qgis::ProcessingMode mode ) const;

    QgsProcessingProvider *provider() const SIP_HOLDGIL;

    QgsProcessingParameterDefinitions parameterDefinitions() const SIP_HOLDGIL { return mParameters; }

    const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const SIP_HOLDGIL;

    int countVisibleParameters() const SIP_HOLDGIL;

    QgsProcessingParameterDefinitions destinationParameterDefinitions() const SIP_HOLDGIL;

    QgsProcessingOutputDefinitions outputDefinitions() const SIP_HOLDGIL { return mOutputs; }

    const QgsProcessingOutputDefinition *outputDefinition( const QString &name ) const SIP_HOLDGIL;

    bool hasHtmlOutputs() const SIP_HOLDGIL;
 

    struct VectorProperties
    {
      QgsFields fields;

      Qgis::WkbType wkbType = Qgis::WkbType::Unknown;

      QgsCoordinateReferenceSystem crs;

      Qgis::ProcessingPropertyAvailability availability = Qgis::ProcessingPropertyAvailability::NotAvailable;
    };

    virtual QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
        const QVariantMap &parameters,
        QgsProcessingContext &context,
        const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const;

    QVariantMap run( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool *ok SIP_OUT = nullptr, const QVariantMap &configuration = QVariantMap(),
                     bool catchExceptions = true ) const SIP_THROW( QgsProcessingException );

    bool prepare( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback );

    QVariantMap runPrepared( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException );

    QVariantMap postProcess( QgsProcessingContext &context, QgsProcessingFeedback *feedback, bool runResult = true );

    virtual QWidget *createCustomParametersWidget( QMainWindow *parent = nullptr ) const SIP_FACTORY;

    virtual QgsExpressionContext createExpressionContext( const QVariantMap &parameters,
        QgsProcessingContext &context, QgsProcessingFeatureSource *source = nullptr ) const;

    virtual bool validateInputCrs( const QVariantMap &parameters,
                                   QgsProcessingContext &context ) const;

    virtual QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const;

    virtual QString asQgisProcessCommand( const QVariantMap &parameters, QgsProcessingContext &context, bool &ok SIP_OUT ) const;

    virtual QVariantMap asMap( const QVariantMap &parameters, QgsProcessingContext &context ) const;

    void setProvider( QgsProcessingProvider *provider ) SIP_HOLDGIL;

    virtual bool supportInPlaceEdit( const QgsMapLayer *layer ) const;
 
  protected:

    virtual QgsProcessingAlgorithm *createInstance() const = 0 SIP_FACTORY SIP_VIRTUALERRORHANDLER( processing_exception_handler );

    virtual void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) = 0;

    bool addParameter( QgsProcessingParameterDefinition *parameterDefinition SIP_TRANSFER, bool createOutput = true ) SIP_HOLDGIL;

    bool addParameter( std::unique_ptr<QgsProcessingParameterDefinition> parameterDefinition, bool createOutput = true ) SIP_SKIP;

    void removeParameter( const QString &name ) SIP_HOLDGIL;

    bool addOutput( QgsProcessingOutputDefinition *outputDefinition SIP_TRANSFER ) SIP_HOLDGIL;

    bool addOutput( std::unique_ptr<QgsProcessingOutputDefinition> outputDefinition ) SIP_SKIP;

    virtual bool prepareAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );

    virtual QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );

    virtual QVariantMap postProcessAlgorithm( QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) SIP_VIRTUALERRORHANDLER( processing_exception_handler );

    QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QList<int> parameterAsInts( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QString parameterAsEnumString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QStringList parameterAsEnumStrings( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    bool parameterAsBoolean( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;

    QgsFeatureSink *parameterAsSink( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QString &destinationIdentifier SIP_OUT,
                                     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;

    QgsProcessingFeatureSource *parameterAsSource( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_FACTORY;

    QString parameterAsCompatibleSourceLayerPath( const QVariantMap &parameters, const QString &name,
        QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr ) const;

    QString parameterAsCompatibleSourceLayerPathAndLayerName( const QVariantMap &parameters, const QString &name,
        QgsProcessingContext &context, const QStringList &compatibleFormats, const QString &preferredFormat = QString( "shp" ), QgsProcessingFeedback *feedback = nullptr, QString *layerName SIP_OUT = nullptr ) const;

    QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsMeshLayer *parameterAsMeshLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsOutputLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsOutputFormat( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsOutputRasterFormat( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsFileOutput( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
                                    const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;

    QgsGeometry parameterAsExtentGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
                                           const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;

    QgsCoordinateReferenceSystem parameterAsExtentCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsPointXY parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
                                 const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;

    QgsCoordinateReferenceSystem parameterAsPointCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsGeometry parameterAsGeometry( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context,
                                     const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem() ) const;

    QgsCoordinateReferenceSystem parameterAsGeometryCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsProcessing::LayerOptionsFlags flags = QgsProcessing::LayerOptionsFlags() ) const;

    QStringList parameterAsFileList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    Q_DECL_DEPRECATED QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const SIP_DEPRECATED;

    QStringList parameterAsStrings( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsPrintLayout *parameterAsLayout( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context );

    QgsLayoutItem *parameterAsLayoutItem( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsPrintLayout *layout );

    QColor parameterAsColor( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsConnectionName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsSchema( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QString parameterAsDatabaseTableName( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QDateTime parameterAsDateTime( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    QgsPointCloudLayer *parameterAsPointCloudLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context, QgsProcessing::LayerOptionsFlags flags = QgsProcessing::LayerOptionsFlags() ) const;

    QgsAnnotationLayer *parameterAsAnnotationLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

    static QString invalidSourceError( const QVariantMap &parameters, const QString &name );

    static QString invalidRasterError( const QVariantMap &parameters, const QString &name );

    static QString invalidSinkError( const QVariantMap &parameters, const QString &name );

    static QString invalidPointCloudError( const QVariantMap &parameters, const QString &name );

    static QString writeFeatureError( QgsFeatureSink *sink, const QVariantMap &parameters, const QString &name );
 
  private:
 
    QgsProcessingProvider *mProvider = nullptr;
    QgsProcessingParameterDefinitions mParameters;
    QgsProcessingOutputDefinitions mOutputs;
    bool mHasPrepared = false;
    bool mHasExecuted = false;
    bool mHasPostProcessed = false;
    std::unique_ptr< QgsProcessingContext > mLocalContext;
 
    bool createAutoOutputForParameter( const QgsProcessingParameterDefinition *parameter );
 
 
    friend class QgsProcessingProvider;
    friend class TestQgsProcessing;
    friend class QgsProcessingModelAlgorithm;
    friend class QgsProcessingToolboxProxyModel;
    friend class DummyRaiseExceptionAlgorithm;
 
#ifdef SIP_RUN
    QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other );
#endif
 
};
 

 
class CORE_EXPORT QgsProcessingFeatureBasedAlgorithm : public QgsProcessingAlgorithm
{
  public:
 
    QgsProcessingFeatureBasedAlgorithm() = default;
 
    Qgis::ProcessingAlgorithmFlags flags() const override SIP_HOLDGIL;

    virtual QgsFeatureList processFeature( const QgsFeature &feature, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) SIP_THROW( QgsProcessingException ) = 0 SIP_VIRTUALERRORHANDLER( processing_exception_handler );

    bool supportInPlaceEdit( const QgsMapLayer *layer ) const override;

    virtual QString inputParameterName() const SIP_HOLDGIL;

    virtual QString inputParameterDescription() const SIP_HOLDGIL;
 
  protected:
 
    void initAlgorithm( const QVariantMap &configuration = QVariantMap() ) override;

    virtual QString outputName() const = 0 SIP_HOLDGIL;

    virtual QList<int> inputLayerTypes() const SIP_HOLDGIL;

    virtual Qgis::ProcessingSourceType outputLayerType() const SIP_HOLDGIL;

    virtual Qgis::ProcessingFeatureSourceFlags sourceFlags() const SIP_HOLDGIL;

    virtual QgsFeatureSink::SinkFlags sinkFlags() const SIP_HOLDGIL;

    virtual Qgis::WkbType outputWkbType( Qgis::WkbType inputWkbType ) const SIP_HOLDGIL;

    virtual QgsFields outputFields( const QgsFields &inputFields ) const SIP_HOLDGIL;

    virtual QgsCoordinateReferenceSystem outputCrs( const QgsCoordinateReferenceSystem &inputCrs ) const SIP_HOLDGIL;

    virtual void initParameters( const QVariantMap &configuration = QVariantMap() );

    QgsCoordinateReferenceSystem sourceCrs() const SIP_HOLDGIL;
 
 
    QVariantMap processAlgorithm( const QVariantMap &parameters, QgsProcessingContext &context, QgsProcessingFeedback *feedback ) override SIP_THROW( QgsProcessingException );

    virtual QgsFeatureRequest request() const;

    void prepareSource( const QVariantMap &parameters, QgsProcessingContext &context );
 
    QgsProcessingAlgorithm::VectorProperties sinkProperties( const QString &sink,
        const QVariantMap &parameters,
        QgsProcessingContext &context,
        const QMap< QString, QgsProcessingAlgorithm::VectorProperties > &sourceProperties ) const override;
 
  private:
 
    std::unique_ptr< QgsProcessingFeatureSource > mSource;
 
};
 
// clazy:excludeall=qstring-allocations
 
#endif // QGSPROCESSINGALGORITHM_H