1. はじめに

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

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

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

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

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

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

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

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

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

QGISライブラリのクラスのドキュメントである complete QGIS 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 アプリケーションのその他の部分へのアクセスが可能になります。

For user convenience, the following statements are executed when the console is started (in the future it will be possible to set further initial commands)

from qgis.core import *
import qgis.utils

For those which use the console often, it may be useful to set a shortcut for triggering the console (within Settings ▶ Keyboard shortcuts...)

1.2. Python プラグイン

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

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

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

注釈

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

1.3. Running Python code when QGIS starts

QGISを起動するたびにPythonコードを実行するには、2つの異なる方法があります。

  1. Creating a startup.py script

  2. Setting the PYQGIS_STARTUP environment variable to an existing Python file

1.3.1. startup.py ファイル

Every time QGIS starts, the user's Python home directory

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

is searched for a file named startup.py. If that file exists, it is executed by the embedded Python interpreter.

注釈

デフォルトパスはオペレーティングシステムによって異なります。ご自身の環境に合ったパスを見つけるには、Pythonコンソールを開いて QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) を実行し、デフォルトディレクトリのリストを見てください。

1.3.2. The PYQGIS_STARTUP environment variable

You can run Python code just before QGIS initialization completes by setting the PYQGIS_STARTUP environment variable to the path of an existing Python file.

This code will run before QGIS initialization is complete. This method is very useful for cleaning sys.path, which may have undesireable paths, or for isolating/loading the initial environment without requiring a virtual environment, e.g. homebrew or MacPorts installs on Mac.

1.4. Python アプリケーション

It is often handy to create scripts for automating processes. With PyQGIS, this is perfectly possible --- import the qgis.core module, initialize it and you are ready for the processing.

Or you may want to create an interactive application that uses GIS functionality --- perform measurements, export a map as PDF, ... The qgis.gui module provides various GUI components, most notably the map canvas widget that can be incorporated into the application with support for zooming, panning and/or any further custom map tools.

PyQGIS custom applications or standalone scripts must be configured to locate the QGIS resources, such as projection information and providers for reading vector and raster layers. QGIS Resources are initialized by adding a few lines to the beginning of your application or script. The code to initialize QGIS for custom applications and standalone scripts is similar. Examples of each are provided below.

注釈

Do not use qgis.py as a name for your script. Python will not be able to import the bindings as the script's name will shadow them.

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

To start a standalone script, initialize the QGIS resources at the beginning of the script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

First we import the qgis.core module and configure the prefix path. The prefix path is the location where QGIS is installed on your system. It is configured in the script by calling the setPrefixPath method. The second argument of setPrefixPath is set to True, specifying that default paths are to be used.

The QGIS install path varies by platform; the easiest way to find it for your system is to use the Pythonコンソールでのスクリプティング from within QGIS and look at the output from running QgsApplication.prefixPath().

After the prefix path is configured, we save a reference to QgsApplication in the variable qgs. The second argument is set to False, specifying that we do not plan to use the GUI since we are writing a standalone script. With QgsApplication configured, we load the QGIS data providers and layer registry by calling the qgs.initQgis() method. With QGIS initialized, we are ready to write the rest of the script. Finally, we wrap up by calling qgs.exitQgis() to remove the data providers and layer registry from memory.

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

The only difference between スタンドアロンスクリプトでPyQGISを使用する and a custom PyQGIS application is the second argument when instantiating the QgsApplication. Pass True instead of False to indicate that we plan to use a GUI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

Now you can work with the QGIS API - load layers and do some processing or fire up a GUI with a map canvas. The possibilities are endless :-)

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

You need to tell your system where to search for QGIS libraries and appropriate Python modules if they are not in a well-known location - otherwise Python will complain:

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

This can be fixed by setting the PYTHONPATH environment variable. In the following commands, <qgispath> should be replaced with your actual QGIS installation path:

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

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

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

Now, the path to the PyQGIS modules is known, but they depend on the qgis_core and qgis_gui libraries (the Python modules serve only as wrappers). The path to these libraries may be unknown to the operating system, and then you will get an import error again (the message might vary depending on the system):

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

Fix this by adding the directories where the QGIS libraries reside to the search path of the dynamic linker:

  • on Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

  • on Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% where <qgisrelease> should be replaced with the type of release you are targeting (eg, qgis-ltr, qgis, qgis-dev)

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

  • require the user to install QGIS prior to installing your application. The application installer should look for default locations of QGIS libraries and allow the user to set the path if not found. This approach has the advantage of being simpler, however it requires the user to do more steps.

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

The two deployment models can be mixed. You can provide a standalone applications on Windows and macOS, but for Linux leave the installation of GIS up to the user and his package manager.

1.5. Technical notes on PyQt and SIP

We've decided for Python as it's one of the most favoured languages for scripting. PyQGIS bindings in QGIS 3 depend on SIP and PyQt5. The reason for using SIP instead of the more widely used SWIG is that the QGIS code depends on Qt libraries. Python bindings for Qt (PyQt) are done using SIP and this allows seamless integration of PyQGIS with PyQt.