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.

Кроме того, некоторая информация о разработке с использованием PyQGIS есть в блоге QGIS. Например, в записи QGIS tutorial ported to Python приведены примеры самостоятельных приложений. Хороший способ узнать о работе с расширениями — загрузить несколько готовых модулей из репозитория и изучить их код.

Консоль Python

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

../../_images/console.png

QGIS Python console

На рисунке выше показано как можно получить выделенный в окне легенды слой, отобразить его ID и, например, если это векторный слой, узнать количество объектов. Для взаимодействия с QGIS предназначена переменная qgis.utils.iface, которая является экземпляром класса QgisInterface. Используя этот интерфейс можно обращаться к карте, меню, панелям инструментов и другим частям QGIS.

Для удобства пользователей при открытии консоли выполняются следующие команды (в дальнейшем можно будет расширять этот список):

from qgis.core import *
import qgis.utils

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

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

Quantum GIS позволяет расширять свой функционал при помощи расширений. Изначально это было возможно только с использованием языка программирования C++. Позже, когда в QGIS появилась поддержка Python, стало возможным создание и использование расширений на Python. Их большим преимуществом, по сравнению с расширениями на С++, является простота распространения (не требуется компиляция под разные платформы) и легкость разработки.

С момента введения поддержки Python было разработано множество расширений, добавляющих самые разные функциии. Установщик модулей позволяет пользователям легко получать, обновлять и удалять расширения на Python. Обратитесь к странице Python Plugin Repositories для получения дополнительной информации.

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