GRASS-Wiki - User contributions [en]

GRASS and Shell

2018-12-20T00:39:40Z

⚠️Pmolzer: /* See also */ add link to windows console page

This page contains information about GRASS GIS' own shell setup and use.

For information about scripting for GRASS, please refer to the page [http://grasswiki.osgeo.org/wiki/Shell_scripting Shell scripting].

== Automated batch jobs: Setting the GRASS environmental variables ==

'''''Main article: [[Working with GRASS without starting it explicitly]]'''''

This section applies to jobs which shall set the entire GRASS environment.
You have to set a couple of variables to enable GRASS command to run from outside GRASS:

# Example in bash shell syntax:

# path to GRASS binaries and libraries:
export GISBASE=/usr/lib64/grass74

export PATH=$PATH:$GISBASE/bin:$GISBASE/scripts
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GISBASE/lib

# set PYTHONPATH to include the GRASS Python lib
if [ ! "$PYTHONPATH" ] ; then
PYTHONPATH="$GISBASE/etc/python"
else
PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
fi
export PYTHONPATH

# use process ID (PID) as lock file number:
export GIS_LOCK=$$

# settings for graphical output to PNG file (optional)
export GRASS_PNGFILE=/tmp/grass6output.png
export GRASS_TRUECOLOR=TRUE
export GRASS_WIDTH=900
export GRASS_HEIGHT=1200
export GRASS_PNG_COMPRESSION=1
export GRASS_MESSAGE_FORMAT=plain

Define a GRASS session with the last used GISDBASE, LOCATION_NAME, and MAPSET

# path to GRASS settings file
export GISRC=$HOME/.grassrc7

Define a GRASS session with a different GISDBASE, LOCATION_NAME, and/or MAPSET

# path to GRASS settings file
export GISRC=/tmp/grass7-${USER}-$GIS_LOCK/gisrc
# remove any leftover files/folder
rm -fr /tmp/grass7-${USER}-$GIS_LOCK
mkdir /tmp/grass7-${USER}-$GIS_LOCK
export TMPDIR="/tmp/grass7-${USER}-$GIS_LOCK"
# set GISDBASE, LOCATION_NAME, and/or MAPSET
echo "GISDBASE: /path/to/some/grassdata" >>$GISRC
echo "LOCATION_NAME: some_location" >>$GISRC
echo "MAPSET: some_mapset" >>$GISRC
# start in text mode
echo "GRASS_GUI: text" >>$GISRC

The following three settings are only recommended if you will be calling the script from another program - e.g. a PHP web page using system() or exec()

export HOME=/var/www
export USER=www-data
export GROUP=www-data

Now you can test:

# this should print the GRASS version used:
g.version
# check GISDBASE, LOCATION_NAME, and MAPSET
g.gisenv
# other calculations go here ...

If this works, you can launch other GRASS commands. The approach works within Shell scripts and also in the command line terminal.

When done, you should cleanup internal tmp files like this:

# run GRASS' cleanup routine
$GISBASE/etc/clean_temp

# remove session tmp directory:
rm -rf /tmp/grass7-${USER}-$GIS_LOCK

'''Changing the prompt:'''

PS1_BACKUP="$PS1"
export PS1="GRASS 6> "

Once you are done, you can set it back (see also next hint about unsetting variables):
export PS1="$PS1_BACKUP"

'''Unsetting variables after usage:'''

Using the "unset VARNAME" command you get rid of it:
unset GISBASE
unset GISRC
...

=== Example ===

* GRASS shell script job to generate a [http://grass.fbk.eu/spearfish/php_grass_earthquakes.php Recent Earthquakes Map] (get the [http://grass.fbk.eu/spearfish/grass_earthquakes.sh grass_earthquakes.sh shell script])

=== Parallel GRASS jobs ===

See [[Parallel GRASS jobs]] for Grid Engine, PBS etc.

=== GRASS Batch jobs ===

Since GRASS GIS 6.4, there is an alternative method to easily run jobs in GRASS from a collection of commands in a shell script file. Just define the environmental variable GRASS_BATCH_JOB with the shell script file containing GRASS (or whatever) commands, preferably with full path. Then launch GRASS and it will be executed. It is best to launch GRASS in <tt>-text</tt> mode and to provide gisdbase/location/mapset as parameters. The job script needs executable file permissions (<tt>chmod</tt> on Unix). In order to get readable percentage output during the processing (0..2..4... 100%), we set the environment variable GRASS_MESSAGE_FORMAT to "plain":

Example:

<source lang="bash">
#### 1) PREPARATION
# First we generate a script which contains the command(s) to be executed:
# for convenience, we save the file in our HOME directory
## You may use also a text editor for this, here we use the "echo" shell command

echo "export GRASS_MESSAGE_FORMAT=plain
# set computational region, here: UTM32N coordinates
g.region n=4900000 s=4800000 w=700000 e=800000 res=100
v.random mymap3000 n=3000
v.out.ogr input=mymap3000 output=mymap3000.shp" > $HOME/my_grassjob.sh

# verify the content of the file
cat $HOME/my_grassjob.sh

# make it user executable (this is important, use 'chmod' or via file manager)
chmod u+x $HOME/my_grassjob.sh

# create a directory (may be elsewhere) to hold the location used for processing
mkdir -p $HOME/grassdata

# create new temporary location for the job, exit after creation of this location
grass70 -c epsg:32632 $HOME/grassdata/mytemploc_utm32n -e

#### 2) USING THE BATCH JOB
# define job file as environmental variable
export GRASS_BATCH_JOB="$HOME/my_grassjob.sh"

# now we can use this new location and run the job defined via GRASS_BATCH_JOB
grass70 $HOME/grassdata/mytemploc_utm32n/PERMANENT

#### 3) CLEANUP
# switch back to interactive mode, for the next GRASS GIS session
unset GRASS_BATCH_JOB

# delete temporary location (consider to export results first in your batch job)
rm -rf $HOME/grassdata/mytemploc_utm32n

# Now you can use the resulting SHAPE file "mymap3000.shp" elsewhere.
</source>

The grass70 command starts GRASS in the given mapset, executes the contents of the job file and leaves GRASS. Since the normal startup/closure is used, all internal tmp files are properly removed.

Note: The $HOME variable (or the ~ shortcut) cannot be used in the batch job itself since the variables are not available here.

==== Example ====

* Another set of GRASS shell scripts to run the job to generate another version of the [http://adhoc.osgeo.osuosl.org/grass/alternate_projections/earthquakes_wintri.png Recent Earthquakes Map] (find the setup files in the [https://trac.osgeo.org/grass/browser/grass-promo/tutorials/batch_processing "batch_processing" tutorials section] of the GRASS SVN)

=== Unattended execution ===

* {{wikipedia|GNU_Screen}} is another ''extremely'' valuable tool if you need to detatch and leave long-running processes unattended. It is well worth your time to learn how to use it if you run scripts on remote systems. There are many good tutorials on the web.
: Usage:
:: Run "screen" in the terminal. You will reach again the command line but now in screen mode. Now start GRASS.
::: - To disconnect from the session press Control-A, Control-D.
::: - To list your screens type "screen -ls" (to find it back)
::: - To reconnect with a disconnected screen run "screen -r [identifier]" (the "identifier" you need only if you have several screens running)
:: Enjoy.

* Along with the "{{wikipedia|nohup}}" (no hang-up) command you can login to your machine, launch the job and leave the machine again.
The process will continue after you logged off when you start it with nohup:
nohup grass64 ~/grassdata/spearfish60/neteler/ &

=== Receive a notification when finished ===

Maybe put email notification at the end of 'my_grassjob.sh' using the "mail" or the "mutt" program, for example like this:

echo "Finished at `date`" > /tmp/done.txt && \
EDITOR=touch mutt -s "Job done" \
me@mydomain.org < /tmp/done.txt && rm -f /tmp/done.txt

or like this:
mail -s "GRASS job $0 finished" me@mydomain.org <<EOF
GRASS GIS has finished the batch job $0
EOF

or simply like this:
echo "GRASS GIS has finished the batch job $0" | mail -s "GRASS job finished" me@mydomain.org

== Stupid pet tricks (don't use them!) ==

Note: This is highly discouraged. Keep fingers off from manually modifying the content of a GRASS GIS mapset (at least don't complain if you break things).

<strike>;Quick cd to the MAPSET directory
To make a quick little function called 'g.cd' to change into the mapset dir, add this to <tt>~/.grass.bashrc</tt>:

<source lang="bash">
g.cd()
{
MAPSET=`g.gisenv get=MAPSET`
LOCATION_NAME=`g.gisenv get=LOCATION_NAME`
GISDBASE=`g.gisenv get=GISDBASE`
LOCATION="$GISDBASE/$LOCATION_NAME/$MAPSET"
cd "$LOCATION/$1"
}
</source>

With that you can also do like: "<tt>g.cd colr/</tt>" to get to the color tables directory, or "<tt>g.cd ..</tt>" to get to the LOCATION directory.

Another method would be
<source lang="bash">
alias g.home='cd `dirname "$HISTFILE"`'
</source>
</strike>

;Simpler command completion from command history

Add this to a file called <tt>~/.inputrc</tt> in your home dir:

<source lang="bash">
set prefer-visible-bell

# -------- Bind page up/down wih history search ---------
"\e[5~": history-search-backward
"\e[6~": history-search-forward
</source>

Then you can type a bit of a command and use PgUp and PgDn to cycle through the command history which matches in a way less clumsy that Ctrl-r. Also it tells to make the shell flash on alarm instead of sending a beep to the speaker (making tab-completion compatible with your office mates).

== See also ==

Generic Shell script tutorials:
* [http://tldp.org/LDP/abs/abs-guide.pdf Advance bash-scripting guide]
* [http://www.linuxconfig.org/Bash_scripting_Tutorial Bash scripting Tutorial]

GRASS Shell script tutorials:
* [http://www.grassbook.org/examples_menu3rd.php GRASS Book script examples]
* [http://www.grassbook.org/unix_commands_table.php List of important UNIX system commands]

Misc:
* [[Script portability]]
* Other GRASS environment {{cmd|variables}}
* [[GRASS and Python]]
* [[Working with GRASS without starting it explicitly]]
* [[GRASS and windows console]]

[[Category:FAQ]]
[[Category:Scripting]]
[[Category:Linking to other languages]]

GRASS and windows console

2018-12-20T00:35:03Z

⚠️Pmolzer: remove useless info from the selecting a shell section. note - this section not valid until next release

''This page shows extended examples how to run GRASS modules in the winGRASS windows console''

==Windows batch files in GRASS==

In order to ease the workflow of analysis, several GRASS modules can be invoked at once by an batch file (*.bat) in the winGRASS windows console.

[https://trac.osgeo.org/grass/browser/grass/trunk/scripts Python grass modules] (e.g. v.db.addcolumn) have to be invoked by ''call'' in the batch-file.

<source lang="bat">
@ECHO ON
g.region -p
v.in.region output=myreg
call v.db.addtable map=myreg
call v.db.addcolumn map=myreg columns="col1 double"
v.to.db map=myreg option=area columns=col1
</source>

Running batch files without starting up GRASS:

<source lang="bat">
"%ProgramFiles?%\QGIS 2.18\bin\Grass72.bat" --exec MyScript.bat D:/myGrassData/MyLoc/MyMapset
</source>

==g.list output as input for another GRASS module==

Using g.list output as input variable for another module, e.g. to remove a list raster map.

<source lang="bat">
FOR /F %c in ('g.list "type=raster" "pattern=*2" "mapset=user1" "separator=comma"') DO SET RASTER2REMOVE=%c

echo %RASTER2REMOVE%
b172,d172,it172,r172

g.remove type=raster name=%RASTER2REMOVE%
The following data base element files would be deleted:
raster/b172@user1
raster/d172@user1
raster/it172@user1
raster/r172@user1
WARNING: Nothing removed. You must use the force flag (-f) to actually
remove them. Exiting.
</source>

Using g.list output as input variable for another module, e.g. to loop through a list of vector maps and buffer them.

<source lang="bat">
FOR /F %c IN ('g.list "type=vector" "separator=comma"') DO SET VECTLIST=%c

FOR %g IN (%VECTLIST%) DO v.buffer input=%g output=%g_buffer_200 distance=200
</source>

== selecting a shell ==
On windows, in the absence of the environmental variable GRASS_SH, the grass startup script selects the shell specified in environment variable ComSpec. This is typically cmd.sh.
The default shell can be overridden by setting the environment variable GRASS_SH. To make powershell the startup command shell set the environment variable with
<source lang="bat">
GRASS_SH=%SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe
</source>

[[Category: Development]]
[[Category: FAQ]]
[[Category: WinGRASS]]

GRASS and windows console

2018-12-20T00:07:21Z

⚠️Pmolzer: added the selecting a shell section

''This page shows extended examples how to run GRASS modules in the winGRASS windows console''

==Windows batch files in GRASS==

In order to ease the workflow of analysis, several GRASS modules can be invoked at once by an batch file (*.bat) in the winGRASS windows console.

[https://trac.osgeo.org/grass/browser/grass/trunk/scripts Python grass modules] (e.g. v.db.addcolumn) have to be invoked by ''call'' in the batch-file.

<source lang="bat">
@ECHO ON
g.region -p
v.in.region output=myreg
call v.db.addtable map=myreg
call v.db.addcolumn map=myreg columns="col1 double"
v.to.db map=myreg option=area columns=col1
</source>

Running batch files without starting up GRASS:

<source lang="bat">
"%ProgramFiles?%\QGIS 2.18\bin\Grass72.bat" --exec MyScript.bat D:/myGrassData/MyLoc/MyMapset
</source>

==g.list output as input for another GRASS module==

Using g.list output as input variable for another module, e.g. to remove a list raster map.

<source lang="bat">
FOR /F %c in ('g.list "type=raster" "pattern=*2" "mapset=user1" "separator=comma"') DO SET RASTER2REMOVE=%c

echo %RASTER2REMOVE%
b172,d172,it172,r172

g.remove type=raster name=%RASTER2REMOVE%
The following data base element files would be deleted:
raster/b172@user1
raster/d172@user1
raster/it172@user1
raster/r172@user1
WARNING: Nothing removed. You must use the force flag (-f) to actually
remove them. Exiting.
</source>

Using g.list output as input variable for another module, e.g. to loop through a list of vector maps and buffer them.

<source lang="bat">
FOR /F %c IN ('g.list "type=vector" "separator=comma"') DO SET VECTLIST=%c

FOR %g IN (%VECTLIST%) DO v.buffer input=%g output=%g_buffer_200 distance=200
</source>

== selecting a shell ==
On windows, in the absence of the environmental variable GRASS_SH, the grass startup script selects the shell specified in environment variable ComSpec. This is typically cmd.sh.
The default shell can be overridden by setting the environment variable GRASS_SH. Several shells are supported in the grass.py wrapper script ( AKA grass74.py for a version 7.4 install). These are ksh, csh, tcsh, bash, sh, zsh, cmd, and powershell. To make powershell the startup command shell set the environment variable with
<source lang="bat">
GRASS_SH=%SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe
</source>

[[Category: Development]]
[[Category: FAQ]]
[[Category: WinGRASS]]