Ważne

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

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. Using PyQGIS in standalone scripts

To start a standalone script, initialize the QGIS resources at the beginning of the script:

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

First we import the qgis.core module and configure the prefix path. The prefix path is the location where QGIS is installed on your system. It is configured in the script by calling the setPrefixPath() method. The second argument of setPrefixPath() is set to True, specifying that default paths are to be used.

The QGIS install path varies by platform; the easiest way to find it for your system is to use the Tworzenie skryptów w konsoli Pythona from within QGIS and look at the output from running:

QgsApplication.prefixPath()

After the prefix path is configured, we save a reference to QgsApplication in the variable qgs. The second argument is set to False, specifying that we do not plan to use the GUI since we are writing a standalone script. With QgsApplication configured, we load the QGIS data providers and layer registry by calling the initQgis() method.

qgs.initQgis()

With QGIS initialized, we are ready to write the rest of the script. Finally, we wrap up by calling exitQgis() to remove the data providers and layer registry from memory.

qgs.exitQgis()

1.4.2. Using PyQGIS in custom applications

The only difference between Using PyQGIS in standalone scripts and a custom PyQGIS application is the second argument when instantiating the QgsApplication. Pass True instead of False to indicate that we plan to use a 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()

Now you can work with the QGIS API - load layers and do some processing or fire up a GUI with a map canvas. The possibilities are endless :-)

1.4.3. Running Custom Applications

You need to tell your system where to search for QGIS libraries and appropriate Python modules if they are not in a well-known location - otherwise Python will complain:

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

This can be fixed by setting the PYTHONPATH environment variable. In the following commands, <qgispath> should be replaced with your actual QGIS installation path:

  • on Linux: export PYTHONPATH=/<qgispath>/share/qgis/python

  • on Windows: set PYTHONPATH=c:\<qgispath>\python

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

Now, the path to the PyQGIS modules is known, but they depend on the qgis_core and qgis_gui libraries (the Python modules serve only as wrappers). The path to these libraries may be unknown to the operating system, and then you will get an import error again (the message might vary depending on the system):

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

Fix this by adding the directories where the QGIS libraries reside to the search path of the dynamic linker:

  • on Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

  • on Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% where <qgisrelease> should be replaced with the type of release you are targeting (eg, qgis-ltr, qgis, qgis-dev)

These commands can be put into a bootstrap script that will take care of the startup. When deploying custom applications using PyQGIS, there are usually two possibilities:

  • require the user to install QGIS prior to installing your application. The application installer should look for default locations of QGIS libraries and allow the user to set the path if not found. This approach has the advantage of being simpler, however it requires the user to do more steps.

  • package QGIS together with your application. Releasing the application may be more challenging and the package will be larger, but the user will be saved from the burden of downloading and installing additional pieces of software.

The two deployment models can be mixed. You can provide a standalone applications on Windows and macOS, but for Linux leave the installation of GIS up to the user and his package manager.

1.5. Technical notes on PyQt and SIP

We’ve decided for Python as it’s one of the most favoured languages for scripting. PyQGIS bindings in QGIS 3 depend on SIP and PyQt5. The reason for using SIP instead of the more widely used SWIG is that the QGIS code depends on Qt libraries. Python bindings for Qt (PyQt) are done using SIP and this allows seamless integration of PyQGIS with PyQt.