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

Python コンソールからの呼び出しアルゴリズム¶

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

>>> import processing

今や、コンソールからこれを使ってできるのは基本的にひとつの(興味深い)ことだけ: つまりアルゴリズムの実行です。runalg() メソッドを使いますが、これはその第一パラメータとしてアルゴリズムの名前を使って、次にアルゴリズムの要件に応じた付加的なパラメータの可変な数値、を使って実行されます。このため、最初に知っておくべきことは、実行するアルゴリズムの名前です。ツールボックスで見える名前ではなく、むしろユニークなコマンドラインの名前です。自分のアルゴリズム用に正しい名前を探す場合は、algslist() メソッドを使うことができます。コンソールで次の行をタイプしてください:

>>> 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`` 付きの文字列を使わなければなりません。

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

Input parameters such as strings, booleans, or numerical values have default values. To use them, specify None for the corresponding parameter entry.

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

アルゴリズムがツールボックスから実行される時とは異なり,Python コンソールから同じアルゴリズムを実行しても出力はマップキャンバスに追加されません.出力を追加したい場合は,アルゴリズムを実行した後に自分でやらなければなりません.それを行うには QGIS APIコマンドを使うことができ,あるいはより簡単に,このようなタスク用に提供されているハンディなメソッドのひとつを使うこともできます.

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

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

アルゴリズム呼び出しに使われるファンクションから離れて、processing パッケージをインポートするとデータ、とりわけベクターデータでの作業を簡単にしてくれる付加ファンクションも同時にインポートします。それらは通常、文法があまり複雑でなく、 QGIS APIからのいくつかのファンクションをラップする便利なファンクションです。これらのファンクションは、入力データの操作を簡単にしてくれるので、新しいアルゴリズムを開発する際には使用するべきです。

下記はこのコマンドのいくつかの一覧です.より詳細な情報は``processing/tools`` パッケージ配下のクラス内と, QGIS とともに提供されたサンプルスクリプト内にもあります.

• getobject(obj): Returns a QGIS object (a layer or table) from the passed object, which can be a filename or the name of the object in the QGIS Table of Contents.

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

• getfeatures(layer): Returns an iterator over the features of a vector layer, considering the existing selection.
• uniquelabels(layer, field): Returns a list of unique values for a given attribute. Attributes can be passed as a field name or a zero-based field index. It considers the existing selection.

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

対応する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() ファンクションを使うことができます。複数入力も文字列値を持ち、セミコロン (;)で区切られた、すべての選択済みオブジェクトに対するファイルパスを含んでいます。

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

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

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

When you declare an output, the algorithm will try to add it to QGIS once it is finished. That is why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded (using the case of our previous example), since it is saved to the file entered by the user, which is the value of the corresponding output.

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

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

##average=output number

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

average = 5

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

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

Several examples are provided. Please check them to see real examples of how to create algorithms using the processing framework classes. You can right-click on any script algorithm and select Edit script to edit its code or just to see it.

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

As in the case of models, you can create additional documentation for your scripts, to explain what they do and how to use them. In the script editing dialog, you will find an [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the section about the graphical modeler to know more about this dialog and how to use it.

Help files are saved in the same folder as the script itself, adding the .help extension to the filename. Notice that you can edit your script’s help before saving the script for the first time. If you later close the script editing dialog without saving the script (i.e., you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving the help content is done automatically.

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

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

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

In the General group of the processing configuration dialog, you will find two entries named Pre-execution script file and Post-execution script file where the filename of the scripts to be run in each case can be entered.