1. はじめに

この文書は、チュートリアルとリファレンスガイドの両方を意図して書かれています。可能な事例をすべて網羅しているわけではありませんが、主要な機能を概観するには役に立つはずです。

Free Software Foundationにより発行された、GNU Free Documentation License, Version 1.3またはより新しいバージョンの条件の下で、この文書を複製、頒布、改変することが許可されます。ただし、変更不可部分、表紙テキスト、裏表紙テキストは含まれません。

ライセンスの写しは GNUフリー文書利用許諾契約書 に含まれています。

ライセンスは本ドキュメントにあるすべてのコードとスニペッツにも適用されます。

PythonのサポートはQGIS 0.9で初めて導入されました。デスクトップ版QGISでPythonを利用するのにはいくつかの方法があります（この後のセクションで説明します）。

  • QGISに付属するPytonコンソールでのコマンドの実行

  • プラグインの作成と利用

  • QGIS起動時のPythonコードの自動実行

  • プロセシングアルゴリズムの作成

  • QGISの「式」で使用する関数の作成

  • QGIS APIを利用するカスタムアプリケーションの作成

QGISサーバでもPythonプラグインを含むPythonバインディングが提供されています(参照 QGIS ServerとPython) そしてPythonバインディングを使うことによってPythonアプリケーションにQGSサーバを埋め込むこともできます。

QGISライブラリのクラスのドキュメントである 完全なQGIS C++ API リファレンスがあります。 Python用の QGIS API（pyqgis） はC ++ APIとほぼ同じです。

頻出タスクの実行方法を学習するには、 プラグインのリポジトリ から既存のプラグインをダウンロードして、そのコードを研究するのもよい方法です。

1.1. Pythonコンソールでのスクリプティング

QGIS はスクリプティングのための Python console を内蔵しています。プラグイン ► Pythonコンソール メニューから開くことができます。

../../_images/console.png

図 1.4 QGIS Python コンソール

上のスクリーンショットは、レイヤリストで現在選択されているレイヤを取得し、その ID を表示し、オプションでベクタレイヤの場合は地物数を表示する方法を示しています。QGIS 環境とのやりとりのために、 QgisInterface のインスタンスである iface 変数があります。このインタフェースにより、地図 キャンバス、メニュー、ツールバー、および QGIS アプリケーションのその他の部分へのアクセスが可能になります。

ユーザーの便宜のために、コンソールの起動時に次のステートメントが実行されます（将来的にはさらに初期コマンドを設定できるようになります）

from qgis.core import *
import qgis.utils

コンソールを頻繁に使用する場合は、コンソールを起動するためのショートカットを設定すると便利な場合があります（ 設定 ► キーボードショートカット... 内）

1.2. Python プラグイン

QGISの機能はプラグインを使って拡張することができます。プラグインはPythonで書くことができます。C++プラグインに比較しての主要な利点は配布の単純さ（プラットフォームごとにコンパイルする必要がありません）と開発の容易さです。

様々な機能をカバーする多くのプラグインがPythonサポートが導入されてから書かれました。プラグインのインストーラはPythonプラグインの取得、アップグレード、削除を簡単に行えます。プラグインとプラグイン開発の詳細については、 Pythonプラグイン ページを参照してください。

Pythonでプラグインを作るのはとても簡単です。詳細は Pythonプラグインを開発する を見てください。

注釈

PythonプラグインはQGISサーバーでも使うことができます。より詳しくは QGIS ServerとPython をご覧ください。

1.2.1. プロセシングプラグイン

プロセシングプラグインはデータを処理するために使うことができます。Pythonプラグインよりも開発が簡単で、より具体的で軽量です。 プロセシングプラグインを書く では、プロセシングアルゴリズムを使用することが適切な場合や、どのように開発すればよいかを説明します。

1.3. QGIS起動時にPythonコードを実行する

QGISが起動する度にPythonコードを実行する方法は複数あります。

  1. startup.py スクリプトを作る

  2. 既存のPythonファイルを PYQGIS_STARTUP 環境変数に設定する

  3. --code init_qgis.py パラメータを使って起動スクリプトを指定する。

1.3.1. startup.py ファイル

QGISが起動する度、ユーザのPythonホームディレクトリとシステムパスのリストに :file:startup.py を探します。そのファイルがあれば、埋め込みPythonインタプリタを使って実行されます。

通常、ユーザーのホームディレクトリにあるパスは、以下のようになります:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

デフォルトのシステムパスは、オペレーティングシステムに依存します。自分に合ったパスを見つけるには、Pythonコンソールを開いて QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) を実行すると、デフォルトディレクトリのリストが表示されます。

startup.py スクリプトは、QGISでpythonを初期化した直後、アプリケーション起動の初期に実行されます。

1.3.2. PYQGIS_STARTUP環境変数

既存のPythonファイルのパスを PYQGIS_STARTUP 環境変数に設定すると、QGISの初期化が完了する直前にPythonコードを実行することができます。

このコードは、QGISの初期化が完了する前に実行されます。この方法は、望ましくないパスが含まれている可能性のあるsys.pathをクリーンアップする場合や、仮想環境を必要としないで初期環境を分離/ロードする場合に非常に役立ちます。 例 MacのhomebrewまたはMacPortsのインストール。

1.3.3. --code パラメータ

QGISの起動パラメータとして実行するカスタムコードを提供することができます。そのためには、例えば qgis_init.py のような Python ファイルを作成し、qgis --code qgis_init.py を用いてコマンドラインから QGIS を実行・起動するようにします。

--code で提供されるコードは、アプリケーションのコンポーネントがロードされた後、QGISの初期化フェーズの後半に実行されます。

1.3.4. Pythonの追加引数

スクリプト --code や実行される他の Python コードに追加の引数を与えるには、 --py-args 引数を使用することができます。--py-args の後で（もしあれば） -- argの前に来る引数は、Pythonに渡されますが、QGISアプリケーション自体では無視されます。

以下の例では、myfile.tif は Python の sys.argv で利用できますが、QGIS では読み込まれません。一方、otherfile.tif はQGISによってロードされますが、sys.argv には存在しません。

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

Pythonから全てのコマンドラインパラメータにアクセスしたい場合は、 QCoreApplication.arguments() を使用することができます。

QgsApplication.instance().arguments()

1.4. Python アプリケーション

多くの場合、プロセスを自動化するためのスクリプトを作成すると便利です。 PyQGISを使用すると、これは完全に可能です--- qgis.core モジュールをインポートし、初期化すると、処理の準備が整います。

または、GIS機能を使用するインタラクティブなアプリケーションを作成することもできます---測定を実行し、地図をPDFとしてエクスポートします...。 qgis.gui モジュールではさまざまなGUIコンポーネントを提供します。特に地図キャンバスウィジェットは、ズーム、パン、その他のカスタムの地図ツールをサポートしてアプリケーションに組み込むことができます。

PyQGISカスタムアプリケーションやスタンドアロンスクリプトは、ベクタレイヤとラスタレイヤを読み取るための投影情報やプロバイダーなどのQGISリソースを見つけるように構成する必要があります。 QGISリソースは、アプリケーションまたはスクリプトの先頭に数行を追加することで初期化されます。カスタムアプリケーションとスタンドアロンスクリプトのQGISを初期化するコードは似ています。それぞれの例を以下に示します。

注釈

スクリプトの名前に qgis.py を使用しないでください。スクリプトの名前が隠すのでPython はバインディングをインポートできなくなります。

1.4.1. スタンドアロンスクリプトでPyQGISを使用する

スタンドアロンスクリプトを始めるには、スクリプトの初めにQGISリソースを初期化します:

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

まず、 qgis.core モジュールをインポートし、プレフィックスパスを設定します。プレフィックスパスは、QGISがシステムにインストールされている場所です。 setPrefixPath() メソッドを呼び出すことでスクリプトで構成されます。 setPrefixPath() の2番目の引数は True に設定されます。これはデフォルトのパスが使用されることを指定しています。

QGISのインストールパスはプラットフォームによって異なります。お手元のシステムに対するインストールパスを見つける最も簡単な方法は、QGIS内から Pythonコンソールでのスクリプティング を使用し、実行からの出力を見ることです：

QgsApplication.prefixPath()

プレフィックスパスを設定した後、 QgsApplication への参照を変数 qgs に保存します。 2番目の引数は False に設定され、スタンドアロンスクリプトを記述しているため、GUIを使用する予定がないことを指定します。 QgsApplication を設定した状態で、 initQgis() メソッドを呼び出してQGISデータプロバイダとレイヤーレジストリをロードします。

qgs.initQgis()

QGISが初期化されたら、残りのスクリプトを書く準備ができています。最後に、 exitQgis() を呼び出して、データプロバイダとレイヤーレジストリをメモリから削除して終了します。

qgs.exitQgis()

1.4.2. カスタムアプリケーションでPyQGISを使用する

スタンドアロンスクリプトでPyQGISを使用する とカスタムPyQGISアプリケーションが違うのは、 QgsApplication <qgis.core.QgsApplication> ` をインスタンス化するときの2番目の引数だけです。 :const:`False の代わりに True を渡して、GUIを使用する予定であることを示します。

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

これでQGIS APIを使用して、レイヤをロードして処理を行ったり、マップキャンバスを使用してGUIを起動したりすることができるようになりました。可能性は無限大です:-)

1.4.3. カスタムアプリケーションを実行する

QGISライブラリと適切なPythonモジュールがよく知られた場所にない場合、どこに検索をかけるかをシステムに指示する必要があります:

>>> import qgis.core
ImportError: No module named qgis.core

これは、環境変数 PYTHONPATH を設定することで修正することができます。以下のコマンドでは、<qgispath> をあなたの実際のQGISのインストールパスに置き換えてください:

  • Linuxでは: export PYTHONPATH=/<qgispath>/share/qgis/python

  • Windowsでは: set PYTHONPATH=c:\<qgispath>\python

  • macOSでは: export PYTHONPATH=/<qgispath>/Contents/Resources/python

これで、PyQGISモジュールへのパスがわかりましたが、それらは qgis_core および qgis_gui ライブラリに依存しています（Pythonモジュールはラッパーとしてのみ機能します）。これらのライブラリへのパスがオペレーティングシステムに認識されていない可能性があり、その後、インポートエラーが再度発生します（メッセージはシステムによって異なる場合があります）:

>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:
  No such file or directory

ダイナミックリンカーの検索パスにQGISライブラリが存在するディレクトリを追加することで修正します:

  • Linuxでは: export LD_LIBRARY_PATH=/<qgispath>/lib

  • Windowsでは: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% <qgisrelease> はターゲットにしているリリースのタイプで置き換えてください（例 qgis-ltr, qgis, qgis-dev）

これらのコマンドはブートストラップスクリプトに入れておくことができます。PyQGISを使ったカスタムアプリケーションを配布するには、これらの二つの方法が可能でしょう:

  • アプリケーションをインストールする前に、ユーザーにQGISをインストールするように要求します。アプリケーションインストーラーはQGISライブラリのデフォルトの場所を探し、見つからない場合はユーザーがパスを設定できるようにする必要があります。このアプローチには、より単純であるという利点がありますが、ユーザーはより多くの手順を実行する必要があります。

  • アプリケーションと一緒にQGISのパッケージを配布する方法です。アプリケーションのリリースにはいろいろやることがあるし、パッケージも大きくなりますが、ユーザーが追加ソフトウェアをダウンロードしてインストールするという負荷を避けられるでしょう。

2つの展開モデルを混在させることができます。 WindowsとmacOSでスタンドアロンアプリケーションを提供できますが、Linuxの場合、GISのインストールはユーザーとそのパッケージマネージャに任せます。

1.5. PYQtとSIPの技術メモ

Pythonが選ばれたのは、それがスクリプト作成に最も好まれる言語の1つであるためです。 QGIS 3のPyQGISバインディングは、SIPとPyQt5に依存しています。より広く使用されているSWIGの代わりにSIPを使用する理由は、QGISコードがQtライブラリに依存しているためです。 Qt (PyQt)のPythonバインディングはSIPを使用して行われ、これによりPyQGISとPyQtのシームレスな統合が可能になります。