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

Pythonスクリプトなどの新しい処理アルゴリズムを書く

対応するPythonのコードを書き、アルゴリズムの意味を定義するのに必要な追加情報を提供するためにいくつかの余分な行を追加することで、独自のアルゴリズムを作成できます。 新しいスクリプトを作成 メニューは Tools グループ Script ツールボックスのアルゴリズムの下にあります。スクリプト版]ダイアログボックスを開くには、それをダブルクリックします。それはコードを入力しなければならないところです。そこからスクリプトを scripts フォルダ( ファイル保存ダイアログを開くときデフォルトのもの)に保存すると、拡張子が .py で、自動的に対応するアルゴリズムを作成します。

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

次のコードをとってみましょう、DEMから直接に地形湿り指数(TWI)を算出するものです。

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

おわかりになるように、それは3つのアルゴリズムを必要とし、それらはすべてがSAGAから来ます。それらの最後の一つはTWIを計算するもので、傾斜レイヤーと流れ蓄積レイヤーを必要とします。これらのレイヤーはありませんが、DEMはありますので、対応するSAGAアルゴリズムを呼び出すことによってそれらを計算できます。

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

これらの行はPythonの二重コメントシンボル( `` ## ``)で始まり、以下の構造を持ちます

[parameter_name]=[parameter_type] [optional_values]

処理スクリプトでサポートされているすべてのパラメータタイプのリスト、構文、およびいくつかの例を示します。

  • `` raster``。ラスターレイヤー

  • `` ベクトル ``。ベクトルレイヤー

  • `` TABLE``。テーブル

  • `` number``。数値。デフォルト値が提供されなければなりません。例えば、 深さ=数2.4

  • `` string``。テキスト文字列。数値の場合と同様に、デフォルト値を追加する必要があります。たとえば、 `` name = string Victor``

  • 「長文字列」。文字列と同じですが、大きなテキストボックスが表示されるため、小さなコードスニペットが必要なスクリプトなど、長い文字列に適しています。

  • `` boolean``。ブール値。デフォルト値を設定するために `` True``または `` False``を追加してください。たとえば、 `` verbose = boolean True``とします。

  • 複数raster。入力されたラスタレイヤのセット。

  • 複数vector。入力ベクトルレイヤーのセット。

  • `` field``。ベクトルレイヤーの属性テーブル内のフィールド。レイヤーの名前を `` field``タグの後に追加する必要があります。たとえば、 `` mylayer = vector``とベクトル入力を宣言している場合、`` myField=フィールドmylayer``を使用するとそのレイヤーからのフィールドをパラメータとして追加できます。

  • `` extent``。XMIN、XMAX、YMIN、YMAXによって規定された空間的広がり

  • `` folder``。フォルダ

  • `` file``。ファイル

  • `` crs``。座標参照系

  • `` selection``。ユーザーが事前にリストから選択できるようにするドロップダウンメニュー。例えば、 単位=選択sq_km; sq_miles; sq_degrees

  • `` name``。スクリプトの名前。これにより、処理ツールボックスのアルゴリズム名として表示されます。例えば、 私のアルゴリズム名= name

  • `` group``。スクリプトが処理ツールボックスに表示されるフォルダ名。例えば、 Utilsの= groups``は、スクリプト内 `Utils``フォルダ内のスクリプトを入れます`加えます。

パラメータ名は、スクリプトコードで使用するアルゴリズムを実行する際にユーザーに表示される名前、また、変数名です。そのパラメータのために、ユーザが入力した値は、その名前の変数に代入されます。

ユーザーにパラメータの名前を示す場合には、名前は見栄えを改善するためにスペースがアンダースコアに置き換える編集がされます。ですから、たとえばユーザーが名前付きパラメータ ``A numerical value``を見たい場合、変数名 ` A_numerical_value``を使用できます。

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

出力は、次のタグを使用して同様の方法で定義されます。

  • 出力raster

  • 出力vector

  • 出力TABLE

  • 出力html

  • 出力file

  • 出力number

  • 出力string

  • 出力extent

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

パラメータおよび出力用のタグに加えて、アルゴリズムが `` group``タグを使用して、表示されるグループも定義できます。

スクリプトのヘッダーで使用できる最後のタグは `` ## nomodeler``です。アルゴリズムをモデラーウィンドウに表示したくないときに使用します。これは、明確な構文を持っていないアルゴリズム(例えば、設計時には作成されるレイヤーの数が予め知られていない場合)に使用する必要があります。グラフィカルモデラーに使用することは不適切です。

アルゴリズムによって作成されたデータの扱い

レイヤー(ラスタ、ベクタまたはテーブル)を表す出力を宣言するときは、このアルゴリズムでは終了時にレイヤーをQGISに追加しようとします。ですから、``runalg()``メソッドはそれが生成するレイヤーをロードしなにもかかわらず最終 TWI レイヤーはロードされるでしょう。それはユーザによって入力されたファイル に保存されるからです、それは対応する出力の値である。

Do not use the load() method in your script algorithms, but just when working with the console line. If a layer is created as output of an algorithm, it should be declared as such. Otherwise, you will not be able to properly use the algorithm in the modeler, since its syntax (as defined by the tags explained above) will not match what the algorithm really creates.

隠された出力(数値と文字列)は値を持ちません。代わりに、それらには値を割り当てる必要があります。それをするには、その出力を宣言するために使用した名前を持つ変数の値を設定するだけです。たとえば、この宣言を使用している場合は、

##average=output number

次の行は、出力の値を5に設定します:

average = 5

ユーザーとのやりとり

アルゴリズムの処理に時間がかかる場合は、ユーザーに通知することをお勧めします。進行状況テキストとプログレスバーを修正するための2つの利用可能なメソッド:setText(テキスト)``と``setPercentage(パーセント)``をもつ progress``という名前のグローバルが利用可能です。

アルゴリズムの進行に関連していない、ユーザーにいくつかの情報を提供する必要がある場合は、 `` progress``オブジェクトから `` SETINFO(テキスト) ``メソッドを使用できます。

スクリプトに何らかの問題がある場合、伝播する正し​​い方法は、 タイプ``GeoAlgorithmExecutionException()``の例外を発生させることです。メッセージを例外のコンストラクタに引数として渡すことができます。処理は、アルゴリズムが(ツールボックス、モデラー、Pythonのコンソール...)から実行されている場所に応じて、それを処理し、ユーザーとの通信の世話をします

スクリプトの文書化

モデルの場合のように、スクリプトの追加ドキュメントを作成することができ、彼らが何をすべきかを説明し、それらを使用する方法。スクリプトの編集ダイアログには** [スクリプト編集のヘルプ] **ボタンがあります。それをクリックすると、ヘルプ編集のダイアログボックスが表示されます。このダイアログとその使用方法についての詳細を調べるには、グラフィカルモデラーについての章をチェックしてください。

ヘルプファイルは、ファイル名に拡張子 .help を追加して、スクリプト自体と同じフォルダに保存されます。スクリプトのヘルプは初めてそれを保存する前でも編集できます。後でスクリプトを保存せずにスクリプト編集ダイアログを閉じた(つまり、それを捨てた)場合、今書いたヘルプコンテンツは失われます。スクリプトがすでに保存されたファイル名に関連付けられている場合は、保存が自動的に実行されます。

サンプルスクリプト

いくつかの例は、ツールボックス内の スクリプト/ツール の下 オンライン・スクリプトのコレクションからスクリプトを取得する ツール項目を選択することでアクセスできるスクリプトのオンラインコレクションでご利用いただけます。

../../../_images/script_online.png

それらをチェックして、処理フレームワーククラスを使用してアルゴリズムを作成する方法の実際の例を参照してください。スクリプトアルゴリズムを右クリックして、 :guilabel:`Edit script`を選択すると、コードを編集できますし、単に見るだけでもできます。

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

ここでは、他のQGISのユーザーと共有したい場合は、特に、スクリプトのアルゴリズムを作成したときに考慮すべきアイデアの簡単な要約です。これらの単純なルールに従うことで、このようなツールボックス、モデラーまたはバッチ処理インターフェースとして異なる処理要素間の整合性を保証します。

  • 結果のレイヤーはロードしないでください。処理に結果を処理させ、必要であれば、レイヤーをロードしてください。

  • 必ずアルゴリズムが作成する出力を宣言してください。そのような1つの出力を宣言し、それらのコレクションを作成するために、その出力に設定された宛先ファイル名を使用するようなものは避けてください。これは、アルゴリズムの正しいセマンティクスを壊し、モデラーで安全にそれを使用することが不可能になります。そのようなアルゴリズムを記述する必要がある場合は、必ず `` ## nomodeler``タグを追加してください。

  • メッセージボックスを表示したり、スクリプトから任意のGUI要素を使用しないでください。ユーザと通信したい場合は、 `` SETINFO() ``メソッドを使用するか、 `` GeoAlgorithmExecutionException``を投げます

  • 経験則として、アルゴリズムは、処理ツールボックス以外のコンテキストで実行される可能性があることを忘れないでください。

実行前および実行後スクリプトフック

スクリプトはアルゴリズムが実行される前後に実行される実行前と実行後のフックを設定するためにも使用できます。これは、アルゴリズムが実行されるたびに実行されるべきタスクを自動化するために使用できます。

構文構文は、上記の説明と同じであるが、名前の追加のグローバル変数 `` alg``は単にされ(又はれようとしている)実行されたアルゴリズムを表す、利用可能です。

処理の設定]ダイアログボックスの General グループの中に 実行前スクリプトファイル実行後スクリプトファイル という名前の2つの入力欄があり、それぞれの場合に実行されるスクリプトのファイル名を入力できます。