Вступ¶

Цей документ створювався як підручник та довідник. І хоча в ньому не розглядаються всі можливі варіанти використання, він повинен дати змістовний огляд основного функціоналу.

Починаючи з версії 0.9, в QGIS реалізовано підтримку сценаріїв на мові Python. Ми вибрали саме Python, оскільки це одна з найпоширеніших скриптових мов. Прив’язки (bindings) PyQGIS залежать від SIP та PyQt4. Основною причиною використання SIP замість більш розповсюдженого SWIG є те, що код QGIS залежить від бібліотек Qt. А прив’язки для Qt (PyQt) також генеруються за допомогою SIP, це дозволяє забезпечити прозору інтеграцію PyQGIS та PyQt.

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

Існує декілька способів використання Python-прив’язок QGIS, вони розглядаються у наступних розділах:

виконання команд у консолі Python QGIS
створення та використання плаґінів на Python
створення власних програм з використанням API QGIS

Існує повний опис QGIS API, у якому зібрано інформацію про всі класи бібліотек QGIS. QGIS Python API практично ідентичне C++ API.

Крім того, деяка інформація про розробку з використанням PyQGIS можна знайти у блозі QGIS. Так у дописі QGIS tutorial ported to Python наведено приклади простих автономних програм. Хороший спосіб дізнатися про розробку плаґінів — завантажити існуючі модулі з репозиторію плаґінів та ознайомитися з їх кодом. Не забувайте що у каталозі python/plugins/ встановленої QGIS, також знаходиться декілька плаґінів, які можна використовувати для навчальних потреб.

Консоль Python¶

Для маленьких сценаріїв можна використовувати вбудовану в QGIS консоль Python. Відкривається вона з меню Плаґіни ‣ Консоль Python. Консоль відкривається як немодальне вікно:

Консоль Python QGIS

Вищенаведений малюнок показує як отримати вибраний у легенді шар, дізнатися його ідентифікатор та, якщо шар векторний, кількість його об’єктів. Для взаємодії з інтерфейсом QGIS використовується змінна iface, яка є екземпляром QgsInterface. Через цей інтерфейс можна звертатися до карти, меню, панелей інструментів та інших частин QGIS.

Для зручності користувачів, під час відкриття консолі виконуються такі команди (у майбутньому цей список можна буде розширювати)

from qgis.core import *
import qgis.utils

Тим, хто використовує консоль часто, варто призначити комбінацію клавіш для її виклику (в меню Налаштування ‣ Комбінації клавіш...)

Плаґіни на Python¶

QGIS дозволяє розширювати свій функціонал через плаґіни. Спочатку це було можливим лише на мові C++. Після реалізації підтримки Python у QGIS, з’явилась можливість використання плаґінів, написаних на Python. Головна перевага таких плаґінів у порівнянні з плаґінами на C++ — простота розповсюдження (відпадає необхідність у компіляції для різних платформ) та розробки.

З моменту введення підтримки Python було розроблено багато плаґінів. Менеджер плаґінів дозволяє легко отримувати, оновлювати та видаляти Python плаґіни. більше інформації про різні джерела плаґінів розміщена на сторінці Python Plugin Repositories.

Створювати плаґіни на Python дуже просто — дивіться розділ Розробка плаґінів на Python.

Програми на Python¶

Під час обробки ГІС-даних часто набагато зручніше створити декілька сценаріїв для автоматизації процесу ніж постійно виконувати ті самі дії знову і знову. PyQGIS допомагає зробити це — просто імпортуйте модуль qgis.core, ініціалізуйте його і у вас все готове до обробки даних.

Або ж вам може знадобитися інтерактивна програма з певним функціоналом ГІС — вимірювання довжин та площ, експорт карти в PDF або щось інше. Модуль qgis.gui містить різноманітні елементи інтерфейсу, найголовніший з них — віджет карти, який легко інтегрується у програму та підтримує переміщення, масштабування і будь-які інші інструменти карти.

Використання PyQGIS у програмах¶

Примітка: не використовуйте ім’я qgis.py, для своїх сценаріїв — Python не зможе імпортувати прив’язки, оскільки ім’я сценарію буде «затінювати» їх.

Перш за все необхідно імпортувати модуль qgis.core та вказати шлях, по якому 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 в інсталятор своєї програми. Підготовка до виписку стане більш складною, а сам інсталятор більш об’ємним. Але користувачі будуть позбавлені необхідності завантажувати та встановлювати додаткові програми самостійно.

Ці два підходи можна комбінувати — розгортати програму разом з QGIS у Windows та Mac OS X, а в Linux залишити встановлення QGIS на розсуд користувача.

Зміст