Introducere

Acest document are rolul de tutorial dar și de ghid de referință. Chiar dacă nu prezintă toate cazurile de utilizare posibile, ar trebui să ofere o bună imagine de ansamblu a funcționalităților principale.

Începând cu versiunea 0.9, QGIS are suport de scriptare opțional, cu ajutorul limbajului Python. Ne-am decis pentru Python deoarece este unul dintre limbajele preferate în scriptare. PyQGIS depinde de SIP și PyQt4. S-a preferat utilizarea SIP în loc de SWIG deoarece întregul cod QGIS depinde de bibliotecile Qt. Legarea Python de Qt (PyQt) se face, de asemenea, cu ajutorul SIP, acest lucru permițând integrarea perfectă a PyQGIS cu PyQt.

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:

  • rularea automată a codului Python atunci când porneşte QGIS

  • scrierea comenzilor în consola Python din QGIS

  • crearea în Python a plugin-urilor

  • crearea aplicațiilor personalizate bazate pe QGIS API

Există o referință API QGIS completă care documentează clasele din bibliotecile QGIS. API-ul QGIS pentru Python este aproape similar cu cel pentru C++.

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

Rularea codului Python atunci când porneşte QGIS

Există două metode distincte de a rula cod Python de fiecare dată când porneşte QGIS.

Variabila de mediu PYQGIS_STARTUP

Puteţi rula cod Python mai înainte de finalizarea inițializării QGIS, indicând în variabila de mediu PYQGIS_STARTUP calea spre un fişier Python existent.

Această metodă este rar utilizată, dar merită menţionată, deoarece reprezintă una din metodele de a rula cod Python în QGIS, şi pentru că acest cod se va executa înainte de finalizarea iniţializării QGIS. Această metodă este foarte utilă pentru curăţarea sys.path, care poate conţine căi nedorite, sau pentru izolarea/încărcarea căilor mediului iniţial fără a fi necesară instalarea unui mediu virtual, cum ar fi homebrew sau MacPorts pe Mac.

Fişierul startup.py

De fiecare dată când porneşte QGIS, directorul home al utilizatorului Python( de obicei .qgis2/python) este căutat un fişier numit startup.py, dacă acesta există, este executat de către interpretorul Python integrat.

Consola Python

Pentru scripting, se poate utiliza consola Python integrată. Aceasta poate fi deschisă din meniul: Plugins ‣ Consola Python. Consola se deschide ca o fereastră utilitară, non-modală:

../../_images/console.png

Consola Python din QGIS

Captura de ecran de mai sus ilustrează cum să puteți obțineți accesul la stratul curent selectat în lista straturilor, pentru a-i afișa ID-ul și, opțional, în cazul în care stratul este de tip vectorial, pentru a calcula numărul total de entități spațiale. Pentru interacțiunea cu mediul QGIS, există o variabilă :date:`iface`, care reprezintă o instanță a clasei QgsInterface. Această interfață permite accesul la canevasul hărții, la meniuri, la barele de instrumente și la alte părți ale aplicației QGIS.

Pentru confortul utilizatorului, următoarele instrucțiuni sunt executate atunci când consola este pornită (în viitor, va fi posibil să stabiliți comenzi inițiale suplimentare)

from qgis.core import *
import qgis.utils

Pentru cei care folosesc des consola, ar putea fi utilă stabilirea unei comenzi rapide pentru deschiderea consolei (prin intermediul meniului Setări ‣ Configurare Comenzi Rapide...)

Plugin-uri Python

QGIS permite îmbunătățirea funcționalităților sale, prin intermediul plugin-urilor. Acest lucru a fost inițial posibil numai cu ajutorul limbajului C. O dată cu adăugarea în QGIS a suportului pentru Python, a devenit posibilă folosirea de plugin-uri scrise în Python. Principalul avantaj față de plugin-urile în C constă în simplitatea distribuției (nu este necesară compilarea pentru fiecare platformă), iar dezvoltarea este mai ușoară.

De la momentul introducerii suportului pentru Python, au fost scrise multe plugin-uri, care acoperă diverse funcționalități. Instalatorul de plugin-uri facilitează utilizatorilor instalarea, actualizarea și eliminarea plugin-urilor Python. Parcurgeți pagina Depozitele de Plugin-uri Python pentru a descoperi diverse surse de plugin-uri.

Crearea de plugin-uri în Python este simplă, instrucțiuni detaliate găsindu-se în :ref: developing_plugins.

Aplicații Python

Adesea, atunci când are loc procesarea unor date GIS, este recomandabilă crearea unor script-uri pentru automatizarea procesului, în locul repetării anevoioase a acelorași pași. Folosind PyQGIS, acest lucru este perfect posibil — importați modulul qgis.core, îl inițializați, apoi sunteți gata de procesare.

Sau poate că doriți să creați o aplicație interactivă care utilizează unele funcționalități GIS — cum ar fi măsurarea anumitor date, exportarea unei hărți în format PDF sau orice altceva. Modulul qgis.gui aduce diverse componente GUI suplimentare, în special controlul grafic pentru canevas, care poate fi foarte ușor încorporat în aplicații, oferind suport pentru instrumentele de transfocare, deplasare și/sau pentru oricare alt instrument de hartă, personalizabil.

Using PyQGIS in custom application

Notă: nu utilizați qgis.py ca nume pentru script-ul de test — în acest caz Python nu va fi capabil să importe legăturile.

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()

Acum puteți lucra cu API-ul QGIS — să încărcați straturile, să faceți unele prelucrări sau să startați un GUI cu un canevas pentru hartă. Posibilitățile sunt nelimitate :-)

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()

Rularea Aplicațiilor Personalizate

Trebuie să indicați sistemului dvs. unde să caute bibliotecile QGIS și modulele Python corespunzătoare, atunci când acestea nu se află într-o locație standard — altfel, Python vă va notifica:

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

Acest lucru se poate remedia prin setarea variabilei de mediu PYTHONPATH. În următoarele comenzi, qgispath ar trebui să fie înlocuit de calea instalării actuale de QGIS:

  • în Linux: export PYTHONPATH=/qgispath/share/qgis/python

  • în Windows: set PYTHONPATH=c:\qgispath\python

Deși calea către modulele PyQGIS este de acum cunoscută, ele depind totuși de bibliotecile qgis_core și qgis_gui (modulele Python servesc numai pentru intermedierea apelării). Calea către aceste biblioteci este de obicei necunoscută sistemului de operare, astfel că veți obține iarăși o eroare de import (mesajul putând varia în funcție de sistem):

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

Remediați acest lucru prin adăugarea directoarelor în care rezidă bibliotecile QGIS la calea de căutare a editorului de legături:

  • în Linux: export LD_LIBRARY_PATH=/qgispath/lib

  • în Windows: set PATH=C:\qgispath;%PATH%

Aceste comenzi pot fi puse într-un script bootstrap, care se va ocupa de pornire. Atunci când livrați aplicații personalizate folosind PyQGIS, există, de obicei, două variante:

  • să cereți utilizatorului să instaleze QGIS pe platforma sa înainte de a instala aplicația dumneavoastră. Programul de instalare al aplicației ar trebui să caute locațiile implicite ale bibliotecilor QGIS și să permită utilizatorului setarea căii, în cazul în care ea nu poate fi găsită. Deși această abordare are avantajul de a fi mai simplă, este nevoie ca utilizatorul să parcurgă mai multe etape.

  • să împachetați QGIS împreună cu aplicația dumneavoastră. Livrarea aplicației poate fi mai dificilă deoarece pachetul va fi foarte mare, dar utilizatorul va fi salvat de povara de a descărca și instala software suplimentar.

Cele două modele pot fi combinate - puteți distribuiți aplicații independente pe Windows și Mac OS X, lăsând la îndemâna utilizatorului și a managerului de pachete instalarea QGIS pe Linux.