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 を内蔵しています。 メニューから開くことができます。

図 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.
startup.py スクリプトを作る
既存のPythonファイルに
PYQGIS_STARTUP
環境変数を設定する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のシームレスな統合が可能になります。