Executing Modules with SAGA CMD

Anonymous

SAGA CMD is a command line interface to execute SAGA modules. Other than SAGA GUI, it provides no functionality for data management and data visualization. It's purpose is to automate tasks by writing scripts or to execute SAGA modules from within an other application like a web server. This section will describe the necessary setup of your system to use SAGA CMD and execute modules.

Please note, that there is also a tutorial on command line scripting available: http://sourceforge.net/projects/saga-gis/files/SAGA%20-%20Documentation/Tutorials/Command_Line_Scripting/


Environment

WINDOWS

SAGA CMD is executed within the command line interface cmd.exe of windows. To make the saga_cmd.exe available from every path, you should add the SAGA installation path to your PATH variable:

C:\>PATH=%PATH%;C:\yourPathToSAGA_CMD
e.g.:
C:\>PATH=%PATH%;C:\saga_2\bin\saga_vc

If you don't like to do so, you will always have to execute provide the path to saga_cmd.exe or execute it from within the SAGA installation path.

Next you have to set the environmental variable SAGA_MLB to make SAGA know where the SAGA module libraries exist on your system. You can do this permanently by using the windows system control center or by defining it temporarily on the command line before executing SAGA CMD:

C:\>SET SAGA_MLB=C:\yourPathToSAGA_modules
e.g.:
C:\>SET SAGA_MLB=C:\saga_2\bin\saga_vc\modules

Now your system is prepared for using SAGA CMD to execute SAGA modules.

LINUX

Unlike to windows systems, saga_cmd should be instantly available in the shell as it is usually installed in /usr/local/bin.
Next you have to set the environmental variable SAGA_MLB to make SAGA know where the SAGA module libraries exist on your system. You can do this permanently by adding the following command to your .bashrc file or by defining it temporarily on the command line before executing SAGA CMD:

[user@localhost ~]$ export SAGA_MLB=/yourPathToSAGA_modules
e.g.:
[user@localhost ~]$ export SAGA_MLB=/usr/local/lib/saga

Now your system is prepared for using SAGA CMD to execute SAGA modules.


Running SAGA CMD

Once you have setup your system (making the paths to SAGA CMD and the SAGA modules known) you can execute SAGA CMD on the command line:

C:\>saga_cmd on WINDOWS and
[user@localhost ~]$ saga_cmd on LINUX respectively

This will not only execute SAGA CMD but also list all of the available module libraries.
Now you can obtain information on how to use SAGA CMD by executing it with the -h or --help flag:

C:\>saga_cmd -h
[user@localhost ~]$ saga_cmd -h

_____________________________________________
  #####   ##   #####    ##
 ###     ###  ##       ###
  ###   # ## ##  #### # ##
   ### ##### ##    # #####
##### #   ##  ##### #   ##

SAGA CMD 2.0.3
_____________________________________________
(C) 2005-08 by O.Conrad
under GNU General Public License (GPL)

Usage:

saga_cmd [-h, --help]
saga_cmd [-create_batch]
saga_cmd <LIBRARY> <MODULE> [-silent] <module specific options...>

[-h], [--help]  : help on usage
[-create_batch] : create a batch file example
[-silent]       : don't wait for user response on errors
<LIBRARY>       : file name of the library
<MODULE>        : either name or index of the module

example:
  saga_cmd ta_morphometry
           "Local Morphometry"
           -ELEVATION c:\dem.sgrd
           -SLOPE     d:\slope.sgrd
           -ASPECT    d:\aspect.sgrd
           -METHOD    1

_____________________________________________
Module libraries are expected to be located in
the directory, that is specified by the environment
variable 'SAGA_MLB'. If this is not found the
current working directory will be searched for instead.

SAGA CMD is particularly useful for the automated
execution of a series of analysis steps, because it
allows you to execute modules using batch files.
Calling saga_cmd with the option '-create_batch'
creates a batch file example. You probably have to edit
the path definitions to make the batch file run on your
computer.

As you can see, you need to append the name of the module library you like to use to the SAGA CMD call, e.g.:

C:\&gt;saga_cmd ta_morphometry

On LINUX, you will have to alter the module library name accordingly by adding "lib" to the module library name:

[user@localhost ~]$ saga_cmd libta_morphometry

Such a call will list you all of the available modules within the module library:

_____________________________________________
  #####   ##   #####    ##
 ###     ###  ##       ###
  ###   # ## ##  #### # ##
   ### ##### ##    # #####
##### #   ##  ##### #   ##

SAGA CMD 2.0.3
_____________________________________________
100%
error: module

available modules:
 0      - Local Morphometry
 1      - Convergence Index
 2      - Convergence Index (Search Radius)
 3      - Surface Specific Points
 4      - Curvature Classification
 5      - Hypsometry
 6      - Real Area Calculation
 7      - Morphometric Protection Index
 8      - Multiresolution Index of Valley Bottom Flatness (MRVBF)
 9      - Downslope Distance Gradient

type -h or --help for further information

The modules are enumerated beginning from zero. To get more information about the module parameters, simply add the number of the module to the call, e.g. (Local Morphometry module)

C:\&gt;saga_cmd ta_morphometry 0
[user@localhost ~]$ saga_cmd libta_morphometry 0

or add the name of the module

C:\&gt;saga_cmd ta_morphometry "Local Morphometry"
[user@localhost ~]$ saga_cmd libta_morphometry "Local Morphometry"

This will print out all of the module parameters:

_____________________________________________
  #####   ##   #####    ##
 ###     ###  ##       ###
  ###   # ## ##  #### # ##
   ### ##### ##    # #####
##### #   ##  ##### #   ##

SAGA CMD 2.0.3
_____________________________________________
100%library path:       C:\yourPathToSAGA\modules
library name:   ta_morphometry
module name :   Local Morphometry
author      :   (c) 2001 by O.Conrad
_____________________________________________
go...
Usage: 0 -ELEVATION <str> -SLOPE <str> -ASPECT <str> [-CURV <str>] [-HCURV <str>] [-VCURV <str>] [-METHOD <num>]
  -ELEVATION:<str>      Elevation
        Grid (input)
  -SLOPE:<str>          Slope
        Grid (output)
  -ASPECT:<str>         Aspect
        Grid (output)
  -CURV:<str>           Curvature
        Grid (optional output)
  -HCURV:<str>          Plan Curvature
        Grid (optional output)
  -VCURV:<str>          Profile Curvature
        Grid (optional output)
  -METHOD:<num>         Method
        Choice
        Available Choices:
        [0] Maximum Slope (Travis et al. 1975)
        [1] Maximum Triangle Slope (Tarboton 1997)
        [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
        [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
        [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
        [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
        [6] Fit 3.Degree Polynom (Haralick 1983)
The value for the option 'ELEVATION' must be specified.

error: executing module [Local Morphometry]

In most cases it's of great help to have a look at the module in SAGA GUI. Take a look at the Description tab of the Properties window of the module. The names in the Identifier column correspond to the flags used with SAGA CMD.


Example: Calculating morphometric parameters of Mt. St. Helens

Download the sample dataset and extract the ZIP file. We will calculate slope, aspect and horizontal and vertical curvature with the Local Morphometry module using the method of Zevenbergen & Thorne (1987). Have a look at the module parameters by calling the module (see above): you MUST specify an ELEVATION input dataset, and a SLOPE and an ASPECT output dataset. In addition you have to specify the METHOD you like to use to calculate these grids. The curvature grids are optional, which means that they are only calculated in case you provide their arguments. A call of the module to calculate these parameters looks like this:

C:\&gt;saga_cmd ta_morphometry 0 -ELEVATION C:\yourPath\DGM_30m_Mt.St.Helens_SRTM.grd -SLOPE C:\yourPath\Helens_slope -ASPECT C:\yourPath\Helens_aspect -HCURV C:\yourPath\Helens_hcurv -VCURV C:\yourPath\Helens_vcurv -METHOD 5

[user@localhost ~]$ saga_cmd libta_morphometry 0 -ELEVATION /yourPath/DGM_30m_Mt.St.Helens_SRTM.grd -SLOPE /yourPath/Helens_slope -ASPECT /yourPath/Helens_aspect -HCURV /yourPath/Helens_hcurv -VCURV /yourPath/Helens_vcurv -METHOD 5

This will result in the following output:

_____________________________________________
  #####   ##   #####    ##
 ###     ###  ##       ###
  ###   # ## ##  #### # ##
   ### ##### ##    # #####
##### #   ##  ##### #   ##

SAGA CMD 2.0.3
_____________________________________________
100%library path:       C:\yourPathToSAGA\modules
library name:   ta_morphometry
module name :   Local Morphometry
author      :   (c) 2001 by O.Conrad
_____________________________________________
go...

Load grid: DGM_30m_Mt.St.Helens_SRTM.grd...
100%
okay

Parameters

Grid system: 30; 312x 458y; 557970x 5108130y
Elevation: DGM_30m_Mt.St.Helens_SRTM.grd
Slope: new
Aspect: new
Curvature: [not set]
Plan Curvature: new
Profile Curvature: new
Method: Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)

100%
Save grid: Helens_slope...
100%
okay

Save grid: Helens_aspect...
100%
okay

Save grid: Helens_hcurv...
100%
okay

Save grid: Helens_vcurv...
100%
okay

This is a simple example, in order to get a clue on how to use other modules and how to build a batch file execute SAGA CMD with the flag -create_batch. This will write out a batch file named saga_cmd_example.bat you can use as a template. The file is an example for WINDOWS but it is easily patched to work as a bash script on LINUX.


Related

Wiki: Executing SAGA Modules

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks