Outdated version of the documentation. Find the latest one here.

処理アルゴリズムをコンソールから使う

処理フレームワークの他のGUIエレメントを使用しては実現できない上級ユーザ向けの生産性向上を可能にします。複数のアルゴリズムを含むモデルは、コマンドラインインタフェースを使って定義できます。また、ループや条件分岐のような付加的な演算子を追加して、より柔軟でパワフルなワークフローを作成することができます。

QGISに処理コンソールはありませんが、すべての処理コマンドはQGIS組み込みのPythonコンソールから代わりに利用できます。それは、コンソールの仕事にこれらのコマンドを組み込み、そこから入手できる他のすべての機能(QGIS APIからの方法を含む)に処理アルゴリズムを接続できることを意味します。

Pythonコンソールから実行できるコードは、たとえいかなる処理メソッドを使っていない場合でも、ちょうど他のアルゴリズムでそうするように、ツールボックス、グラフィカルなモデラー、あるいはいかなる他のコンポーネントからでも呼び出すことができます。実際、ツールボックス内で見られるアルゴリズムの中にはシンプルなスクリプトもあります。

このセクションでは、Pythonを使用してアルゴリズムを作成する方法を、そしてQGIS Pythonのコンソールから処理アルゴリズムを使用する方法も、見ていきます。

Python コンソールからアルゴリズムを呼び出す

最初にやるべきことは、次行で処理ファンクションをインポートすることです:

>>> import processing

Now, there is basically just one (interesting) thing you can do with that from the console: execute an algorithm. That is done using the runalg() method, which takes the name of the algorithm to execute as its first parameter, and then a variable number of additional parameters depending on the requirements of the algorithm. So the first thing you need to know is the name of the algorithm to execute. That is not the name you see in the toolbox, but rather a unique command–line name. To find the right name for your algorithm, you can use the alglist() method. Type the following line in your console:

>>> processing.alglist()

このようなものを目にするでしょう。

Accumulated Cost (Anisotropic)---------------->saga:accumulatedcost(anisotropic)
Accumulated Cost (Isotropic)------------------>saga:accumulatedcost(isotropic)
Add Coordinates to points--------------------->saga:addcoordinatestopoints
Add Grid Values to Points--------------------->saga:addgridvaluestopoints
Add Grid Values to Shapes--------------------->saga:addgridvaluestoshapes
Add Polygon Attributes to Points-------------->saga:addpolygonattributestopoints
Aggregate------------------------------------->saga:aggregate
Aggregate Point Observations------------------>saga:aggregatepointobservations
Aggregation Index----------------------------->saga:aggregationindex
Analytical Hierarchy Process------------------>saga:analyticalhierarchyprocess
Analytical Hillshading------------------------>saga:analyticalhillshading
Average With Mask 1--------------------------->saga:averagewithmask1
Average With Mask 2--------------------------->saga:averagewithmask2
Average With Thereshold 1--------------------->saga:averagewiththereshold1
Average With Thereshold 2--------------------->saga:averagewiththereshold2
Average With Thereshold 3--------------------->saga:averagewiththereshold3
B-Spline Approximation------------------------>saga:b-splineapproximation
...

これが、アルファベット順の、対応するコマンドライン名に沿った、利用可能な全アルゴリズムの一覧です。

このメソッドでは、パラメ-タとして文字列を使えます。アルゴリズムの全文を返却する代わりに、その文字列を含むものだけを表示します。もし、例えば、DEMからスロープを計算するアルゴリズムを探している場合、alglist("slope") とタイプすると次のような結果が得られます:

DTM Filter (slope-based)---------------------->saga:dtmfilter(slope-based)
Downslope Distance Gradient------------------->saga:downslopedistancegradient
Relative Heights and Slope Positions---------->saga:relativeheightsandslopepositions
Slope Length---------------------------------->saga:slopelength
Slope, Aspect, Curvature---------------------->saga:slopeaspectcurvature
Upslope Area---------------------------------->saga:upslopearea
Vegetation Index[slope based]----------------->saga:vegetationindex[slopebased]

この結果は、あなたが利用可能なアルゴリズムによって変わります。

これであなたが探しているアルゴリズムは探しやすくなったはずです。コマンドライン名はこの場合 saga:slopeaspectcurvature です。

いったんアルゴリズムのコマンドライン名が分かれば、次にやるのはそれを実行する構文を知ることです。それはすなわち、必要なパラメータと runalg() メソッドを呼び出す際に引き渡す順序を知ることです。アルゴリズムを詳細に説明するメソッドがあり、アルゴリズムが必要とするパラメータと、生成されるアウトプットの一覧を取得することができます。その目的のために、alghelp(name_of_the_algorithm) メソッドを使うことができます。説明用の長い名前ではなく、コマンドライン名を使用してください。

saga:slopeaspectcurvature をパラメータとしてこのメソッドを呼び出すと,次の説明が得られるでしょう.

>>> processing.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
   ELEVATION <ParameterRaster>
   METHOD <ParameterSelection>
   SLOPE <OutputRaster>
   ASPECT <OutputRaster>
   CURV <OutputRaster>
   HCURV <OutputRaster>
   VCURV <OutputRaster>

これであらゆるアルゴリズムを実行する準備ができました。すでに述べたとおり、アルゴリズムを実行するのは単一のコマンド: runalg() だけです。その構文は以下の通りです:

>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
         Output1, Output2, ..., OutputN)

追加すべきパラメータとアウトプットの一覧は実行したいアルゴリズムによって異なり、まさに``alghelp()`` メソッドから受け取った通りで、順番も表示された通りです。

パラメータの種別により,値は様々に説明されます.次は各種別の入力パラメータ値の説明方法についてのクイックレビューです:

  • ラスターレイヤー、ベクタレイヤまたはテーブル。使用するデータ・オブジェクトを識別する名前での文字列(それがQGISの目次で持つ名前)、またはファイル名を単に使用します(対応するレイヤが開かれていない場合、それは開かれるが地図キャンバスには追加されないでしょう)。レイヤーを表すQGISオブジェクトのインスタンスを持っている場合は、それをパラメータとして渡すことができます。入力はオプションで、任意のデータオブジェクトを使用しない場合、 None を使用します。

  • 選択。アルゴリズムに選択パラメータがある場合、そのパラメータの値は整数値で入力すべきです。利用可能なオプションを調べるには、 algoptions() コマンドを使って、次の例のように表示させることができます:

    >>> processing.algoptions("saga:slopeaspectcurvature")
    METHOD(Method)
        0 - [0] Maximum Slope (Travis et al. 1975)
        1 - [1] Maximum Triangle Slope (Tarboton 1997)
        2 - [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
        3 - [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
        4 - [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
        5 - [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
        6 - [6] Fit 3.Degree Polynom (Haralick 1983)
    

    この場合,アルゴリズムには、そのようなパラメータのひとつが,7つのオプション付きであります.順序はゼロから始まることに注意してください.

  • 複数のインプット.値はセミコロン (;)で区切られたインプット記述子付きの文字列です.単一のレイヤやテーブルの場合と同様,各インプット記述子にはデータオブジェクト名やファイルパスが使えます.

  • XXX のテーブル項目名。項目名の文字列を利用して使ってください。このパラメータは大文字小文字を区別します。

  • 固定テーブル.カンマ (,) で区切られ,引用符 (")で閉じられた全てのテーブル値の一覧をタイプします.値は上部の列から始まり,左から右に進みます.テーブルを表す2次元の配列も使えます.

  • CRS. 必要なCRSのEPSG コード番号を入力。

  • 拡張。カンマ (,)区切りの xmin, xmax, ymin および ymax 付きの文字列を使わなければなりません。

ブーリアン、ファイル、文字列および数値のパラメータには、追加説明は不要です。

文字列,ブーリアン,数値といった入力パラメータにはデフォルト値があります.それを使う場合は,対応するパラメータエントリーに``None`` を使ってください.

アウトプットデータオブジェクト用には,ツールボックスでそうするように,保存時は使用するファイルパスをタイプしてください.結果を一時ファイルに保存したい場合は,``None``を使用してください.ファイルの拡張子でファイル形式が決まります.アルゴリズムがサポートしていない拡張子を入力した場合は,その出力種別用のデフォルトのファイル形式が使用され,与えられたファイルパスに対応する拡張子が追加されます.

Pythonのコンソールから同じアルゴリズムを実行した場合、アルゴリズムは、ツールボックスから実行された場合とは異なり、出力がマップキャンバスに追加されません。マップキャンバスに出力を追加したい場合は、アルゴリズムを実行した後、それを自分で行う必要があります。そのためには、QGIS APIコマンドを使用するか、または、さらに簡単に、このようなタスクのために提供便利な方法のいずれかを使用できます。

runalg メソッドは出力名(アルゴリズムの説明に書かれているもの)付きの辞書をキーとして、出力のファイルパスを値として返します。そのファイルパスを``load()`` メソッドに渡すことでこれらのレイヤをロードすることができます.

データ操作用の付加的なファンクション

別にアルゴリズムを呼び出すために使用される関数から、 `` processing``パッケージをインポートすることも、それが簡単にデータ、特にベクトルデータで動作するようにさせるいくつかの追加機能をインポートします。彼らは通常より少ない複雑な構文で、QGISのAPIからのいくつかの機能をラップだけで便利な機能です。新しいアルゴリズムを開発するとき、彼らはそれが簡単に入力されたデータで動作するようにさせるように、これらの機能は、使用すべきです。

以下は、これらのコマンドのいくつかのリストです。詳細は 加工/tools パッケージの下のクラス、およびQGISで提供されるサンプルスクリプトに見つけることができます。

  • getObject(obj) :ファイル名またはQGISレイヤーリスト内のオブジェクトの名前を指定でき渡されたオブジェクトからQGISオブジェクト(レイヤまたはテーブル)を返します

  • values(layer, fields): 渡された項目に,ベクターレイヤの属性テーブル内の値を返します.項目は項目名またはゼロから始まる項目インデックスで渡すことができます.渡された項目の識別子をキーとして,一覧の辞書を返します。既存の選択を考慮します.

  • features(layer): ベクターレイヤにかかる反復子を既存の選択を考慮して返します。

  • uniqueValues(layer, field): 保有している属性のユニークな値の一覧を返却します。属性は項目名またはゼロから始まる項目のインデックスとして渡すことができます.既存の選択を考慮します.

スクリプトの作成とツールボックスからの実行

対応するPythonのコードを書いたり,アルゴリズムのセマンティクスを定義するのに必要な付加情報をいくつか追加することで,自分自身のアルゴリズムを作成することができます.ツールボックスの Script アルゴリズムブロック内の Tools グループの下にある Create new script メニューが見つかると思います.それをダブルクリックしてスクリプト編集ダイアログを開いて下さい.これがコードを打ち込む場所です. ここで入力したスクリプトを scripts フォルダ (ファイル保存ダイアログを開くときのデフォルトのひとつ)に .py という拡張子で保存すると, それに対応するアルゴリズムが自動的に作られます.

アルゴリズムの名前(ツールボックスで見えるもの)はファイル名から、拡張子を除き、アンダースコアを空白に置き換えて作成されます。

次のコードを取り上げましょう。これは地表流水指標(TWI)をDEMから直接計算します

##dem=raster
##twi=output
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

見て頂いたとおり,これは3つのアルゴリズムを含んでおり,それらは全てSAGAから来ています.最後のものはTWIを計算しますが,斜面のレイヤと流量蓄積のレイヤが必要です.これらのものはありませんが,DEMがあるので,対応するSAGAアルゴリズムを呼び出して計算することができるのです.

この処理が行われるコードの部分は本章の前節を読んでいれば理解は難しくありません。しかしながら、最初の行にはもう少し説明が必要です。ツールボックスやグラフィカルモデラーのように、あらゆるGUIコンポーネントから実行できるようなアルゴリズムへとあなたのコードを変えるのに必要な情報が提供されています。

これらの行はダブルPython コメントシンボル (##) で始まり、次のような構造を持っています

[parameter_name]=[parameter_type] [optional_values]

これは,処理スクリプト中でサポートされる全パラメータ種別の一覧,文法,そしていくつかの例です.

  • raster. A ラスターレイヤ

  • vector. A ベクターレイヤ

  • table. A テーブル

  • number.A 数値.A デフォルト値が必要です.たとえば、depth=number 2.4

  • string。テキスト文字列。数値と同様、デフォルト値が必須です。例、 name=string Victor

  • boolean。ブーリアン値。その後に``True`` または False を追加してデフォルト値をセットします。例えば、 verbose=boolean True

  • multiple raster 。入力ラスターレイヤのセット。

  • multiple vector 。入力ベクターレイヤのセット。

  • field 。ベクターレイヤの属性テーブル内の項目。レイヤ名を``field`` タグの後に追加しなければなりません。例えば、ベクター入力を``mylayer=vector``で宣言した場合、myfield=field mylayer を使ってパラメータとしてそのレイヤから項目を追加することができます。

  • folder. あるフォルダ.

  • file. あるファイル名.

パラメータ名はアルゴリズム実行時にユーザに表示される名前であり、同時にスクリプトコード内で使う変数名でもあります。このパラメータに対してユーザが入力した値は、この名前の変数に割り当てられます。

ユーザにパラメータ名を表示する場合、名前は見栄えを改善するために、アンダースコアを空白に置き換えて、編集されます。このため、例えば、ユーザに ``A numerical value``という名前のパラメータを見せたければ、``A_numerical_value``という変数名を使うことができます。

レイヤーとテーブル値は、対応するオブジェクトのファイルパスを含む文字列です。それらをQGISオブジェクトにするには、 processing.getObjectFromUri() 関数を使用できます。複数の入力も1つの文字列値になります。すべての選択されたオブジェクトへのファイルパスがセミコロン( ; )で区切られたものになります。

出力は同様のやり方で定義されます。次のタグを使います:

  • output raster
  • output vector
  • output table
  • output html
  • output file
  • output number
  • output string

出力変数に割り当てられた値は常にファイルパス付きの文字列です。ユーザが出力ファイル名を入力していない場合の一時ファイルパスに対応します。

出力を宣言すると、アルゴリズムは終了するとその出力をQGISに追加しようとします。そのため、 runalg() メソッドはそれが生成するレイヤーをロードしないけれども、最終的なTWIレイヤーは、(前の例のケースを使用して)ロードされます、なぜならそれはユーザによって入力されたファイルに保存される、それは対応する出力の値であるから。

load() メソッドは自分のアルゴリズム内ではなく、コンソール行での作業中に使ってください。レイヤがアルゴリズムの出力として作成されている場合は、そのように宣言すべきです。さもないと、モデラー内のアルゴリズムを正しく使えないことになります。なぜならその文法(上述のタグで定義されているとおり)はアルゴリズムが実際に作成するものと一致しないからです。

非表示の出力(数値及び文字列)は値を持ちません。代わりに、それらに値を割り当てるのはあなたです。そうするためには、その出力の定義で使用した名前付きの変数の値をセットします。例えば、この宣言を使っている場合、

##average=output number

次の行は出力の値を5にセットします:

average = 5

パラメータと出力向けのタグに加えて、``group``タグを使えばその下にアルゴリズムが表示されるグループを定義することができます。

あなたのアルゴリズムが、処理に時間が掛かる場合、ユーザに知らせるのは良いアイデアです。progress``という名前のglobal を使って2つのメソッド: ``setText(text) および setPercentage(percent) で進捗テキストと進捗バーを変更することができます。

いくつかの例が提供されています。処理フレームワーククラスを使っているアルゴリズムの作成方法を実際の例でチェックしてみてください。任意のスクリプトアルゴリズム上で右クリックして Edit script を選んでコードを編集したり、単に閲覧したりすることができます。

自分のスクリプトのドキュメント化

モデルの場合と同様、自分のスクリプト用に付加的な文書を作成して、その内容や使い方を説明することができます。スクリプト編集ダイアログに、[Edit script help] ボタンがあります。それをクリックすると、ヘルプ編集ダイアログに移動します。グラフィカルモデラーについての章をチェックして、このダイアログについての詳細やその使い方を知ることができます。

ヘルプファイルはスクリプトと同じフォルダに保存されており、:file:`.help`拡張子がファイル名に追加されています。自分のスクリプトのヘルプは、最初に保存する前に編集できますので注意してください。後で、スクリプトを保存せずにスクリプト編集ダイアログを閉じた場合(例えば無視して)、自分で書いたヘルプの内容は失われます。自分のスクリプトが既に保存され、ファイル名に関連付けられていれば、保存は自動的に行われます。

実行前後のスクリプトのフック

アルゴリズムを動かす前後に走らせる実行前および実行後フックをセットするのにもスクリプトは利用可能です。これは、アルゴリズムが実行される都度実行すべきタスクを自動化するのに使うことができます。

文法は上述のものと同様ですが、付加的に``alg`` という名前のグローバル変数を使うことができ、これはたった今(あるいはまさにこれから)実行されたアルゴリズムを表します。

処理構成ダイアログの General グループ内に、 実行前スクリプトファイル 及び 実行後スクリプトファイル名 という2つのエントリ名があり、ここでそれぞれの場合に実行するスクリプトのファイル名を入力することができます。