Working with GRASS without starting it explicitly: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(+ Python: GRASS GIS 8 with existing location)
 
(30 intermediate revisions by 6 users not shown)
Line 1: Line 1:
GRASS modules and imports of GRASS Python packages works only in a specific environmental settings (GRASS session). This settings is ensured by starting GRASS GIS application which prepares this GRASS session for you. It is possible to set up you system in the way GRASS session will be always active (GRASS is not running, just the environmental settings is ready). People often prefer to set up the GRASS environment in their script or program and this is what this article discuss. However, it must be noted that the the generally preferred (and easy) way is to create scripts and programs as GRASS modules which means that your don't have to bother with setting up the environment since the GRASS module should be always invoked only in GRASS session.
GRASS GIS modules and the import of GRASS Python packages works only in a specific environmental settings (GRASS session). This settings is ensured by starting GRASS GIS application which prepares this GRASS session for you. It is possible to set up you system in the way that the GRASS session will be always active (i.e. the GRASS startup script is not running, just the environmental settings are done). People often prefer to set up the GRASS environment in their script or program and this is what this article discuss. However, it must be noted that the the generally preferred (and easy) way is to create scripts and programs as GRASS modules which means that your don't have to bother with setting up the environment since the GRASS module should be always invoked only in GRASS session.


== GRASS sessions ==
== GRASS sessions ==


It is possible to access GRASS modules without explicitly starting a "GRASS session". GRASS libraries require certain [http://grass.osgeo.org/grass70/manuals/variables.html environment variables] to be set. In fact a "GRASS session" is just a set of processes (e.g. a shell and/or GUI) which have the necessary environment settings, specifically:
It is possible to access GRASS modules without explicitly starting a "GRASS session". GRASS libraries require certain [http://grass.osgeo.org/grass78/manuals/variables.html environment variables] to be set. In fact a "GRASS session" is just a set of processes (e.g. a shell and/or GUI) which have the necessary environment settings, specifically:


* '''GISBASE''' needs to be set to the top-level directory of the GRASS installation.
* '''GISBASE''' needs to be set to the top-level directory of the GRASS installation.
Line 19: Line 19:
See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.
See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.


=== Accessing GRASS modules without starting a GRASS session ===
=== Starting a GRASS session and terminating it automatically ===
 
A GRASS session can be started and terminated automatically with the -e flag.
 
Since GRASS GIS 7.2.x you can execute commands from outside by passing the command to be executed (or a script with a collection of GRASS GIS commands) to the --exec flag:
 
Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:
<source lang="bash">
grass78 -c elevation.tiff -e /path/to/grassdata/test1/
</source>
 
Linking external raster data to PERMANENT Mapset:
<source lang="bash">
grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=basins.tiff output=basins
grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=elevation.tiff output=elevation
</source>
 
Get statistics for one raster map:
<source lang="bash">
grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.univar map=elevation
</source>
 
==== Start a GRASS session but do not terminate it automatically ====
 
Compare the rasters visually:
<source lang="bash">
grass78 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
</source>
 
Read more in the [https://grass.osgeo.org/grass78/manuals/grass7.html#batch-jobs-with-the-exec-interface manual].


==== Python examples ====
==== Python examples ====


See also [[GRASS Python Scripting Library]]
For details on GRASS GIS Python programming, see also [[GRASS Python Scripting Library]].
 
===== Python: GRASS GIS 7 with an external library: grass-session =====
 
The [https://github.com/zarch/grass-session "grass-session" Python library] is an easy way to control GRASS GIS from "outside"-Python. To install the current version, run:
 
<source lang="bash">
pip install grass-session
# for the latest development version use:
# pip install git+https://github.com/zarch/grass-session.git
</source>
 
Then write
<source lang="python">
#!/usr/bin/env python
# filename: test_session.py
 
from grass_session import Session
from grass.script import core as gcore
 
# create a new location from EPSG code (can also be a GeoTIFF or SHP or ... file)
with Session(gisdb="/tmp", location="mylocation",
            create_opts="EPSG:4326"):
  # run something in PERMANENT mapset:
  print(gcore.parse_command("g.gisenv", flags="s"))
# expected output:
# {u'GISDBASE': u"'/tmp/';",
#  u'LOCATION_NAME': u"'mylocation';",
#  u'MAPSET': u"'PERMANENT';",}
 
# create a new mapset in an existing location
with Session(gisdb="/tmp", location="mylocation", mapset="test",
            create_opts=""):
    # do something in the test mapset.
    print(gcore.parse_command("g.gisenv", flags="s"))
# expected output:
# {u'GISDBASE': u"'/tmp/';",
#  u'LOCATION_NAME': u"'mylocation';",
#  u'MAPSET': u"'test';",}
 
</source>


===== Python: GRASS GIS 7 =====
The grass-session library looks at the <tt>GRASSBIN</tt> environmental variable. If the variable is not set, the library tries to use the current stable release of GRASS GIS (e.g. <tt>grass78</tt> on Linux for the 7.8 release).
For instance, to execute the previous example using a custom installation of 7.9 version, write:


The script initializes the session and lists available raster and vector maps:
<source lang="bash">
# WAY 1
# set variable "on the fly" for python call
GRASSBIN="$HOME/bin/grass79 python test_session.py"


<source lang=python>
# WAY 2
export GRASSBIN="$HOME/bin/grass79"
python3 test_session.py
{'GISDBASE': "'/tmp';", 'LOCATION_NAME': "'mylocation';", 'MAPSET': "'PERMANENT';"}
{'GISDBASE': "'/tmp';", 'LOCATION_NAME': "'mylocation';", 'MAPSET': "'test';"}
</source>
 
See below for a solution with docker.
 
====== Using 'grass-session' with PyGRASS ======
 
If you need to use python libraries that are using ctypes, run it like this for example:
 
<source lang="python">
# file: test_session_ctypes.py
import grass_session
from grass.pygrass.vector import VectorTopo
 
print('DONE!')
</source>
 
The above script will raise an exception because is not possible to dynamically import the linked library in the same process.
 
<source lang="bash">
$ GRASSBIN=/home/pietro/.local/bin/grass78 python test.py
GRASSBIN: /home/pietro/.local/bin/grass78
GISBASE: /home/pietro/.local/grass-7.8.dev
Traceback (most recent call last):
  File "test.py", line 3, in <module>
    from grass.pygrass.vector import VectorTopo
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/pygrass/vector/__init__.py", line 5, in <module>
    import grass.lib.gis as libgis
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/gis.py", line 23, in <module>
    _libs["grass_gis.7.8.dev"] = load_library("grass_gis.7.8.dev")
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/ctypes_loader.py", line 62, in load_library
    return self.load(path)
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/ctypes_loader.py", line 78, in load
    raise ImportError(e)
ImportError: libgrass_datetime.7.8.dev.so: cannot open shared object file: No such file or directory
</source>
 
But you can set the <tt>LD_LIBRARY_PATH</tt> variable before launching the program. For instance from the command line you can define:
 
<source lang="bash">
$ LD_LIBRARY_PATH=/home/pietro/.local/grass-7.8.dev/lib \
  GRASSBIN=/home/pietro/.local/bin/grass78 \
  python test_session_ctypes.py
GRASSBIN: /home/pietro/.local/bin/grass78
GISBASE: /home/pietro/.local/grass-7.8.dev
DONE!
</source>
 
 
The use of the <tt>with-statement</tt> close automatically the session.
If you have to manage more complex workflow you can manually define the opening and closing actions.
For example:
 
<source lang="bash">
import os
 
# import grass_session
from grass_session import Session
 
# import grass python libraries
from grass.pygrass.modules.shortcuts import general as g
 
 
# set some common environmental variables, like:
os.environ.update(dict(GRASS_COMPRESS_NULLS='1',
                      GRASS_COMPRESSOR='ZSTD'))
 
# create a PERMANENT mapset
# create a Session instance
PERMANENT = Session()
PERMANENT.open(gisdb='/tmp', location='mytest',
              create_opts='EPSG:4326')
 
 
# execute some command inside PERMANENT
g.mapsets(flags="l")
g.list(type="raster", flags="m")
 
# exit from PERMANENT
PERMANENT.close()
 
# create a new mapset in the same location
user = Session()
user.open(gisdb='/tmp', location='mytest', mapset='user',
              create_opts='')
 
# execute some command inside user
g.mapsets(flags="l")
g.list(type="raster", flags="m")
 
# exit from user
user.close()
</source>
 
===== Hint: find the path to the GRASS GIS package start script =====
 
Hint: in order to find the '''path to the GRASS GIS package''', launch it with <tt> --config path</tt>:
 
<source lang="bash">
# Linux
grass78 --config path
/usr/bin/grass-7.8.0
 
# Windows
C:\>grass78.bat --config path
C:\OSGeo4W\apps\grass\grass-7.8
</source>
 
===== Python: GRASS GIS 8 with existing location =====
 
See the example in the [https://grass.osgeo.org/grass-stable/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:
 
<source lang="python">
#!/usr/bin/env python
 
import os
import subprocess
import sys
 
# define GRASS data settings (adapt to your needs)
grassdata = "/home/mneteler/grassdata/"
location = "nc_spm_08_grass7"
mapset = "user1"
 
# Python path: we ask GRASS GIS where its Python packages are
sys.path.append(
    subprocess.check_output(["grass", "--config", "python_path"], text=True).strip()
)
 
# Import GRASS Python bindings
import grass.script as gs
import grass.script.setup as gsetup
 
# Start GRASS Session
session = gsetup.init(grassdata, location, mapset)
</source>
 
At this point we are in a running GRASS GIS session, let's verify.
 
<source lang="python">
# show current GRASS GIS settings
print(gs.read_command("g.gisenv"))
</source>
 
Now we may also import further functionality (e.g. [https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html?highlight=vectortopo VectorTopo of pygrass]):
 
<source lang="python">
from grass.pygrass.vector import VectorTopo
</source>
 
and can for example retrieve the topology of a vector map (using the [https://grass.osgeo.org/download/data/#NorthCarolinaDataset North Carolina dataset]):
 
<source lang="python">
test_vect = VectorTopo("zipcodes_wake")
test_vect.open(mode="r")
test_vect.num_primitive_of("point")
test_vect.num_primitive_of("line")
test_vect.num_primitive_of("centroid")
test_vect.num_primitive_of("boundary")
test_vect.close()
</source>
 
This should report:
 
<source lang="python">
>>> test_vect.num_primitive_of('point')
0
>>> test_vect.num_primitive_of('line')
0
>>> test_vect.num_primitive_of('centroid')
48
>>> test_vect.num_primitive_of('boundary')
158
</source>
 
===== Python: GRASS GIS 7 with existing location =====
 
See the example in the [https://grass.osgeo.org/grass78/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:
 
'''''NOTE: see GRASS GIS 8 example above which is much easier!'''''
 
Note: For Python3 support you need to use at least GRASS GIS 7.8. Details are found at https://trac.osgeo.org/grass/wiki/Python3Support
 
<source lang="python">
#!/usr/bin/env python
#!/usr/bin/env python


Line 36: Line 296:
import subprocess
import subprocess


# some predefined variables, name of the GRASS launch script + location/mapset
# path to the GRASS GIS launch script
#grass7bin = 'C:\Program Files (x86)\GRASS GIS 7.0.svn\grass70svn.bat'
# MS Windows
grass7bin = 'grass71'
grass7bin_win = r'C:\OSGeo4W\bin\grass78dev.bat'
location = "nc_spm_08_grass7"
# uncomment when using standalone WinGRASS installer
# grass7bin_win = r'C:\Program Files (x86)\GRASS GIS 7.8.0\grass78.bat'
# Linux
grass7bin_lin = 'grass78'
# Mac OS X
# this is TODO
grass7bin_mac = '/Applications/GRASS/GRASS-7.8.app/'
 
# DATA
# define GRASS DATABASE
# add your path to grassdata (GRASS GIS database) directory
gisdb = os.path.join(os.path.expanduser("~"), "grassdata")
# the following path is the default path on MS Windows
# gisdb = os.path.join(os.path.expanduser("~"), "Documents/grassdata")
 
# specify (existing) location and mapset
location = "nc_spm_08"
mapset  = "user1"
mapset  = "user1"


########### SOFTWARE
########### SOFTWARE
if sys.platform.startswith('linux'):
    # we assume that the GRASS GIS start script is available and in the PATH
    # query GRASS 7 itself for its GISBASE
    grass7bin = grass7bin_lin
elif sys.platform.startswith('win'):
    grass7bin = grass7bin_win
else:
    raise OSError('Platform not configured.')
# query GRASS 7 itself for its GISBASE
# query GRASS 7 itself for its GISBASE
# we assume that GRASS GIS' start script is available and in the PATH
startcmd = [grass7bin, '--config', 'path']
startcmd = grass7bin + ' --config path'
 
p = subprocess.Popen(startcmd, shell=True,  
p = subprocess.Popen(startcmd, shell=False,
                     stdout=subprocess.PIPE, stderr=subprocess.PIPE)
                     stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
out, err = p.communicate()
Line 52: Line 338:
     print >>sys.stderr, "ERROR: Cannot find GRASS GIS 7 start script (%s)" % startcmd
     print >>sys.stderr, "ERROR: Cannot find GRASS GIS 7 start script (%s)" % startcmd
     sys.exit(-1)
     sys.exit(-1)
gisbase = out.strip('\n')
gisbase = out.strip('\n\r')


# Set GISBASE environment variable
# Set GISBASE environment variable
os.environ['GISBASE'] = gisbase
os.environ['GISBASE'] = gisbase
# the following not needed with trunk
os.environ['PATH'] += os.pathsep + os.path.join(gisbase, 'extrabin')
# add path to GRASS addons
home = os.path.expanduser("~")
os.environ['PATH'] += os.pathsep + os.path.join(home, '.grass7', 'addons', 'scripts')
# define GRASS-Python environment
# define GRASS-Python environment
gpydir = os.path.join(gisbase, "etc", "python")
gpydir = os.path.join(gisbase, "etc", "python")
Line 61: Line 353:


########### DATA
########### DATA
# define GRASS DATABASE
gisdb = os.path.join(os.path.expanduser("~"), "grassdata")
# Set GISDBASE environment variable
# Set GISDBASE environment variable
os.environ['GISDBASE'] = gisdb
os.environ['GISDBASE'] = gisdb
 
# import GRASS Python bindings (see also pygrass)
# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script as gscript
import grass.script.setup as gsetup
import grass.script.setup as gsetup
 
###########
###########
# launch session
# launch session
Line 81: Line 371:
for rast in gscript.list_strings(type = 'rast'):
for rast in gscript.list_strings(type = 'rast'):
     print rast
     print rast
 
gscript.message('Available vector maps:')
gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
for vect in gscript.list_strings(type = 'vect'):
     print vect
     print vect
sys.exit(0)
</source>
</source>


===== Python: GRASS GIS 6 =====
===== Python: GRASS GIS 7 without existing location using metadata only =====


The script initializes the session and lists available raster maps:
The script initializes the GRASS GIS session, creates a temporary GRASS location and lists available raster and vector maps:


<source lang=python>
<source lang=python>
#!/usr/bin/env python
# Python script to generate a new GRASS GIS 7 location simply from metadata
# Markus Neteler, 2014, 2020
# ?? LINUX USAGE: First set LIBRARY SEARCH PATH
#export LD_LIBRARY_PATH=$(grass78 --config path)/lib
#python start_grass7_create_new_location_ADVANCED.py
# some predefined variables
# Windows
grass7path = r'C:\OSGeo4W\apps\grass\grass-7.8.dev'
grass7bin_win = r'C:\OSGeo4W\bin\grass78dev.bat'
# Linux
grass7bin_lin = 'grass78'
# MacOSX
grass7bin_mac = '/Applications/GRASS/GRASS-7.8.app/'
#myepsg = '4326' # latlong
myepsg = '3044' # ETRS-TM32, http://spatialreference.org/ref/epsg/3044/
#myfile = '/home/neteler/markus_repo/books/kluwerbook/data3rd/lidar/lidar_raleigh_nc_spm.shp'
myfile = '/data/maps/world_natural_earth_250m/europe_north_east.tif'
#myfile = r'C:\Dati\Padergnone\square_p95.tif'
###########
import os
import os
import sys
import sys
import subprocess
import shutil
import binascii
import tempfile
########### SOFTWARE
if sys.platform.startswith('linux'):
    # we assume that the GRASS GIS start script is available and in the PATH
    # query GRASS 7 itself for its GISBASE
    grass7bin = grass7bin_lin
elif sys.platform.startswith('win'):
    grass7bin = grass7bin_win
else:
    OSError('Platform not configured.')
startcmd = grass7bin + ' --config path'
p = subprocess.Popen(startcmd, shell=True,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
if p.returncode != 0:
print >>sys.stderr, 'ERROR: %s' % err
print >>sys.stderr, "ERROR: Cannot find GRASS GIS 7 start script (%s)" % startcmd
sys.exit(-1)
if sys.platform.startswith('linux'):
gisbase = out.strip('\n')
elif sys.platform.startswith('win'):
    if out.find("OSGEO4W home is") != -1:
gisbase = out.strip().split('\n')[1]
    else:
gisbase = out.strip('\n')
    os.environ['GRASS_SH'] = os.path.join(gisbase, 'msys', 'bin', 'sh.exe')
# Set GISBASE environment variable
os.environ['GISBASE'] = gisbase
# define GRASS-Python environment
gpydir = os.path.join(gisbase, "etc", "python")
sys.path.append(gpydir)
########
# define GRASS DATABASE
if sys.platform.startswith('win'):
    gisdb = os.path.join(os.getenv('APPDATA', 'grassdata'))
else:
    gisdb = os.path.join(os.getenv('HOME', 'grassdata'))
# override for now with TEMP dir
gisdb = os.path.join(tempfile.gettempdir(), 'grassdata')
try:
    os.stat(gisdb)
except:
    os.mkdir(gisdb)
# location/mapset: use random names for batch jobs
string_length = 16
location = binascii.hexlify(os.urandom(string_length))
mapset  = 'PERMANENT'
location_path = os.path.join(gisdb, location)
# Create new location (we assume that grass7bin is in the PATH)
#  from EPSG code:
startcmd = grass7bin + ' -c epsg:' + myepsg + ' -e ' + location_path
#  from SHAPE or GeoTIFF file
#startcmd = grass7bin + ' -c ' + myfile + ' -e ' + location_path


gisbase = os.environ['GISBASE'] = "/usr/local/src/grass_trunk/dist.x86_64-unknown-linux-gnu"
print startcmd
p = subprocess.Popen(startcmd, shell=True,
                    stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
if p.returncode != 0:
    print >>sys.stderr, 'ERROR: %s' % err
    print >>sys.stderr, 'ERROR: Cannot generate location (%s)' % startcmd
    sys.exit(-1)
else:
    print 'Created location %s' % location_path


gisdbase = os.path.join(os.environ['HOME'], "grassdata")
# Now the location with PERMANENT mapset exists.
location = "nc_spm_08"
 
mapset  = "user1"
########
# Now we can use PyGRASS or GRASS Scripting library etc. after
# having started the session with gsetup.init() etc
 
# Set GISDBASE environment variable
os.environ['GISDBASE'] = gisdb
 
# Linux: Set path to GRASS libs (TODO: NEEDED?)
path = os.getenv('LD_LIBRARY_PATH')
dir  = os.path.join(gisbase, 'lib')
if path:
    path = dir + os.pathsep + path
else:
    path = dir
os.environ['LD_LIBRARY_PATH'] = path
 
# language
os.environ['LANG'] = 'en_US'
os.environ['LOCALE'] = 'C'
 
# Windows: NEEDED?
#path = os.getenv('PYTHONPATH')
#dirr = os.path.join(gisbase, 'etc', 'python')
#if path:
#    path = dirr + os.pathsep + path
#else:
#    path = dirr
#os.environ['PYTHONPATH'] = path
 
#print os.environ


sys.path.append(os.path.join(os.environ['GISBASE'], "etc", "python"))
## Import GRASS Python bindings
import grass.script as grass
import grass.script as grass
import grass.script.setup as gsetup
import grass.script.setup as gsetup


gsetup.init(gisbase,
###########
            gisdbase, location, mapset)
# Launch session and do something
gsetup.init(gisbase, gisdb, location, mapset)


# say hello
grass.message('--- GRASS GIS 7: Current GRASS GIS 7 environment:')
print grass.gisenv()
print grass.gisenv()


grass.message('Raster maps:')
# do something in GRASS now...
for rast in grass.list_strings(type = 'rast'):
 
    print rast
grass.message('--- GRASS GIS 7: Checking projection info:')
in_proj = grass.read_command('g.proj', flags = 'jf')
 
# selective proj parameter printing
kv = grass.parse_key_val(in_proj)
print kv
print kv['+proj']
 
# print full proj parameter printing
in_proj = in_proj.strip()
grass.message("--- Found projection parameters: '%s'" % in_proj)
 
# show current region:
grass.message('--- GRASS GIS 7: Checking computational region info:')
in_region = grass.region()
grass.message("--- Computational region: '%s'" % in_region)
 
# do something else: r.mapcalc, v.rectify, ...
 
# Finally remove the temporary batch location from disk
print 'Removing location %s' % location_path
shutil.rmtree(location_path)
 
sys.exit(0)
</source>
</source>


==== Bash examples (GNU/Linux) ====
==== Bash examples (GNU/Linux) ====


Below an example of a '''~/.bash_profile''' script to set the required settings in order to access GRASS commands outside of a GRASS-session. Specifically it is for GRASS 7 (commented parts for GRASS 6.4.2):
'''''Note: see [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]] for a really easy approach.'''''
 
Below an example of a '''~/.bash_profile''' script to set the required settings in order to access GRASS commands outside of a GRASS GIS session


<source lang=bash>
<source lang=bash>
# example for GRASS 7
export GISBASE=/usr/local/grass-7.8.dev
export GISBASE=/usr/local/grass-7.0.svn
export GRASS_VERSION="7.8.dev"
# example for GRASS 6.4.2
### export GISBASE=/usr/local/grass-6.4.2svn
 
# GRASS 7
export GRASS_VERSION="7.0.svn"
# GRASS 6.4.2
### export GRASS_VERSION="6.4.2svn"


#generate GISRCRC
#generate GISRCRC
MYGISDBASE=$HOME/grassdata
MYGISDBASE=$HOME/grassdata
MYLOC=nc_spm_08
MYLOC=nc_spm_08_grass7
MYMAPSET=user1
MYMAPSET=user1


Line 157: Line 592:
export GRASS_HTML_BROWSER=firefox
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat
export GRASS_PAGER=cat
export GRASS_WISH=wish
 
       
#For the temporal modules
export TGISDB_DRIVER=sqlite
export TGISDB_DATABASE=$MYGISDBASE/$MYLOC/PERMANENT/tgis/sqlite.db
 
# for fun, we can even set the shell prompt to contain a hint on GRASS GIS env being active
export PS1="[\u@\h \W G-$GRASS_VERSION]$ "
 
# system vars
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export LD_LIBRARY_PATH="$GISBASE/lib"
Line 164: Line 606:
export PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
export PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
export MANPATH=$MANPATH:$GISBASE/man
export MANPATH=$MANPATH:$GISBASE/man
#For the temporal modules
export TGISDB_DRIVER=sqlite
export TGISDB_DATABASE=$MYGISDBASE/$MYLOC/PERMANENT/tgis/sqlite.db


# test a command
# test a command
g.list rast
g.list rast
v.info zipcodes_wake


######### below not needed ########
######### below not needed ########
# GRASS 7
# GRASS 7
tmp=/tmp/grass7-"`whoami`"-$GIS_LOCK
tmp=/tmp/grass7-"`whoami`"-$GIS_LOCK
# GRASS 6.4.2
### tmp=/tmp/grass6-"`whoami`"-$GIS_LOCK


export GISRC="$tmp/rc"
export GISRC="$tmp/rc"
mkdir "$tmp"
mkdir "$tmp"


# GRASS 7
cp $HOME/.grass7/rc "$GISRC"
cp ~/.grass7/rc "$GISRC"
 
# GRASS 6.4.2
### cp ~/.grassrc6 "$GISRC"
######### END below not needed ########
######### END below not needed ########
</source>
</source>
Line 201: Line 636:
=== Important notes ===
=== Important notes ===


Launching a grassXY session could still permit access on GRASS modules of the version that is set with the above script. The reason being is that grassXY scripts (e.g.: grass64, grass65, grass70) prepend the GRASS directories to '''PATH''', '''LD_LIBRARY_PATH''', etc. They won't remove any entries which are already there. A solution to this is to ''switch'' between GRASS versions by using a script like the following:
Launching a grassXY session could still permit access on GRASS modules of the version that is set with the above script. The reason being is that grassXY scripts (e.g.: grass78) prepend the GRASS directories to '''PATH''', '''LD_LIBRARY_PATH''', etc. They won't remove any entries which are already there. A solution to this is to ''switch'' between GRASS versions by using a script like the following:


<source lang="bash">
<source lang="bash">
Line 234: Line 669:


Using normal grass sessions commands are recorded in '''$GISDBASE/$LOCATION_NAME/$MAPSET/.bash_history'''. While working with "pure" bash, shell entries go in '''~/.bash_history'''. Merging existing "grass-bash_history(-ies)" with the bash history log, would probably be not a good idea. Perhaps it is wise(r) to use normal GRASS sessions when working on real projects. Nevertheless, it is upon the users preferences and expertise level to decide what is best.
Using normal grass sessions commands are recorded in '''$GISDBASE/$LOCATION_NAME/$MAPSET/.bash_history'''. While working with "pure" bash, shell entries go in '''~/.bash_history'''. Merging existing "grass-bash_history(-ies)" with the bash history log, would probably be not a good idea. Perhaps it is wise(r) to use normal GRASS sessions when working on real projects. Nevertheless, it is upon the users preferences and expertise level to decide what is best.
=== Hints and troubleshooting ===
Some hints for MS Windows users:
# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
When everything works well, the installer should take care of all of these.
To manage parallel sessions on Linux, use process ID (PID) as lock file number and set the GIS_LOCK variable, for example
  export GIS_LOCK=$$
in Bash.


=== References ===
=== References ===
* Instructions and discussion on ''how to access GRASS mapsets outside of a GRASS session'' in the grass-user mailing list [http://n2.nabble.com/can-I-access-mapset-outside-of-grass-by-using-python-td3405902.html#a3405902].
* Instructions and discussion on [http://n2.nabble.com/can-I-access-mapset-outside-of-grass-by-using-python-td3405902.html#a3405902 how to access GRASS mapsets outside of a GRASS session] in the grass-user mailing list.
* removing duplicate entries in $PATH taken from [http://chunchung.blogspot.com/2007/11/remove-duplicate-paths-from-path-in.html]
* removing duplicate entries in $PATH taken from [http://chunchung.blogspot.com/2007/11/remove-duplicate-paths-from-path-in.html]


Line 248: Line 699:


* You can create a new mapset when starting GRASS with the -c flag. e.g.
* You can create a new mapset when starting GRASS with the -c flag. e.g.
  grass64 -c /path/to/location/new_mapset_name
  grass78 -c /path/to/location/new_mapset_name


=== Minimal locations ===
=== Minimal locations ===

Latest revision as of 07:30, 22 July 2022

GRASS GIS modules and the import of GRASS Python packages works only in a specific environmental settings (GRASS session). This settings is ensured by starting GRASS GIS application which prepares this GRASS session for you. It is possible to set up you system in the way that the GRASS session will be always active (i.e. the GRASS startup script is not running, just the environmental settings are done). People often prefer to set up the GRASS environment in their script or program and this is what this article discuss. However, it must be noted that the the generally preferred (and easy) way is to create scripts and programs as GRASS modules which means that your don't have to bother with setting up the environment since the GRASS module should be always invoked only in GRASS session.

GRASS sessions

It is possible to access GRASS modules without explicitly starting a "GRASS session". GRASS libraries require certain environment variables to be set. In fact a "GRASS session" is just a set of processes (e.g. a shell and/or GUI) which have the necessary environment settings, specifically:

  • GISBASE needs to be set to the top-level directory of the GRASS installation.
  • GISRC needs to contain the absolute path to a file containing settings for GISDBASE, LOCATION_NAME and MAPSET.
  • PATH needs to include $GISBASE/bin and $GISBASE/scripts.

If the GRASS libraries are shared libraries, the loader needs to be able to find them. This normally means that LD_LIBRARY_PATH (Linux, Solaris), DYLD_LIBRARY_PATH (MacOSX) or PATH (Windows) need to contain $GISBASE/lib, although there are other means to the same end (e.g. on Linux, putting $GISBASE/lib (with $GISBASE replaced by its actual value) into /etc/ld.so.conf then running ldconfig).

Some libraries and modules use other variables. More information for most of them is available in the file $GISBASE/docs/html/variables.html. The display libraries used by d.* commands use additional variables, which are documented along with the individual drivers.

Batch jobs

You can run GRASS scripts non-interactively from outside of a GRASS session with the GRASS_BATCH_JOB environment variable. When GRASS is started with this environment variable set it will automatically run the contents of the script given in the variable, then close the GRASS session when complete. In this way full lock-checking, GRASS variables setup, and temporary file cleaning tasks are still performed.

See the Batch jobs section of the GRASS shell-help wiki page for details.

Starting a GRASS session and terminating it automatically

A GRASS session can be started and terminated automatically with the -e flag.

Since GRASS GIS 7.2.x you can execute commands from outside by passing the command to be executed (or a script with a collection of GRASS GIS commands) to the --exec flag:

Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:

grass78 -c elevation.tiff -e /path/to/grassdata/test1/

Linking external raster data to PERMANENT Mapset:

grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=basins.tiff output=basins
grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=elevation.tiff output=elevation

Get statistics for one raster map:

grass78 /path/to/grassdata/test1/PERMANENT/ -e --exec r.univar map=elevation

Start a GRASS session but do not terminate it automatically

Compare the rasters visually:

grass78 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins

Read more in the manual.

Python examples

For details on GRASS GIS Python programming, see also GRASS Python Scripting Library.

Python: GRASS GIS 7 with an external library: grass-session

The "grass-session" Python library is an easy way to control GRASS GIS from "outside"-Python. To install the current version, run:

pip install grass-session
# for the latest development version use:
# pip install git+https://github.com/zarch/grass-session.git

Then write

#!/usr/bin/env python
# filename: test_session.py

from grass_session import Session
from grass.script import core as gcore

# create a new location from EPSG code (can also be a GeoTIFF or SHP or ... file)
with Session(gisdb="/tmp", location="mylocation",
             create_opts="EPSG:4326"):
   # run something in PERMANENT mapset:
   print(gcore.parse_command("g.gisenv", flags="s"))
# expected output:
# {u'GISDBASE': u"'/tmp/';",
#  u'LOCATION_NAME': u"'mylocation';",
#  u'MAPSET': u"'PERMANENT';",}

# create a new mapset in an existing location
with Session(gisdb="/tmp", location="mylocation", mapset="test",
             create_opts=""):
    # do something in the test mapset.
    print(gcore.parse_command("g.gisenv", flags="s"))
# expected output:
# {u'GISDBASE': u"'/tmp/';",
#  u'LOCATION_NAME': u"'mylocation';",
#  u'MAPSET': u"'test';",}

The grass-session library looks at the GRASSBIN environmental variable. If the variable is not set, the library tries to use the current stable release of GRASS GIS (e.g. grass78 on Linux for the 7.8 release). For instance, to execute the previous example using a custom installation of 7.9 version, write:

# WAY 1
# set variable "on the fly" for python call
GRASSBIN="$HOME/bin/grass79 python test_session.py"

# WAY 2
export GRASSBIN="$HOME/bin/grass79"
python3 test_session.py
{'GISDBASE': "'/tmp';", 'LOCATION_NAME': "'mylocation';", 'MAPSET': "'PERMANENT';"}
{'GISDBASE': "'/tmp';", 'LOCATION_NAME': "'mylocation';", 'MAPSET': "'test';"}

See below for a solution with docker.

Using 'grass-session' with PyGRASS

If you need to use python libraries that are using ctypes, run it like this for example:

# file: test_session_ctypes.py
import grass_session
from grass.pygrass.vector import VectorTopo

print('DONE!')

The above script will raise an exception because is not possible to dynamically import the linked library in the same process.

$ GRASSBIN=/home/pietro/.local/bin/grass78 python test.py 
GRASSBIN: /home/pietro/.local/bin/grass78
GISBASE: /home/pietro/.local/grass-7.8.dev
Traceback (most recent call last):
  File "test.py", line 3, in <module>
    from grass.pygrass.vector import VectorTopo
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/pygrass/vector/__init__.py", line 5, in <module>
    import grass.lib.gis as libgis
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/gis.py", line 23, in <module>
    _libs["grass_gis.7.8.dev"] = load_library("grass_gis.7.8.dev")
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/ctypes_loader.py", line 62, in load_library
    return self.load(path)
  File "/home/pietro/.local/grass-7.8.dev/etc/python/grass/lib/ctypes_loader.py", line 78, in load
    raise ImportError(e)
ImportError: libgrass_datetime.7.8.dev.so: cannot open shared object file: No such file or directory

But you can set the LD_LIBRARY_PATH variable before launching the program. For instance from the command line you can define:

$ LD_LIBRARY_PATH=/home/pietro/.local/grass-7.8.dev/lib \
   GRASSBIN=/home/pietro/.local/bin/grass78 \
   python test_session_ctypes.py
GRASSBIN: /home/pietro/.local/bin/grass78
GISBASE: /home/pietro/.local/grass-7.8.dev
DONE!


The use of the with-statement close automatically the session. If you have to manage more complex workflow you can manually define the opening and closing actions. For example:

import os

# import grass_session
from grass_session import Session

# import grass python libraries
from grass.pygrass.modules.shortcuts import general as g


# set some common environmental variables, like:
os.environ.update(dict(GRASS_COMPRESS_NULLS='1',
                       GRASS_COMPRESSOR='ZSTD'))

# create a PERMANENT mapset
# create a Session instance
PERMANENT = Session()
PERMANENT.open(gisdb='/tmp', location='mytest',
               create_opts='EPSG:4326')


# execute some command inside PERMANENT
g.mapsets(flags="l")
g.list(type="raster", flags="m")

# exit from PERMANENT
PERMANENT.close()

# create a new mapset in the same location
user = Session()
user.open(gisdb='/tmp', location='mytest', mapset='user',
               create_opts='')

# execute some command inside user
g.mapsets(flags="l")
g.list(type="raster", flags="m")

# exit from user
user.close()
Hint: find the path to the GRASS GIS package start script

Hint: in order to find the path to the GRASS GIS package, launch it with --config path:

# Linux
grass78 --config path
/usr/bin/grass-7.8.0

# Windows
C:\>grass78.bat --config path
C:\OSGeo4W\apps\grass\grass-7.8
Python: GRASS GIS 8 with existing location

See the example in the documentation or the script which initializes the session and lists available raster and vector maps:

#!/usr/bin/env python

import os
import subprocess
import sys

# define GRASS data settings (adapt to your needs)
grassdata = "/home/mneteler/grassdata/"
location = "nc_spm_08_grass7"
mapset = "user1"

# Python path: we ask GRASS GIS where its Python packages are
sys.path.append(
    subprocess.check_output(["grass", "--config", "python_path"], text=True).strip()
)

# Import GRASS Python bindings
import grass.script as gs
import grass.script.setup as gsetup

# Start GRASS Session
session = gsetup.init(grassdata, location, mapset)

At this point we are in a running GRASS GIS session, let's verify.

# show current GRASS GIS settings
print(gs.read_command("g.gisenv"))

Now we may also import further functionality (e.g. VectorTopo of pygrass):

from grass.pygrass.vector import VectorTopo

and can for example retrieve the topology of a vector map (using the North Carolina dataset):

test_vect = VectorTopo("zipcodes_wake")
test_vect.open(mode="r")
test_vect.num_primitive_of("point")
test_vect.num_primitive_of("line")
test_vect.num_primitive_of("centroid")
test_vect.num_primitive_of("boundary")
test_vect.close()

This should report:

>>> test_vect.num_primitive_of('point')
0
>>> test_vect.num_primitive_of('line')
0
>>> test_vect.num_primitive_of('centroid')
48
>>> test_vect.num_primitive_of('boundary')
158
Python: GRASS GIS 7 with existing location

See the example in the documentation or the script which initializes the session and lists available raster and vector maps:

NOTE: see GRASS GIS 8 example above which is much easier!

Note: For Python3 support you need to use at least GRASS GIS 7.8. Details are found at https://trac.osgeo.org/grass/wiki/Python3Support

#!/usr/bin/env python

import os
import sys
import subprocess

# path to the GRASS GIS launch script
# MS Windows
grass7bin_win = r'C:\OSGeo4W\bin\grass78dev.bat'
# uncomment when using standalone WinGRASS installer
# grass7bin_win = r'C:\Program Files (x86)\GRASS GIS 7.8.0\grass78.bat'
# Linux
grass7bin_lin = 'grass78'
# Mac OS X
# this is TODO
grass7bin_mac = '/Applications/GRASS/GRASS-7.8.app/'

# DATA
# define GRASS DATABASE
# add your path to grassdata (GRASS GIS database) directory
gisdb = os.path.join(os.path.expanduser("~"), "grassdata")
# the following path is the default path on MS Windows
# gisdb = os.path.join(os.path.expanduser("~"), "Documents/grassdata")

# specify (existing) location and mapset
location = "nc_spm_08"
mapset   = "user1"


########### SOFTWARE
if sys.platform.startswith('linux'):
    # we assume that the GRASS GIS start script is available and in the PATH
    # query GRASS 7 itself for its GISBASE
    grass7bin = grass7bin_lin
elif sys.platform.startswith('win'):
    grass7bin = grass7bin_win
else:
    raise OSError('Platform not configured.')

# query GRASS 7 itself for its GISBASE
startcmd = [grass7bin, '--config', 'path']

p = subprocess.Popen(startcmd, shell=False,
                     stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
if p.returncode != 0:
    print >>sys.stderr, "ERROR: Cannot find GRASS GIS 7 start script (%s)" % startcmd
    sys.exit(-1)
gisbase = out.strip('\n\r')

# Set GISBASE environment variable
os.environ['GISBASE'] = gisbase
# the following not needed with trunk
os.environ['PATH'] += os.pathsep + os.path.join(gisbase, 'extrabin')
# add path to GRASS addons
home = os.path.expanduser("~")
os.environ['PATH'] += os.pathsep + os.path.join(home, '.grass7', 'addons', 'scripts')

# define GRASS-Python environment
gpydir = os.path.join(gisbase, "etc", "python")
sys.path.append(gpydir)

########### DATA
# Set GISDBASE environment variable
os.environ['GISDBASE'] = gisdb
 
# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script.setup as gsetup
 
###########
# launch session
gsetup.init(gisbase,
            gisdb, location, mapset)
 
gscript.message('Current GRASS GIS 7 environment:')
print gscript.gisenv()
 
gscript.message('Available raster maps:')
for rast in gscript.list_strings(type = 'rast'):
    print rast
 
gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
    print vect
Python: GRASS GIS 7 without existing location using metadata only

The script initializes the GRASS GIS session, creates a temporary GRASS location and lists available raster and vector maps:

#!/usr/bin/env python

# Python script to generate a new GRASS GIS 7 location simply from metadata
# Markus Neteler, 2014, 2020

# ?? LINUX USAGE: First set LIBRARY SEARCH PATH
#export LD_LIBRARY_PATH=$(grass78 --config path)/lib
#python start_grass7_create_new_location_ADVANCED.py

# some predefined variables

# Windows
grass7path = r'C:\OSGeo4W\apps\grass\grass-7.8.dev'
grass7bin_win = r'C:\OSGeo4W\bin\grass78dev.bat'
# Linux
grass7bin_lin = 'grass78'
# MacOSX
grass7bin_mac = '/Applications/GRASS/GRASS-7.8.app/'
#myepsg = '4326' # latlong
myepsg = '3044' # ETRS-TM32, http://spatialreference.org/ref/epsg/3044/
#myfile = '/home/neteler/markus_repo/books/kluwerbook/data3rd/lidar/lidar_raleigh_nc_spm.shp'
myfile = '/data/maps/world_natural_earth_250m/europe_north_east.tif'
#myfile = r'C:\Dati\Padergnone\square_p95.tif'

###########
import os
import sys
import subprocess
import shutil
import binascii
import tempfile

########### SOFTWARE
if sys.platform.startswith('linux'):
    # we assume that the GRASS GIS start script is available and in the PATH
    # query GRASS 7 itself for its GISBASE
    grass7bin = grass7bin_lin
elif sys.platform.startswith('win'):
    grass7bin = grass7bin_win
else:
    OSError('Platform not configured.')

startcmd = grass7bin + ' --config path'

p = subprocess.Popen(startcmd, shell=True, 
					 stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
if p.returncode != 0:
	print >>sys.stderr, 'ERROR: %s' % err
	print >>sys.stderr, "ERROR: Cannot find GRASS GIS 7 start script (%s)" % startcmd
	sys.exit(-1)
if sys.platform.startswith('linux'):
	gisbase = out.strip('\n')
elif sys.platform.startswith('win'):
    if out.find("OSGEO4W home is") != -1:
		gisbase = out.strip().split('\n')[1]
    else:
		gisbase = out.strip('\n')
    os.environ['GRASS_SH'] = os.path.join(gisbase, 'msys', 'bin', 'sh.exe')

# Set GISBASE environment variable
os.environ['GISBASE'] = gisbase
# define GRASS-Python environment
gpydir = os.path.join(gisbase, "etc", "python")
sys.path.append(gpydir)
########
# define GRASS DATABASE
if sys.platform.startswith('win'):
    gisdb = os.path.join(os.getenv('APPDATA', 'grassdata'))
else:
    gisdb = os.path.join(os.getenv('HOME', 'grassdata'))

# override for now with TEMP dir
gisdb = os.path.join(tempfile.gettempdir(), 'grassdata')
try:
    os.stat(gisdb)
except:
    os.mkdir(gisdb)

# location/mapset: use random names for batch jobs
string_length = 16
location = binascii.hexlify(os.urandom(string_length))
mapset   = 'PERMANENT'
location_path = os.path.join(gisdb, location)

# Create new location (we assume that grass7bin is in the PATH)
#  from EPSG code:
startcmd = grass7bin + ' -c epsg:' + myepsg + ' -e ' + location_path
#  from SHAPE or GeoTIFF file
#startcmd = grass7bin + ' -c ' + myfile + ' -e ' + location_path

print startcmd
p = subprocess.Popen(startcmd, shell=True, 
                     stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
if p.returncode != 0:
    print >>sys.stderr, 'ERROR: %s' % err
    print >>sys.stderr, 'ERROR: Cannot generate location (%s)' % startcmd
    sys.exit(-1)
else:
    print 'Created location %s' % location_path

# Now the location with PERMANENT mapset exists.

########
# Now we can use PyGRASS or GRASS Scripting library etc. after 
# having started the session with gsetup.init() etc

# Set GISDBASE environment variable
os.environ['GISDBASE'] = gisdb

# Linux: Set path to GRASS libs (TODO: NEEDED?)
path = os.getenv('LD_LIBRARY_PATH')
dir  = os.path.join(gisbase, 'lib')
if path:
    path = dir + os.pathsep + path
else:
    path = dir
os.environ['LD_LIBRARY_PATH'] = path

# language
os.environ['LANG'] = 'en_US'
os.environ['LOCALE'] = 'C'

# Windows: NEEDED?
#path = os.getenv('PYTHONPATH')
#dirr = os.path.join(gisbase, 'etc', 'python')
#if path:
#    path = dirr + os.pathsep + path
#else:
#    path = dirr
#os.environ['PYTHONPATH'] = path

#print os.environ

## Import GRASS Python bindings
import grass.script as grass
import grass.script.setup as gsetup

###########
# Launch session and do something
gsetup.init(gisbase, gisdb, location, mapset)

# say hello
grass.message('--- GRASS GIS 7: Current GRASS GIS 7 environment:')
print grass.gisenv()

# do something in GRASS now...

grass.message('--- GRASS GIS 7: Checking projection info:')
in_proj = grass.read_command('g.proj', flags = 'jf')

# selective proj parameter printing
kv = grass.parse_key_val(in_proj)
print kv
print kv['+proj']

# print full proj parameter printing
in_proj = in_proj.strip()
grass.message("--- Found projection parameters: '%s'" % in_proj)

# show current region:
grass.message('--- GRASS GIS 7: Checking computational region info:')
in_region = grass.region()
grass.message("--- Computational region: '%s'" % in_region)

# do something else: r.mapcalc, v.rectify, ...

# Finally remove the temporary batch location from disk
print 'Removing location %s' % location_path
shutil.rmtree(location_path)

sys.exit(0)

Bash examples (GNU/Linux)

Note: see GRASS Batch jobs for a really easy approach.

Below an example of a ~/.bash_profile script to set the required settings in order to access GRASS commands outside of a GRASS GIS session

export GISBASE=/usr/local/grass-7.8.dev
export GRASS_VERSION="7.8.dev"

#generate GISRCRC
MYGISDBASE=$HOME/grassdata
MYLOC=nc_spm_08_grass7
MYMAPSET=user1

# Set the global grassrc file to individual file name
MYGISRC="$HOME/.grassrc.$GRASS_VERSION.$$"

echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
echo "GRASS_GUI: text" >> "$MYGISRC"
 
# path to GRASS settings file
export GISRC=$MYGISRC
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=plain
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat

#For the temporal modules
export TGISDB_DRIVER=sqlite
export TGISDB_DATABASE=$MYGISDBASE/$MYLOC/PERMANENT/tgis/sqlite.db

# for fun, we can even set the shell prompt to contain a hint on GRASS GIS env being active
export PS1="[\u@\h \W G-$GRASS_VERSION]$ "

# system vars
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export GRASS_LD_LIBRARY_PATH="$LD_LIBRARY_PATH"
export PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
export MANPATH=$MANPATH:$GISBASE/man

# test a command
g.list rast
v.info zipcodes_wake

######### below not needed ########
# GRASS 7
tmp=/tmp/grass7-"`whoami`"-$GIS_LOCK

export GISRC="$tmp/rc"
mkdir "$tmp"

cp $HOME/.grass7/rc "$GISRC"

######### END below not needed ########

The above script will allow GRASS commands to be used anywhere. Furthermore, if the ~/.Xsession sources the bash startup scripts, the settings aren't limited to interactive shells, but also work for e.g. M-! in XEmacs). Each interactive shell gets a separate "session" (i.e. a separate $GISRC file), while GUI programs share a common session.

Note, however, that ~/.bash_profile is a personal initialization startup script and, thus, read during the login process. Any modifications to it will be read after (re-)login or explicitly sourcing it.

At the end of the ~/.bash_profile file, the following lines can be added to ensure no duplication of entries in the PATH variable.

 PATH=`awk -F: '{for(i=1;i<=NF;i++){if(!($i in a)){a[$i];printf s$i;s=":"}}}'<<<$PATH`
 PYTHONPATH=`awk -F: '{for(i=1;i<=NF;i++){if(!($i in a)){a[$i];printf s$i;s=":"}}}'<<<$PYTHONPATH`

Important notes

Launching a grassXY session could still permit access on GRASS modules of the version that is set with the above script. The reason being is that grassXY scripts (e.g.: grass78) prepend the GRASS directories to PATH, LD_LIBRARY_PATH, etc. They won't remove any entries which are already there. A solution to this is to switch between GRASS versions by using a script like the following:

        strippath()
        {
            (
            oldpath="$1"
            newpath=
            IFS=:
            for dir in $oldpath ; do
                case "${dir}" in
                *grass*)
                        ;;
                *)
                        newpath="$newpath:$dir"
                        ;;
                esac
            done
            echo "${newpath#:}"
            )
        }
        
        PATH=`strippath $PATH`
        
        export GISBASE=$PWD/dist.i686-pc-linux-gnu
        export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
        export LD_LIBRARY_PATH="$GISBASE/lib"
        export PYTHONPATH="$GISBASE/etc/python"

Note: the above script needs to be "source"d; executing it won't work. It might also require some adjustments (e.g. the GISBASE variable).

Using normal grass sessions commands are recorded in $GISDBASE/$LOCATION_NAME/$MAPSET/.bash_history. While working with "pure" bash, shell entries go in ~/.bash_history. Merging existing "grass-bash_history(-ies)" with the bash history log, would probably be not a good idea. Perhaps it is wise(r) to use normal GRASS sessions when working on real projects. Nevertheless, it is upon the users preferences and expertise level to decide what is best.

Hints and troubleshooting

Some hints for MS Windows users:

  1. The Python interpreter (python.exe) needs to be in the PATH
  2. Python needs to be associated with the .py extension
  3. PATHEXT needs to include .py if you want to be able to omit the extension

When everything works well, the installer should take care of all of these.

To manage parallel sessions on Linux, use process ID (PID) as lock file number and set the GIS_LOCK variable, for example

 export GIS_LOCK=$$

in Bash.

References

GRASS databases

(project file structure)

Minimal mapsets

within a functional LOCATION (see below) the minimal mapset is a subdirectory of the MAPSET's name, containing a WIND file. The WIND file can simply be copied from PERMANENT/DEFAULT_WIND. Optionally you can put a VAR file in there too to define the default database driver to use.

  • You can create a new mapset when starting GRASS with the -c flag. e.g.
grass78 -c /path/to/location/new_mapset_name

Minimal locations

Within the GISDATABASE (which is simply a subdirectory some where), the minimum LOCATION consists of a directory giving the LOCATION its name, which in turn contains a PERMANENT subdirectory for the PERMANENT mapset. The PERMANENT mapset contains a few special files that regular mapsets don't. These are:

PROJ_INFO
contains the location's projection information
PROJ_UNITS
contains the location's map units definition
DEFAULT_WIND
the default region (WINDow file). The format is identical to the WIND files created by g.region
WIND
(optional?)

See also