SAGA Removal & TM Update: Module 18 (Lesson 18.1-18.9)

docs/training_manual/processing/crs.rst

@@ -15,6 +15,7 @@ some general rules about how they are handled by geoalgorithms when creating a n
   the CRS of input layers is shown along with its name in the parameters dialog.
 
 .. figure:: img/crs/crs_layer.png
+   :align: center
 
 * If there are no input layer, it will use the project CRS, unless the algorithm
   contains a specific CRS field (as it happened in the last lesson with the
@@ -29,8 +30,10 @@ actually the same layer.
 Open the :guilabel:`Add geometry attributes` algorithm.
 
 .. figure:: img/crs/add_geom.png
+   :align: center
+   :width: 70%
 
-This algorithm add new columns to the attributes table of a vector layer.
+This algorithm adds new columns to the attributes table of a vector layer.
 The content of the columns depend on the type of geometry of the layer.
 In the case of points, it adds new columns with the X and Y coordinates
 of each point.
@@ -43,19 +46,21 @@ Select the 4326 layer.
 The other parameter of the algorithm allows to set how the algorithm uses
 coordinates to calculate the new value that it will add to the resulting
 layers. Most algorithms do not have an option like that, and just use the
-coordinates directly. Select the :guilabel:`Layer CRS` option to just use coordinates
+coordinates directly. Select the :guilabel:`Cartesian Calculations in Layer's CRS` option to just use coordinates
 as they are. This is how almost all geoalgorithms work.
 
 You should get a new layer with exactly the same points as the other two layers.
 If you right click on the name of the layer and open its properties, you will
-see that it shares the same CRS of the input layer, that is, EPSG:4326.
+see that it shares the same CRS of the input layer, that is, ``EPSG:4326``.
 When the layer is loaded into QGIS, you will not be asked to enter the CRS
 of the layer, since QGIS already knows about it.
 
 If you open the attributes table of the new layer you will see that it
 contains two new fields with the X and Y coordinates of each point.
 
 .. figure:: img/crs/attribs2.png
+   :align: center
+   :width: 70%
 
 Those coordinate values are given in the layer CRS, since we chose that option.
 However, even if you choose another option, the output CRS of the layer would
@@ -67,12 +72,14 @@ the CRS of the input one.
 
 Now do the same calculation using the other layer. You should find the resulting
 layer rendered exactly in the same place as the other ones, and it will have the
-EPSG:23030 CRS, since that was the one of the input layer.
+``EPSG:23030`` CRS, since that was the one of the input layer.
 
 If you go to its attribute table, you will see values that are different to
 the ones in the first layer that we created.
 
 .. figure:: img/crs/attribs.png
+   :align: center
+   :width: 70%
 
 This is because the original data is different (it uses a different CRS),
 and those coordinates are taken from it.
@@ -97,8 +104,10 @@ but it will not use its CRS for the output one.
 Open the :guilabel:`Reproject layer` algorithm.
 
 .. figure:: img/crs/reprojection.png
+   :align: center
+   :width: 70%
 
-Select any of the layers as input, and select EPSG:23029 as the destination CRS.
+Select any of the layers as input, and select ``EPSG:23029`` as the destination CRS.
 Run the algorithm and you will get a new layer, identical to the input one,
 but with a different CRS. It will appear on the same region of the canvas,
 like the other ones, since QGIS will reproject it on the fly, but its original

docs/training_manual/processing/first_alg.rst

@@ -15,6 +15,7 @@ First, open the QGIS project corresponding to this lesson. It contains just a
 single layer with two polygons
 
 .. figure:: img/first_alg/canvas.png
+   :align: center
 
 Now go to the text box at the top of the toolbox. That is the search box, and if
 you type text in it, it will filter the list of algorithms so just those ones
@@ -25,32 +26,31 @@ not active, an additional label will be shown in the lower part of the toolbox.
 Type ``centroids`` and you should see something like this.
 
 .. figure:: img/first_alg/toolbox.png
+   :align: center
+   :width: 50%
 
 The search box is a very practical way of finding the algorithm you are looking
-for. At the bottom of the dialog, an additional label shows that there are
-algorithms that match your search but belong to a provider that is not active.
-If you click on the link in that label, the list of algorithms will also
-include results from those inactive providers, which will be shown in light gray.
-A link to activate each inactive provider is also shown. We'll see later how to
-activate other providers.
-
-.. figure:: img/first_alg/toolbox_providers.png
+for.
 
 To execute an algorithm, you just have to double-click on its name in the
 toolbox. When you double-click on the :guilabel:`Centroids` algorithm, you will
 see the following dialog.
 
 .. figure:: img/first_alg/centroids.png
+   :align: center
+   :width: 80%
 
 All algorithms have a similar interface, which basically contains input
 parameters that you have to fill, and outputs that you have to select where to
 store. In this case, the only input we have is a vector layer with polygons.
 
-Select the ``Polygons`` layer as input. This also can be done by dragging
+Select the ``polygons`` layer as input. This also can be done by dragging
 and dropping the layer from the layers panel to the input box.
 The algorithm has a single output, which
 is the centroids layer. There are two options to define where a data output is
 saved: enter a filepath or save it to a temporary filename.
+You can also enter the layer name as desired before
+running the algorithm and it will appear directly in the layer panel.
 
 In case you want to set a destination and not save the result in a temporary
 file, the format of the output is defined by the filename extension. To select
@@ -76,6 +76,8 @@ algorithm.
 You will get the following output.
 
 .. figure:: img/first_alg/canvas2.png
+   :align: center
+   :width: 80%
 
 The output has the same CRS as the input. Geoalgorithms assumes all input layers
 share the same CRS and do not perform any reprojection. Except in the case of

docs/training_manual/processing/first_saga_alg.rst → docs/training_manual/processing/first_grass_alg.rst

@@ -3,7 +3,7 @@ Running an external algorithm
 
 
 .. note:: In this lesson we will see how to use algorithms that depend on a
- third-party application, particularly SAGA, which is one of the main
+ third-party application, particularly GRASS, which is one of the main
  algorithm providers.
 
 All the algorithms that we have run so far are part of processing framework.
@@ -16,93 +16,96 @@ and use QGIS data to run them.
 
 Some of the algorithms that you see in the simplified view require third party
 applications to be installed in your system. One algorithm provider of special
-interest is SAGA (System for Automated Geospatial Analysis). First, we need to
-configure everything so QGIS can correctly call SAGA. This is not difficult,
+interest is GRASS (Geographic Resources Analysis Support System)
+configure everything so QGIS can correctly call GRASS. This is not difficult,
 but it's important to understand how it works. Each external application has
 its own configuration, and later in this same manual we will talk about some
-of the other ones, but SAGA is going to be our main backend, so we will discuss it here.
+of the other ones, but GRASS is going to be our main backend, so we will discuss it here.
 
 If you are on Windows, the best way to work with external algorithms is to
 install QGIS using the standalone installer. It will take care of installing
-all the needed dependencies, including SAGA, so if you have used it, there is
-nothing else to do. You can open the settings dialog and go to the *Providers/SAGA* group.
+all the needed dependencies, including GRASS, so if you have used it, there is
+nothing else to do. You can open the setting dialog and go to the *Providers/GRASS* group.
 
-.. figure:: img/first_saga_alg/saga_config.png
+.. figure:: img/first_GRASS_alg/GRASS_config.png
+   :align: center
 
-The SAGA path should already be configured and pointing to the folder where SAGA is installed.
 
-If you have installed QGIS not using the standalone installer, then you must
-enter the path to your SAGA installation (which you must have installed separately)
-there. The required version is SAGA 2.1 [this is changing according to the releases of SAGA].
-
-In case you are using Linux, you do not have to set the path to your SAGA installation
-in the processing configuration. Instead, you must install SAGA and make sure that
-the SAGA folder is in PATH, so it can be called from the console (just open a
-console and type ``saga_cmd`` to check it). Under Linux, the target version for
-SAGA is also 2.1, but in some installations (such as the OSGeo Live DVD)
+In case you are using Linux, you do not have to set the path to your GRASS installation
+in the processing configuration. Instead, you must install GRASS and make sure that
+the GRASS folder is in PATH, so it can be called from the console (just open a
+console and type ``GRASS_cmd`` to check it). Under Linux, the target version for
+GRASS is also 2.1, but in some installations (such as the OSGeo Live DVD)
 you might have just 2.0.8 available. There are some 2.1 packages available,
 but they are not commonly installed and might have some issues, so if you prefer
 to use the more common and stable 2.0.8, you can do it by enabling 2.0.8
-compatibility in the configuration dialog, under the *SAGA* group.
+compatibility in the configuration dialog, under the *GRASS* group.
 
-.. figure:: img/first_saga_alg/enable208.png
+.. figure:: img/first_GRASS_alg/enable208.png
+   :align: center
 
-Once SAGA is installed, you can launch a SAGA algorithm double clicking on its name,
+Once GRASS is installed, you can launch a GRASS algorithm double clicking on its name,
 as with any other algorithm. Since we are using the simplified interface,
-you do not know which algorithms are based on SAGA or in another external
+you do not know which algorithms are based on GRASS or in another external
 application, but if you happen to double--click on one of them and the
 corresponding application is not installed, you will see something like this.
 
-.. figure:: img/first_saga_alg/missing_saga.png
+.. figure:: img/first_GRASS_alg/missing_GRASS.png
+   :align: center
+   :width: 50%
 
-In our case, and assuming that SAGA is correctly installed and configured,
+In our case, and assuming that GRASS is correctly installed and configured,
 you should not see this window, and you will get to the parameters dialog instead.
 
-Let's try with a SAGA--based algorithm, the one called *Split shapes layer randomly*.
+Let's try with a GRASS--based algorithm, the one called *Split shapes layer randomly*.
 
-.. figure:: img/first_saga_alg/split.png
+.. figure:: img/first_GRASS_alg/split.png
+   :align: center
 
 Use the points layer in the project corresponding to this lesson as input,
 and the default parameter values, and you will get something like this
 (the split is random, so your result might be different).
 
-.. figure:: img/first_saga_alg/split_layer.png
+.. figure:: img/first_GRASS_alg/split_layer.png
+   :align: center
 
 The input layer has been split in two layers, each one with the same number of
-points. This result has been computed by SAGA, and later taken by QGIS and
+points. This result has been computed by GRASS, and later taken by QGIS and
 added to the QGIS project.
 
-If all goes fine, you will not notice any difference between this SAGA--based
-algorithm and one of the others that we have previously run. However, SAGA might,
+If all goes fine, you will not notice any difference between this GRASS--based
+algorithm and one of the others that we have previously run. However, GRASS might,
 for some reason, not be able to produce a result and not generate the file that
 QGIS is expecting. In that case, there will be problems adding the result to the
 QGIS project, and an error message like this will be shown.
 
-.. figure:: img/first_saga_alg/missing_result.png
+.. figure:: img/first_GRASS_alg/missing_result.png
+   :align: center
 
-This kind of problems might happen, even if SAGA (or any other application that
+This kind of problems might happen, even if GRASS (or any other application that
 we are calling from the processing framework) is correctly installed, and it is
 important to know how to deal with them. Let's produce one of those error messages.
 
 Open the *Create graticule* algorithm and use the following values.
 
-.. figure:: img/first_saga_alg/create_graticule.png
+.. figure:: img/first_GRASS_alg/create_graticule.png
+   :align: center
 
 
 We are using  width and height values that is larger than the specified extent,
-so SAGA cannot produce any output. In other words, the parameter values are wrong,
-but they are not checked until SAGA gets them and tries to create the graticule.
+so GRASS cannot produce any output. In other words, the parameter values are wrong,
+but they are not checked until GRASS gets them and tries to create the graticule.
 Since it cannot create it, it will not produce the expected layer, and you will
 see the error message shown above.
 
-.. note:: In SAGA >= 2.2.3, the command will adjust automatically wrong input data,
+.. note:: In GRASS >= 2.2.3, the command will adjust automatically wrong input data,
  so you'll not get an error. To provoke an error, use negative values for division.
 
 Understanding this kind of problems will help you solve them and find an explanation
 to what is happening. As you can see in the error message, a test is performed
-to check that the connection with SAGA is working correctly, indicating you
+to check that the connection with GRASS is working correctly, indicating you
 that there might be a problem in how the algorithm was executed. This applies
-not only to SAGA, but also to other external applications as well.
+not only to GRASS, but also to other external applications as well.
 
 In the next lesson we will introduce the processing log, where information about
 commands run by geoalgorithms is kept, and you will see how to get more detail

docs/training_manual/processing/index.rst

@@ -22,7 +22,7 @@ Contents:
    second_alg
    crs
    selection
-   first_saga_alg
+   first_grass_alg
    log
    no_data
    vector_calculator

docs/training_manual/processing/log.rst

@@ -12,7 +12,7 @@ To open the log, click on the balloon at the bottom right, on the QGIS status ba
 Some algorithms might leave here information about their execution.
 For instance, those algorithms that call an external application
 usually log the console output of that application to this entry.
-If you have a look at it, you will see that the output of the SAGA algorithm that we just run
+If you have a look at it, you will see that the output of the GRASS algorithm that we just run
 (and that fails to execute because input data was not correct) is stored here.
 
 This is helpful to understand what is going on.
@@ -33,6 +33,8 @@ and you have the full history of your working session.
 Here is how that history looks like:
 
 .. figure:: img/log/history.png
+   :align: center
+   :width: 50%
 
 This can be very useful when starting working with the console, to learn about the syntax of algorithms.
 We will use it when we discuss how to run analysis commands from the console.