Outdated version of the documentation. Find the latest one here.

Введение

Этот документ задумывался как учебник и справочное пособие. Вы не найдёте здесь описания всех возможных вариантов использования, это скорее обзор основных функциональных возможностей.

Начиная с версии 0.9, в QGIS появилась возможность поддержки сценариев на языке программирования Python. Мы выбрали Python, так как это один из наиболее известных скриптовых языков. Привязки (bindings) PyQGIS зависят от SIP и PyQt4. Основная причина использования SIP вместо более распространенного SWIG состоит в том, что код QGIS зависит от библиотек Qt. Привязки Python к Qt (PyQt) также создаются с использованием SIP, что позволяет обеспечить прозрачную интерграцию PyQGIS и PyQt.

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

Есть несколько способов программирования на Python в QGIS, подробнее они будут рассмотрены в следующих разделах:

  • ввод команд в консоли Python QGIS

  • создание и использование расширений на Python

  • создание собственного приложения на базе QGIS API

Существует полное описание QGIS API, в котором собрана информация обо всех классах библиотек QGIS. QGIS Python 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

Консоль Python

Для небольших сценариев можно воспользоваться встроенной консолью Python. Открыть её можно из меню: Модули ‣ Консоль Python. Консоль откроется как немодальное окно:

../../_images/console.png

QGIS Python console

The screenshot above illustrates how to get the layer currently selected in the layer list, show its ID and optionally, if it is a vector layer, show the feature count. For interaction with QGIS environment, there is a iface variable, which is an instance of QgsInterface. This interface allows access to the map canvas, menus, toolbars and other parts of the QGIS application.

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

from qgis.core import *
import qgis.utils

Тем, кто использует консоль часто, стоит назначить комбинацию клавиш для её вызова (в меню Установки ‣ Комбинации клавиш...)

Расширения на Python

QGIS allows enhancement of its functionality using plugins. This was originally possible only with C++ language. With the addition of Python support to QGIS, it is also possible to use plugins written in Python. The main advantage over C++ plugins is its simplicity of distribution (no compiling for each platform needed) and easier development.

Many plugins covering various functionality have been written since the introduction of Python support. The plugin installer allows users to easily fetch, upgrade and remove Python plugins. See the Python Plugin Repositories page for various sources of plugins.

Создание расширений на Python — это просто, см. Разработка расширений на Python.

Приложения на Python

При обработке ГИС данных часто удобнее создать несколько сценариев, автоматизирующих процесс, чем постоянно выполнять одни и те же действия. Это более чем возможно при использовании PyQGIS — просто импортируйте модуль qgis.core, инициализируйте его и всё готово к обработке.

Или же вам может потребоваться интерактивное приложение, обладающее некоторым функционалом ГИС — измерение данных, экспорт карты в формат PDF или что-то ещё. Модуль qgis.gui предоставляет различные элементы интерфейса, наиболее важный среди них — виджет карты, который легко интегрируется в приложение и поддерживает масштабирование, панорамирование и/или любые другие инструменты для работы с картой.

Использование PyQGIS в приложениях

Примечание: не используйте имя qgis.py для своих сценариев — Python не сможет импортировать привязки, так как имя сценария будет “затенять” их.

Прежде всего нужно импортировать модуль qgis и задать путь, где QGIS будет искать ресурсы — базу проекций, провайдеров и др. Если при установке путей поиска второй аргумент задан как True, QGIS инициализирует все пути стандартными значениями с использованием заданного префикса. Вызов функции initQgis() очень важен, так как позволят QGIS выполнить поиск доступных провайдеров данных.

from qgis.core import *

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

# load providers
QgsApplication.initQgis()

Теперь можно работать с API QGIS — загружать слои, выполнять какую-то обработку или создать графическое приложение с картой. Возможности бесконечны :-)

После окончания работы с библиотеками QGIS вызовите exitQgis(), чтобы быть уверенными, что все ресурсы были освобождены (например, что список слоев карты очищен и все слои удалены):

QgsApplication.exitQgis()

Запуск приложений

Необходимо указать системе где искать библиотеки 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

Теперь путь к модулям PyQGIS известен, но они в свою очередь зависят от библиотек qgis_core и qgis_gui (модули Python служат всего лишь “обёртками” над этими библиотеками). Обычно, операционной системе неизвестно расположение этих библиотек, поэтому вы получите ошибку импорта еще раз (сообщение может отличаться в зависимости от системы):

>>> 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 на попечении пользователя и пакетного менеджера.