How to use SAGA GIS Command Line saga_cmd, and why?

Fellow researchers and open-source GIS enthusiasts,

Welcome to my blog!

I’d like to start with a disclaimer – I may be a researcher of this very area but that doesn’t mean everything I do or write here will work for you, in your own desktop configurations and package versions. I have no responsibility if you lose data or mess up your installation. I also do not authorize any copies of my content.

Today, we are going to discuss the SAGA GIS Command Line “saga_cmd” called by QGIS 3.16 (and other versions of QGIS).

To start, I have some tips for using the command line version, and a rationalization about why I use the command line version more often than the QGIS GUI wrapping.

SAGA GIS (System for Automated Geoscientific Analyses) is a free software consisted of many algorithms for geoprocessing. Never heard of it? But if you are a QGIS user, you probably used it at some point. What do I mean by that?

SAGA GIS is built within QGIS and if you search on the Processing Toolbox of QGIS, many SAGA algorithms will be there. Those algorithms that generate files with the .sdat extension are probably from SAGA.

Why using command line SAGA?

SAGA also has its own Graphical User Interface (GUI). And it also has its own Command Line version. One may ask, why would someone deliberately choose to use a Command Line version in detriment of a GUI? Well, a GUI uses its own share of memory, CPU, sometimes GPU, to run. When running on command line, not only the same outputs are there, but also you don’t have that extra use of resources. This is especially useful if you are working with big spatial data in a computer that was not built for that, such as a notebook. If you are working with big data, or in a legacy computer, consider switching to the command line version.

If you don’t use the SAGA GUI directly, there may be an extra reason to use command line.

If you are used to running SAGA algorithms in a different software, such as QGIS, check the SAGA version that is being called by the program. For reference, now, in March 2021, the current SAGA version is 7.9.0. Example given, in QGIS 3.16.4 Hannover, the SAGA version included is 2.3.2. If you really like using a GUI (no judgment here!), but still wants the newest SAGA, there is an experimental plugin that may be able to allow the use of newer versions of SAGA within QGIS, but I haven’t tried it yet.

In my humble opinion, the easiest way to use the newest SAGA version is downloading it and using the command line version via Command Prompt.

What QGIS does to run SAGA algorithms is to collect the input information users provide on the GUI and then run Command Line SAGA “saga_cmd” in the background.

When running an algorithm from the Processing Toolbox on QGIS, the tab “Log” shows the evolution of the algorithm. Now, many of us don’t give a second glance into that screen, but it shows what QGIS is running on the background, in case, the SAGA algorithm.

For example, I open a window on QGIS to run a SAGA algorithm:

I click “Run” and the tab changes to “Log”. When it finishes running, if you scroll within this tab, it will show what has been run.

Hey, that is the SAGA header!

Scroll a little bit more to the top and you will see the code that has been run, something like this:

io_gdal 0 -TRANSFORM 1 -RESAMPLING 3 -GRIDS \
"C:/Users/L/AppData/Local/Temp/processing/fe9d7f3f0a155/teste.sgrd" \ 
-FILES "D:/mapateste/teste.tif"

contrib_perego "Destriping" -INPUT "C:/Users/L/AppData/Local/Temp/processing/fe9d7f3f0a155/teste.sgrd" \
-ANG 0.0 -R 10.0 -D 2.0 \
-RESULT3 "C:/Users/L/AppData/Local/Temp/processing/fe9d7f3f0a155/RESULT3.sdat" \
-RESULT1 "C:/Users/L/AppData/Local/Temp/processing/fe9d7f3f0a155/RESULT1.sdat" \
-RESULT2 "C:/Users/L/AppData/Local/Temp/processing/fe9d7f3f0a155/RESULT2.sdat"

From this command, you can see the structure is:

First:

saga_cmd io_gdal 0 

io_gdal 0 is “GDAL Raster Import” – a tool used to import the .tif grid.

Second:

saga_cmd contrib_perego “Destriping”

contrib_perego “Destriping” is from Module Destriping of SAGA, a tool used to remove stripes from rasters.

So, what we can see is that it is possible to observe in the tab “Log” the SAGA algorithms that are being used by QGIS. This is especially useful if you get errors in the execution – we’ll get to that another day.

Well, I want to run SAGA on Command Line, but how do I do it?

Windows users have it easier this time: just download the newest version (http://www.saga-gis.org/). I didn’t install it. saga_cmd works fine for me just opening the Command Prompt in the same folder as the executable saga_cmd.exe is located.

In Linux distros, you will probably have to build the application, unless you use the repository version, which I believe is older than the one available for building (but check it on the package manager to be sure). Go to the SAGA website (www.saga-gis.org) for directions.

Then, type in the Prompt “saga_cmd” (or, if you’re in Ubuntu, type it in the Terminal). If everything goes well, a list of the available categories of scripts will be shown:

“ta” is the abbreviation for Terrain Analysis. Ok, now let’s look what is inside the library “ta_preprocessor” by typing saga_cmd ta_preprocessor:

In ta_preprocessor, there are seven algorithms available. Let’s try the fifth one, Fill Sinks XXL by Wang and Liu. Type saga_cmd ta_preprocessor 5 to see the requirements.

Look at the usage: saga_cmd ta_preprocessor 5 -ELEV -FILLED -MINSLOPE

str means the algorithm is looking for a string in that location, like a word, or, in this case, the name and the path of the file. Double means it is looking for a double precision number, which means it can be any number, but it will be saved as double precision while the algorithm is running.

To use this algorithm, I would type something like this:

saga_cmd ta_preprocessor 5 -ELEV C:/my_path/my_DEM.tif -FILLED C:/my_path/output_name.sdat -MINSLOPE 0.1

Wait until the end of the command and check your raster (the .sdat file).

For this, I like to open QGIS again, check if the raster has been generated correctly and then save this raster as .tif exporting it from QGIS.

To check the mandatory and optional entries for each algorithm as well as the references for the algorithms, check the SAGA GIS Documentation, available at http://www.saga-gis.org/saga_tool_doc.

To execute the same command that was executed in QGIS up there, I would execute the same algorithms that we saw in the Log. In this case, the equivalent would be contrib_perego 5:

saga_cmd contrib_perego 5 -INPUT teste.tif -RESULT3 destriped.tif -RESULT2 output2.tif -RESULT1 output1.tif 

It’s a lot of work – does it pay off?

Yes, I think it does. As time goes by, I get more and more used to using saga_cmd directly. Also, using the command line version allows you to execute long algorithms in parts, and to do batch processing easily. I will approach this matter in the future. It also saves memory and CPU usage, allowing for larger rasters to be processed.

So, do you think SAGA GIS wrapping in QGIS is useless?

No, not at all! Far from useless, it integrates SAGA with QGIS! And it is a quick way to use SAGA algorithms! I just like to show that there is another option, without using a GUI, that people may not be aware of. There are even other options that I did not cite here, but that I plan on approaching in the future.

Extras:

• I want to stop this algorithm, how can I stop it?

Press Ctrl + C.

• I don’t know where my output file is.

Have you checked the folder where saga_cmd.exe is?

• I don’t want to type everything by hand.

You can type it somewhere else, like in Notepad, and then paste it in the Prompt. Also, the top arrow shows the last command you used, it might be useful.

• There was an error and the algorithm usage was presented back at me.

Try the same algorithm in QGIS. If the error persists, we’ll get to that, soon.

• Saga version used is not the most recent, although I downloaded the most recent./saga_cmd is not recognized as a program.

Check if you are in the same folder as saga_cmd.exe. Call dir command to show all the files in the folder and look for saga_cmd.exe to check.