26.5. The model designer

The model designer allows you to create complex models using a simple and easy-to-use interface. When working with a GIS, most analysis operations are not isolated, rather part of a chain of operations. Using the model designer, that chain of operations can be wrapped into a single process, making it convenient to execute later with a different set of inputs. No matter how many steps and different algorithms it involves, a model is executed as a single algorithm, saving time and effort.

The model designer can be opened from the Processing menu (Processing ► Graphical Modeler).

26.5.1. The model designer interface 

../../../_images/modeler_canvas.png — Abb. 26.17 Model designer

In its main part, the modeler has a working canvas where the structure of the model and the workflow it represents can be constructed.

At the top of the dialog, different menus and the Navigation toolbar give access to a variety of tools.

26.5.1.1. Model menu 

Bezeichnung	Tastenkürzel	Beschreibung
Validate Model		Checks whether the algorithms and inputs used in the model exist. Convenient before releasing a model.
Run Model…	`F5`	Executes the model
Reorder Model Inputs…		Sets the order in which inputs are presented to the user in the algorithm dialog.
Open Model…	`Strg+O`	Opens a `.model3` file for edit or execution
Save Model	`Strg+S`	Saves the model to disk as a `.model3` file
Save Model as…	`Strg+Shift+S`	Saves the model to disk as a new `.model3` file
Save Model in project		Embeds the model file in the project file, making it available when sharing the project file.
Edit Model Help…		An interface to document the model, the algorithms, the parameters and outputs, as well as the author and versioning
Export ►
► Export as Image…		Saves the model’s graphical design to an image file format (for illustration purpose)
► Export as PDF…		Saves the model’s graphical design to a `PDF` file format (for illustration purpose)
► Export as SVG…		Saves the model’s graphical design to an `SVG` file format (for illustration purpose)
► Export as Script Algorithm…		Generates a python script file including the model’s instructions

26.5.1.2. Menü Bearbeiten 

Bezeichnung	Tastenkürzel	Beschreibung
Alles wählen	`Strg+A`	Selects all the model components in the designer
Snap selected components to Grid		snaps and aligns the elements into a grid
Wiederholen	`Strg+Y`	Rollback the latest canceled action. See also the Undo/Redo panel.
Rückgängig	`Strg+Z`	Cancel the previous change. See also the Undo/Redo panel.
Ausschneiden	`Strg+X`	Cuts a selection of components from the model.
Kopieren	`Strg+C`	Copies a selection of components from the model.
Einfügen	`Strg+V`	Pastes a cut or copied selection of components from a model to another or within the same model. The selected components keep their original properties and comments.
Delete selected components	`Entf`	Removes a component from the model.
Add Group Box		Adds a box at the background of related components in order to visually group them. Particularly useful in big models to keep the workflow clean.

26.5.1.3. Menü Ansicht 

Bezeichnung	Tastenkürzel	Beschreibung
Zoom To ►		Zooms to the selected group box extent
Hineinzoomen	`Ctrl++`
Herauszoomen	`Ctrl+-`
Zoom to 100%	`Strg+1`
Volle Ausdehnung	`Strg+0`	Displays all the components in the designer current canvas
Show Comments		Displays comments associated to every algorithm or input in the graphical designer
Enable Snapping
Toggle Panel Visibility	`Strg+Tab`	Switches ON or OFF the panels in the designer

26.5.1.4. Bedienfelder 

The left part of the window is a section with five panels that can be used to add new elements to the model:

Model Properties: specify the name (required) of the model and the group in which it will be displayed in the Processing Toolbox
Inputs: all the input parameters that could shape your model
Algorithms: the available Processing algorithms
Variables: Models can contain dedicated variables that are unique and only available to them. These variables can be accessed by any expression used within the model. They are useful to control algorithms within a model and control multiple aspects of the model by changing a single variable. The variables can be viewed and modified in the Variables panel.
Undo History: this panel will register everything that happens in the modeler, making it easy to cancel things you did wrong.

26.5.1.5. Zu den verfügbaren Algorithmen 

Some algorithms that can be executed from the toolbox do not appear in the list of available algorithms when you are designing a model. To be included in a model, an algorithm must have the correct semantic. If an algorithm does not have such a well-defined semantic (for instance, if the number of output layers cannot be known in advance), then it is not possible to use it within a model, and it will not appear in the list of algorithms that you can find in the modeler dialog. On the other hand some algorithms are specific to the modeler. Those algorithms are located within the group ‚Modeler Tools‘.

26.5.2. Creating a model 

Das Erstellen eines Modells beinhaltet zwei grundlegende Schritte:

Definition von erforderlichen Eingaben. Diese Eingaben werden dem Paramterfenster hinzugefügt, so dass der Anwender Ihre Werte einstellen kann wenn er das Modell ausführt. Das Modell selber ist ein Algorithmus, also wird das Parameterfenster automatisch erstellt, so wie es mit allen Algorithmen, die in der Verarbeiten Umgebung zur Verfügung stehen, passiert.
Definition des Arbeitsablaufs. Der Arbeitsablauf wird definiert, indem Algorithmen hinzugefügt werden. In diesen wird festgelegt, wie sie die definierten Eingaben oder die von anderen Algorithmen im Modell erzeugten Ausgaben verwenden.

26.5.2.1. Definition von Eingaben 

Der erste Schritt besteht darin, die Eingaben für das Modell zu definieren. Die folgenden Elemente befinden sich auf der Registerkarte :guilabel: Eingaben auf der linken Seite des Modellierfensters:

Tab. 26.1 List of parameter types for model building
`Annotation Layer`	`Authentication Configuration`	`Boolean`	`Color`	`Connection Name`
`Coordinate Operation`	`CRS`	`Database Schema`	`Database Table`	`Datetime`
`Distance`	`Duration`	`DXF Layers`	`Enum`	`Expression`
`Extent`	`Field Aggregates`	`Fields Mapper`	`File/Folder`	`Geometry`
`Map Layer`	`Map Theme`	`Matrix`	`Mesh Dataset Groups`	`Mesh Dataset Time`
`Mesh Layer`	`Multiple Input`	`Number`	`Point`	`Point Cloud Layer`
`Print Layout`	`Print Layout Item`	`Range`	`Raster Band`	`Raster Layer`
`Scale`	`String`	`TIN Creation Layers`	`Vector Features`	`Vector Field`
`Vector Layer`	`Vector Tile Writer Layers`

Bemerkung

Wenn Sie mit der Maus über die Eingaben fahren, wird ein Tooltip mit zusätzlichen Informationen angezeigt.

Wenn Sie auf ein Element doppelklicken, wird ein Dialog angezeigt, in dem Sie seine Eigenschaften definieren können. Je nach Parameter enthält der Dialog mindestens ein Grundelement (die Beschreibung, die der Benutzer bei der Ausführung des Modells sieht). Wenn Sie einen numerischen Wert hinzufügen, wie in der nächsten Abbildung zu sehen ist, müssen Sie, zusätzlich zur Beschreibung des Parameters, einen Standardwert und den Bereich der gültigen Werte festlegen.

../../../_images/models_parameters.png — Abb. 26.18 Definition der Modellparameter

Sie können Ihre Eingabe als zwingend für Ihr Modell definieren, indem Sie das Kontrollkästchen ^Zwingend ankreuzen. Durch Ankreuzen des Kontrollkästchens :sup: Erweitert können Sie die Eingabe so einstellen, dass sie sich im Abschnitt Erweitert befindet. Dies ist besonders nützlich, wenn das Modell viele Parameter hat und einige davon nicht trivial sind, Sie diese aber dennoch wählen möchten.

Für jede hinzugefügte Eingabe wird der Modellierungsebene ein neues Element hinzugefügt.

../../../_images/models_parameters2.png — Abb. 26.19 Modellparameter

Sie können Eingaben auch hinzufügen, indem Sie den Eingabetyp aus der Liste an die gewünschten Stelle im Modellierungsfenster ziehen. Wenn Sie einen Parameter einer bestehenden Eingabe ändern möchten, doppelklicken Sie einfach darauf, und es erscheint der gleiche Dialog.

When using a model within another model, the inputs and outputs necessary will be displayed in the canvas.

26.5.2.2. Definition des Arbeitsablaufs 

In the following example we will add two inputs and two algorithms. The aim of the model is to copy the elevation values from a DEM raster layer to a line layer using the Drape algorithm, and then calculate the total ascent of the line layer using the Climb Along Line algorithm.

In the Inputs tab, choose the two inputs as Vector Layer for the line and Raster Layer for the DEM. We are now ready to add the algorithms to the workflow.

Die Algorithmen finden Sie auf der Registerkarte Algorithmen, ähnlich gruppiert wie in der Verarbeitungs-Werkzeugkiste.

../../../_images/models_parameters3.png — Abb. 26.20 Modell-Eingaben

To add an algorithm to a model, double-click on its name or drag and drop it, just like for inputs. As for the inputs you can change the description of the algorithm and add a comment. When adding an algorithm, 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 following picture shows both the Drape (set Z value from raster) and the Climb along line algorithm dialogs.

../../../_images/models_parameters4.png — Abb. 26.21 Modell-Algorithmus-Parameter

As you can see, there are however some differences. Each parameter has a drop-down menu next to it allowing to control how it will be served during the workflow:

^Value: allows you to assign a static value to the parameter. Depending on the parameter type, the widget will let you enter a number (5.0), a string (mytext), select layer(s) loaded in the QGIS project or from a folder, pick items from a list, …
^{Pre-calculated Value}: opens the Expression Builder dialog and lets you define an expression to fill the parameter. Model inputs together with some other layer statistics are available as variables and are listed at the top of the Search dialog of the Expression Builder. The expression is evaluated once before the child algorithm is executed and used during the execution of that algorithm.
^{Model Input}: allows to use an input added to the model as a parameter. Once clicked, this option will list all the suitable inputs for the parameter.
^{Algorithm Output}: allows to use the output of another algorithm as an input of the current algorithm. As of model inputs, this option will list all the suitable inputs for the parameter.
The output parameter also has the above options in its drop-down menu:
- add static outputs for child algorithms, e.g. always saving a child algorithm’s output to a predefined geopackage or postgres layer
- use an expression based output values for child algorithms, e.g. generating an automatic file name based on today’s date and saving outputs to that file
- use a model input, e.g. the File/Folder model input to specify an output file or folder
- use another algorithm output, e.g. the output of the Create directory algorithm (from Modeler tools)
- an addditional ^{Model Output} option makes the output of the algorithm available in the model. If a layer generated by the algorithm is only to be used as input to another algorithm, don’t edit that text box.
In the following picture you can see the two input parameters defined as Model Input and the temporary output layer:

Abb. 26.22 Algorithm Input and Output parameters

You will also find an additional parameter named Dependencies 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. This will force the parent algorithm to be executed before the current one.

Wenn Sie die Ausgabe eines vorherigen Algorithmus als Eingabe Ihres Algorithmus verwenden, wird der vorherige Algorithmus implizit als übergeordneter Algorithmus des aktuellen festgelegt (und der entsprechende Pfeil im Modellierungsfenster platziert). In einigen Fällen kann ein Algorithmus jedoch von einem anderen Algorithmus abhängen, selbst wenn er kein Ausgabeobjekt von diesem verwendet (z.B. ein Algorithmus, der einen SQL-Satz auf einer PostGIS-Datenbank ausführt und ein anderer, der einen Layer in dieselbe Datenbank importiert). In diesem Fall wählen Sie einfach den vorherigen Algorithmus im Parameter Dependencies aus und sie werden in der richtigen Reihenfolge ausgeführt.

Sobald allen Parametern gültige Werte zugewiesen wurden, klicken Sie auf OK und der Algorithmus wird der Oberfläche hinzugefügt. Er wird mit den Elementen auf der Oberfläche (Algorithmen oder Eingaben) verknüpft, die Objekte liefern, die als Eingaben für den Algorithmus verwendet werden.

Elements can be dragged to a different position on the canvas using the ^{Select/Move Item} tool. This is useful to make the structure of the model clearer and more intuitive. You can also resize the elements, grasping their border. This is particularly useful if the description of the input or algorithm is long. With View ► Enable snapping option checked, items resizing or displacement can be bound to a virtual grid, for a more visually structured algorithm design.

Links between elements are updated automatically and you can see a + button at the top and at the bottom of each algorithm. Clicking the button will list all the inputs and outputs of the algorithm so you can have a quick overview.

../../../_images/models_model.png — Abb. 26.23 Ein komplettes Modell

With the Edit ► Add Group Box tool, you can add a draggable box to the canvas. This feature is very useful in big models to group related elements in the modeler canvas and to keep the workflow clean. For example we might group together all the inputs of the example:

../../../_images/model_group_box.png — Abb. 26.24 Model Group Box

You can change the name and the color of the boxes. Group boxes are very useful when used together with View ► Zoom To ► tool, allowing you to zoom to a specific part of the model. You can also zoom in and out by using the mouse wheel.

You might want to change the order of the inputs and how they are listed in the main model dialog. At the bottom of the Input panel you will find the Reorder Model Inputs... button and by clicking on it a new dialog pops up allowing you to change the order of the inputs:

../../../_images/model_reorder_inputs.png — Abb. 26.25 Reorder Model Inputs

Comments can also be added to inputs or algorithms present in the modeler. This can be done by going in the Comment tab of the item or with a right-click. In the same tab a color can be set manual for individual model comments. Comments are visible only in the modeler canvas and not in the final algorithm dialog; they can be hidden by deactivating View ► Show Comments.

You can run your algorithm any time by clicking on the ^{Run model} button. When using the editor to execute a model, any non-default values will be saved in the inputs. This means that executing the model at a later time from the editor will have the dialog prefilled with those values on any subsequent run.

In order to use the algorithm from the toolbox, it has to be saved and the modeler dialog closed, to allow the toolbox to refresh its contents.

26.5.2.3. Documenting your model 

You need to document your model, and this can be done from the modeler itself. Click on the ^{Edit model help} button, and a dialog like the one shown next will appear.

../../../_images/help_edition.png — Abb. 26.26 Hilfe bearbeiten

Auf der rechten Seite finden Sie eine einfache HTML-Seite, die anhand der Eingabeparameter und Ausgaben des Algorithmus erstellt wurde, zusammen mit einigen zusätzlichen Einträgen wie eine allgemeine Beschreibung des Modells und seines Autors. Wenn Sie den Hilfeeditor das erste Mal öffnen, sind alle diese Beschreibungen leer, Sie können Sie aber mit Hilfe der Elemente auf der linken Seite des Dialogs bearbeiten. Wählen Sie ein Element im oberen Teil aus und schreiben Sie seine Beschreibung in das Textfeld unten.

Modell-Hilfe wird als Teil des Modells selbst gespeichert.

26.5.3. Speichern und laden von Modellen 

26.5.3.1. Saving models 

Use the ^{Save model} button to save the current model and the ^{Open Model} button to open a previously saved model. Models are saved with the .model3 extension. If the model has already been saved from the modeler window, you will not be prompted for a filename. Since there is already a file associated with the model, that file will be used for subsequent saves.

Bevor Sie ein Modell speichern, müssen Sie in den Textfeldern im oberen Teil des Fensters einen Namen und eine Gruppe für das Modell eingeben.

Modelle, die im Ordner models gespeichert sind (der Standardordner, wenn Sie zur Eingabe eines Dateinamens zum Speichern des Modells aufgefordert werden), erscheinen in der Toolbox in der entsprechenden Rubrik. Wenn die Toolbox aufgerufen wird, durchsucht sie den Ordner models nach Dateien mit der Erweiterung .model3 und lädt die darin enthaltenen Modelle. Da ein Modell selbst ein Algorithmus ist, kann es wie jeder andere Algorithmus zur Toolbox hinzugefügt werden.

Modelle können auch innerhalb der Projektdatei mit der Schaltfläche ^{Modell im Projekt speichern} gespeichert werden. Modelle, die mit dieser Methode gespeichert werden, werden nicht als :file:``.model3` Dateien auf die Platte geschrieben, sondern in die Projektdatei eingebettet.

Project models are available in the Project models menu of the toolbox and in the Project ► Models menu item.

Die Verarbeitungsmodellierung kann im Verarbeitungskonfigurationsdialog in der Models Gruppe eingestellt werden.

Modelle, die aus dem Ordner models geladen wurden, erscheinen nicht nur in der Toolbox, sondern auch in der Algorithmenliste im Reiter Algorithms des Modellierfensters. Das bedeutet, dass Sie ein Modell als Teil eines größeren Modells einbinden können, genau wie andere Algorithmen.

Die Modelle werden im Panel Browser angezeigt und können von dort aus gestartet werden.

26.5.3.2. Exportieren eines Modells als Python Skript 

As we will see in a later chapter, Processing algorithms can be called from the QGIS Python console, and new Processing algorithms can be created using Python. A quick way to create such a Python script is to create a model and then export it as a Python file.

To do so, click on the ^{Export as Script Algorithm…} in the modeler canvas or right click on the name of the model in the Processing Toolbox and choose ^{Export Model as Python Algorithm…}.

26.5.3.3. Exportieren eines Modells als Bild, PDF oder SVG 

A model can also be exported as an image, SVG or PDF (for illustration purposes) by clicking ^{Export as image}, ^{Export as PDF} or ^{Export as SVG}.

26.5.4. Ein Modell editieren 

Sie können das Modell, das Sie gerade erstellen, bearbeiten und dabei den Workflow und die Beziehungen zwischen den Algorithmen und Eingaben, die das Modell definieren, ändern.

Wenn Sie mit der rechten Maustaste auf einen Algorithmus in der Leinwand klicken, sehen Sie ein Kontextmenü wie das folgende:

../../../_images/modeler_right_click.png — Abb. 26.27 Rechtsklick auf den Modeler

Wird die Remove Option gewählt, bewirkt dies, dass der ausgewählte Algorithmus entfernt wird. Ein Algorithmus kann nur entfernt werden wenn keine weiteren Algorithmen von ihm abhängen. Das heißt, wenn keine Ausgabe des Algorithmus in einem anderen als Eingabe verwendet wird. Wenn Sie versuchen einen Algorithmus, von dem andere abhängen, zu entfernen, wird eine Warnmeldung wie die, die Sie unten sehen können, gezeigt:

../../../_images/cannot_delete_alg.png — Abb. 26.28 Kann Algorithmus nicht entfernen

Wenn Sie die Option :guilabel: Bearbeiten wählen, wird der Parameterdialog des Algorithmus angezeigt, so dass Sie die Eingaben und Parameterwerte ändern können. Es werden nicht alle im Modell verfügbaren Eingabeelemente als verfügbare Eingaben angezeigt. Layer oder Werte, die bei einem weiter entwickelten Schritt des Arbeitsablaufes erzeugt wurden, sind nicht verfügbar, wenn sie zirkuläre Abhängigkeiten verursachen.

Wählen Sie die neuen Werte aus und klicken Sie wie gewohnt auf die Schaltfläche OK. Die Verbindungen zwischen den Modellelementen ändern sich in der Modellierungsarbeitsfläche entsprechend.

The Add comment… allows you to add a comment to the algorithm to better describe the behavior.

A model can be run partially by deactivating some of its algorithms. To do it, select the Deactivate option in the context menu that appears when right-clicking on an algorithm element. The selected algorithm, and all the ones in the model that depend on it will be displayed in grey and will not be executed as part of the model.

../../../_images/deactivated.png — Abb. 26.29 Modell mit deaktivierten Algorithmen

Wenn Sie mit der rechten Maustaste auf einen Algorithmus klicken, der nicht aktiv ist, sehen Sie die Menüoption :guilabel: Aktivieren, mit der Sie den Algorithmus reaktivieren können.