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

Navigation Toolbar

Beschreibung

success Validate Model

Checks whether the algorithms and inputs used in the model exist. Convenient before releasing a model.

play Run Model…

F5

checkbox

Executes the model

Reorder Model Inputs…

Sets the order in which inputs are presented to the user in the algorithm dialog.

fileOpen Open Model…

Strg+O

checkbox

Opens a .model3 file for edit or execution

fileSave Save Model

Strg+S

checkbox

Saves the model to disk as a .model3 file

fileSaveAs Save Model as…

Strg+Shift+S

checkbox

Saves the model to disk as a new .model3 file

fileSave Save Model in project

checkbox

Embeds the model file in the project file, making it available when sharing the project file.

helpContents Edit Model Help…

checkbox

An interface to document the model, the algorithms, the parameters and outputs, as well as the author and versioning

Export ►

saveMapAsImage ► Export as Image…

checkbox

Saves the model’s graphical design to an image file format (for illustration purpose)

saveAsPDF► Export as PDF…

Saves the model’s graphical design to a PDF file format (for illustration purpose)

saveAsSVG► Export as SVG…

Saves the model’s graphical design to an SVG file format (for illustration purpose)

fileSave► Export as Script Algorithm…

checkbox

Generates a python script file including the model’s instructions

26.5.1.2. Menü Bearbeiten

Bezeichnung

Tastenkürzel

Navigation Toolbar

Beschreibung

selectAll 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

redo Wiederholen

Strg+Y

checkbox

Rollback the latest canceled action. See also the Undo/Redo panel.

undo Rückgängig

Strg+Z

checkbox

Cancel the previous change. See also the Undo/Redo panel.

editCut Ausschneiden

Strg+X

Cuts a selection of components from the model.

editCopy Kopieren

Strg+C

Copies a selection of components from the model.

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

deleteSelected 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

Navigation Toolbar

Beschreibung

Zoom To ►

Zooms to the selected group box extent

zoomIn Hineinzoomen

Ctrl++

checkbox

zoomOut Herauszoomen

Ctrl+-

checkbox

zoomActual Zoom to 100%

Strg+1

checkbox

zoomFullExtent Volle Ausdehnung

Strg+0

checkbox

Displays all the components in the designer current canvas

checkbox Show Comments

Displays comments associated to every algorithm or input in the graphical designer

unchecked Enable Snapping

unchecked 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:

  1. Model Properties: specify the name (required) of the model and the group in which it will be displayed in the Processing Toolbox

  2. Inputs: all the input parameters that could shape your model

  3. Algorithms: the available Processing algorithms

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

  5. 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:

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

  2. 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 checkboxZwingend ankreuzen. Durch Ankreuzen des Kontrollkästchens unchecked: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:

  • fieldInteger 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, …

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

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

  • processingAlgorithm 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 modelOutput 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:

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

    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 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 start 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 editHelpContentEdit 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 fileSaveSave model button to save the current model and the fileOpenOpen 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 addToProjectModell 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 qgsProjectFileProject 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 saveAsPythonExport as Script Algorithm… in the modeler canvas or right click on the name of the model in the Processing Toolbox and choose saveAsPythonExport 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 saveMapAsImageExport as image, saveAsPDFExport as PDF or saveAsSVGExport 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.