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

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()``メソッドから受け取った通りで、順番も表示された通りです。

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

• Raster Layer, Vector Layer or Table. Simply use a string with the name that identifies the data object to use (the name it has in the QGIS Table of Contents) or a filename (if the corresponding layer is not opened, it will be opened but not added to the map canvas). If you have an instance of a QGIS object representing the layer, you can also pass it as parameter. If the input is optional and you do not want to use any data object, use 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``を使用してください.ファイルの拡張子でファイル形式が決まります.アルゴリズムがサポートしていない拡張子を入力した場合は,その出力種別用のデフォルトのファイル形式が使用され,与えられたファイルパスに対応する拡張子が追加されます.

Unlike when an algorithm is executed from the toolbox, outputs are not added to the map canvas if you execute that same algorithm from the Python console. If you want to add an output to the map canvas, you have to do it yourself after running the algorithm. To do so, you can use QGIS API commands, or, even easier, use one of the handy methods provided for such tasks.

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

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

Apart from the functions used to call algorithms, importing the processing package will also import some additional functions that make it easier to work with data, particularly vector data. They are just convenience functions that wrap some functionality from the QGIS API, usually with a less complex syntax. These functions should be used when developing new algorithms, as they make it easier to operate with input data.

Below is a list of some of these commands. More information can be found in the classes under the processing/tools package, and also in the example scripts provided with 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): 渡された項目に,ベクターレイヤの属性テーブル内の値を返します.項目は項目名またはゼロから始まる項目インデックスで渡すことができます.渡された項目の識別子をキーとして,一覧の辞書を返します。既存の選択を考慮します.

• 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``という変数名を使うことができます。

Layers and table values are strings containing the file path of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the file paths to all selected object, separated by semicolons (;).

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

• 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) で進捗テキストと進捗バーを変更することができます。

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

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

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

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

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

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

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

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