26.9. 新たなプロセシングアルゴリズムをPythonスクリプトで作成する

Pythonを使ってプロセシングアルゴリズムを書くためには、ふたつの選択肢があります。

• QgsProcessingAlgorithm クラスを 拡張する

• @alg デコレータを使う

QGIS内では、 プロセシングツールボックス の上部にある スクリプト メニューの 新しいスクリプトを作成 を使用して、自分のコードを書ける プロセシングスクリプトエディタ を開いて作成できます。タスクを簡素化するには、同じメニューの テンプレートから新しいスクリプトを作成する を使用して、スクリプトテンプレートから開始できます。これにより QgsProcessingAlgorithm を拡張するテンプレートが開きます。

スクリプトを scripts フォルダ(デフォルトの場所) に .py という拡張子で保存するとそのアルゴリズムは プロセシングツールボックス で利用できるようになります。

26.9.1. QgsProcessingAlgorithmを拡張する

以下のコードの内容です

1. ベクタレイヤを入力に指定します

2. 地物の数を数えます

3. バッファの操作を行います

4. バッファ操作の結果を使ってラスタレイヤを作ります

5. バッファレイヤ,ラスタレイヤと地物の数を返します

from qgis.PyQt.QtCore import QCoreApplication
from qgis.core import (QgsProcessing,
                       QgsProcessingAlgorithm,
                       QgsProcessingException,
                       QgsProcessingOutputNumber,
                       QgsProcessingParameterDistance,
                       QgsProcessingParameterFeatureSource,
                       QgsProcessingParameterVectorDestination,
                       QgsProcessingParameterRasterDestination)
from qgis import processing


class ExampleProcessingAlgorithm(QgsProcessingAlgorithm):
    """
    This is an example algorithm that takes a vector layer,
    creates some new layers and returns some results.
    """

    def tr(self, string):
        """
        Returns a translatable string with the self.tr() function.
        """
        return QCoreApplication.translate('Processing', string)

    def createInstance(self):
        # Must return a new copy of your algorithm.
        return ExampleProcessingAlgorithm()

    def name(self):
        """
        Returns the unique algorithm name.
        """
        return 'bufferrasterextend'

    def displayName(self):
        """
        Returns the translated algorithm name.
        """
        return self.tr('Buffer and export to raster (extend)')

    def group(self):
        """
        Returns the name of the group this algorithm belongs to.
        """
        return self.tr('Example scripts')

    def groupId(self):
        """
        Returns the unique ID of the group this algorithm belongs
        to.
        """
        return 'examplescripts'

    def shortHelpString(self):
        """
        Returns a localised short help string for the algorithm.
        """
        return self.tr('Example algorithm short description')

    def initAlgorithm(self, config=None):
        """
        Here we define the inputs and outputs of the algorithm.
        """
        # 'INPUT' is the recommended name for the main input
        # parameter.
        self.addParameter(
            QgsProcessingParameterFeatureSource(
                'INPUT',
                self.tr('Input vector layer'),
                types=[QgsProcessing.TypeVectorAnyGeometry]
            )
        )
        self.addParameter(
            QgsProcessingParameterVectorDestination(
                'BUFFER_OUTPUT',
                self.tr('Buffer output'),
            )
        )
        # 'OUTPUT' is the recommended name for the main output
        # parameter.
        self.addParameter(
            QgsProcessingParameterRasterDestination(
                'OUTPUT',
                self.tr('Raster output')
            )
        )
        self.addParameter(
            QgsProcessingParameterDistance(
                'BUFFERDIST',
                self.tr('BUFFERDIST'),
                defaultValue = 1.0,
                # Make distance units match the INPUT layer units:
                parentParameterName='INPUT'
            )
        )
        self.addParameter(
            QgsProcessingParameterDistance(
                'CELLSIZE',
                self.tr('CELLSIZE'),
                defaultValue = 10.0,
                parentParameterName='INPUT'
            )
        )
        self.addOutput(
            QgsProcessingOutputNumber(
                'NUMBEROFFEATURES',
                self.tr('Number of features processed')
            )
        )

    def processAlgorithm(self, parameters, context, feedback):
        """
        Here is where the processing itself takes place.
        """
        # First, we get the count of features from the INPUT layer.
        # This layer is defined as a QgsProcessingParameterFeatureSource
        # parameter, so it is retrieved by calling
        # self.parameterAsSource.
        input_featuresource = self.parameterAsSource(parameters,
                                                     'INPUT',
                                                     context)
        numfeatures = input_featuresource.featureCount()

        # Retrieve the buffer distance and raster cell size numeric
        # values. Since these are numeric values, they are retrieved
        # using self.parameterAsDouble.
        bufferdist = self.parameterAsDouble(parameters, 'BUFFERDIST',
                                            context)
        rastercellsize = self.parameterAsDouble(parameters, 'CELLSIZE',
                                                context)
        if feedback.isCanceled():
            return {}
        buffer_result = processing.run(
            'native:buffer',
            {
                # Here we pass on the original parameter values of INPUT
                # and BUFFER_OUTPUT to the buffer algorithm.
                'INPUT': parameters['INPUT'],
                'OUTPUT': parameters['BUFFER_OUTPUT'],
                'DISTANCE': bufferdist,
                'SEGMENTS': 10,
                'DISSOLVE': True,
                'END_CAP_STYLE': 0,
                'JOIN_STYLE': 0,
                'MITER_LIMIT': 10
            },
            # Because the buffer algorithm is being run as a step in
            # another larger algorithm, the is_child_algorithm option
            # should be set to True
            is_child_algorithm=True,
            #
            # It's important to pass on the context and feedback objects to
            # child algorithms, so that they can properly give feedback to
            # users and handle cancelation requests.
            context=context,
            feedback=feedback)

        # Check for cancelation
        if feedback.isCanceled():
            return {}

        # Run the separate rasterization algorithm using the buffer result
        # as an input.
        rasterized_result = processing.run(
            'qgis:rasterize',
            {
                # Here we pass the 'OUTPUT' value from the buffer's result
                # dictionary off to the rasterize child algorithm.
                'LAYER': buffer_result['OUTPUT'],
                'EXTENT': buffer_result['OUTPUT'],
                'MAP_UNITS_PER_PIXEL': rastercellsize,
                # Use the original parameter value.
                'OUTPUT': parameters['OUTPUT']
            },
            is_child_algorithm=True,
            context=context,
            feedback=feedback)

        if feedback.isCanceled():
            return {}

        # Return the results
        return {'OUTPUT': rasterized_result['OUTPUT'],
                'BUFFER_OUTPUT': buffer_result['OUTPUT'],
                'NUMBEROFFEATURES': numfeatures}

プロセシングアルゴリズムの標準関数:

• createInstance (必須)

  自作のアルゴリズムの新しいコピーを返さなければいけません。クラスの名前を変更する場合はここで返す値も必ず一致するように更新して下さい!

• name (必須)

  アルゴリズムの識別に使う、ユニークなアルゴリズムの名前を返します。

• displayName (必須)

  変換されたアルゴリズム名を返します.

• group

  このアルゴリズムが所属しているグループ名を返します.

• groupId

  このアルゴリズムが所属しているグループのユニークIDを返します.

• shortHelpString

  このアルゴリズムの翻訳された短縮ヘルプ文字列を返します.

• initAlgorithm (必須)

  ここでアルゴリズムの入力と出力を定義します.

  INPUT と OUTPUT はそれぞれメインの入力と出力パラメータ用の推奨名称です.

  もしパラメータが他のパラメータに依存する場合, parentParameterName がこの関係を示します (フィールド/レイヤのバンドまたはレイヤの距離単位は利用できません).

• processAlgorithm (必須)

  ここで処理が実行されます.

  パラメータはインスタンスによって parameterAsSource や parameterAsDouble のような特別な用途の関数を使って取得されます.

  processing.run を使うとプロセシングアルゴリズムから他のアルゴリズムを実行できます。最初のパラメータはアルゴリズムの名前です。２つめのパラメータはそのアルゴリズム用のパラメータの辞書です。他のアルゴリズム内で実行される場合 is_child_algorithm は通常 True に設定します。context と feedback は実行環境とユーザとのやりとりのチャンネルをアルゴリズムに伝えます（キャンセルリクエストのキャッチ、実行状況のレポート、テキストによるフィードバックの提供）。 (親) アルゴリズムのパラメータが "子" アルゴリズムのパラメータとして利用される場合、オリジナルの値を利用する必要があります(例. parameters['OUTPUT'])。

  可能な限りキャンセルのためにフィードバックオブジェクトをチェックすることをお勧めします！そうすることで、不要な処理が発生するまでユーザーを待たせずに、すぐにキャンセルすることが可能になります。

  アルゴリズムは、辞書として定義したすべての出力パラメータの値を返す必要があります。この場合、それはバッファとラスタライズされた出力レイヤ、および処理された地物数です。辞書キーは、元のパラメータ/出力名と一致する必要があります。

26.9.2. @alg デコレータ

@algデコレータを使用すると、独自のアルゴリズムを作ることができます。Pythonコードを書き、それを適切なプロセシングアルゴリズムにする追加情報を提供する数行を加えます。この手法はアルゴリズムの作成、および入力と出力の指定を簡単にします。

アルゴリズム作成にデコレータを使う手法には一つの重要な制約があります．それは作成されたアルゴリズムが常にユーザープロセシングスクリプトプロバイダに追加されることです -- アルゴリズムをカスタムプロバイダに追加して、例えばプラグイン内で使うことはできません．

以下のコードは @alg デコレータを使って次の機能を実装してます

1. ベクタレイヤを入力として利用します

2. 地物の数を数えます

3. バッファ操作を実行します

4. バッファ操作の結果を使ってラスタレイヤを作ります

5. バッファレイヤ,ラスタレイヤと地物の数を返します

from qgis import processing
from qgis.processing import alg
from qgis.core import QgsProject

@alg(name='bufferrasteralg', label='Buffer and export to raster (alg)',
     group='examplescripts', group_label='Example scripts')
# 'INPUT' is the recommended name for the main input parameter
@alg.input(type=alg.SOURCE, name='INPUT', label='Input vector layer')
# 'OUTPUT' is the recommended name for the main output parameter
@alg.input(type=alg.RASTER_LAYER_DEST, name='OUTPUT',
           label='Raster output')
@alg.input(type=alg.VECTOR_LAYER_DEST, name='BUFFER_OUTPUT',
           label='Buffer output')
@alg.input(type=alg.DISTANCE, name='BUFFERDIST', label='BUFFER DISTANCE',
           default=1.0)
@alg.input(type=alg.DISTANCE, name='CELLSIZE', label='RASTER CELL SIZE',
           default=10.0)
@alg.output(type=alg.NUMBER, name='NUMBEROFFEATURES',
            label='Number of features processed')

def bufferrasteralg(instance, parameters, context, feedback, inputs):
    """
    Description of the algorithm.
    (If there is no comment here, you will get an error)
    """
    input_featuresource = instance.parameterAsSource(parameters,
                                                     'INPUT', context)
    numfeatures = input_featuresource.featureCount()
    bufferdist = instance.parameterAsDouble(parameters, 'BUFFERDIST',
                                            context)
    rastercellsize = instance.parameterAsDouble(parameters, 'CELLSIZE',
                                                context)
    if feedback.isCanceled():
        return {}
    buffer_result = processing.run('native:buffer',
                               {'INPUT': parameters['INPUT'],
                                'OUTPUT': parameters['BUFFER_OUTPUT'],
                                'DISTANCE': bufferdist,
                                'SEGMENTS': 10,
                                'DISSOLVE': True,
                                'END_CAP_STYLE': 0,
                                'JOIN_STYLE': 0,
                                'MITER_LIMIT': 10
                                },
                               is_child_algorithm=True,
                               context=context,
                               feedback=feedback)
    if feedback.isCanceled():
        return {}
    rasterized_result = processing.run('qgis:rasterize',
                               {'LAYER': buffer_result['OUTPUT'],
                                'EXTENT': buffer_result['OUTPUT'],
                                'MAP_UNITS_PER_PIXEL': rastercellsize,
                                'OUTPUT': parameters['OUTPUT']
                               },
                               is_child_algorithm=True, context=context,
                               feedback=feedback)
    if feedback.isCanceled():
        return {}
    return {'OUTPUT': rasterized_result['OUTPUT'],
            'BUFFER_OUTPUT': buffer_result['OUTPUT'],
            'NUMBEROFFEATURES': numfeatures}

ご覧の通りこのコードには２つのアルゴリズム('native:buffer' と 'qgis:rasterize')が含まれています. 後の物 ('qgis:rasterize') は最初のもの ('native:buffer') が作成したバッファレイヤを利用してラスタレイヤを作成します.

この処理が行われるコードの部分は、前の章を読んでいれば理解するのは難しくありません。しかし、最初の行には補足説明が必要です。それらは、あなたのコードをツールボックスやモデルデザイナーなどのGUIコンポーネントから実行できるアルゴリズムにするために必要な情報を提供します。

これらの行は @alg デコレータ関数を呼び出しています。その結果アルゴリズムを簡単にコーディングできます。

• @alg デコレータはツールボックス内でのアルゴリズムの名前と場所を定義するのに利用されます。

• @alg.input デコレータはアルゴリズムの入力を定義するのに使われます。

• @alg.output デコレータはアルゴリズムの出力を定義するのに使われます。

26.9.3. プロセシングアルゴリズムのための入力と出力の型

対応するalgデコレータ定数を使用してProcessingでサポートされる入力タイプと出力タイプのリストを次に示します（ algfactory.py ファイルにはalg定数の完全なリストが含まれています）。クラス名でソートされています。

26.9.3.1. 入力タイプ

クラス	Alg定数	説明
QgsProcessingParameterAnnotationLayer	alg.ANNOTATION_LAYER	注記レイヤ
QgsProcessingParameterAuthConfig	alg.AUTH_CFG	ユーザに利用可能な認証構成を選択させるか新しい認証構成を作成させます
QgsProcessingParameterBand	alg.BAND	ラスタレイヤのバンド
QgsProcessingParameterBoolean	alg.BOOL	ブール値
QgsProcessingParameterColor	alg.COLOR	色
QgsProcessingParameterCoordinateOperation	alg.COORDINATE_OPERATION	座標操作（CRS変換）
QgsProcessingParameterCrs	alg.CRS	座標参照系
QgsProcessingParameterDatabaseSchema	alg.DATABASE_SCHEMA	データベーススキーマ
QgsProcessingParameterDatabaseTable	alg.DATABASE_TABLE	データベーステーブル
QgsProcessingParameterDateTime	alg.DATETIME	日付時刻（または日付または時刻）
QgsProcessingParameterDistance	alg.DISTANCE	距離の値用の倍精度数値パラメータ
QgsProcessingParameterEnum	alg.ENUM	事前定義された複数の値からの選択を許す列挙
QgsProcessingParameterExpression	alg.EXPRESSION	式
QgsProcessingParameterExtent	alg.EXTENT	xmin, xmax, ymin, ymaxで定義された空間領域
QgsProcessingParameterField	alg.FIELD	ベクタレイヤの属性テーブルのフィールド
QgsProcessingParameterFile	alg.FILE	既存ファイルのファイル名
QgsProcessingParameterFileDestination	alg.FILE_DEST	新たに作成された出力ファイルのファイル名
QgsProcessingParameterFolderDestination	alg.FOLDER_DEST	フォルダー（保存先フォルダー）
QgsProcessingParameterGeometry	alg.GEOMETRY	ジオメトリ
QgsProcessingParameterNumber	alg.INT	整数
QgsProcessingParameterLayout	alg.LAYOUT	レイアウト
QgsProcessingParameterLayoutItem	alg.LAYOUT_ITEM	レイアウトアイテム
QgsProcessingParameterMapLayer	alg.MAPLAYER	マップレイヤ
QgsProcessingParameterMapTheme	alg.MAP_THEME	プロジェクトマップテーマ
QgsProcessingParameterMatrix	alg.MATRIX	配列
QgsProcessingParameterMeshLayer	alg.MESH_LAYER	メッシュレイヤ
QgsProcessingParameterMultipleLayers	alg.MULTILAYER	レイヤのセット
QgsProcessingParameterNumber	alg.NUMBER	数値
QgsProcessingParameterPoint	alg.POINT	点
QgsProcessingParameterPointCloudDestination	alg.POINTCLOUD_LAYER_DEST	アルゴリズムによって作成される点群レイヤの保存先パスを指定する、点群レイヤ保存先パラメータ
QgsProcessingParameterPointCloudLayer	alg.POINTCLOUD_LAYER	点群レイヤ
QgsProcessingParameterProviderConnection	alg.PROVIDER_CONNECTION	データベースプロバイダの利用可能な接続
QgsProcessingParameterRange	alg.RANGE	数値の範囲
QgsProcessingParameterRasterLayer	alg.RASTER_LAYER	ラスタレイヤ
QgsProcessingParameterRasterDestination	alg.RASTER_LAYER_DEST	ラスタレイヤの保存先パラメータ、アルゴリズムが作成したラスタレイヤの保存先パスを指定するためのパラメータ
QgsProcessingParameterScale	alg.SCALE	地図の縮尺
QgsProcessingParameterFeatureSink	alg.SINK	地物シンク
QgsProcessingParameterFeatureSource	alg.SOURCE	地物ソース
QgsProcessingParameterString	alg.STRING	テキストストリング
QgsProcessingParameterVectorLayer	alg.VECTOR_LAYER	ベクターレイヤー
QgsProcessingParameterVectorDestination	alg.VECTOR_LAYER_DEST	アルゴリズムで作成されたベクタレイヤの保存先パスを指定するためのベクタレイヤの保存先パラメータ

26.9.3.2. 出力タイプ

クラス	Alg定数	説明
QgsProcessingOutputBoolean	alg.BOOL	ブール値
QgsProcessingOutputNumber	alg.DISTANCE	距離の値用の倍精度数値パラメータ
QgsProcessingOutputFile	alg.FILE	既存ファイルのファイル名
QgsProcessingOutputFolder	alg.FOLDER	フォルダ
QgsProcessingOutputHtml	alg.HTML	HTML
QgsProcessingOutputNumber	alg.INT	整数
QgsProcessingOutputLayerDefinition	alg.LAYERDEF	レイヤ定義
QgsProcessingOutputMapLayer	alg.MAPLAYER	マップレイヤ
QgsProcessingOutputMultipleLayers	alg.MULTILAYER	レイヤのセット
QgsProcessingOutputNumber	alg.NUMBER	数値
QgsProcessingOutputPointCloudLayer	alg.POINTCLOUD_LAYER	点群レイヤ
QgsProcessingOutputRasterLayer	alg.RASTER_LAYER	ラスタレイヤ
QgsProcessingOutputString	alg.STRING	テキストストリング
QgsProcessingOutputVectorLayer	alg.VECTOR_LAYER	ベクターレイヤー

26.9.4. アルゴリズムの出力を渡す

出力としてレイヤ（ラスタまたはベクタ）を指定すると、アルゴリズムは終了後にそれをQGISに追加しようとします。

• ラスタレイヤ出力: QgsProcessingParameterRasterDestination / alg.RASTER_LAYER_DEST.

• ベクタレイヤ出力: QgsProcessingParameterVectorDestination / alg.VECTOR_LAYER_DEST.

したがって processing.run() メソッドが作成したレイヤをユーザの現在のプロジェクトに加えない場合でも、２つの出力レイヤ (バッファとラスタバッファ)が読み込まれます．これらはユーザが入力した保存先 (またはユーザが保存先を指定しない場合は一時的な保存先)に保存されるからです.

レイヤがアルゴリズムの出力として作成される場合、そのように宣言する必要があります。そうしないと、宣言されたものがアルゴリズムが実際に作成するものと一致しないため、モデラーでアルゴリズムを適切に使用できません。

結果の辞書で文字列、数値などを指定することで返すことができます（「NUMBEROFFEATURES」で示したとおり）が、それらは常にアルゴリズムからの出力として明示的に定義する必要があります。アルゴリズムがモデルの一部として使用される場合、これらのアルゴリズムは後のアルゴリズムで使用するのに役立つ可能性があるため、アルゴリズムではできるだけ多くの有用な値を出力することをを推奨します。

26.9.5. ユーザーとやりとりする

あなたのアルゴリズムが処理に長い時間を必要とする場合、ユーザに進捗状況を知らせるのは良い考えです. feedback (QgsProcessingFeedback) を利用するとそれを実現できます.

処理状況テキストとプログレスバーは２つのメソッドを使って更新できます: setProgressText(text) と setProgress(percent) です.

次のメソッドを使うとさらに多くの情報を提供できます pushCommandInfo(text), pushDebugInfo(text), pushInfo(text) と reportError(text).

スクリプトに問題がある場合、それを処理する正しい方法は QgsProcessingException を発生させることです。メッセージを引数として例外のコンストラクタに渡すことができます。プロセシングでは、アルゴリズムの実行元（ツールボックス、モデラー、Pythonコンソールなど）に応じてプロセシングとユーザーとの通信を処理します。

26.9.6. スクリプトのドキュメントを作成する

以下のものをオーバーロードするとあなたのスクリプトのドキュメントを作れます helpString() と helpUrl() methods of QgsProcessingAlgorithm.

26.9.7. フラグ

QgsProcessingAlgorithm の flags() メソッドをオーバーライドすると、QGISにアルゴリズムについてより詳しく伝えることができます。例えば、スクリプトをモデラーから隠すこと、キャンセルすること、スレッドセーフでないこと、などをQGISに伝えることができます。

Tip

デフォルトでは、処理タスクの実行中にQGISの応答性を維持するために、Processingはアルゴリズムを別のスレッドで実行します。アルゴリズムが定期的にクラッシュする場合は、おそらくバックグラウンドスレッドで安全に実行できないAPI呼び出しを使用している可能性があります。アルゴリズムのflags() メソッドからQgsProcessingAlgorithm.FlagNoThreadingフラグを返して、代わりにメインスレッドでアルゴリズムを実行するように強制します。

26.9.8. スクリプトアルゴリズムを書くためのベストプラクティス

スクリプトアルゴリズムを作成する際、特に他のQGISユーザーと共有したい場合に考慮すべきアイデアの簡単な概要を以下に示します。これらの単純な規則に従うことで、ツールボックス、モデラー、バッチ処理インターフェースなどのさまざまな処理要素間で一貫性が確保されます。

• 結果のレイヤは読み込まないでください。結果はプロセシングに処理させ、必要であればレイヤを読み込ませてください。

• あなたのアルゴリズム作成する出力について常に宣言して下さい.

• メッセージボックスを表示したり、スクリプトのGUI要素を使用したりしないでください。ユーザーと通信する場合は、フィードバックオブジェクトのメソッド（ QgsProcessingFeedback ）を使用するか、 QgsProcessingException をスローします。

QGISにはすでに多くのプロセシングアルゴリズムが用意されています。コードは QGIS のレポにあります。