SAGA User Group Association

Automation of Workflows with SAGA

[vw@localhost~]$saga_cmd
Error:noargumentsforsagacall
Error:library
63loadedmodulelibraries(569modules):
imagery_tools
ta_morphometry
...
typehorhelpforfurtherinformation

Automation of Workflows with

SAGA
Command line scripting in a nutshell

Volker Wichmann
alpS GmbH Centre for Climate Change Adaptation
Laserdata GmbH

AGIT 2013

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | Introduction why scripting ?

Why scripting?Why

Allows to automate workflows

Why automatisation?Why

Automation is the use of ... information technologies to optimize productivity in the

production of goods and delivery of services (http://en.wikipedia.org/wiki/Automation)

several similar calculations that need

to be done for a large number of tiles,
e.g. import fromASCII, calculation
of ...

Web Processing Service (WPS)

- a web interface requests a certain
processing result, e.g. a hillshade
computation

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | Introduction SAGA CMD and Environmental Variables

Command line application: saga_cmd (.exe)

Environmental variable PATH:
either change to the directory of the saga_cmd (.exe) binary
or add the path to saga_cmd (.exe) to the PATH environmental variable
print contents of the PATH variable
echo%PATH%
[windows]
echo$PATH
[linux]
set PATH variable
setPATH=%PATH%;C:\my_path_to_saga_cmd [windows]
exportPATH=$PATH:/my_path_to_saga_cmd [linux]
Environmental variable SAGA_MLB
SAGA_MLB stores the path to the (optional) SAGA module libraries to be
used with saga_cmd (.exe)
Remark: since SAGA 2.1.0, all native SAGA module libraries are found
automatically, making it obsolete to set SAGA_MLB in case you do not use any
own libraries stored in an additional path

setSAGA_MLB=C:\my_path_to_saga_mlbs
exportSAGA_MLB=/my_path_to_saga_mlbs

[windows]
[linux]
V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage

a simple call to saga_cmd results in:

[vw@localhost~]$saga_cmd
Error:noargumentsforsagacall
Error:library
63loadedmodulelibraries(569modules):
shapes_points
io_grid_grib2
imagery_tools
ta_morphometry
...
typehorhelpforfurtherinformation

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage

a call to saga_cmd with --help results in:

[vw@localhost~]$saga_cmdhelp
...
_____________________________________________
Usage:
saga_cmd[h,help]
saga_cmd[v,version]
saga_cmd[b,batch]
saga_cmd[d,docs]
saga_cmd[f,flags][=qrsilpx][c,cores][=#]<LIBRARY><MODULE><OPTIONS>
saga_cmd[f,flags][=qrsilpx][c,cores][=#]<SCRIPT>
[h],[help]:helponusage
[v],[version]:printversioninformation
[b],[batch]:createabatchfileexample
[d],[docs]:createmoduledocumentationincurrentworkingdirectory
[c],[cores]:numberofphysicalprocessorstouseforcomputation
[f],[flags]:variousflagsforgeneralusage[qrsilpx]
q:noprogressreport
r:nomessagesreport
s:silentmode(noprogressandnomessagesreport)
i:allowuserinteraction
l:loadtranslationdictionary
p:loadprojectionsdictionary
x:useXMLmarkupsforsynopsesandmessages
<LIBRARY>:nameofthelibrary
<MODULE>:eithernameorindexofthemodule
<OPTIONS>:modulespecificoptions
<SCRIPT>:sagacmdscriptfilewithoneormoremodulecalls
_____________________________________________
Example:
saga_cmdf=sta_lighting0ELEVATION=c:\dem.sgrdSHADE=c:\shade.sgrd
V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage

a call to saga_cmd with a <LIBRARY> results in:

[vw@localhost~]$saga_cmdta_lighting
...
Error:module
modules:
0 AnalyticalHillshading
2 PotentialIncomingSolarRadiation
3 SkyViewFactor
4 TopographicCorrection
5 TopographicOpenness
6 Visibility(points)
typehorhelpforfurtherinformation

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage

a call to saga_cmd with a <LIBRARY> and <MODULE> results in:

[vw@localhost~]$saga_cmdta_lighting"AnalyticalHillshading"
...
librarypath: /usr/local/lib/saga/libta_lighting.so
libraryname: TerrainAnalysisLighting,Visibility
modulename: AnalyticalHillshading
author: O.Conrad,V.Wichmann(c)20032013
_____________________________________________
Usage:saga_cmdELEVATION<str>[SHADE<str>][METHOD<str>][AZIMUTH<str>]
[DECLINATION<str>][EXAGGERATION<str>][NDIRS<num>][RADIUS<str>]

ELEVATION:<str>
Elevation
Grid(input)
SHADE:<str>
AnalyticalHillshading
Grid(output)
METHOD:<str>
ShadingMethod
Choice
AvailableChoices:
[0]Standard
[1]Standard(max.90Degree)
[2]CombinedShading
[3]RayTracing
[4]AmbientOcclusion
Default:0
AZIMUTH:<str>
Azimuth[Degree]
Floatingpoint
Default:315.000000

DECLINATION:<str>
Floatingpoint
Default:45.000000
EXAGGERATION:<str>
Floatingpoint
Default:4.000000
NDIRS:<num>
Integer
Minimum:2
Default:8
RADIUS:<str>
Floatingpoint
Minimum:0.001000
Default:100.000000

Declination[Degree]
Exaggeration
NumberofDirections

SearchRadius

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage

a call to saga_cmd with a <LIBRARY> <MODULE> and <OPTIONS> results in:

[vw@localhost~]$saga_cmdta_lighting"AnalyticalHillshading"
ELEVATION=Mt_St_Helens_SRTM.sgrdSHADE="Mt_St_Helens_shade.sgrd"METHOD=0
...
_____________________________________________
librarypath: /usr/local/lib/saga/libta_lighting.so
libraryname: TerrainAnalysisLighting,Visibility
modulename: AnalyticalHillshading
author: O.Conrad,V.Wichmann(c)20032013
_____________________________________________
Loadgrid:Mt_St_Helens_SRTM.sgrd...
100%okay
Parameters
Gridsystem:30;312x458y;557970x5108130y
Elevation:Mt_St_Helens_SRTM
AnalyticalHillshading:AnalyticalHillshading
ShadingMethod:Standard
Azimuth[Degree]:315.000000
Declination[Degree]:45.000000
Exaggeration:4.000000
NumberofDirections:8
SearchRadius:100.000000
101%Savegrid:Mt_St_Helens_shade.sgrd...
100%okay

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage Parameter Types

SAGA Parameter Types

Dataobjects:
(Optional)Input
(Optional)Output
Dataobject Types:
Grid
Shapes
Tables
Pointclouds
File(path)
DataobjectLists

filename.sgrd
filename.shp
filename.txt or filename.dbf
filename.spc
filepath/filename.ext
filename.ext;filename.ext;filename.ext

TableField (shapes, tables, pointclouds):

Fieldnumber
(first field = 0)
Fieldname
the field name
TableFields (shapes, tables, pointclouds):
Fieldnumbers
0,3,7,8
Fieldnames
id,landuse,slope,aspect

V. Wichmann

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD usage Parameter Types

SAGA Parameter Types

Boolean

if IDENTIFIER is passed: Parameter = TRUE

if IDENTIFIER is NOT passed: Parameter = FALSE

Value

integer or floating point value (decimal separator is .)

Degree

unlike in the GUI: decimal degree (floating point)

Range

two parameters: IDENTIFIER_MIN and IDENTIFIER_MAX

Choice

the number of the choice to use

String

character string, quoted in case it contains spaces

GridSystem
USER_XMIN
USER_XMAX
USER_YMIN
USER_YMAX
USER_SIZE

Left
Right
Bottom
Top
Cellsize
V. Wichmann

10

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Environment

Scripting Environment

Windows:
Microsoft command interpreter (cmd.exe)
batch files (*.bat): text files containing a series of commands to be executed
http://en.wikibooks.org/wiki/Windows_Batch_Scripting
GNU/Linux, Mac OSX:
Bash command processor (Unix shell)
Bash files (*.sh): text files containing a series of commands to be executed
http://tldp.org/LDP/abs/html/
Drawbacks:
The parsing of a command line into a sequence of commands is complex and
varies from command interpreter to command interpreter, including
Variable substitution
Quoting
Syntax
Redirection
Different scripts are needed on different operating systems
V. Wichmann

11

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Environment

Scripting Environment

Python:
Widely used general-purpose, high-level programming language
Often used as scripting language
http://docs.python.org/2/tutorial/
Advantages:
Platform independent --> use the same script on different operating systems
It's a complete programming language --> very powerful
Statements and flow control
Expressions, e.g. string manipulation
Functions
Libraries, providing tools suited to many tasks
Redirection (logging)
...
... and there is also a SAGA Python API available, providing even more
flexibility
V. Wichmann

12

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Examples

Scripting Examples

Task:
Convert ESRI ASCII files (DEMs) stored in a folder to SAGA grids
Calculate an analytical hillshade for each tile
Next slides show scripts for Windows, GNU/Linux and Python

V. Wichmann

13

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Example Windows batch_example.bat

V. Wichmann

14

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Example GNU/Linux bash_example.sh

V. Wichmann

15

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Example Python python_example.py

V. Wichmann

16

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Example Python python_example.py

V. Wichmann

17

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting Example Python python_example.py

V. Wichmann

18

SAGA User Group Association

Automation of Workflows with SAGA

AGIT 2013

SAGA | CMD Scripting - Outlook

Outlook

SAGA Python API:

Direct access to the SAGA API from the script
No need to save datasets between module calls
Examples on how to use the SAGA Python API are available in the SAGA
sources, see folder saga-gis/src/scripting/python/

... and in case you really like to stick to batch scripting: create an example script file
from the GUI as template ;-)

V. Wichmann

19