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

The graphical modeler

Der grafische Modeller ermöglicht es, komplexe Modelle mit einer einfachen und leicht zu bedienenden Benutzeroberfläche zu erstellen. Beim Arbeiten mit einem GIS finden die meisten Analyse-Operationen nicht isoliert, sondern als Teil einer Kette von Operationen statt. Der grafische Modeller kann eine Kette von Prozessen in einen einzigen Prozess einpacken. So ist es einfacher und bequemer, als einzelne Prozesse nacheinander auszuführen. Egal, wie viele Schritte und verschiedene Algorithmen es sind, sie können als Modell in einem einzigen Algorithmus ausgeführt werden. Das spart Zeit und Mühe, besonders für größere Modelle.

The modeler can be opened from the processing menu.

Der Modeller hat einen Arbeitsdialog, wo die Struktur des Modells und der Workflow dargestellt wird. Auf der linken Seite des Fensters kann ein Bereich mit zwei Reitern verwendet werden, um neue Elemente in das Modell zu integrieren.

Figure Processing 16:

../../../_images/modeler_canvas.png

Modeler win

Das Erstellen eines Modells geht in zwei Schritten:

  1. Definition of necessary inputs. These inputs will be added to the parameters window, so the user can set their values when executing the model. The model itself is an algorithm, so the parameters window is generated automatically as it happens with all the algorithms available in the processign framework.
  2. Definition of the workflow. Using the input data of the model, the workflow is defined adding algorithms and selecting how they use those inputs or the outputs generated by other algorithms already in the model

Definition von Eingaben

The first step to create a model is to define the inputs it needs. The following elements are found in the Inputs tab on the left side of the modeler window:

  • Rasterlayer

  • Vektorlayer

  • Text

  • Tabellenspalte

  • Tabelle

  • Extent
  • Number
  • Boolean
  • File

Ein Doppelklick auf einen von ihnen öffnet einen Dialog, um ihre Eigenschaften zu definieren. Je nach Parameter, enthält der Dialog nur ein Grundelement (die Beschreibung, die der Benutzer sieht, wenn er das Modell ausführt) oder mehrere. Zum Beispiel, wenn Sie einen numerischen Wert verwenden, wie es in der folgenden Abbildung zu sehen ist, müssen Sie abgesehen von der Beschreibung der Parameter auch einen Standardwert und eine Reihe von gültigen Werten setzen.

Figure Processing 17:

../../../_images/models_parameters.png

Model Parameters win

Für jede Eingabe wird ein neues Element im Modeller-Fenster erstellt.

Figure Processing 18:

../../../_images/models_parameters2.png

Model Parameters win

Definition des Workflows

Wenn die Eingaben definiert sind, ist es Zeit die Algorithmen festzulegen. Die Algorithmen können im Reiter Algorithmen ausgewählt werden. Die Gruppierung entspricht der Toolbox.

Figure Processing 19:

../../../_images/models_parameters3.png

Model Parameters win

The appearance of the toolbox has two modes here as well: simplified and advanced. However, there is no element to switch between views in the modeler, and you have to do it in the toolbox. The mode that is selected in the toolbox is the one that will be used for the list of algorithms in the modeler.

To add an algorithm to a model, double-click on its name. An execution dialog will appear, with a content similar to the one found in the execution panel that is shown when executing the algorithm from the toolbox. The one shown next correspond to the SAGA ‘Convergence index’ algorithm, the same one we saw in the section dedicated to the toolbox.

Figure Processing 20:

../../../_images/models_parameters4.png

Model Parameters win

As you can see, some differences exist. Instead of the file output box that was used to set the filepath for output layers and tables, a simple text box is. If the layer generated by the algorithm is just a temporary result that will be used as the input of another algorithm and should not be kept as a final result, just do not edit that text box. Typing anything on it means that the result is a final one, and the text that you supply will be the description for the output, which will be the one the user will see when executing the model.

Selecting the value of each parameter is also a bit different, since there are important differences between the context of the modeler and the toolbox one. Let’s see how to introduce the values for each type of parameter.

  • Layers (raster and vector) and tables. They are selected from a list, but in this case the possible values are not the layers or tables currently loaded in QGIS, but the list of model inputs of the corresponding type, or other layers or tables generated by algorithms already added to the model.
  • Numerical values. Literal values can be introduced directly on the text box. But this text box is also a list that can be used to select any of the numerical value inputs of the model. In this case, the parameter will take the value introduced by the user when executing the model.
  • Text. Wie im Fall von numerischen Werten können Zeichenketten eingegeben werden oder ein Eingabe-String ausgewählt werden.

  • Table field. The fields of the parent table or layer cannot be known at design-time, since they depend of the selection of the user each time the model is executed. To set the value for this parameter, type the name of a field directly in the text box, or use the list to select a table field input already added to the model. The validity of the selected field will be checked at run-time.

In all cases, you will find an additional parameter named Parent algorithms that is not available when calling the algorithm from the toolbox. This parameter allows you to define the order in which algorithms are executed, by explicitly defining one algorithm as a parent of the current one, which will force it to be executed before it.

When you use the output of a previous algorithm as the input of your algorithm, that implicitly sets the former as parent of the current one (and places the corresponding arrow in the modeler canvas). However, in some cases an algorithm might depend on another one even if it does not use any output object from it (for instance, and algorithm that executes an SQL sentence on a PostGIS database and another one which imports a layer into that same database) In that case, just select it in the Parent algorithms parameter and they will be executed in the correct order.

Sobald alle Parameter gültigen Werten zugewiesen wurden, klicken Sie auf [OK] und der Algorithmus wird zum Dialogfenster hinzugefügt. Es wird mit allen anderen Elemente verknüpft, egal ob Algorithmus oder Parameter, die Objekte bereitstellen, die als Eingabe für diesen Algorithmus verwendet werden.

Figure Processing 21:

../../../_images/models_parameters5.png

Model Parameters win

Elemente können an eine andere Position innerhalb der Leinwand gezogen werden, um die Art der Modelldarstellung zu ändern und dadurch klarer und intuitiver zu machen. Verbindungen zwischen Elementen werden automatisch aktualisiert.

Sie können Ihren Algorithmus jederzeit starten, in dem Sie auf den [Run] Knopf drücken. Allerdings, um es aus der Toolbox zu verwenden, muss es gespeichert und der Modeller Dialog geschlossen werden, damit die Toolbox seinen Inhalt aktualisieren kann.

Speichern und laden von Modellen

Verwenden Sie den [Speichern] Knopf, um das aktuelle Modell zu speichern und den [Öffnen] Knopf, um zuvor gespeicherte wieder zu laden. Modelle werden mit der Dateierweiterung .models gespeichert. Wenn das Modell zuvor bereits aus dem Modellerfenster gespeichert wurde, werden Sie nicht nochmal nach einem Dateinamen gefragt, da es bereits eine Datei mit diesem Modell gibt, und dieser verwendet wird.

Vor dem Speichern eines Modells müssen Sie einen Namen und eine Gruppe angeben. Nutzen Sie dazu die Textfelder im oberen Teil des Fensters.

Models saved on the models folder (the default folder when you are prompted for a filename to save the model) will appear in the toolbox in the corresponding branch. When the toolbox is invoked, it searches the models folder for files with .model extension and loads the models they contain. Since a model is itself an algorithm, it can be added to the toolbox just like any other algorithm.

The models folder can be set from the processing configuration dialog, under the Modeler group.

Models loaded from the models folder appear not only in the toolbox, but also in the algorithms tree in the Algorithms tab of the modeler window. That means that you can incorporate a model as a part of a bigger model, just as you add any other algorithm.

In some cases, a model might not be loaded because not all the algorithms included in its workflow are available. If you have used a given algorithm as part of your model, it should be available (that is, it should appear on the toolbox) in order to load that model. Deactivating an algorithm provider in the processing configuration window renders all the algorithms in that provider unusable by the modeler, which might cause problems when loading models. Keep that in mind when you have trouble loading or executing models.

Ein Modell editieren

Sie können das Modell, das Sie gerade erstellen editieren, den Workflow neu definieren sowie die Beziehungen zwischen den Algorithmen und den Eingangsdaten, die das Modell ausmachen ändern.

Wenn Sie mit der rechten Maustaste auf einen Algorithmus im Dialog-Fenster klicken, wird ein Kontextmenü geöffnet. wie in der nächsten Abbildung zu sehen:

Figure Processing 22:

../../../_images/modeler_right_click.png

Modeler Right Click win

Selecting the Remove option will cause the selected algorithm to be removed. An algorithm can be removed only if there are no other algorithms depending on it. That is, if no output from the algorithm is used in a different one as input. If you try to remove an algorithm that has others depending on it, a warning message like the one you can see below will be shown:

Figure Processing 23:

../../../_images/cannot_delete_alg.png

Cannot Delete Algorithm win

Auswählen der Bearbeiten Option oder einfaches Doppelklicken auf das Symbol des Algorithmus zeigt den Parameter-Dialog des Algorithmus, um die Ein- und Ausgabe Parameter-Werte zu ändern. Nicht alle Eingabe-Elemente des Modells werden in diesem Fall als verfügbare Eingänge angezeigt. Layer oder Werte, die in einem fortgeschrittenen Schritt im Workflow durch das Modell erzeugt wurden, stehen nicht zur Verfügung, wenn sie zirkuläre Abhängigkeiten verursachen.

Wählen Sie die neuen Werte und klicken dann auf den [OK] Knopf wie gewohnt. Die Verbindungen zwischen den Elementen des Modells ändern sich entsprechend im Modeller-Fenster.

Algorithmen aktivieren und deaktivieren

Algorithmen können im Modeller deaktiviert werden, damit sie nicht ausgeführt werden, wenn das Modell ausgeführt wird. Dies kann verwendet werden, um nur einen bestimmten Teil eines Modells zu nutzen, oder wenn Sie nicht alle Ausgaben brauchen.

Um einen Algorithmus zu deaktivieren, klicken Sie auf das entsprechende Symbol im Modell-Fenster mit der rechten Maustaste und wählen Sie deaktivieren. Sie werden sehen, dass der Algorithmus nun mit einem roten Label unter seinem Namen darauf hinweist, dass er nicht aktiv ist.

Figure Processing 24:

../../../_images/deactivated.png

Deactivate win

Alle Algorithmen die (direkt oder indirekt) an diesem Algorithmus hängen, werden auch als inaktiv angezeigt, da sie nicht ausgeführt werden können.

Um einen Algorithmus zu aktivieren, klicken Sie mit der rechten Maustaste auf das Icon und wählen Sie dann die Option Aktivieren.

Editieren der Modell-Hilfe Datei und der Metainformationen

You can document your models from the modeler itself. Just click on the [Edit model help] button and a dialog like the one shown next will appear.

Figure Processing 25:

../../../_images/help_edition.png

Help Edition win

On the right-hand side you will see a simple HTML page, created using the description of the input parameters and outputs of the algorithm, along with some additional items like a general description of the model or its author. The first time you open the help editor all those descriptions are empty, but you can edit them using the elements on the left-hand side of the dialog. Select an element on the upper part and the write its description in the text box below.

Die Modell Hilfe wird in einer Datei im gleichen Ordner wie das Modell selbst gespeichert. Sie müssen nichts tun, um es zu speichern, da es automatisch geschieht.

Zu den verfügbaren Algorithmen

Sie haben vielleicht bemerkt, dass einige Algorithmen, die aus der Toolbox ausgeführt werden können nicht in der Liste der verfügbaren Algorithmen erscheint, wenn Sie ein Modell entwerfen. Um in einem Modell enthalten zu sein, muss der Algorithmus eine korrekte Semantik haben, um im Workflow verknüpft zu werden. Wenn ein Algorithmus keine solche definierte Semantik besitzt (zum Beispiel, wenn die Anzahl der Ausgangskanäle oder Layer nicht im Voraus bekannt ist), dann ist es nicht möglich, diesen in einem Modell zu verwenden, und somit erscheint er auch nicht in der Liste.

Additionally, you will see some algorithms in the modeler that are not found in the toolbox. This algorithms are meant to be used exclusively as part of a model, and they are of no interest in a different context. The ‘Calculator’ algorithm is an example of that. It is just a simple arithmetic calculator that you can use to modify numerical values (entered by the user or generated by some other algorithm). This tools is really useful within a model, but outside of that context, it doesn’t make too much sense.

Saving models as Python code

Given a model, it is possible to automatically create Python code that performs the same task as the model itself. This code is used to create a console script (we will explain them later in this manual) and you can modify that script to incorporate actions and methods not available in the graphical modeler, such as loops or conditional sentences.

This feature is also a very practical way of learning how to use processign algorithms from the console and how to create new algorithms using Python code, so you can use it as a learning tool when you start creating your own scripts.

Save your model in the models folder and go to the toolbox, where it should appear now, ready to be run. Right click on the model name and select Save as Python script in the context menu that will pop-up. A dialog will prompt you to introduce the file where you want to save the script.