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

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.

Există mai multe modalități de a crea legături între QGIS și Python, acestea fiind detaliate în următoarele secțiuni:

  • 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

Legăturile cu Python sunt, de asemenea, disponibile pentru QGIS Server:

  • începând cu versiunea 2.8, plugin-urile Python sunt, de asemenea, disponibile pentru QGIS Server (v. Plugin-urile Serverului Python)

  • începând cu versiunea 2.11 (master-ul din 2015-08-11), biblioteca Serverului QGIS are legături către Python, care pot fi utilizate pentru a încorpora QGIS Server într-o aplicație Python.

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

O metodă bună de învățare, atunci când lucrați cu plugin-uri, este de a le descărca din depozitul de plugin-uri, apoi să le examinați codul. De asemenea, folderul python/plugins/ din instalarea QGIS conține unele plugin-uri din care puteți învăța, în scopul dezvoltării unora similare, capabile să efectueze majoritatea sarcinilor comune.

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, în directorul home Python al utilizatorului (de obicei .qgis2/python) este căutat un fişier denumit startup.py, dacă acesta există atunci el va fi 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.

Note

Plugin-urile Python sunt, de asemenea, disponibile pentru QGIS Server (QGIS ca și Server de Date OGC), v. Plugin-uri Python pentru Serverul QGIS pentru mai multe detalii.

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.

Aplicațiile personalizate PyQGIS, sau script-urile de sine stătătoare, trebuie să fie configurate pentru a putea găsi resursele QGIS, cum ar fi informațiile despre proiecție, furnizorii pentru citirea straturilor vectoriale și raster etc. Resursele QGIS sunt inițializate prin adăugarea a câtorva rânduri la începutul aplicației sau script-ului. Codul de inițializalizare QGIS este similar, atât pentru aplicațiile personalizate cât și pentru script-urile de sine stătătoare, exemplele fiind prezentate mai jos.

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.

Utilizarea PyQGIS în script-uri de sine stătătoare

Pentru a starta un script independent, inițializați resursele QGIS la începutul script-ului, similar codului următor:

from qgis.core import *

# supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# create a reference to the QgsApplication, setting the
# second argument to False disables the GUI
qgs = QgsApplication([], False)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing algorithms, etc.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

Începem prin importarea modulului qgis.core, urmată de configurarea prefixului căii. Prefixul căii este reprezentat de locația în care este instalat QGIS pe sistemul dumneavoastră. Configurarea sa în cadrul script-ului are loc prin apelarea metodei setPrefixPath. Al doilea argument al lui setPrefixPath este setat pe TRUE, care stabilește dacă sunt folosite căile implicite.

Calea de instalare a QGIS variază în funcție de platformă; cel mai simplu mod de a o identifica pe cea din sistemul dvs. este de a utiliza Consola Python din interiorul QGIS și analizând rezultatul generat de execuția QgsApplication.prefixPath().

După configurarea căii prefixului, în variabila qgs vom salva o referință către QgsApplication. Al doilea argument este setat la False, ceea ce indică faptul că nu avem de gând să utilizăm un GUI, atât timp cât dorim să scriem un script de sine stătător. Având QgsApplication configurată, vom încărca furnizorii de date QGIS și registrul stratului, prin apelarea metodei qgs.initQgis(). Aplicația QGIS fiind inițializată, suntem gata să scriem restul script-ul. În cele din urmă, vom încheia printr-un apel la qgs.exitQgis(), pentru a elimina din memorie furnizorii de date și registrul stratului.

Utilizarea PyQGIS în aplicații personalizate

Singura diferență dintre Utilizarea PyQGIS în script-uri de sine stătătoare și o aplicație PyQGIS particularizată este dată de al doilea argument, la instanțierea QgsApplication. Vom transmite True în loc de``False``, pentru a indica faptul că intenționăm să utilizăm o interfață grafică.

from qgis.core import *

# supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# create a reference to the QgsApplication
# setting the second argument to True enables the GUI, which we need to do
# since this is a custom application
qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing algorithms, etc.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

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

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.