Automating SAGA Workflows Using Command Line Scripting
Introduction
Background
This project aims to create a solution for companies to increase productivity by analysis automation. Automation in this context is to effectively use information technologies to optimize productivity in data and results, as well as requesting certain processing results. This project in the end will effectively guide the user on how to communicate with SAGA GIS with this goal in mind. SAGA stands for System for Automated Geoscientific Analyses; it is run and created by members of the Department of Physical Geography at the University of Hamburg in Germany. SAGA is a GIS system that is free open source software, it is one of the more popular free open source programs. It is approachable, visual, fairly intuitive and very useful. The project will enable users to use Python and extraction methods to manipulate workflows within a Windows and Linux environment (because there are differences when working with either).
SAGA source codes have been licensed to be public, meaning the codes are open and available to be modified. This allows for code to be accessible for any user. SAGA is compatible with Python, which is a highly used, well-documented programming language, and SAGA has a Python API (application program interface) embedded within.
To access SAGA [1]
To access Python [2]
Objectives
1. Understand the code embedded in the previously existing modules in SAGA (i.e. analytical hillshade).
2. Understand the ways of automation and how to execute them in Python.
3. Providing translations between Windows and Linux.
Methodology
SAGA_CMD
Exploring the environment of the command line application (saga_cmd)
The following are the basics for understanding the use of the command line within SAGA. Users can use the command line to quickly and efficiently run scripts to execute functions with specified parameters.
1. The path is telling the program where and how to access files. To set a path to a variable the following command is to be used:
set PATH=%PATH%;C:\”file name” [windows]
OR
export PATH=$PATH:/”file name” [linux]
To see where a variable is that already has a path set, users can “print” the contents of the variable by using the following:
echo %PATH% [windows]
OR
echo $PATH [linux]
This will give a result of the path (where to locate file).
To access help files the following script can be used:
$ saga_cmd [--help] [windows]
OR
saga_cmd [-h] [linux]
This pulls up a way to decode command scripts (see figure 1)
Figure 1. help file outputs in SAGA.
By using various series of this language, the user is able to automatically pick from the library, module, options and produce a script.
To call on the library, a simple call can be used (“saga_cmd”). Simply calling on the command line automatically produces a list of the module libraries (see figure 2).
Figure 2. Command line results in SAGA for calling on the existing modules by using the command line.
To call on the library, which identifies functionality within a module, the user must input the name of the module after calling on “saga_cmd”. The result ends up with a list of the tools and functions of that specific library (see figure 3).
Figure 3. SAGA output results where calling on the command line and the associated library (this is using saga_cmd ta_lighting to call on the lighting module in SAGA).
For example, a workflow for hillshade analysis (calculating the angle between the surface and the incoming light beams in radians) can be used by automating the process of taking ASCII grids or DEMS, converting them into SAGA grids and then creating an analytical hillshade for each tile. The following command would be used to pull up all parameters in the hillshade analysis (see figure 4). Parameters must be defined and then can be run within the command line.
$ saga_cmd ta_lighting "Analytical Hillshading"
Reminder: (“ta_lighting” refers to the module it belongs to and “Analytical Hillshading” refers to the function name in the library of the module).
Figure 4. Variables to define in hillshade analysis.
Also, when left clicking “Analytical Hillshading” in the index, you can select “Create Script Command File” (see figure 5), where you can copy and paste command snippets to alter parameters (see figure 6).
Figure 5. Left clicking in index allows option to “Create Script Command File” to enable editing process of parameters included in module.
Figure 6. Script command file created in process of figure 3.
When doing more basic tasks in SAGA, the command line is the most useful, as it requires the least amount of code associated with these processes. If the user is more interested in doing a more complicated analysis, or combine various tools and functions, this is where an outside program needs to be used. In this case, Python has been chosen to modify scripts and increase the functionality of SAGA.
When doing more basic tasks in SAGA, the command line is the most useful, as it requires the least amount of code associated with these processes. If the user is more interested in doing a more complicated analysis, or combine various tools and functions, this is where an outside program needs to be used. In this case, Python has been chosen to modify scripts and increase the functionality of SAGA.
Using Python
By using a similar workflow as the saga_cmd, the following can be used in Python to do the same tasks.
To call on module library:
mlb= saga_api.CSG_Module_Library
To choose a module from the library:
m= mlb.Get_Module(1)
- The number 1 refers to the ID number of the module (see figure 1 for that list in saga_cmd). You can also add in the name of the module, m= mlb.Get_Module(‘Analytical Hillshade”)
To get and set parameters:
P =m.Get_Parameters()
P(‘FILE’).Set_Value(fASC)
To run module:
print m.Get_Name() + ‘ : ’ = p( ‘FILE’ ) .asString()
For More Information...
http://sourceforge.net/p/saga-gis/wiki/Creating%20Python%20scripts/ http://sourceforge.net/projects/saga-gis/files/SAGA%20-%20Documentation/Tutorials/Command_Line_Scripting/
