Ważne

Tłumaczenie jest wysiłkiem społeczności QGISa przyłącz się. Ta strona jest obecnie przetłumaczona w 96.34%.

1. Wprowadzenie

Ten dokument ma służyć zarówno jako samouczek, jak i przewodnik referencyjny. Chociaż nie obejmuje wszystkich możliwych przypadków użycia, powinien zapewnić dobry przegląd najważniejszych funkcji.

Udziela się zezwolenia na kopiowanie, rozpowszechniania i/lub modyfikację tego dokumentu zgodnie z zasadami Licencji GNU Wolnej Dokumentacji w wersji 1.3 lub dowolnej późniejszej wersji publikowanej przez Free Software Foundation; bez Części Stałych, bez Treści Przedniej Okładki oraz bez Treści Tylnej Okładki.

Kopia licencji znajduje się w sekcji GNU Free Documentation License.

Niniejsza licencja obejmuje również wszystkie fragmenty kodu w tym dokumencie.

Obsługa języka Python została po raz pierwszy wprowadzona w QGIS 0.9. Istnieje kilka sposobów korzystania z Pythona w QGIS Desktop (omówionych w następujących sekcjach):

  • Wprowadzanie poleceń w konsoli Pythona w QGIS-ie

  • Tworzenie i używanie wtyczek

  • Automatyczne wykonywanie kodu Pythona przy uruchamianiu QGIS-a

  • Tworzenie algorytmów przetwarzania

  • Tworzenie funkcji do wyrażeń w QGIS-ie

  • Tworzenie własnych aplikacji opartych na QGIS API

Dostępne są również interfejsy Pythona dla QGIS Servera, w tym wtyczki Pythona (zobacz QGIS Server and Python) i interfejsy Pythona, które mogą zostać użyte do osadzenia QGIS Server w aplikacji Pythona.

Dostępny jest kompletny opis interfejsu QGIS API w języku C++ , który zawiera dokumentację klas z bibliotek QGIS-a. QGIS API w języku Python (pyqgis) jest niemal identyczne z API C++.

Innym dobrym źródłem wiedzy na temat wykonywania typowych zadań jest pobranie istniejących wtyczek z repozytorium wtyczek i przeanalizowanie ich kodu.

1.1. Tworzenie skryptów w konsoli Pythona

QGIS udostępnia zintegrowaną konsolę Pythona do tworzenia skryptów. Można ją otworzyć z poziomu menu Wtyczki ► Konsola Pythona:

../../_images/console.png

Rys. 1.11 Konsola Pythona w QGIS-ie

Zrzut ekranu powyżej przedstawia, jak pobrać warstwę aktualnie zaznaczoną na liście warstw, wyświetlić jej identyfikator oraz opcjonalnie, jeśli jest to warstwa wektorowa, wyświetlić liczbę obiektów. Do interakcji ze środowiskiem QGIS-a służy zmienna iface, która jest instancją klasy QgisInterface. Interfejs ten umożliwia dostęp do obszaru roboczego mapy, menu, pasków narzędzi i innych elementów aplikacji QGIS.

Dla wygody użytkownika poniższe polecenia są wykonywane po uruchomieniu konsoli (w przyszłości będzie możliwe ustawienie dodatkowych poleceń startowych).

from qgis.core import *
import qgis.utils

Dla osób często korzystających z konsoli przydatne może być ustawienie skrótu klawiszowego do jej uruchamiania (w menu Ustawienia► Skróty klawiszowe…).

1.2. Python Plugins

Funkcjonalność programu QGIS można rozszerzyć za pomocą wtyczek. Wtyczki można napisać w języku Python. Ich główną zaletą w porównaniu z wtyczkami napisanymi w języku C++ jest prostota dystrybucji (brak konieczności kompilacji dla każdej platformy) i łatwiejszy proces tworzenia.

Od czasu wprowadzenia obsługi języka Python powstało wiele wtyczek obejmujących różnorodne funkcjonalności. Menadżer wtyczek umożliwia użytkownikom łatwe pobieranie, aktualizowanie i usuwanie wtyczek. Więcej informacji o wtyczkach i ich tworzeniu można znaleźć na stronie poświęconej wtyczkom.

Tworzenie wtyczek w języku Python jest proste, szczegółowe instrukcje znajdziesz w rozdziale Developing Python Plugins.

Informacja

Wtyczki Pythona są również dostępne dla QGIS Server. Więcej szczegółów znajdziesz w rozdziale QGIS Server and Python.

1.2.1. Wtyczki algorytmów przetwarzania

Processing Plugins can be used to process data. They are easier to develop, more specific and more lightweight than Python Plugins. Writing a Processing plugin explains when the use of Processing algorithms is appropriate and how to develop them.

1.3. Uruchamianie kodu Pythona podczas uruchamiania QGIS-a

Istnieje kilka sposobów uruchamiania kodu w Pythona podczas uruchamiania QGIS-a.

  1. Stworzenie skryptu startup.py

  2. Ustawienie zmiennej środowiskowej PYQGIS_STARTUP w istniejącym pliku Pythona

  3. Wskazanie skryptu startowego za pomocą parametru --code init_qgis.py

1.3.1. Skrypt startup.py

Przy każdym uruchomieniu QGIS-a katalog domowy Pythona użytkownika oraz lista ścieżek systemowych są przeszukiwane w celu odnalezienia pliku startup.py. Jeśli ten plik istnieje, jest uruchamiany przez wbudowany interpreter Pythona.

Ścieżka do katalogu domowego użytkownika zazwyczaj znajduje się w:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

Domyślne ścieżki systemowe zależą od systemu operacyjnego. Aby sprawdzić, jakie ścieżki są w Twoim przypadku prawidłowe, otwórz konsolę Pythona i uruchom polecenie QStandardPaths.standardLocations(QStandardPaths.AppDataLocation), aby wyświetlić listę domyślnych katalogów.

Skrypt startup.py jest uruchamiany natychmiast po zainicjowaniu środowiska Python w programie QGIS, na samym początku uruchamiania aplikacji.

1.3.2. Zmienna środowiskowa PYQGIS_STARTUP

Możesz uruchomić kod Pythona tuż przed zakończeniem inicjalizacji QGIS-a, ustawiając zmienną środowiskową PYQGIS_STARTUP na ścieżkę do istniejącego pliku Pythona.

This code will run before QGIS initialization is complete. This method is very useful for cleaning sys.path, which may have undesirable paths, or for isolating/loading the initial environment without requiring a virtual environment, e.g. homebrew or MacPorts installs on Mac.

1.3.3. Parametr --code

Możesz dostarczyć własny kod do wykonania jako parametr startowy programu QGIS. W tym celu utwórz plik Pythona, np. qgis_init.py, a następnie uruchom QGIS z poziomu wiersza poleceń za pomocą polecenia qgis --code qgis_init.py.

Kod przekazany za pomocą flagi --code jest wykonywany pod koniec fazy inicjalizacji programu QGIS, po załadowaniu wszystkich komponentów aplikacji.

1.3.4. Dodatkowe argumenty kodu Pythona

Aby przekazać dodatkowe argumenty dla skryptu --code lub innego wykonywanego kodu Pythona, można użyć argumentu --py-args. Każdy argument umieszczony po --py-args i przed argumentem -- (jeśli występuje), zostanie przekazany do Pythona, ale zignorowany przez samą aplikację QGIS.

W poniższym przykładzie plik myfile.tif będzie dostępny poprzez sys.argv w Pythonie, ale nie zostanie załadowany przez QGIS-a. Natomiast plik otherfile.tif zostanie załadowany przez QGIS, ale nie będzie widoczny w sys.argv.

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

Jeśli chcesz uzyskać dostęp do wszystkich parametrów wiersza poleceń z poziomu Pythona, możesz użyć QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. Aplikacje Pythona

Często przydaje się tworzenie skryptów do automatyzacji procesów. Z PyQGIS jest to całkowicie możliwe — wystarczy zaimportować moduł qgis.core, zainicjować go i można przystąpić do przetwarzania.

Możesz też stworzyć interaktywną aplikację wykorzystującą funkcje GIS - wykonywanie pomiarów, eksportowanie mapy do formatu PDF… Moduł qgis.gui udostępnia różne komponenty GUI, w szczególności płótno mapy, które można zintegrować z aplikacją wraz z obsługą powiększania, przesuwania i/lub dodatkowych niestandardowych narzędzi mapy.

Niestandardowe aplikacje PyQGIS lub samodzielne skrypty muszą być skonfigurowane tak, aby mogły zlokalizować zasoby QGIS-a, takie jak informacje o projekcji i sterownikach do odczytu warstw wektorowych i rastrowych. Zasoby QGIS są inicjowane poprzez dodanie kliku linijek kodu na początku aplikacji lub skryptu. Kod służący do inicjalizacji QGIS-a w niestandardowych aplikacjach i samodzielnych skryptach jest podobny, Przykłady każdego z nich są podane poniżej.

Informacja

Nie używaj qgis.py jako nazwy twojego skryptu. Python nie będzie w stanie zaimportować zależności ponieważ nazwa skryptu je przysłoni.

1.4.1. Korzystanie z PyQGIS w samodzielnych skryptach

Aby uruchomić samodzielny skrypt, zainicjuj zasoby QGIS na początku skryptu:

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

Na początku importujemy moduł qgis.core i konfigurujemy prefiks ścieżki. Ścieżka prefiksu to lokalizacja, w której QGIS został zainstalowany w systemie. Jest konfigurowana w skrypcie poprzez wywołanie metody setPrefixPath() . Drugi argument setPrefixPath() jest ustawiony na True, co oznacza, że mają być używane domyślne ścieżki.

Ścieżka instalacji QGIS-a różni się w zależności od platformy; najłatwiejszym sposobem na jej znalezienie w systemie jest skorzystanie z Tworzenie skryptów w konsoli Pythona w QGIS-ie i sprawdzenie wyniku wykonania następującego polecenia:

QgsApplication.prefixPath()

Po skonfigurowaniu ścieżki prefiksu, zapisujemy odwołanie do QgsApplication pod zmienną qgs. Drugi argument jest ustawiony na False, co oznacza, że nie planujemy korzystać z interfejsu graficznego, ponieważ piszemy samodzielny skrypt. Po skonfigurowaniu QgsApplication ładujemy sterowniki dostawców danych i rejestr warstw, wywołując metodę initQgis().

qgs.initQgis()

Po zainicjowaniu QGIS-a jesteśmy gotowi do napisania reszty skryptu. Na koniec wywołujemy metodę exitQgis(), aby usunąć dostawców danych i rejestr warstw z pamięci.

qgs.exitQgis()

1.4.2. Wykorzystanie PyQGIS w aplikacjach dedykowanych

Jedyną różnicą między Korzystanie z PyQGIS w samodzielnych skryptach a aplikacją dedykowaną jest drugi argument przekazywany podczas tworzenia instancji QgsApplication. Należy przekazać True zamiast False, aby wskazać, że planujemy użyć GUI.

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

Teraz możesz korzystać z QGI API - wczytywać warstwy i wykonywać przetwarzanie lub uruchamiać interfejs graficzny z obszarem roboczym mapy. Możliwości są nieograniczone :-)

1.4.3. Uruchamianie aplikacji dedykowanych

Musisz wskazać swojemu systemowi, gdzie szukać bibliotek QGIS-a i odpowiednich modułów Pythona, jeśli nie znajdują się w znanej lokalizacji - w przeciwnym razie Python wyświetli komunikat o błędzie:

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

Można to naprawić poprzez ustawienie zmiennej środowiskowej PYTHONPATH. W poniższych poleceniach <qgispath> należy zastąpić rzeczywistą ścieżką instalacji QGIS-a:

  • na Linuxie: export PYTHONPATH=/<qgispath>/share/qgis/python

  • na Windowsie: set PYTHONPATH=c:\<qgispath>\python

  • na macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Teraz ścieżka do modułów PyQGIS jest znana, ale są one zależne od bibliotek qgis_core i qgis_gui (moduły Pythona służą jedynie jako nakładki). Ścieżka do tych bibliotek może być nieznana systemowi operacyjnemu i wówczas ponownie pojawi się błąd importu (komunikat może różnić się w zależności od systemu):

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

Można to naprawić, dodając katalogi, w których znajdują się biblioteki QGIS-a, do ścieżki wyszukiwania dynamicznego linkera:

  • na Linuxie: export LD_LIBRARY_PATH=/<qgispath>/lib

  • na Windowsie: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH%, gdzie <qgisrelease> należy zastąpić typem wydania, do którego się odwołujesz (eg, qgis-ltr, qgis, qgis-dev)

Te polecenia można umieścić w skrypcie startowym, który zajmie się inicjalizacją aplikacji. Podczas wdrażania niestandardowych aplikacji przy użyciu PyQGIS zazwyczaj istnieją dwie możliwości:

  • wymaganie od użytkownika zainstalowania QGIS przed zainstalowaniem twojej aplikacji. Instalator aplikacji powinien wyszukać domyślne lokalizacje bibliotek QGIS-a i umożliwić użytkownikowi ustawić ścieżkę, jeśli nie zostanie odnaleziona. To podejście ma tę zaletę, że jest prostsze, jednak wymaga od użytkownika wykonania kilku dodatkowych kroków.

  • spakowanie QGIS-a razem z aplikacją. Wydanie aplikacji może być trudniejsze, a pakiet będzie większy, ale użytkownik uniknie kłopotu związanego z pobieraniem i instalowaniem dodatkowego oprogramowania.

Oba modele wdrażania można ze sobą łączyć. Możesz dostarczać samodzielne aplikacje na Windowsa i macOS, ale na Linuxie pozostawić instalację GIS użytkownikowi i jego menadżerowi pakietów.

1.5. Uwagi techniczne dotyczące PyQt i SIP

Zdecydowaliśmy się na Pythona, ponieważ jest to jeden z najpopularniejszych języków skryptowych. Powiązania PyQGIS w QGIS 3 zależą od SIP i PyQt5. Powodem wykorzystania SIP zamiast powszechniej używanego SWIG jest to, że kod QGIS-a opiera się na bibliotekach Qt. Powiązania Pythona z Qt (PyQt) są tworzone przy użyciu SIP, co pozwala na bezproblemową integrację PyQGIS z PyQt,