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

.

Verarbeitung Algorithmen von der Konsole aus verwenden

Die Konsole ermöglicht es fortgeschrittenen Anwendern ihre Produktivität zu erhöhen und komplexe Operationen, die nicht anhand eines der GUI Elemente der Verarbeitung Umgebung ausgeführt werden können, durchzuführen. Modelle mit mehreren Algorithmen können anhand der Kommandozeilenssschnittstelle definiert werden und zusätzliche Operationen wie Schleifen und Bedingungssätze können hinzugefügt werden, um flexiblere und leistungsfähigere Workflows zu erstellen.

Es gibt in QGIS keine Verarbeitung Konsole, aber alle Verarbeitung Befehle stehen anstelledessen in der eingebauten QGIS Python Konsole zur Verfügung. Das heisst dass Sie diese Befehle in Ihre Konsolenarbeit integrieren können und Verarbeitung Algorithmen mit allen anderen dort zur Verfügung stehenden Objekten (einschließlich Methoden aus der QGIS API) verbinden können.

Der Code den Sie von der Python Konsole aus ausführen können, auch wenn er keine spezifische Verarbeitung Methode aufruft, kann in einen neuen Algorithmus überführt werden den Sie später aus der Werkzeugkiste, der Grafischen Modellierung oder jeder anderen Komponente aufrufen können, so wie Sie es mit jedem anderen Algorithmus tun würden. In der Tat sind einige Algorithmen, die Sie in der Werkzeugkiste finden können einfache Scripte.

In diesem Abschnitt werden wir uns angucken wie man Verarbeitung Algorithmen aus der QGIS Python Konsole heraus verwendet und auch wie man Algorithmen in Python schreibt.

Algorithmen von der Python Konsole aus aufrufen

Das erste, was Sie machen müssen, ist die Verarbeitung Funktionen mit der folgenden Zeile importieren:

>>> import processing

Nun gibt es im Grunde nur eine (interessante) Sache, die Sie damit von der Konsole aus tun können: einen Algorithmus ausführen. Das wird anhand der runalg()``Methode gemacht, die den Namen des Algorithmus nimmt um ihn als seinen ersten Parameter auszuführen und dann eine variable Anzahl von zusätzlichen Parametern abhängig von den Anforderungen des Algorithmus. Das erste was Sie also wissen müssen ist der Name des Algorithmus, der ausgeführt werden soll. Das ist nicht der Name, den Sie in der Werkzeugkiste sehen können, sondern ein eindeutiger Kommandozeilenname. Um den richtigen Namen für Ihren Algorithmus zu finden, können Sie die ``algslist() Methode verwenden. Geben Sie den folgenden Satz in Ihre Konsole ein:

>>> processing.alglist()

Sie werden etwas wie dieses sehen.

Accumulated Cost (Anisotropic)---------------->saga:accumulatedcost(anisotropic)
Accumulated Cost (Isotropic)------------------>saga:accumulatedcost(isotropic)
Add Coordinates to points--------------------->saga:addcoordinatestopoints
Add Grid Values to Points--------------------->saga:addgridvaluestopoints
Add Grid Values to Shapes--------------------->saga:addgridvaluestoshapes
Add Polygon Attributes to Points-------------->saga:addpolygonattributestopoints
Aggregate------------------------------------->saga:aggregate
Aggregate Point Observations------------------>saga:aggregatepointobservations
Aggregation Index----------------------------->saga:aggregationindex
Analytical Hierarchy Process------------------>saga:analyticalhierarchyprocess
Analytical Hillshading------------------------>saga:analyticalhillshading
Average With Mask 1--------------------------->saga:averagewithmask1
Average With Mask 2--------------------------->saga:averagewithmask2
Average With Thereshold 1--------------------->saga:averagewiththereshold1
Average With Thereshold 2--------------------->saga:averagewiththereshold2
Average With Thereshold 3--------------------->saga:averagewiththereshold3
B-Spline Approximation------------------------>saga:b-splineapproximation
...

Das ist eine Liste von allen zur Verfügung stehenden Algorithmen, alfabetisch geordnet, zusammen mit ihren entsprechenden Kommandozeilennamen.

Sie können einen String als Parameter für diese Methode benutzen. Statt die ganze Liste von Algorithmen herauszugeben wird sie nur die zeigen die diesen String enthalten. Wenn Sie beispielsweise nach einem Algorithmus zum Berechnen der Hangneigung aus einem DEM suchen, geben Sie alglist("slope") ein, um folgendes Ergebnis zu erhalten:

DTM Filter (slope-based)---------------------->saga:dtmfilter(slope-based)
Downslope Distance Gradient------------------->saga:downslopedistancegradient
Relative Heights and Slope Positions---------->saga:relativeheightsandslopepositions
Slope Length---------------------------------->saga:slopelength
Slope, Aspect, Curvature---------------------->saga:slopeaspectcurvature
Upslope Area---------------------------------->saga:upslopearea
Vegetation Index[slope based]----------------->saga:vegetationindex[slopebased]

Dieses Ergebnis kann sich abhängig von den Ihnen zur Verfügung stehenden Algorithmen ändern.

Es ist jetzt einfacher den Algorithmus und seinem Kommandozeilennamen, nach dem Sie suchen, zu finden, in diesem Fall saga:slopeaspectcurvature.

Wenn Sie erstmal den Kommandozeilennamen des Algorithmus wissen ist das nächste, was Sie tun müssen die richtige Syntax, um ihn auszuführen, zu bestimmen. Das heißt zu wissen welche Parameter benötigt werden und die Reihenfolge, in der sie eingegeben werden müssen, wenn die runalg() Methode aufgerufen wird. Es gibt eine Methode, um den Algorithmus im Detail zu beschreiben, die dazu benutzt werden kann um eine Liste von Parametern, die ein Algorihmus erfordert und die Ausgaben, die er erzeugt, zu erstellen. Um diese Information zu erhalten können Sie die alghelp(name_of_the_algorithm) Methode verwenden. Verwenden Sie den Kommandozeilennamen des Algorithmus, nicht den vollen beschreibenden Namen.

Wenn Sie die Methode mit saga:slopeaspectcurvature als Parameter aufrufen erhalten Sie die folgende Beschreibung:

>>> processing.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
   ELEVATION <ParameterRaster>
   METHOD <ParameterSelection>
   SLOPE <OutputRaster>
   ASPECT <OutputRaster>
   CURV <OutputRaster>
   HCURV <OutputRaster>
   VCURV <OutputRaster>

Jetzt haben Sie alles was Sie brauchen um einen Algorithmus auszuführen. Wie wir bereits erwähnt haben, gibt es nur einen einzigen Befehl um einen Algorithmus auszuführen: runalg(). Seine Syntax ist wie folgt:

>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
         Output1, Output2, ..., OutputN)

Die Liste von Parametern und Ausgaben hängen von dem Algorithmus den Sie ausführen wollen ab und ist genau die Liste die die alghelp() Methode Ihnen herausgibt, in der gleichen Reihenfolge wie gezeigt.

Abhängig vom Parametertyp werden Werte verschieden eingeführt. Die nächste Liste gibt einen kurzen Überblick darüber wie man Werte für jeden Typ von Eingabeparameter einführt:

  • Rasterlayer, Vektorlayer oder Tabelle. Verwenden Sie einfach einen String mit dem Namen, der das zu verwendende Datenobjekt (den Namen, den es im QGIS Inhaltsverzeichnis hat) identifiziert oder einen Dateinamen (wenn der entsprechende Layer nicht geöffnet ist, wird er geöffnet aber nicht dem Kartenfenster hinzugefügt). Wenn Sie eine Instanz eines QGIS Objektes, das den Layer repräsentiert, haben, können Sie es als Parameter eingeben. Wenn der Input optional ist und Sie kein Datenobjekt verwenden wollen, benutzen Sie None.

  • Auswahl. Wenn ein Algorithmus einen Auswahlparameter besitzt, sollte der Wert des Parameters eingegeben werden, indem man einen Integerwert verwendet. Um die zur Verfügung stehenden Optionen zu ermitteln, können Sie den algoptions() Befehl verwenden, wie im folgenden Beispiel gezeigt:

    >>> processing.algoptions("saga:slopeaspectcurvature")
    METHOD(Method)
        0 - [0] Maximum Slope (Travis et al. 1975)
        1 - [1] Maximum Triangle Slope (Tarboton 1997)
        2 - [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
        3 - [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
        4 - [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
        5 - [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
        6 - [6] Fit 3.Degree Polynom (Haralick 1983)
    

    In diesem Fall hat der Algorithmus einen solchen Parameter mit sieben Optionen. Beachten Sie dass die Bearbeitungsreihenfolge bei null anfängt.

  • Multiple input. Der Wert ist ein String mit Eingabebeschreibungen getrennt durch Semikolons (;). Wie im Fall von einfachen Layern oder Tabellen kann jede Eingabebeschreibung der Datenobjektname oder sein Dateipfad sein.

  • Tabellen Feld von XXX. Verwenden Sie einen String mit dem Namen des Feldes, das benutzt werden soll. Dieser Parameter unterscheidet zwischen Groß- und Kleinschreibung.

  • Fixed Table. Geben Sie die Liste aller Tabellenwerte, die durch Kommas (,) getrennt sind und zwischen Anführungsstrichen (") eingeschlossen sind. Die Werte beginnen in der oberen Zeile und gehen von links nach rechts. Sie können auch einen 2D-Array von Werten, die die Tabelle repräsentieren, verwenden.

  • CRS. Geben Sie den EPSG Code des gewünschten KBS ein.

  • Extent. Sie müssen einen String mit xmin, xmax, ymin und ymax Werten getrennt durch Kommas (,) eingeben.

Boolean, file, string und numerical parameters brauchen keien zusätzlichen Erläuterungen.

Input parameters such as strings, booleans, or numerical values have default values. To use them, specify None in the corresponding parameter entry.

Für Ausgabedatenobjekte geben Sie den Dateipfad, der benutzt wird um es zu speichern, ein, genauso wie es in der Werkzeugkiste gemacht wird. Wenn Sie das Ergebnis in einer temporären Datei speichern wollen, verwenden sie None. Die Erweiterung der Datei bestimmt das Dateiformat. Wenn Sie eine Dateierweiterung, die nicht vom Algorithmus unterstützt wird, eingeben, wird das Standarddateiformat für den Ausgabetyp verwendet und seine entsprechende Erweiterung an den gebebenen Dateipfad angehängt.

Im Gegensatz zum Ausführen aus der Werkzeugkiste werden Ausgaben nicht zum Kartenfenster hinzugefügt, wenn Sie den gleichen Algorithmus aus der Python Konsole ausführen. Wenn Sie eine Ausgabe dem Kartenfenster hinzufügen wollen, müssen Sie das selber nach dem Ausführen des Algorithmus machen. Sie können dafür QGIS API Befehle, oder noch einfacher eine der praktischen Methoden, die für solche Aufgaben bereitgestellt werden, verwenden.

Die runalg Methode gibt ein Wörterbuch mit den Ausgabenamen (diejenigen die in the Algorithmusbeschreibung gezeigt werden) als Schlüssel und die Dateipfade dieser Ausgaben als Werte zurück. Sie können diese Layer laden indem Sie die entsprechenden Dateipfade an die load() Methode übergeben.

Zusätzliche Funktionen für den Umgang mit Daten

Abgesehen von den Funktionen, die verwendet werden um Algorithmen aufzurufen, importiert das Importieren des ``processing` Paketes einige zusätzliche Funktionen, die es einfacher machen mit Daten zu arbeiten, insbesondere Vektordaten. Sie sind einfach Komfortfunktionen, die etwas Funktionalität aus der QGIS API zusammenfassen, für gewöhnlich mit einer weniger komplexen Syntax. Diese Funktionen sollten verwendet werden wenn neue Algorithmen entwickelt werden, das sie es einfacher machen mit den Eingabedaten zu verfahren.

Unten steht eine Liste mit diesen Befehlen. Mehr Informationen können Sie in den Klassen im processing/tools Paket und auch in den Beispielscripts, die mit QGIS bereitgestellt werden, finden.

  • getObject(obj): Returns a QGIS object (a layer or table) from the passed object, which can be a filename or the name of the object in the QGIS Table of Contents.
  • values(layer, fields): Gibt die Werte für die zutreffenden Felder aus der Attributtabelle eines Vektorlayers zurück. Felder können als Feldnamen oder als null-basierte Feldindizes zurückgegeben werden. Es gibt ein Wörterbuch von Listen zurück, mit den zurückgegebenen Feld Identifiers als Schlüssel. Es wird die bestehende Auswahl berücksichtigt.

  • features(layer): Returns an iterator over the features of a vector layer, considering the existing selection.
  • uniqueValues(layer, field): Returns a list of unique values for a given attribute. Attributes can be passed as a field name or a zero-based field index. It considers the existing selection.

Scripte erstellen und diese aus der Werkzeugkiste starten.

Sie können Ihre eigenen Algorithmen erstellen indem Sie entsprechenden Python Code schreiben und einige zusätzliche Zeilen schreiben um zusätzliche Informationen, die benötigt werden um die Semantik des Algorithmus zu definieren, zu liefern. Sie können ein Create new script Menü in der Tools Gruppe im Script Algorithmus Block der Werkzeugkiste finden. Machen Sie einen Doppelklick darauf um den Skripteditor Dialog zu öffnen. Dort sollten Sie Ihren Code eingeben. Wenn Sie von dort aus mit der Erweiterung .py in den Ordner scripts (der Standardordner wenn Sie den Datei speichern Dialog öffnen) speichern wird automatisch ein entsprechender Algorithmus erstellt.

Der Name des Algorithmus (derjenige den Sie in der Werkzeugkiste sehen) wird aus dem Dateinamen erstellt, seine Erweiterung entfernt und Unterstriche mit Leerzeichen ersetzt.

Lassen Sie uns einen Blick auf den folgenden Code, der den Topographic Wetness Index (TWI) direkt von einem DGM berechnet, werfen.

##dem=raster
##twi=output
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

Wie Sie sehen können beinhaltet die Berechnung drei Algorithmen, die alle aus SAGA kommen. Der letzte davon berechnet den TWI, er braucht aber einen Hangneigungslayer und einen Abflussakkumulationslyer. Diese Layer haben wir nicht, aber da ein DGM zur Verfügung steht, können wir sie berechnen indem wir die entsprechenden SAGA Algorithmen aufrufen.

Der Teil des Codes wo dieses Verarbeiten stattfindet ist nicht schwer zu verstehen wenn Sie die vorherigen Abschnitte in diesem Kapitel gelesen haben. Die ersten Zeilen jedoch erfordern einige zusätzliche Erklärungen. Sie stellen Informationen, die für das Umwandeln Ihres Codes in einen Algorithmus, der von jeder der GUI Komponenten, wie die Werkzeugkiste oder die Grafische Modellierung, ausgeführt werden kann, zur Verfügung.

Diese Zeilen beginnen mit einem doppelten Python Kommentar (``##`) und haben die folgende Struktur:

[parameter_name]=[parameter_type] [optional_values]

Hier ist eine Liste von allen Parametertypen, die in Verarbeitung Scripts unterstützt werden, mit Ihrer Syntax und einigen Beispielen.

  • raster. Ein Rasterlayer.

  • vector. Ein Vektorlayer.

  • table. Eine Tabelle.

  • number. Ein numerischer Wert. Es muss ein Standardwert vergeben werden. Beispielsweise depth=number 2.4.

  • string. Ein Text String. Wie im Fall von numerischen Werten muss ein Standardwert eingefügt werden. Beispielsweise name=string Victor.

  • boolean. Ein boolscher Wert. Geben Sie True oder False danach ein um den Standardwert zu setzen. Zum Beispiel verbose=boolean True.

  • multiple raster. Ein Satz von Eingaberasterlayern.

  • multiple vector. Ein Satz von Eingabevektorlayern.

  • field. Ein Feld in der Attributtabelle eines Vektorlayers. Der Name des Layers muss nach dem field Tag hinzugefügt werden. Beispielsweise wenn Sie eine Vektoreingabe mit mylayer=vector deklariert haben, könnten Sie myfield=field mylayer verwenden um ein Feld dieses Layers als Parameter hinzuzufügen.

  • folder. Ein Ordner.

  • file. Ein Dateiname.

Der Parametername ist der Name, der dem Anwender gezeigt wird wenn er den Algorithmus ausführt und gleichzeitig der Variablenname der verwendet werden muss, um den Script Code zu verwenden.

Wenn der Name des Parameters dem Anwender gezeigt wird, wird der Name bearbeitet um seine Erscheinung zu verbessern, dabei werden Unterstriche mit Leerzeilen ersetzt. Wenn Sie also beispielsweise wollen, dass der Anwender einen Parameter mit Namen A numerical value sieht, können Sie den Variablennamen A_numerical_value verwenden.

Layer und Tabellenwerte sind Strings, die einen Dateipfad des entsprechenden Objekts enthalten. Um Sie zu einem QGIS Objekt zu machen können Sie die processing.getObjectFromUri() Funktion verwenden. Mehrfacheingaben haben auch einen String Wert, welcher die Dateipfade zu allen ausgewählten Objekten, getrennt durch Semikolons (;), enthält.

Ausgaben werden auf ähnliche Weise mit Hilfe der folgenden Tags definiert:

  • output raster
  • output vector
  • output table
  • output html
  • output file
  • output number
  • output string

Der der Ausgabevariable zugewiesene Wert ist immer ein String mit einem Dateipfad. Er entspricht einem temporären Dateipfad wenn der Anwender nicht einen Ausgabedateinamen eingegeben hat.

Wenn Sie eine Ausgabe deklarieren wird der Algorithmus versuchen ihn zu QGIS hinzuzufügen nachdem sie beendet wurde. Darum wird auch, trotzdessen die runalg() Methode nicht die Layer, die sie produziert, lädt, der endgültige TWI Layer geladen (indem der Fall unseres vorherigen Beispiels verwendet wird), da er in die Datei gespeichert wird, die von Anwender eingegeben wird, welche der Wert der entsprechenden Ausgabe ist.

Verwenden Sie die load() Methode nicht in Ihren Script Algorithmen, nur wenn Sie mit der Kommandozeile arbeiten. Wenn ein Layer als Ausgabe eines Algorithmus erstellt wird, sollte er als solcher deklariert sein. Andernfalls werden Sie nicht in der Lage sein den Algorithmus richtig in der Modellierung zu verwenden, da seine Syntax (die oben erklärt durch Tags definiert wird) nicht das treffen wird was der Algorithmus wirklich erstellt.

Versteckte Ausgaben (Nummern und Strings) haben keinen Wert. Anstelledessen müssen Sie ihnen einen Wert zuweisen. Um das zu tun setzen Sie einfach den Wert einer Variablen mit dem Namen, den Sie verwendet haben, um die Ausgabe zu deklarieren. Wenn Sie beispielsweise diese Deklaration verwendet haben,

##average=output number

die folgende Zeile setzt den Wert der Ausgabe auf 5:

average = 5

Zusätzlich zu den Tags für Parameter und Ausgaben können Sie zusätzlich die Gruppe, in der der Algorithmus dann gezeigt wird, definieren, indem Sie den group Tag benutzen.

Wenn Ihr Algorithmus lange Zeit zum Berechnen braucht ist es eine gute Idee den Anwender zu benachrichtigen. Es steht Ihnen eine Globale genannt progress mit zwei möglichen Methoden zur Verfügung: setText(text) und setPercentage(percent) mit denen Sie den progress Text und die progress Leiste verändern können.

Mehrere Beispiele werden zur Verfügung gestellt. Bitte gehen Sie sie durch um anhand von echten Beispielen zu erfahren wie man Algorithmen anhand der Verarbeitung Umgebung Klassen erstellt. Sie können auf jeden Script Algorithmus rechtklicken und Edit script wählen um seinen Code anzuschauen oder ihn zu bearbeiten.

Ihre Scripte dokumentieren

Wie bei Modellen können Sie zusätzliche Dokumentationen für Ihre Scripts erstellen, um zu erklären was sie tun und wie man sie benutzen kann. Im Skript-Editor Dialog werden Sie einen [Skripthilfe bearbeiten] Knopf finden. Klicken Sie darauf und er wird Sie zum Hilfe-Editor Dialog bringen. Gehen Sie den Abschnitt über die Grafische Modellierung durch um mehr über diesen Dialog und seine Anwendung zu erfahren.

Hilfedateien werden in dem gleichen Ordner wie das Script selber unter Hinzufügen der .help Erweiterung gespeichert. Beachten Sie dass Sie Ihre Script Hilfe bearbeiten können bevor Sie das Script zum ersten Mal speichern. Wenn Sie später den Script-Editor Dialog ohne das Script zu speichern (z.B. wenn Sie es verwerfen) schließen geht der Hilfeinhalt, den Sie geschrieben haben, verloren. Wenn Ihr Script bereits gespeichert wurde und mit einem Dateinamen versehen wurde, läuft das Speichern des Hilfeinhalts automatisch ab.

Pre- und Post-execution Script Hooks

Scripts können auch verwendet werden um Pre- und Post-execution Hooks, die vor und nach einem Algorithmus ausgeführt werden, zu setzen. Dies kann dafür benutzt werden um Aufgaben zu automatisieren wann immer ein Algorithmus ausgeführt wird.

Die Syntax ist identisch zu der oben erklärten Syntax, es steht aber eine zusätzliche Globalvariable genannt alg zur Verfügung, die den Algorithmus, der gerade ausgeführt wurde (oder ausgeführt wird), repräsentiert.

In der General Gruppe des Verarbeitungsoptionen Dialogs finden Sie zwei Einträge genannt Pre-execution script und Post-execution script wo die Dateinamen der Scripts, die ausgeführt werden sollen, in jedem Fall eingegeben werden können.