qgsprocessingmodelalgorithm.h

/***************************************************************************
                         qgsprocessingmodelalgorithm.h
                         -----------------------------
    begin                : June 2017
    copyright            : (C) 2017 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 QGSPROCESSINGMODELALGORITHM_H
#define QGSPROCESSINGMODELALGORITHM_H

#include "qgis_core.h"
#include "qgis.h"
#include "qgsprocessingalgorithm.h"

///@cond NOT_STABLE

/**
 * \class QgsProcessingModelAlgorithm
 * \ingroup core
 * Model based algorithm with processing.
  * \since QGIS 3.0
 */
class CORE_EXPORT QgsProcessingModelAlgorithm : public QgsProcessingAlgorithm
{
  public:

    /**
     * Source for the value of a parameter for a child algorithm within a model.
     * \since QGIS 3.0
     * \ingroup core
     */
    class CORE_EXPORT ChildParameterSource
    {
      public:

        //! Possible parameter value sources
        enum Source
        {
          ModelParameter, //!< Parameter value is taken from a parent model parameter
          ChildOutput, //!< Parameter value is taken from an output generated by a child algorithm
          StaticValue, //!< Parameter value is a static value
        };

        /**
         * Constructor for ChildParameterSource. It is recommended that the static methods
         * fromStaticValue(), fromModelParameter() and fromChildOutput() are used instead.
         */
        ChildParameterSource() = default;

        bool operator==( const QgsProcessingModelAlgorithm::ChildParameterSource &other ) const;
        bool operator!=( const QgsProcessingModelAlgorithm::ChildParameterSource &other ) const
        {
          return !operator==( other );
        }

        /**
         * Returns a new ChildParameterSource which takes its value from a static \a value.
         * \see fromModelParameter()
         * \see fromChildOutput()
         */
        static QgsProcessingModelAlgorithm::ChildParameterSource fromStaticValue( const QVariant &value );

        /**
         * Returns a new ChildParameterSource which takes its value from a parent model parameter.
         * \see fromStaticValue()
         * \see fromChildOutput()
         */
        static QgsProcessingModelAlgorithm::ChildParameterSource fromModelParameter( const QString &parameterName );

        /**
         * Returns a new ChildParameterSource which takes its value from an output generated by a child algorithm.
         * \see fromStaticValue()
         * \see fromModelParameter()
         */
        static QgsProcessingModelAlgorithm::ChildParameterSource fromChildOutput( const QString &childId, const QString &outputName );

        /**
         * Returns the parameter value's source.
         */
        Source source() const;

        /**
         * Returns the source's static value. This is only used when the source() is StaticValue.
         * \see setStaticValue()
         */
        QVariant staticValue() const { return mStaticValue; }

        /**
         * Sets the source's static value. Calling this will also change the source() to StaticValue.
         * \see staticValue()
         */
        void setStaticValue( const QVariant &value ) { mStaticValue = value; mSource = StaticValue; }

        /**
         * Returns the source's model parameter name. This is only used when the source() is ModelParameter.
         * \see setParameterName()
         */
        QString parameterName() const { return mParameterName; }

        /**
         * Sets the source's model parameter \a name. Calling this will also change the source() to ModelParameter.
         * \see parameterName()
         */
        void setParameterName( const QString &name ) { mParameterName = name; mSource = ModelParameter; }

        /**
         * Returns the source's child algorithm ID from which the output value will be taken. This is only used when the source() is ChildOutput.
         * \see setOutputChildId()
         * \see outputName()
         */
        QString outputChildId() const { return mChildId; }

        /**
         * Sets the source's child algorithm \a id from which the output value will be taken. Calling this will also change the source() to ChildOutput.
         * \see parameterName()
         * \see setOutputName()
         */
        void setOutputChildId( const QString &id ) { mChildId = id; mSource = ChildOutput; }

        /**
         * Returns the source's child algorithm output name from which the output value will be taken. This is only used when the source() is ChildOutput.
         * \see setOutputName()
         * \see outputChildId()
         */
        QString outputName() const { return mOutputName; }

        /**
         * Sets the source's child algorithm output \a name from which the output value will be taken. Calling this will also change the source() to ChildOutput.
         * \see outputName()
         * \see setOutputChildId()
         */
        void setOutputName( const QString &name ) { mOutputName = name; mSource = ChildOutput; }

        /**
         * Saves this source to a QVariant.
         * \see loadVariant()
         */
        QVariant toVariant() const;

        /**
         * Loads this source from a QVariantMap.
         * \see toVariant()
         */
        bool loadVariant( const QVariantMap &map );

        /**
         * Attempts to convert the source to executable Python code.
         */
        QString asPythonCode() const;

      private:

        Source mSource = StaticValue;
        QVariant mStaticValue;
        QString mParameterName;
        QString mChildId;
        QString mOutputName;

    };

    /**
     * Represents a component of a model algorithm.
     * \since QGIS 3.0
     * \ingroup core
     */
    class CORE_EXPORT Component
    {
      public:

        /**
         * Returns the friendly description text for the component.
         * \see setDescription()
         */
        QString description() const;

        /**
         * Sets the friendly \a description text for the component.
         * \see description()
         */
        void setDescription( const QString &description );

        /**
         * Returns the position of the model component within the graphical modeler.
         * \see setPosition()
         */
        QPointF position() const;

        /**
         * Sets the \a position of the model component within the graphical modeler.
         * \see position()
         */
        void setPosition( const QPointF &position );

      protected:

        //! Only subclasses can be created
        Component( const QString &description = QString() );

        //! Copies are protected to avoid slicing
        Component( const QgsProcessingModelAlgorithm::Component &other ) = default;

        //! Copies are protected to avoid slicing
        Component &operator=( const QgsProcessingModelAlgorithm::Component &other ) = default;

        /**
         * Saves the component properties to a QVariantMap.
         * \see restoreCommonProperties()
         */
        void saveCommonProperties( QVariantMap &map ) const;

        /**
         * Restores the component properties from a QVariantMap.
         * \see saveCommonProperties()
         */
        void restoreCommonProperties( const QVariantMap &map );

      private:

        //! Position of component within model
        QPointF mPosition;

        QString mDescription;

    };

    /**
     * Represents an input parameter used by the model.
     * \since QGIS 3.0
     * \ingroup core
     */
    class CORE_EXPORT ModelParameter : public QgsProcessingModelAlgorithm::Component
    {
      public:

        /**
         * Constructor for ModelParameter. The parameter name should match one of the
         * parameters from the parent model.
         */
        ModelParameter( const QString &parameterName = QString() );

        /**
         * Returns the associated parameter name. The parameter name should match one of the
         * parameters from the parent model.
         * \see parameterName()
         */
        QString parameterName() const { return mParameterName; }

        /**
         * Sets the associated parameter name. The parameter name should match one of the
         * parameters from the parent model.
         * \see parameterName()
         */
        void setParameterName( const QString &name ) { mParameterName = name; }

        /**
         * Saves this parameter to a QVariant.
         * \see loadVariant()
         */
        QVariant toVariant() const;

        /**
         * Loads this parameter from a QVariantMap.
         * \see toVariant()
         */
        bool loadVariant( const QVariantMap &map );

      private:

        QString mParameterName;

    };


    /**
     * Represents a final output created by the model.
     * \since QGIS 3.0
     * \ingroup core
     */
    class CORE_EXPORT ModelOutput : public QgsProcessingModelAlgorithm::Component
    {
      public:

        /**
         * Constructor for ModelOutput with the specified \a name and \a description.
         */
        ModelOutput( const QString &name = QString(), const QString &description = QString() );

        /**
         * Returns the model output name.
         * \see setName()
         */
        QString name() const { return mName; }

        /**
         * Sets the model output \a name.
         * \see name()
         */
        void setName( const QString &name ) { mName = name; }

        /**
         * Returns the child algorithm ID from which this output is generated.
         * \see setChildId()
         */
        QString childId() const { return mChildId; }

        /**
         * Sets the child algorithm \a id from which this output is generated.
         * \see childId()
         */
        void setChildId( const QString &id ) { mChildId = id; }

        /**
         * Returns the child algorithm output name from which this output is generated.
         * \see setOutputName()
         */
        QString childOutputName() const { return mOutputName; }

        /**
         * Sets the child algorithm output \a name from which this output is generated.
         * \see outputName()
         */
        void setChildOutputName( const QString &name ) { mOutputName = name; }

        /**
         * Saves this output to a QVariant.
         * \see loadVariant()
         */
        QVariant toVariant() const;

        /**
         * Loads this output from a QVariantMap.
         * \see toVariant()
         */
        bool loadVariant( const QVariantMap &map );

      private:

        QString mName;
        QString mChildId;
        QString mOutputName;
    };

    /**
     * Child algorithm representing a single component of a QgsProcessingModelAlgorithm.
     * \since QGIS 3.0
     * \ingroup core
     */
    class CORE_EXPORT ChildAlgorithm : public QgsProcessingModelAlgorithm::Component
    {
      public:

        /**
         * Constructor for ChildAlgorithm. The \a algorithmId parameter
         * should be set to a QgsProcessingAlgorithm algorithm ID.
         */
        ChildAlgorithm( const QString &algorithmId = QString() );

        /**
         * Returns the child algorithm's unique ID string, used the identify
         * this child algorithm within its parent model.
         * \see setChildId()
         * \see generateChildId()
         */
        QString childId() const;

        /**
         * Sets the child algorithm's unique \a id string, used the identify
         * this child algorithm within its parent model.
         * \see childId()
         * \see generateChildId()
         */
        void setChildId( const QString &id );

        /**
         * Automatically generates a unique childId() for the algorithm,
         * avoiding child IDs which are already present in \a model.
         * \see childId()
         * \see setChildId()
         */
        void generateChildId( const QgsProcessingModelAlgorithm &model );

        /**
         * Returns the underlying child algorithm's ID.
         * \see algorithm()
         * \see setAlgorithmId()
         */
        QString algorithmId() const;

        /**
         * Sets the underlying child algorithm's ID. This
         * should be set to an existing QgsProcessingAlgorithm algorithm ID.
         * \see algorithm()
         * \see algorithmId()
         */
        void setAlgorithmId( const QString &algorithmId );

        /**
         * Returns the underlying child algorithm, or a nullptr
         * if a matching algorithm is not available.
         * \see algorithmId()
         */
        const QgsProcessingAlgorithm *algorithm() const;

        /**
         * Returns a map of parameter sources. The keys are the child algorithm
         * parameter names, the values are the source for that parameter.
         * \see setParameterSources()
         * \see addParameterSource()
         */
        QMap< QString, QgsProcessingModelAlgorithm::ChildParameterSource > parameterSources() const;

        /**
         * Sets the map of parameter \a sources. The keys are the child algorithm
         * parameter names, the values are the source for that parameter.
         * \see parameterSources()
         * \see addParameterSource()
         */
        void setParameterSources( const QMap< QString, QgsProcessingModelAlgorithm::ChildParameterSource > &sources );

        /**
         * Adds a parameter source. The \a name argument should match
         * one of the child algorithm's parameter names, and the \a source
         * argument is used to set the source for that parameter.
         *
         * Any existing parameter source with matching name will be replaced.
         * \see parameterSources()
         * \see setParameterSources()
         */
        void addParameterSource( const QString &name, const QgsProcessingModelAlgorithm::ChildParameterSource &source );

        /**
         * Returns true if the child algorithm is active.
         * \see setActive()
         */
        bool isActive() const;

        /**
         * Sets whether the child algorithm is active.
         * \see isActive()
         */
        void setActive( bool active );

        /**
         * Returns the list of child algorithms from the parent model on which this
         * algorithm is dependent. The returned list contains the id() of the
         * dependent algorithms.
         * \see setDependencies()
         */
        QStringList dependencies() const;

        /**
         * Sets the list of child algorithms from the parent model on which this
         * algorithm is dependent. The list should contain the id() of the
         * dependent algorithms.
         * \see dependencies()
         */
        void setDependencies( const QStringList &dependencies );

        /**
         * Returns true if the list of parameters for this algorithm should be collapsed
         * in the graphical modeller.
         * \see setParametersCollapsed()
         * \see outputsCollapsed()
         */
        bool parametersCollapsed() const;

        /**
         * Sets whether the list of parameters for this algorithm should be collapsed
         * in the graphical modeller.
         * \see parametersCollapsed()
         * \see setOutputsCollapsed()
         */
        void setParametersCollapsed( bool collapsed );

        /**
         * Returns true if the list of outputs for this algorithm should be collapsed
         * in the graphical modeller.
         * \see setParametersCollapsed()
         * \see parametersCollapsed()
         */
        bool outputsCollapsed() const;

        /**
         * Sets whether the list of outputs for this algorithm should be collapsed
         * in the graphical modeller.
         * \see outputsCollapsed()
         * \see setParametersCollapsed()
         */
        void setOutputsCollapsed( bool collapsed );

        /**
         * Returns the map of final model outputs which are generated by this child algorithm.
         * The keys are the output names from this child algorithm. Only outputs which are
         * part of the final outputs from the model are included in this map.
         * \see setModelOutputs()
         * \see modelOutput()
         */
        QMap<QString, QgsProcessingModelAlgorithm::ModelOutput> modelOutputs() const;

        /**
         * Returns the final model output with matching \a name. If no output
         * exists with the name, a new one will be created and returned.
         *
         * If child model outputs are altered by this method, QgsProcessingModelAlgorithm::updateDestinationParameters()
         * must be called on the parent model.
         *
         * \see modelOutputs()
         * \see setModelOutputs()
         */
        QgsProcessingModelAlgorithm::ModelOutput &modelOutput( const QString &name );

        /**
         * Sets the map of final model \a outputs which are generated by this child algorithm.
         * Only outputs which are part of the final outputs from the model should be included in this map.
         *
         * If child model outputs are altered by this method, QgsProcessingModelAlgorithm::updateDestinationParameters()
         * must be called on the parent model.
         *
         * \see modelOutputs()
         */
        void setModelOutputs( const QMap<QString, QgsProcessingModelAlgorithm::ModelOutput> &outputs );

        /**
         * Saves this child to a QVariant.
         * \see loadVariant()
         */
        QVariant toVariant() const;

        /**
         * Loads this child from a QVariant.
         * \see toVariant()
         */
        bool loadVariant( const QVariant &child );

        /**
         * Attempts to convert the child to executable Python code.
         */
        QString asPythonCode() const;

      private:

        QString mId;

        QString mAlgorithmId;

        //! A map of parameter sources. Keys are algorithm parameter names.
        QMap< QString, QgsProcessingModelAlgorithm::ChildParameterSource > mParams;

        //! A map of ModelOutput for final model outputs generated by this child algorithm. Keys are output names from the child algorithm.
        QMap< QString, QgsProcessingModelAlgorithm::ModelOutput > mModelOutputs;

        bool mActive = true;

        //! List of child algorithms from the parent model on which this algorithm is dependent
        QStringList mDependencies;

        //! Whether list of parameters should be collapsed in the graphical modeller
        bool mParametersCollapsed = true;
        //! Whether list of outputs should be collapsed in the graphical modeller
        bool mOutputsCollapsed = true;
    };

    /**
     * Constructor for QgsProcessingModelAlgorithm.
     */
    QgsProcessingModelAlgorithm( const QString &name = QString(), const QString &group = QString() );

    QString name() const override;
    QString displayName() const override;
    QString group() const override;
    QIcon icon() const override;
    QString svgIconPath() const override;
    QString shortHelpString() const override;
    QString helpUrl() const override;

    bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const override;
    QString asPythonCommand( const QVariantMap &parameters, QgsProcessingContext &context ) const override;

    /**
     * Sets the model \a name.
     * \see name()
     */
    void setName( const QString &name );

    /**
     * Sets the model \a group.
     * \see group()
     */
    void setGroup( const QString &group );

    /**
     * Returns the map of child algorithms contained in the model. The keys
     * are the child algorithm ids (see QgsProcessingModelAlgorithm::ChildAlgorithm::childId()).
     * \see childAlgorithm()
     * \see setChildAlgorithms()
     * \see addChildAlgorithm()
     */
    QMap<QString, QgsProcessingModelAlgorithm::ChildAlgorithm> childAlgorithms() const;

    /**
     * Sets the map of child algorithms contained in the model. The keys
     * are the child algorithm ids (see QgsProcessingModelAlgorithm::ChildAlgorithm::childId()).
     * All existing child algorithms will be replaced.
     * \see childAlgorithms()
     * \see childAlgorithm()
     * \see setChildAlgorithm()
     * \see addChildAlgorithm()
     */
    void setChildAlgorithms( const QMap<QString, QgsProcessingModelAlgorithm::ChildAlgorithm> &childAlgorithms );

    /**
     * Sets the child \a algorithm within the model. If a child algorithm already
     * exists in the model with the same child ID then that algorithm will be replaced.
     * \see addChildAlgorithm()
     * \see setChildAlgorithms()
     */
    void setChildAlgorithm( const QgsProcessingModelAlgorithm::ChildAlgorithm &algorithm );

    /**
     * Adds a new child \a algorithm to the model. If a child algorithm already exists
     * in the model with the same child ID then \a algorithm will be assigned a new
     * autogenerated unique ID.
     * The assigned child ID will be returned.
     * \see childAlgorithms()
     * \see childAlgorithm()
     * \see setChildAlgorithm()
     * \see setChildAlgorithms()
     */
    QString addChildAlgorithm( QgsProcessingModelAlgorithm::ChildAlgorithm &algorithm );

    /**
     * Returns the child algorithm with matching \a id. If no child algorithm exists with
     * this ID a new algorithm will be added to the model and returned.
     * \see addChildAlgorithm()
     * \see childAlgorithms()
     */
    QgsProcessingModelAlgorithm::ChildAlgorithm &childAlgorithm( const QString &id );

    /**
     * Attempts to remove the child algorithm with matching \a id.
     * Returns true if the algorithm could be removed, or false
     * if the algorithm could not be removed (e.g. due to other
     * child algorithms depending on it).
     * \see deactivateChildAlgorithm()
     */
    bool removeChildAlgorithm( const QString &id );

    /**
     * Deactivates the child algorithm with matching \a id.
     * All other child algorithms which depend on the child
     * algorithm will also be deactivated.
     * \see removeChildAlgorithm()
     * \see activateChildAlgorithm()
     */
    void deactivateChildAlgorithm( const QString &id );

    /**
     * Attempts to activate the child algorithm with matching \a id.
     * If any child algorithms on which the child depends are not active,
     * then the child will not be activated and false will be returned.
     * \see deactivateChildAlgorithm()
     */
    bool activateChildAlgorithm( const QString &id );

    /**
     * Returns a list of the child algorithm IDs depending on the child
     * algorithm with the specified \a childId.
     * \see dependsOnChildAlgorithms()
     */
    QSet< QString > dependentChildAlgorithms( const QString &childId ) const;

    /**
     * Returns a list of the child algorithm IDs on which the child
     * algorithm with the specified \a childId depends upon.
     * \see dependentChildAlgorithms()
     */
    QSet< QString > dependsOnChildAlgorithms( const QString &childId ) const;

    /**
     * Adds a new parameter to the model, with the specified \a definition and graphical \a component.
     * Ownership of \a definition is transferred to the model.
     * \see updateModelParameter()
     * \see removeModelParameter()
     */
    void addModelParameter( QgsProcessingParameterDefinition *definition SIP_TRANSFER, const QgsProcessingModelAlgorithm::ModelParameter &component );

    /**
     * Replaces the definition of an existing parameter (by parameter name) with a new \a definition. Ownership of
     * \a definition is transferred to the model, and any existing parameter is deleted.
     * \see addModelParameter()
     * \see removeModelParameter()
     */
    void updateModelParameter( QgsProcessingParameterDefinition *definition SIP_TRANSFER );

    /**
     * Removes an existing model parameter by \a name. The definition of the matching parameter
     * is deleted.
     * \see addModelParameter()
     * \see updateModelParameter()
     */
    void removeModelParameter( const QString &name );

    /**
     * Returns true if any child algorithms depend on the model parameter
     * with the specified \a name.
     */
    bool childAlgorithmsDependOnParameter( const QString &name ) const;

    /**
     * Returns the map of parameter components used by the model. The keys
     * should match the algorithm's parameter names (see parameterDefinitions() ).
     * \see setParameterComponent()
     * \see parameterComponent()
     */
    QMap<QString, QgsProcessingModelAlgorithm::ModelParameter> parameterComponents() const;

    /**
     * Sets the map of parameter components used by the model. The keys
     * should match the algorithm's parameter names (see parameterDefinitions() ).
     * All existing parameter components will be replaced.
     * \see parameterComponents()
     * \see setParameterComponent()
     * \see parameterComponent()
     */
    void setParameterComponents( const QMap<QString, QgsProcessingModelAlgorithm::ModelParameter> &parameterComponents );

    /**
     * Sets a parameter \a component for the model. If a parameter component already
     * exists in the model with the same parameter name then that component will be replaced.
     * \see parameterComponents()
     * \see setParameterComponents()
     * \see parameterComponent()
     */
    void setParameterComponent( const QgsProcessingModelAlgorithm::ModelParameter &component );

    /**
     * Returns the parameter component with matching \a name. If no parameter component exists with
     * this name a new component will be added to the model and returned.
     * \see parameterComponents()
     * \see setParameterComponents()
     * \see setParameterComponent()
     */
    QgsProcessingModelAlgorithm::ModelParameter &parameterComponent( const QString &name );

    /**
     * Updates the model's parameter definitions to include all relevant destination
     * parameters as required by child algorithm ModelOutputs.
     * Must be called whenever child algorithm ModelOutputs are altered.
     */
    void updateDestinationParameters();

    /**
     * Writes the model to a file, at the specified \a path.
     * \see fromFile()
     */
    bool toFile( const QString &path ) const;

    /**
     * Reads the model from a file, at the specified \a path.
     * \see toFile()
     */
    bool fromFile( const QString &path );

    /**
     * Returns the model's help contents (a free-form map of values describing the algorithm's
     * use and metadata).
     * \see setHelpContent()
     */
    QVariantMap &helpContent() { return mHelpContent; }

    /**
     * Returns the model's help contents (a free-form map of values describing the algorithm's
     * use and metadata).
     * \see setHelpContent()
     */
    SIP_SKIP QVariantMap helpContent() const;

    /**
     * Sets the model's help \a contents (a free-form map of values describing the algorithm's
     * use and metadata).
     * \see helpContent()
     */
    void setHelpContent( const QVariantMap &contents );

    /**
     * Returns the source file path for the model, if available.
     * \see setSourceFilePath()
     */
    QString sourceFilePath() const;

    /**
     * Sets the source file \a path for the model, if available.
     * \see sourceFilePath()
     */
    void setSourceFilePath( const QString &path );

    /**
     * Attempts to convert the model to executable Python code.
     */
    QString asPythonCode() const;

  protected:

    QVariantMap processAlgorithm( const QVariantMap &parameters,
                                  QgsProcessingContext &context, QgsProcessingFeedback *feedback ) const override;

  private:

    QString mModelName;
    QString mModelGroup;

    QMap< QString, ChildAlgorithm > mChildAlgorithms;

    //! Map of parameter name to model parameter component
    QMap< QString, ModelParameter > mParameterComponents;

    QVariantMap mHelpContent;

    //! Model source file
    QString mSourceFile;

    void dependsOnChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends ) const;
    void dependentChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends ) const;

    QVariantMap parametersForChildAlgorithm( const ChildAlgorithm &child, const QVariantMap &modelParameters, const QMap<QString, QVariantMap> &results ) const;

    /**
     * Returns true if an output from a child algorithm is required elsewhere in
     * the model.
     */
    bool childOutputIsRequired( const QString &childId, const QString &outputName ) const;

    /**
     * Saves this model to a QVariantMap, wrapped in a QVariant.
     * You can use QgsXmlUtils::writeVariant to save it to an XML document.
     *
     * \see loadVariant()
     */
    QVariant toVariant() const;

    /**
     * Loads this model from a QVariantMap, wrapped in a QVariant.
     * You can use QgsXmlUtils::readVariant to load it from an XML document.
     *
     * \see toVariant()
     */
    bool loadVariant( const QVariant &model );

    friend class TestQgsProcessing;
};

///@endcond

#endif // QGSPROCESSINGMODELALGORITHM_H