.
処理フレームワークの他のGUIエレメントを使用しては実現できない上級ユーザ向けの生産性向上を可能にします。複数のアルゴリズムを含むモデルは、コマンドラインインタフェースを使って定義できます。また、ループや条件分岐のような付加的な演算子を追加して、より柔軟でパワフルなワークフローを作成することができます。
QGIS 内には処理コンソールはありませんが、 QGIS ビルトインPython コンソールで代わりにすべての処理コマンドが使えます.これは,自分のコンソール作業に対してそれらのコマンドを組み合わせて,そこから利用できるあらゆる他の地物( QGIS APIからのメソッドも含め)に対する処理アルゴリズムにつなぐことができるということを意味しています.
Pythonコンソールから実行できるコードは、たとえいかなる処理メソッドを使っていない場合でも、ちょうど他のアルゴリズムでそうするように、ツールボックス、グラフィカルなモデラー、あるいはいかなる他のコンポーネントからでも呼び出すことができます。実際、ツールボックス内で見られるアルゴリズムの中にはシンプルなスクリプトもあります。
この章では QGIS Python コンソールから,処理アルゴリズムの使い方と,同時に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`` 付きの文字列を使わなければなりません。
ブーリアン、ファイル、文字列および数値のパラメータには、追加説明は不要です。
文字列,ブーリアン,数値といった入力パラメータにはデフォルト値があります.それを使う場合は,対応するパラメータエントリーに``None`` を使ってください.
アウトプットデータオブジェクト用には,ツールボックスでそうするように,保存時は使用するファイルパスをタイプしてください.結果を一時ファイルに保存したい場合は,``None``を使用してください.ファイルの拡張子でファイル形式が決まります.アルゴリズムがサポートしていない拡張子を入力した場合は,その出力種別用のデフォルトのファイル形式が使用され,与えられたファイルパスに対応する拡張子が追加されます.
アルゴリズムがツールボックスから実行される時とは異なり,Python コンソールから同じアルゴリズムを実行しても出力はマップキャンバスに追加されません.出力を追加したい場合は,アルゴリズムを実行した後に自分でやらなければなりません.それを行うには QGIS APIコマンドを使うことができ,あるいはより簡単に,このようなタスク用に提供されているハンディなメソッドのひとつを使うこともできます.
runalg メソッドは出力名(アルゴリズムの説明に書かれているもの)付きの辞書をキーとして、出力のファイルパスを値として返します。そのファイルパスを``load()`` メソッドに渡すことでこれらのレイヤをロードすることができます.
アルゴリズム呼び出しに使われるファンクションから離れて、processing パッケージをインポートするとデータ、とりわけベクターデータでの作業を簡単にしてくれる付加ファンクションも同時にインポートします。それらは通常、文法があまり複雑でなく、 QGIS APIからのいくつかのファンクションをラップする便利なファンクションです。これらのファンクションは、入力データの操作を簡単にしてくれるので、新しいアルゴリズムを開発する際には使用するべきです。
下記はこのコマンドのいくつかの一覧です.より詳細な情報は``processing/tools`` パッケージ配下のクラス内と, QGIS とともに提供されたサンプルスクリプト内にもあります.
getObject(obj): 渡されたオブジェクトから|qg| オブジェクト (レイヤまたはテーブル)を返します。これはファイル名または|qg| の目次内のオブジェクト名になることができます。
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() ファンクションを使うことができます。複数入力も文字列値を持ち、セミコロン (;)で区切られた、すべての選択済みオブジェクトに対するファイルパスを含んでいます。
出力は同様のやり方で定義されます。次のタグを使います:
出力変数に割り当てられた値は常にファイルパス付きの文字列です。ユーザが出力ファイル名を入力していない場合の一時ファイルパスに対応します。
出力を宣言すると、アルゴリズムは終了時に、それを|qg| に追加しようとします。このため、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 グループ内に、 実行前スクリプトファイル 及び :guilabel:`実行後スクリプトファイル名`という２つのエントリ名があり、ここでそれぞれの場合に実行するスクリプトのファイル名を入力することができます。