はじめに

このドキュメントはチュートリアルとリファレンスガイドの両方の役割を意図して書かれています。すべてのユースケースを満たしてはいませんが、主要な機能の良い概要となるでしょう。

0.9リリースからQGISはPythonを使ったスクリプト処理をサポートしました。Pythonはスクリプト処理でもっとも好まれている言語の一つだと思います。PyQGISバインディングはSIPとPyQt4に依存しています。これはSIPはSWIGの代わりに広く使われていて、QGISのコードはQtライブラリに依存しています。QtのPythonバインディング(PyQt)もSIPを使っていて、これによりPyQtによるPyQGISの実装がシームレスに実現しています。

TODO:
Getting PyQGIS to work (Manual compilation, Troubleshooting)

There are several ways how to use QGIS python bindings, they are covered in detail in the following sections:

  • automatically run Python code when QGIS starts

  • QGIS の中の Python コンソールのコマンドについて

  • Pythonでプラグインを作り、使う方法

  • QGIS APIベースのカスタムアプリケーションの作成

QGIS ライブラリのクラスのドキュメントは`完全な QGIS API <http://doc.qgis.org/>`_ のリファレンスにあります。PythonのQGIS APIは C++ のAPIとほぼ同じです。

There are some resources about programming with PyQGIS on QGIS blog. See QGIS tutorial ported to Python for some examples of simple 3rd party apps. A good resource when dealing with plugins is to download some plugins from plugin repository and examine their code. Also, the python/plugins/ folder in your QGIS installation contains some plugin that you can use to learn how to develop such plugin and how to perform some of the most common tasks

Run Python code when QGIS starts

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

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 method is something you will probably rarely need, but worth mentioning here because it is one of the several ways to run Python code within QGIS and because 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 environ without requiring a virt env, e.g. homebrew or MacPorts installs on Mac.

The startup.py file

Every time QGIS starts, the user’s Python home directory (usually: .qgis2/python) is searched for a file named startup.py, if that file exists, it is executed by the embedded Python interpreter.

Python コンソール

スクリプト処理をする上で、(QGISに)統合されているPython コンソールから多くの利点を得られるでしょう。これはメニューの プラグイン ‣ Pythonコンソール から開くことができます。コンソールはモーダルではないユーティリティウィンドウに開きます:

../../_images/console.png

QGIS Python コンソール

上記のスクリーンショットはレイヤーのリストから現在選択中のレイヤーを取得して、IDや他の情報を表示してるところを見せていて、もしベクターレイヤーであれば、フューチャーの数を表示することができます。QGIS環境とやりとりするには QgisInterface のインスタンスである qgis.utils.iface 変数を使います。このインターフェイスはマップキャンバス、メニュー、ツールバーやその他のQGISアプリケーションのパーツにアクセスすることができます。

利便性を上げるためには、コンソールがスタートしたときに次の命令を入力してください(将来的には初期実行されるコマンドになるかもしれません):

from qgis.core import *
import qgis.utils

このコンソールをたびたび使うなら、ショートカットを設定しておくとよいでしょう(メニューの 設定 ‣ ショートカットの構成... から行えます)

Python プラグイン

QGIS はプラグインによる機能拡張が可能です。元々はC++でのみ可能でした。QGISにPythonサポートを追加したことで、Pythonでもプラグインを書く事ができるようになりました。C++プラグインよりもよりよい利点は簡単な配布(プラットフォームごとのコンパイルする必要がありません)ができ、また簡単に開発ができます。

様々な機能をカバーする多くのプラグインはPythonサポートが導入されてから書かれました。プラグインのインストーラはPythonプラグインの取得、アップグレード、削除を簡単に行えます。様々なプラグインのソースが Python Plugin Repositories から見つけることができます。

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

Python アプリケーション

GISデータを処理するときは、繰り返し同じタスクを実行するのに簡単なスクリプトを書いて自動化することがたびたびあります。PyQGISなら完璧に行えます — qgis.core モジュールを import すれば、初期化が行われて処理を行う準備が完了します。

もしくはいくつかのGISの機能 — いくつかのデータの距離を測ったり、地図をPDFに変換したり、または他の機能など – を使ったインタラクティブなアプリケーションを作りたいのかもしれません。 qgis.gui モジュールは様々なGUIコンポーネントを追加することができ、とりわけマップキャンバスのwidgetはズームやパンや他のマップを制御するツールと一緒にアプリケーションに簡単に組み込むことができます。

Using PyQGIS in custom application

注意: qgis.py という名前をあなたのテストスクリプトで*使わないでください* — このスクリプトの名前がバインディングを隠蔽してしまってpythonでimportできなくなるでしょう。

First of all you have to import qgis module, set QGIS path where to search for resources — database of projections, providers etc. When you set prefix path with second argument set as True, QGIS will initialize all paths with standard dir under the prefix directory. Calling initQgis() function is important to let QGIS search for the available providers.

from qgis.core import *

# supply path to where is your qgis installed
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# load providers
QgsApplication.initQgis()

これでQGIS API — レイヤーを読み込んだり、処理を行ったり、マップキャンバスと共にGUIを起動したり - を動かす事ができます。可能性は無限です :-)

When you are done with using QGIS library, call exitQgis() to make sure that everything is cleaned up (e.g. clear map layer registry and delete layers):

QgsApplication.exitQgis()

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

QGISのライブラリとPythonモジュールが一般的な場所に置かれて無ければ、システムに適切な場所を伝える必要があるでしょう — そうしないと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

これでPyQGISモジュールのパスがわかるようになりました。一方これらは qgis_core と ``qgis_gui``ライブラリに依存します(Pythonライブラリはラッパーとして振る舞うだけです)。これらのライブラリのパスがOSで読み込めないものであれば、またもやimportエラーが発生するでしょう(このメッセージはシステムにかなり依存していることを示します):

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

これを修正するにはQGISライブラリが存在するディレクトリを動的リンカのパスに追加するをします:

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

  • Windowsでは: set PATH=C:\qgispath;%PATH%

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

  • QGISを対象となるプラットフォームにインストールするのをユーザに要求します。アプリケーションのインストーラはQGISライブラリの標準的な場所を探すことができ、もし見つからなければユーザがパスをセットできるようにします。この手段はシンプルである利点がありますが、しかしながらユーザに多くの手順を要求します。

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

これらのモデルは組み合わせることができます - Windows と Mac OS Xではスタンドアローンアプリケーションとして配布をして、LinuxではQGISのインストールをユーザとユーザが使っているパッケージマネージャに任せるとか。