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

The toolbox

The Toolbox is the main element of the processing GUI, and the one that you are more likely to use in your daily work. It shows the list of all available algorithms grouped in different blocks, and is the access point to run them whether as a single process or as a batch process involving several executions of a same algorithm on different sets of inputs.

Figure Processing 5:

../../../_images/toolbox.png

Processing Toolbox win

The toolbox contains all the available algorithms, divided into predefined groups. All these groups are found under a single tree entry named Geoalgorithms.

Additionally, two more entries are found, namely Models and Scripts. These include user-created algorithms, and allow you to define your own workflows and processing tasks. We will devote a full section to them a bit later.

Im oberen Teil der Toolbox finden Sie ein Suchfeld. Um die Anzahl der angezeigten Algorithmen in der Toolbox zu reduzieren und es leichter zu machen, Sie zu finden, können Sie ein beliebiges Wort oder Satz in das Textfeld eingeben. Beachten Sie, während Sie schreiben wird die Anzahl der Algorithmen in der Toolbox reduziert, so dass nur diejenigen sichtbar sind, die den Text enthalten, den Sie im Suchfeld eingeben haben.

In the lower part you will find a box that allows you to switch between the simplified algorithm list (the one explained above), and the advanced list. If you change to the advanced mode, the toolbox will look like this:

Figure Processing 6:

../../../_images/toolbox_advanced.png

Processing Toolbox (advanced mode) win

In the advanced view, each group represents a so-called ‘algorithm provider’, which is a set of algorithms coming from the same source, for instance, from a third-party application with geoprocessing capabilities. Some of this groups represent algorithms from one of such third-party applications (like SAGA, GRASS or R), while other contain algorithms directly coded as part of the processing plugin, not relying on any additional software.

This view is recommended to those users that have a certain knowledge of the applications that are backing those algorithms, since they will be shown with their original names and groups.

Also, some additional algorithms are available only in the advanced view, such as LiDAR tools or scripts based on the R statistical computing software, among others. Independent QGIS plugins that add new algorithms to the toolbox will only be shown in the advanced view.

In particular, the simplified view contains algorithms from the following providers:

  • GRASS
  • SAGA
  • OTB
  • Native QGIS algorithms

In the particular case of running QGIS under Windows, these algorithms are fully-functional in a fresh installation of QGIS and they can be run without requiring any additional installation. Also running them requires no prior knowledge of the external applications they use, making them more accesible for first-time users.

If you want to use an algorithm not provided by the any of above providers, switch to the advanced mode by selecting the corresponding option at the bottom of the toolbox.

Um einen Algorithmus zu starten, klicken Sie einfach doppelt auf den Namen in der Toolbox.

Der Algorithmus Dialog

Sobald Sie auf den Namen des Algorithmus klicken, den Sie ausführen möchten, wird ein Dialog angezeigt, wie unten zu sehen (in diesem Fall der SAGA-Dialog für den “Konvergenz-Index”-Algorithmus).

Figure Processing 7:

../../../_images/parameters_dialog.png

Parameters Dialog win

Dieser Dialog wird verwendet, um die Eingangs-Werte anzugeben, damit der Algorithmus ausgeführt werden kann. Er zeigt eine Tabelle, in der Eingangswerte und Konfigurationsparameter zu setzen sind. Der Inhalt des Dialogs steht in Abhängigkeit vom Algorithmus, der ausgeführt werden soll, und wird automatisch auf Basis der Anforderungen erstellt. Auf der linken Seite wird der Name des Parameters angezeigt. Auf der rechten Seite wird der Parameter gesetzt.

Obwohl die Anzahl und Art der Parameter von den Eigenschaften des Algorithmus abhängt, ist die Struktur des Dialogs für alle ähnlich. Die Parameter können folgende Typen sein.

  • A raster layer, to select from a list of all the ones available (currently opened) in QGIS. The selector contains as well a button on its right-hand side, to let you select filenames that represent layers currently not loaded in QGIS.

  • A vector layer, to select from a list of all the ones available in the QGIS. Layers not loaded in QGIS can be selected as well, as in the case of raster layers, but only if the algorithm does not require a table field selected from the attributes table of the layer. In that case, only opened layers can be selected, since they need to be open so as to retrieve the list of field names available.

    You will see a button by each vector layer selector, as shown in the figure below.

Figure Processing 8:

../../../_images/vector_iterator.png

Vector iterator button win

If the algorithm contains several of them, you will be able to toggle just one of them. If the button corresponding to a vector input is toggled, the algorithm will be executed iteratively on each one of its features instead of just once for the whole layer, producing as many outputs as times the algorithm is executed. This allows for automating the process when all features in a layer have to be processed separately.

  • A table, to select from a list of all the ones available in QGIS. Non-spatial tables are loaded into QGIS like vector layers, and in fact they are treated as such by the program. Currently, the list of available tables that you will see when executing an algorithm that needs one of them is restricted to tables coming from files in DBase (.dbf) or Comma-Separated Values (.csv) formats.
  • Eine Option, um mögliche Parameter aus einer Auswahlliste zu wählen.

  • A numerical value, to be introduced in a text box. You will find a button by its side. Clicking on it you will see a dialog that allows you to enter a mathematical expression, so you can use it as a handy calculator. Some useful variables related to data loaded into QGIS can be added to your expression, so you can select a value derived from any of this variables such as the cellsize of a layer or the northern most coordinate of another one.

Figure Processing 9:

../../../_images/number_selector.png

Number Selector win

  • Ein Wertebereich mit Minimum und Maxmum, der über zwei Textfelder angegeben wird.

  • Ein Text, der in ein Textfeld eingegeben wird.

  • Eine Spalte, die aus einer Attributtabelle ausgewählt wird oder eine einzelne Tabelle.

  • A Coordinate Reference System. You can type the EPSG code directly in the text box, or select it from the CRS selection dialog that appear when you click on the button on the right-hand size

  • Vier Zahlen, die eingegeben werden, um die xmin, xmax, ymin, ymax Grenzen festzulegen. Mit einem Klick auf den Knopf auf der rechten Seite erscheint ein Pop-up-Menü mit zwei Optionen: um den Wert aus einem Layer zu übernehmen oder um das aktuelle Ausmaß über das Kartenfensters zu wählen, indem Sie durch Aufziehen eines Rechtecks im Kartenfenster die Ausdehnung definieren.

    Figure Processing 10

    ../../../_images/extent.png

    Extent selector win

    Wenn Sie die erste Option wählen, sehen Sie einen Dialog wie den nächsten.

    Figure Processing 11

    ../../../_images/extent_list.png

    Extent List win

    Wenn Sie den zweiten wählen, wird das Parameter-Fenster verschwinden, damit Sie durch Klicken und Ziehen im Kartenfenster einen Bereich definieren können. Wenn das Rechteck definiert ist, wird der Dialog mit den Werten wieder auftauchen.

    Figure Processing 12:

    ../../../_images/extent_drag.png

    Extent Drag win

  • A list of elements (whether raster layers, vector ones or tables), to select from the list of the ones available in QGIS. To make the selection, click on the small button on the left side of the corresponding row to see a dialog like the following one.

    Figure Processing 13:

    ../../../_images/multiple_selection.png

    Multiple Selection win

  • Eine kleine Tabelle, um vom Benutzer editiert werden kann. Diese wird verwendet, um Parameter wie Lookup-Tabellen oder Convolution Filter zu definieren.

    Klicken Sie auf den Knopf auf der rechten Seite, um die Tabelle zu sehen und zu editieren.

    Figure Processing 14:

    ../../../_images/fixed_table.png

    Fixed Table win

    In Abhängigkeit vom Algorithmus kann die Anzahl der Zeilen verändert werden oder auch nicht, indem Sie auf den Knopf rechts neben dem Fenster klicken.

You will find a [Help] tab in the the parameters dialog. If a help file is available, it will be shown, giving you more information about the algorithms and detailed descriptions of what each parameter does. Unfortunately, most algorithms lack good documentation, but if you feel like contributing to the project, this would be a good place to start.

Bemerkung zum Thema Projektionen

Algorithms run from the processing framework — and also most of the external applications whose algorithms are exposed through it — do not perform any reprojection on input layers and assumes that all of them are already in a common coordinate system and ready to be analized. Whenever you use more than one layer as input to an algorithm, whether vector or raster, it is up to you to make sure that they are all in the same coordinate system.

Note that, due to QGIS‘s on-the-fly reprojecting capabilities, although two layers might seem to overlap and match, that might not be true if their original coordinates are used without reprojecting them onto a common coordinate system. That reprojection should be done manually and then use the resulting files as input to the algorithm. Also note that the reprojection process can be performed with the algorithms that are available in the processing framework itself.

By default, the parameters dialog will show a description of the CRS of each layer along with its name, making it easy to select layers that share the same CRS to be used as input layers. If you do not want to see this additional information, you can disable this functionality in the processing config dialog, unchecking the Show CRS option.

If you try to execute an algorithm using as input two or more layers with unmatching CRS’s, a warning dialog will be shown.

You still can execute the algorithm, but be aware that in most cases that will produce wrong results, such as empty layers due to input layers not overlapping.

Data objects generated by algorithms

Data objects generated by an algorithm can be of any of the following types:

  • Rasterlayer

  • Vektorlayer

  • Tabelle

  • HTML-Datei (wird für Text und grafische Ausgabe verwendet)

They are all saved to disk, and the parameters table will contain a text box corresponding to each one of these outputs, where you can type the output channel to use for saving it. An output channel contains the information needed to save the resulting object somewhere. In the most usual case, you will save it to a file, but the architecture allows for any other way of storing it. For instance, a vector layer can be stored in a database or even uploaded to a remote server using a WFS-T service. Although solutions like these are not yet implemented, the processing framework is prepared to handle them, and we expect to add new kinds of output channels in a near feature.

To select an output channel, just click on the button on the right side of the text box. That will open a save file dialog, where you can select the desired filepath. Supported file extensions are shown in the file format selector of the dialog, depending on the kind of output and the algorithm.

The format of the output is defined by the filename extension. The supported formats depend on the ones supported by the algorithm itself. To select a format, just select the corresponding file extension (or add it if you are directly typing the filepath instead). If the extension of the filepath you entered does not match any of the supported ones, a default extension (usually .dbf` for tables, .tif for raster layers and .shp for vector ones) will be appended to the filepath and the file format corresponding to that extension will be used to save the layer or table.

If you do not enter any filename, the result will be saved as a temporary file and in the corresponding default file format, and will be deleted once you exit QGIS (take care with that in case you save your project and it contains temporary layers).

You can set a default folder for output data objects. Go to the configuration dialog (you can open it from the Processing menu), and in the General group you will find a parameter named Output folder. This output folder is used as the default path in case you type just a filename with no path (i.e. myfile.shp) when executing an algorithm.

When running an algorithm that uses vector layer in iterative mode, the entered file path is used as the base path for all generated files, which are named using the base name and appending a number representing the index of the iteration. The file extension (and format) is used for all those generated files.

Apart from raster layers and tables, algorithms also generates graphics and texts as HTML files. These results are shown at the end of the algorithm execution in a new dialog. This dialog will keep the results produced by any algorithm during the current session, and can be shown at any time by selecting the Processing ‣ Results viewer from QGIS main menu.

Some external applications might have files (with no particular extension restrictions) as output, but they do not belong to any of the categories above. Those output files will not be processed by QGIS (opened or included into the current QGIS project), since most of the times correspond to file formats or elements not supported by QGIS. This is, for instance, the case with LAS files used for LiDAR data. The files get created, but you won’t see anything new in your QGIS working session.

For all the other types of outputs, you will find a check box that you can use to tell the algorithm whether to load the file once it is generated by the algorithm or not. By default, all files are opened.

Optional outputs are not supported, so all outputs are created, but you can uncheck the corresponding check box if you are not interested in a given output, which virtually makes it behave like an optional output (although the layer is created anyway, but if you leave the text box empty, it will be saved to a temporary file and deleted once you exit QGIS)

Configuring the processing framework

As it has been mentioned, the configuration menu gives access to a new dialog where you can configure how algorithms work. Configuration parameters are structured in separate blocks that you can select on the left-hand side of the dialog.

Along with the aforementioned Output folder entry, the General block contains parameters for setting the default rendering style for output layers (that is, layers generated by using algorithms from any of the framework GUI components). Just create the style you want using QGIS, save it to a file, and then enter the path to that file in the settings so the algorithms can use it. Whenever a layer is loaded by SEXTANTE and added to the QGIS canvas, it will be rendered with that style.

Rendering styles can be configured individually for each algorithm and each one of its outputs. Just right-click on the name of the algorithm in the toolbox and select Edit rendering styles. You will see a dialog like the one shown next.

Figure Processing 15:

../../../_images/rendering_styles.png

Rendering Styles win

Wählen Sie die Stildatei (.qml) für jede Ausgabedatei und klicken Sie dann [OK].

Other configuration parameters in the General group are the following ones:

  • Use filename as layer name. The name of each resulting layer created by an algorithm is defined by the algorithm itself. In some cases, a fixed name might be used, that meaning that the same name will be used, no matter which input layer is used. In other cases, the name might depend on the name of the input layer or some of the parameters used to run the algorithm. If this checkbox is checked, the name will be taken from the output filename instead. Notice, that, if the output is saved to a temporary file, the filename of this temporary file is usually long and meaningless one intended to avoid collision with other already existing filenames.
  • Use only selected features. If this option is selected, whenever a vector layer is used as input for an algorithm, only its selected features will be used. If the layer has no selected features, all of them will be used.
  • Pre-execution script file and Post-execution script file. This parameters refer to scripts written using the processing scripting functionality, and are explained in the section covering scripting and the console.

Abgesehen vom Bereich Allgemein im Menü Einstellungen, finden Sie auch einen für jeden Algorithmus-Provider. Sie enthalten ein aktivieren Element, das Sie verwenden können, um festzulegen, ob Algorithmen dieses Providers in der Toolbox erscheinen oder nicht. Auch haben einige Provider ihre eigene Algorithmus-Konfiguration, die wir später noch genauer erklären.