Schreiben neuer Verarbeitungsalgorithmen wie Python-Skripte¶

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 raster
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindextwi, 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.

• longstring. Das gleiche wie String, nur ein größeres Textfeld wird angezeigt, so ist es besser geeignet für lange Strings, wie zum Beispiel für ein Skript, um einen kleinen Code-Schnipsel zu schreiben.

• 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.

• Ausmaß. Ein räumliches Ausmaß, welches sich durch xmin, xmax, ymin, ymax definiert

• folder. Ein Ordner

• file. Ein Dateiname

• crs. Ein Koordinatensystem

• Auswahl. Ein Drop-down-Menü, dass dem Benutzer erlaubt aus einer vorgefertigten liste zu wählen. Zum Beispiel units=selection sq_km;sq_miles;sq_degrees

• Name. Name des Skripts. Dies wird als Algorithmusname gezeigt in der Verarbeitungstoolbox. Zum Beispiel My Algorithm Name=name

• Gruppe. Ordername, in dem das Skript in der Verarbeitungstoolbox erscheint. Zum Beispiel, hinzufügen von Utils=groups setzt das Skript in den Utils Ordner innerhalb des Skripts.

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
• output extent

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.

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.

Das letzte Tag, dass Sie in Ihrem Skript-Header verwenden können, ist ##nomodeler. Verwenden Sie dass, wenn Sie nicht wollen, dass Ihr Algorithmus in dem Modellierer-Fenster angezeigt wird. Dies sollte für Algorithmen verwendet werden, die nicht über eine klare Syntax verfügen (zum Beispiel, wenn die Anzahl der erstellten Layer im Voraus nicht bekannt werden soll, zur Design-Zeit), die sie ungeeignet für die grafische Modellierer machen

Umgang mit Daten die durch den Algorithmus erzeugt wurden¶

Wenn Sie eine Ausgabe (Raster, Vektor oder Tabelle) deklarieren wird der Algorithmus versuchen ihn zu QGIS hinzuzufügen nachdem sie beendet wurde. Darum wird auch, trotz dessen die runalg() Methode nicht die Layer, die sie produziert, lädt, der endgültige TWI Layer geladen, 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

Die Kommunikation mit dem Benutzer¶

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.

Wenn Sie einige Informationen für den Benutzer zur Verfügung stellen, die nicht den Fortschritt des Algorithmus zeigen, können Sie die setinfo(text) Methode verwenden, auch aus dem progress Objekt.

Wenn Ihr Skript irgendein Problem hat, ist der richtige Weg zu propagieren seine Ausnahme vom Typ GeoAlgorithmExecutionException() zu erhöhen. Sie können eine Nachricht als Argument für den Konstruktor der Ausnahme übergeben. Die Verarbeitung kümmert sich um die Handhabung und steht in Verbindung mit dem Benutzer, je nachdem, wo der Algorithmus aus ausgeführt wird (Toolbox, Modellierer, Python Konsole...)

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.

Beispielskripte¶

Einige Beispiele stehen in der Online-Sammlung von Skripten zur Verfügung, die Sie durch die Auswahl des Get script from on-line script collection Werkzeugs unter dem * Skripte/Werkzeuge* Eintrag in der Toolbox zugreifen können.

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 rechtsklicken und Edit script wählen um seinen Code anzuschauen oder ihn zu bearbeiten.

Bewährte Verfahren für das Schreiben von Skript-Algorithmen¶

Hier ist eine kurze Zusammenfassung von Ideen zum Berücksichtigen, wenn Sie Skript Algorithmen schaffen und vor allem, wenn Sie diese mit anderen QGIS Benutzern teilen möchten. Im Anschluss an diese einfachen Regeln, wird die Konsistenz zwischen den verschiedenen Verarbeitungselemente gewährleistet, wie die der Toolbox, des Modellierers oder der Batch-Verarbeitung-Schnittstelle.

• Laden Sie keine Ergebnislayer. Lassen Sie die Verarbeitung Ihrer Ergebnisse abarbeiten und laden Sie Ihre Layer, wenn nötig.

• Erklären Sie immer die Ausgänge Ihres erzeugten Algorithmus. Vermeiden Sie Dinge, wie zum Beispiel eine Ausgabe deklarieren und dann mit dem Zieldateinamen für die Ausgabe eine Sammlung von ihnen zu erstellen. Das wird die richtige Semantik des Algorithmus brechen und macht es unmöglich, sie in dem Modellierer sicher zu verwenden. Wenn Sie einen Algorithmus, so schreiben, stellen Sie sicher, dass Sie die ## nomodeler-Tag hinzufügen.

• Zeige keine Meldungsfelder oder GUI-Element aus dem Skript mehr. Wenn Sie mit dem Benutzer kommunizieren möchten, verwenden Sie die setinfo() Methode oder einen Geo-AlgorithmusExecutionException

• Als Faustregel gilt: vergessen Sie nicht, dass Ihr Algorithmus in einem anderen Kontext ausgeführt werden könnte als der Verarbeitungswerkzeugleiste.

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.