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 and 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 and Python をご覧ください。

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

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

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

There are different methods to run Python code every time QGIS starts.

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

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

  3. Specifying a startup script using the --code init_qgis.py parameter.

1.3.1. startup.py ファイル

Every time QGIS starts, the user's Python home directory and a list of system paths are searched for a file named startup.py. If that file exists, it is executed by the embedded Python interpreter.

The path in the user's home directory usually is found under:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

The default system paths depend on the operating system. To find the paths that work for you, open the Python Console and run QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) to see the list of default directories.

The startup.py script is executed immediately upon initializing python in QGIS, early on in the start of the application.

1.3.2. PYQGIS_STARTUP環境変数

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

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

1.3.3. The --code parameter

You can provide custom code to execute as startup paramteter to QGIS. To do so, create a python file, for example qgis_init.py, to execute and start QGIS from the command line using qgis --code qgis_init.py.

Code provided via --code is executed late in the QGIS initialization phase, after the application components have been loaded.

1.3.4. Additional arguments for Python

To provide additional arguments for your --code script or for other python code that is executed, you can use the --py-args argument. Any argument coming after --py-args and before a -- arg (if present) will be passed to Python but ignored by the QGIS application itself.

In the following example, myfile.tif will be available via sys.argv in Python but will not be loaded by QGIS. Whereas otherfile.tif will be loaded by QGIS but is not present in sys.argv.

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

If you want access to every command line parameter from within Python, you can use QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. Python アプリケーション

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

Oまたは、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番目の引数はis set to 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つであるため、Pythonを選択しました。 QGIS 3のPyQGISバインディングは、SIPとPyQt5に依存しています。より広く使用されているSWIGの代わりにSIPを使用する理由は、QGISコードがQtライブラリに依存しているためです。 Qt（PyQt）のPythonバインディングはSIPを使用して行われ、これによりPyQGISとPyQtのシームレスな統合が可能になります。