GRASS Python Scripting Library: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
 
(51 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{Python}}
{{Python}}
See also [[GRASS and Python]] for more general info.
Python API documentation:


The code in {{src|lib/python/|lib/python}} provides <tt>grass.script</tt> in order to support GRASS scripts written in Python. The {{src|scripts}} directory of GRASS 7 contains a series of examples actually provided to the end users (while the script in GRASS 6 are shell scripts). See also [[Converting Bash scripts to Python]].
* [https://grass.osgeo.org/grass78/manuals/libpython/ Python API for GRASS GIS 7] and [http://grass.osgeo.org/grass78/manuals/libpython/script_intro.html Python Scripting Library]
* (old: [https://grass.osgeo.org/programming6/pythonlib.html for GRASS GIS 6]: core.py, db.py, raster.py, vector.py, setup.py, array.py task.py)


Python Scripting Library code details:
The GRASS Python Scripting Library can be imported by statement
 
<source lang=python>
import grass.script as grass
</source>
 
The other packages such as PyGRASS can be imported in a similar way.
 
The code in {{src|lib/python/|lib/python}} provides <tt>grass.script</tt> and other packages in order to support GRASS scripts written in Python. The {{src|scripts}} directory of GRASS GIS 7 contains a series of examples actually provided to the end users (while the script in GRASS GIS 6 are shell scripts).
 
For more general info, see also [[GRASS and Python]] and see also [[Converting Bash scripts to Python]] if you have some Bash scripts you want to rewrite to Python.
 
 
=== Calling a GRASS module in Python ===
 
Imagine, you wanted to execute this command in Python:
<source lang="bash">
  r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>
 
All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:
 
<source lang="python">
      grass.run_command('r.profile',
              input = input_map,
              output = output_file,
              profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
              profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>
 
i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.
 
'''What is the proper way to include keyword-arguments tuples?'''
 
For example, "g.list -f type=rast,vect" translates into:
<source lang="python">
      import grass.script as grass
      grass.run_command("g.list", flags="f", type="rast,vect")
</source>
or:
<source lang="python">
      import grass.script as grass
      grass.run_command("g.list", flags="f", type=["rast","vect"])
</source>
 
The various *_command() functions accept arbitrary keyword arguments. Any keywords which don't have a specific meaning to either the *_command() function or the Popen constructor are treated as arguments to the GRASS module.
 
'''What is the proper way to use multiple flags?'''
 
How can I call a module with multiple flags set (e.g., -a and -b) in GRASS-Python?
 
  flags = "ab"
 
Example:
<source lang="python">
      import grass.script as grass
      grass.run_command("r.info", flags="eg", map=["elevation"])
</source>
 
 
'''Differences between ''run_command()'' and ''read_command()'':'''


* [http://grass.osgeo.org/programming6/pythonlib.html for GRASS 6]: core.py, db.py, raster.py, vector.py, setup.py, array.py task.py
* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* [http://grass.osgeo.org/programming7/pythonlib.html for GRASS 7]: core.py, db.py, raster.py, vector.py, setup.py, array.py task.py
* {{pyapi|script|script.core|read_command}} executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.


The GRASS Python Scripting Library can be imported by statement
'''How to retrieve error messages from ''read_command()'':'''
 
None of the existing *_command functions redirect stderr. You can do so with e.g.:
 
<source lang="python">
import grass.script as grass


<source lang=python>
def read2_command(*args, **kwargs):
import grass.script as grass
  kwargs['stdout'] = grass.PIPE
  kwargs['stderr'] = grass.PIPE
  ps = grass.start_command(*args, **kwargs)
  return ps.communicate()
</source>
</source>
This behaves like <tt>read_command()</tt> except that it returns a tuple of (stdout, stderr) rather than just stdout.


== Uses for read, feed and pipe, start and exec commands ==
== Uses for read, feed and pipe, start and exec commands ==


All of the <tt>*_command</tt> functions use {{api|namespacepython_1_1script_1_1core.html#aa2444a79bb55892b2b6f6f566baf8d23|make_command()}} to construct a command
All of the <tt>*_command</tt> functions use {{pyapi|script|script.core|make_command}} to construct a command
line for a program which uses the {{cmd|g.parser|desc=GRASS parser}}. Most of them then pass
line for a program which uses the {{cmd|g.parser|desc=GRASS parser}}. Most of them then pass
that command line to <tt>subprocess.Popen()</tt> via {{api|namespacepython_1_1script_1_1core.html#aaf04d4c1f92c1c6d07ea76844e3e3e69|start_command()}}, except
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
for {{api|/namespacepython_1_1script_1_1core.html#a8506efccf72d70147012f9cf74e23fea|exec_command()}} which uses <tt>os.execvpe()</tt>.
for {{pyapi|script|script.core|exec_command}} which uses <tt>os.execvpe()</tt>.


[To be precise, they use <tt>grass.Popen()</tt>, which just calls
[To be precise, they use <tt>grass.Popen()</tt>, which just calls
Line 28: Line 102:
binary executables.]
binary executables.]


{{api|namespacepython_1_1script_1_1core.html#aaf04d4c1f92c1c6d07ea76844e3e3e69|start_command()}} separates the arguments into those which
{{pyapi|script|script.core|start_command}} separates the arguments into those which
<tt>subprocess.Popen()</tt> understands and the rest. The rest are passed to
<tt>subprocess.Popen()</tt> understands and the rest. The rest are passed to
<tt>make_command()</tt> to construct a command line which is passed as the
<tt>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.
"args" parameter to <tt>subprocess.Popen()</tt>.


In other words, {{api|namespacepython_1_1core.html#aee8a8b146a1b33fa4fb2f86ce635962b|start_command()}} is a GRASS-oriented interface to
In other words, {{pyapi|script|script.core|start_command}} is a GRASS-oriented interface to
<tt>subprocess.Popen()</tt>. It should be suitable for any situation where you
<tt>subprocess.Popen()</tt>. It should be suitable for any situation where you
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
Line 41: Line 115:
Most of the others are convenience wrappers around <tt>start_command()</tt>, for common use cases.
Most of the others are convenience wrappers around <tt>start_command()</tt>, for common use cases.


* {{api|namespacepython_1_1script_1_1core.html#a0cbf4805e1691904c8245037ea359c71|run_command()}} calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to <tt>system()</tt>.
* {{pyapi|script|script.core|run_command}} calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to <tt>system()</tt>.


* {{api|namespacepython_1_1script_1_1core.html#a3438e30e604715ad3024cb6ae0a5768a|pipe_command()}} calls <tt>start_command()</tt> with 'stdout=PIPE' and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").
* {{pyapi|script|script.core|pipe_command}} calls <tt>start_command()</tt> with 'stdout=PIPE' and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").


* {{api|namespacepython_1_1script_1_1core.html#a36e3d8eb94d86af2f2fb35f0b455d9de|feed_command()}} calls <tt>start_command()</tt> with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")
* {{pyapi|script|script.core|feed_command}} calls <tt>start_command()</tt> with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")


* {{api|namespacepython_1_1script_1_1core.html#ae0094c84f0e1f244045e029170b22d98|read_command()}} calls <tt>pipe_command()</tt>, reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.
* {{pyapi|script|script.core|read_command}} calls <tt>pipe_command()</tt>, reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.


* {{api|namespacepython_1_1script_1_1core.html#ad4aa4b661c2ff3bef4907bb2bec7716e|write_command()}} calls <tt>feed_command()</tt>, sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".
* {{pyapi|script|script.core|write_command}} calls <tt>feed_command()</tt>, sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".


* {{api|namespacepython_1_1script_1_1core.html#a799f7849212b38f9d8ac094327bb2784|parse_command()}} calls <tt>read_command()</tt> and parses its output as key-value pairs. Useful for obtaining information from {{cmd|g.region}}, {{cmd|g.proj}}, {{cmd|r.info}}, etc.
* {{pyapi|script|script.core|parse_command}} calls <tt>read_command()</tt> and parses its output as key-value pairs. Useful for obtaining information from {{cmd|g.region}}, {{cmd|g.proj}}, {{cmd|r.info}}, etc.


* {{api|namespacepython_1_1script_1_1core.html#a8506efccf72d70147012f9cf74e23fea|exec_command()}} doesn't use <tt>start_command()</tt> but <tt>os.execvpe()</tt>. This causes the specified command to replace the current program (i.e. the Python script), so <tt>exec_command()</tt> never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step. Notes: exec_command() is rarely appropriate. You probably want run_command() instead. On Windows, exec_command() will probably require the ".exe" suffix.
* {{pyapi|script|script.core|exec_command}} doesn't use <tt>start_command()</tt> but <tt>os.execvpe()</tt>. This causes the specified command to replace the current program (i.e. the Python script), so <tt>exec_command()</tt> never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step. Notes: exec_command() is rarely appropriate. You probably want run_command() instead. On Windows, exec_command() will probably require the ".exe" suffix.


If you have any other questions, you might want to look at the code ({{src|lib/python/core.py}}). Most of these functions are only a few lines long.
If you have any other questions, you might want to look at the code ({{src|lib/python/script/core.py}}). Most of these functions are only a few lines long.
 
=== Hints for parse_command() ===
 
To turn this command
        g.rename raster=old_name,new_name
into a g.parse_command() call, you need to consider that it is a function call with three arguments:
# "g.rename"
# raster=old_name
# new_name
 
The second argument is a keyword argument, the first and third are
positional (non-keyword) arguments. Python doesn't allow positional
arguments to follow keyword arguments; positional arguments come
first, keyword arguments last.
 
Given the context, it's safe to assume that you want to pass a pair of
map names as the value to the rast= option. This requires explicit
parentheses so that the comma is treated as forming a tuple rather
than as an argument separator:
 
        g.parse_command("g.rename", raster=(old_name,new_name))
 
The parentheses in a tuple value can only be omitted if it doesn't
result in the comma being ambiguous (as is the case in a function
call).


== Interfacing ==
== Interfacing ==
Line 61: Line 160:
=== Interfacing with NumPy ===
=== Interfacing with NumPy ===


The {{api|pythonlib.html#pythonArray|grass.script.array}} module defines a {{api|classpython_1_1array_1_1array.html|class array}} which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}. Metadata can be read with {{api|namespacepython_1_1raster.html#a69e4a61eb59a31608410b733d174b8a7|raster::raster_info}}():
The {{pyapi|script|script.array|array}} module defines a <code>class array</code> which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] that reads/writes the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}. Metadata can be read with {{pyapi|script|script.raster|raster_info}}:


Example:
Example:
Line 70: Line 169:


def main():
def main():
     map = "elevation.dem"
     map = "elevation"


     # read map
     # read map
     a = garray.array()
     a = garray.array(map)
    a.read(map)


     # get raster map info
     # get raster map info
     print grass.raster_info(map)['datatype']
     print(grass.raster_info(map)['datatype'])
     i = grass.raster_info(map)
     i = grass.raster_info(map)
      
      
     # get computational region info
     # get computational region info
     c = grass.region()
     c = grass.region()
     print "rows: %d" % c['rows']
     print("rows: %d" % c['rows'])
     print "cols: %d" % c['cols']
     print("cols: %d" % c['cols'])


     # new array for result
     # new array for result
Line 98: Line 196:
be much larger, but processing the entire array in one go is likely to
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.
produce in-memory results of a similar size.
'''NULL (no data) management:'''
For integer maps, the NULL value is -2^31 = -2147483648. For floating-point maps, the NULL value is NaN. Note that the null= parameter for read() and write() specifies the value in the numpy array which is mapped to/from null values in the GRASS raster map.
If you're using floating-point numpy arrays, then use (Note: This assumes that atof() and sscanf("%lf") recognise "nan"; this is the case on Linux, but doesn't appear to work on Windows)
null=numpy.nan
For integer arrays, using
null=-2147483648
will ensure that valid values don't collide with NYLLs.
'''MASK support:'''
Reading and writing use r.out.bin and r.in.bin respectively. r.out.bin respects the MASK.


=== Interfacing with NumPy and SciPy  ===
=== Interfacing with NumPy and SciPy  ===
Line 109: Line 222:


def main():
def main():
     map = "elevation.dem"
     map = "elevation"


     x = garray.array()
     x = garray.array(map)
    x.read(map)


     # Descriptive Statistics:
     # Descriptive Statistics:
     print "max, min, mean, var:"
     print("max, min, mean, var:")
     print x.max(), x.min(), x.mean(), x.var()
     print(x.max(), x.min(), x.mean(), x.var())
     print "Skewness test: z-score and 2-sided p-value:"
     print("Skewness test: z-score and 2-sided p-value:")
     print stats.skewtest(stats.skew(x))
     print(stats.skewtest(stats.skew(x)))
</source>
</source>


Line 173: Line 285:
#%Module
#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#% description: Drapes a color raster over a shaded relief map using d.his
#% keyword: display
#% keyword: raster
#%End
#%End
#%option
#%option
Line 214: Line 328:
=== Parsing the options and flags  ===
=== Parsing the options and flags  ===


{{api|namespacepython_1_1core.html#a312bbda14eb375619ceaf9d306287c47|grass.parser()}} is an interface to {{cmd|g.parser}}, and allows to parse the ''options'' and ''flags'' passed to your script on the command line. It is to be called at the top-level:
{{pyapi|script|script.core|parser}} is an interface to {{cmd|g.parser}}, and allows to parse the ''options'' and ''flags'' passed to your script on the command line. It is to be called at the top-level:


<source lang="python">
<source lang="python">
Line 232: Line 346:
</source>
</source>


'''Accessing the --quiet and --verbose flags:'''
See {{pyapi|script|script.core|verbosity}} for the 5 verbosity levels:
<source lang="python">
from grass.script import core as grass
# to hide non-error messages from subprocesses
if grass.verbosity() <= 2:
    outdev = open(os.devnull, 'w')
else:
    outdev = sys.stdout
</source>
=== Parsing tabular text output ===
Examples in Python for configurable separator for parsing their tabular text output:
* {{src|scripts/m.proj/m.proj.py}}
* {{src|scripts/v.report/v.report.py}}
* {{src|scripts/r.out.xyz/r.out.xyz.py}}
* {{src|scripts/r.tileset/r.tileset.py}}


'''Passing several floats to a single option:'''
=== Passing several floats to a single option ===


Example:
Example:
Line 266: Line 402:
For more information on option definitions, see:
For more information on option definitions, see:


http://grass.osgeo.org/programming7/gislib.html#Complete_Structure_Members_Table
https://grass.osgeo.org/programming7/gislib.html#Complete_Structure_Members_Table


=== Example for embedding r.mapcalc (map algebra) ===
=== Example for embedding r.mapcalc (map algebra) ===


{{api|namespacepython_1_1raster.html#a0f8268995af8d19e6b86e1f67295aaaf|grass.mapcalc()}} accepts a template string followed by keyword
{{pyapi|script|script.raster|mapcalc}} accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):
arguments for the substitutions, e.g. (code snippets):


Line 295: Line 431:
                   rast2 = raster2)
                   rast2 = raster2)
</source>
</source>
Performing multiple computations using <tt>grass.script.raster.mapcalc()</tt>:
<source lang="python">
expr = ";".join([
        "$out.r = r#$first * $frac + (1.0 - $frac) * r#$second",
        "$out.g = g#$first * $frac + (1.0 - $frac) * g#$second",
        "$out.b = b#$first * $frac + (1.0 - $frac) * b#$second"])
grass.mapcalc(expr, out=out, first=first, second=second, frac=percent/100.0)
</source>
Hint: multi-line strings can be separated by using a semicolon instead of a newline.
=== Looping over file names stored in an ASCII file ===
When looping over file names stored in an ASCII file and getting the error
  WARNING: Illegal filename <map.f1jan.05216.something
          >. Character <
          > not allowed.
then the line terminators may be the reason.
When you iterate over a file, the strings include the line terminators (e.g. '\n' or '\r\n'). Use e.g.
<source lang="python">
    for line in gl:
        renamed = line.rstrip().replace('.','_')
        ...
</source>
to remove any trailing whitespace (including newlines) from each line.


=== Example for parsing raster category labels ===
=== Example for parsing raster category labels ===
Line 316: Line 482:
'''Q:''' How to obtain the number of cells of a certain category?
'''Q:''' How to obtain the number of cells of a certain category?


'''A:''' It is recommended to use {{api|namespacepython_1_1core.html#a5fb43aaa254a348cffba81d2fead03d1|pipe_command()}} and parse the output, e.g.:
'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:


<source lang="python">
<source lang="python">
Line 326: Line 492:
       p.wait()
       p.wait()
</source>
</source>
=== Example for parsing the region output of a module ===
Some of the GRASS GIS modules are delivering region information (e.g. {{cmd|r.in.xyz}} which scans a LiDAR file for the extent of the point cloud). The retrieved region settings (using '''-g''' flag for script style output) can be parsed in Python:
<source lang="python">
import os
from grass.script import core as gcore
from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.modules.shortcuts import raster as r
# scan a LiDAR xyz point file for its extent
compregion = gcore.parse_command("r.in.xyz", input="tmp.xyz", separator="space", flags="sg", output="bbox",
                                  parse=(gcore.parse_key_val, {'sep': '=', 'vsep': ' '}))
print(compregion)
# set computational region from LiDAR extent
# hint: we turn here the dictionary to a region by unpacking the dictionary:
g.region(res="1", flags="p", **compregion)
</source>
Note the two '''*''' above which unpack the dictionary (see also the related [https://docs.python.org/2/tutorial/controlflow.html#keyword-arguments Python manual] page).


=== Example for getting the region's number of rows and columns ===
=== Example for getting the region's number of rows and columns ===
Line 331: Line 519:
'''Q:''' How to obtain the number of rows and columns of the current region?
'''Q:''' How to obtain the number of rows and columns of the current region?


'''A:''' It is recommended to use the {{api|namespacepython_1_1core.html#afdb0ab1a23d62fd6ef3e56ca63f062a5|grass.region()}} function which will create a dictionary with values for extents and resolution, e.g.:
'''A:''' It is recommended to use the {{pyapi|script|script.core|region}} function which will create a dictionary with values for extents and resolution, e.g.:


<source lang="python">
<source lang="python">
Line 349: Line 537:
#%Module
#%Module
#% description: Print number of rows, cols of current geographic region
#% description: Print number of rows, cols of current geographic region
#% keywords: region
#% keyword: region
#%end
#%end


Line 381: Line 569:
     cols = gregion['cols']
     cols = gregion['cols']
      
      
     # print rows, cols properly formated
     # print rows, cols properly formatted
     print 'rows=%d \ncols=%d' % (rows, cols)
     print 'rows=%d \ncols=%d' % (rows, cols)
    # average resolution (in case of non-square pixels)
    avg_res=(gregion['nsres'] + gregion['ewres']) / 2.0


# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly  
# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly  
Line 392: Line 583:
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://download.osgeo.org/grass/grass6_progman/pythonlib.html#pythonCore
# [3] https://grass.osgeo.org/grass78/manuals/libpython
</source>
</source>


=== Managing mapsets ===
=== Managing mapsets ===


To check if a certain mapset exists in the active location, use {{api|namespacepython_1_1core.html#a4fe7b767e915bc29d14d9408669e0d0a|mapsets}}
To check if a certain mapset exists in the active location, use {{pyapi|script|script.core|mapsets}}


<source lang="python">
<source lang="python">
Line 427: Line 618:


The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than <tt>quiet</tt>, <tt>verbose</tt> or <tt>overwrite</tt>) specify substitutions.
The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than <tt>quiet</tt>, <tt>verbose</tt> or <tt>overwrite</tt>) specify substitutions.
=== r.mapcalc example: defining a moving window ===
Moving window of 4 cell in every 8 direction and do a boolean comparison. Boolean value (e.g. the result of a comparison) is an integer, with 1 for true, 0 for false.
Then do a r.mapcalc calculation with the moving window.
<source lang="python">
      import grass.script as grass
         
      # define a moving window of 4 cell in every 8 direction
      #
      # map[4,4]                                    map[4,0]                                    map[4,-4]
      #     map[3,3]                        map[3,0]                        map[3,-3]
      #       map[2,2]              map[2,0]              map[2,-2]
      #                                  map[1,1]  map[1,0]  map[1,-1]
      # map[0,4]  map[0,3]  map[0,2]  map[0,1]      x      map[0,-1]  map[0,-2]  map[0,-3]  map[0,-4]
      #                                  map[-1,1]  map[-1,0]  map[-1,-1]
      #                      map[-2,2]            map[-2,0]            map[-2,-2]
      #            map[-3,3]                        map[-3,0]                        map[-3,-3]
      # map[-4,4]                                  map[-4,0]                                  map[-4,-4]
     
      # define the offet duplets
     
      offsets = [d
          for j in xrange(1,4+1)
          for i in [j,-j]
          for d in [(i,0),(0,i),(i,i),(i,-i)]]
     
      # >>>offsets
      # [(1, 0), (0, 1), (1, 1), (1, -1), (-1, 0), (0, -1), (-1, -1), (-1, 1), (2, 0), (0, 2), (2, 2), (2, -2), (-2, 0), (0, -2), \
      # (-2, -2), (-2, 2), (3, 0), (0, 3), (3, 3), (3, -3), (-3, 0), (0, -3), (-3, -3), (-3, 3), (4, 0), (0, 4), (4, 4), (4, -4), \
      # (-4, 0), (0, -4), (-4, -4), (-4, 4)]
     
      # define the calculation term
     
      terms = ["(myelevnc[%d,%d] < myelevnc)" % d
                for d in offsets]
     
      # >>>terms
      # ['(myelevnc[1,0] < myelevnc)', '(myelevnc[0,1] < myelevnc)', '(myelevnc[1,1] < myelevnc)', '(myelevnc[1,-1] < myelevnc)', \
      # '(myelevnc[-1,0] < myelevnc)', '(myelevnc[0,-1] < myelevnc)', '(myelevnc[-1,-1] < myelevnc)', '(myelevnc[-1,1] < myelevnc)',\
      # '(myelevnc[2,0] < myelevnc)', '(myelevnc[0,2] < myelevnc)', '(myelevnc[2,2] < myelevnc)', '(myelevnc[2,-2] < myelevnc)', \
      # '(myelevnc[-2,0] < myelevnc)', '(myelevnc[0,-2] < myelevnc)', '(myelevnc[-2,-2] < myelevnc)', '(myelevnc[-2,2] < myelevnc)', \
      # '(myelevnc[3,0] < myelevnc)', '(myelevnc[0,3] < myelevnc)', '(myelevnc[3,3] < myelevnc)', '(myelevnc[3,-3] < myelevnc)', \
      # '(myelevnc[-3,0] < myelevnc)', '(myelevnc[0,-3] < myelevnc)', '(myelevnc[-3,-3] < myelevnc)', '(myelevnc[-3,3] < myelevnc)', \
      # '(myelevnc[4,0] < myelevnc)', '(myelevnc[0,4] < myelevnc)', '(myelevnc[4,4] < myelevnc)', '(myelevnc[4,-4] < myelevnc)', \
      # '(myelevnc[-4,0] < myelevnc)', '(myelevnc[0,-4] < myelevnc)', '(myelevnc[-4,-4] < myelevnc)', '(myelevnc[-4,4] < myelevnc)']
     
      # define the calculation expression
     
      expr = "elevation_percentile4 = (100.0 / 48.0) * (%s)" % " + ".join(terms)
     
      # >>>expr
      #  elevation_percentile4 = (100.0 / 48.0) * ((myelevnc[1,0] < myelevnc) + (myelevnc[0,1] < myelevnc) + (myelevnc[1,1] < myelevnc) + \
      # (myelevnc[1,-1] < myelevnc) + (myelevnc[-1,0] < myelevnc) + (myelevnc[0,-1] < myelevnc) + (myelevnc[-1,-1] < myelevnc) + \
      # (myelevnc[-1,1] < myelevnc) + (myelevnc[2,0] < myelevnc) + (myelevnc[0,2] < myelevnc) + (myelevnc[2,2] < myelevnc) + \
      # (myelevnc[2,-2] < myelevnc) + (myelevnc[-2,0] < myelevnc) + (myelevnc[0,-2] < myelevnc) + (myelevnc[-2,-2] < myelevnc) + \
      # (myelevnc[-2,2] < myelevnc) + (myelevnc[3,0] < myelevnc) + (myelevnc[0,3] < myelevnc) + (myelevnc[3,3] < myelevnc) + \
      # (myelevnc[3,-3] < myelevnc) + (myelevnc[-3,0] < myelevnc) + (myelevnc[0,-3] < myelevnc) + (myelevnc[-3,-3] < myelevnc) + \
      # (myelevnc[-3,3] < myelevnc) + (myelevnc[4,0] < myelevnc) + (myelevnc[0,4] < myelevnc) + (myelevnc[4,4] < myelevnc) + \
      # (myelevnc[4,-4] < myelevnc) + (myelevnc[-4,0] < myelevnc) + (myelevnc[0,-4] < myelevnc) + (myelevnc[-4,-4] < myelevnc)\
      #  + (myelevnc[-4,4] < myelevnc))
     
      # do the r.mapcalc calculation with the moving window
     
      grass.mapcalc( expr )
</source>


=== Using output from GRASS modules in the script ===
=== Using output from GRASS modules in the script ===
Line 432: Line 692:
Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.
Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.


Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use {{api|namespacepython_1_1raster.html#a69e4a61eb59a31608410b733d174b8a7|grass.raster_info()}}, e.g.:
Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use {{pyapi|script|script.raster|raster_info}}, e.g.:


<source lang="python">
<source lang="python">
Line 442: Line 702:
</source>
</source>


=== Calling a GRASS module in Python ===
=== Using output from r.what ===


Imagine, you wanted to execute this command in Python:
''Q: How does one return attribute values from a call to the 'r.what' module running in a python script?''
<source lang="bash">
  r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>
 
All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:


<source lang="python">
A: If you use <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.
      grass.run_command('r.profile',
              input = input_map,
              output = output_file,
              profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
              profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>


i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.
PyGRASS which requires you to add <tt>stdout_=PIPE</tt>, then you can get the output as a string from <tt>module.outputs.stdout</tt>.


'''What is the proper way to include keyword-arguments tuples?'''
Or using directly the C API through python with (North Carolina dataset example):


For example, "g.list -f type=rast,vect" translates into:
<source lang="python">
<source lang="python">
      grass.run_command("g.list",flags="f",type="rast,vect")
from grass.pygrass.vector import VectorTopo
</source>
from grass.pygrass.raster import RasterRow
or:
from grass.pygrass.gis.region import Region
<source lang="python">
 
      grass.run_command("g.list",flags="f",type=["rast","vect"])
with RasterRow('elevation', mode='r') as rast:
    with VectorTopo('hospitals', mode='r') as hospitals:
        region = Region()
        for hosp in hospitals:
            value = rast.get_value(hosp, region)
            if value is not None:
                print(hosp.cat, value)
</source>
</source>


The various *_command() functions accept arbitrary keyword arguments. Any keywords which don't have a specific meaning to either the *_command() function or the Popen constructor are treated as arguments to the GRASS module.
=== Avoiding a syntax error for r.rescale ===


'''Differences between ''run_command()'' and ''read_command()'':'''
''Q: How to avoid a syntax error for r.rescale related to "from=" ?


* {{api|namespacepython_1_1core.html#af6691d41ff96f1e0f8c6c1822c6b808c|run_command()}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
A: "from" is a reserved word, use from_ instead:
* {{api|namespacepython_1_1core.html#ab31171b0b6dd9120414c518d61a8109f|read_command()}} executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.
 
'''How to retrieve error messages from ''read_command()'':'''
 
None of the existing *_command functions redirect stderr. You can do so with e.g.:


<source lang="python">
<source lang="python">
def read2_command(*args, **kwargs):
grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')
  kwargs['stdout'] = grass.PIPE
  kwargs['stderr'] = grass.PIPE
  ps = grass.start_command(*args, **kwargs)
  return ps.communicate()
</source>
</source>
This behaves like <tt>read_command()</tt> except that it returns a tuple of (stdout, stderr) rather than just stdout.


=== Interface to copying maps (g.copy) ===
=== Interface to copying maps (g.copy) ===
Line 508: Line 748:
<source lang="python">
<source lang="python">
       grass.run_command('g.copy', **{datatype: (input, output)})
       grass.run_command('g.copy', **{datatype: (input, output)})
</source>
=== Interface to listing maps (g.list) ===
You may use the functions in [https://grass.osgeo.org/grass-stable/manuals/libpython/script.html?highlight=list_grouped#script.core.list_grouped script.core.list_grouped()]:
<source lang="python">
# list all
list_grouped('raster')['PERMANENT']
[..., 'lakes', ..., 'slope', ...
# list with pattern
list_grouped('vect', pattern='*roads*')['PERMANENT']
['railroads', 'roadsmajor']
</source>
For temporal data, see likewise [https://grass.osgeo.org/grass-stable/manuals/libpython/temporal.html?highlight=list_grouped#temporal.gui_support.tlist_grouped temporal.gui_support.tlist_grouped()]
See also [[Python/pygrass#Sample_PyGRASS_scripts|Sample PyGRASS scripts]] for an alternative solution.
=== i.group with patterns as name for input ===
Imagery groups can be populated like this:
<source lang="python">
from grass.pygrass.gis import Mapset
run_command("i.group", group="mygroup", input=mset.glist("raster", pattern="mypattern_*"))
</source>
</source>


=== Percentage output for progress of computation ===
=== Percentage output for progress of computation ===


A) Within a Python script, the {{api|namespacepython_1_1core.html#a14ce86fd0c5c18da189e6e3d0cc10501|grass.percent()}} module method wraps the <tt>g.message -p</tt> command.
A) Within a Python script, the {{pyapi|script|script.core|percent}} module method wraps the <tt>g.message -p</tt> command.


B) If you call a GRASS command within the Python code, you have to parse the output by setting <tt>GRASS_MESSAGE_FORMAT=gui</tt> in the environment when running the command and read from the command's stderr; e.g.
B) If you call a GRASS command within the Python code, you have to parse the output by setting <tt>GRASS_MESSAGE_FORMAT=gui</tt> in the environment when running the command and read from the command's stderr; e.g.
Line 548: Line 816:
</source>
</source>


Using the Python API, The 'min' and 'max' values in the result of the {{api|namespacepython_1_1raster.html#a69e4a61eb59a31608410b733d174b8a7|raster_info()}} function will be <tt>None</tt>.
Using the Python API, The 'min' and 'max' values in the result of the {{pyapi|script|script.raster|raster_info}} function will be <tt>None</tt>.


=== Counting cells ===
=== Counting cells ===
Line 593: Line 861:
       path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
       path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>
</source>
=== Parse the GRASS GIS version or revision or path to library ===
In order to a avoid hardcoded versions or to scan the SVN revision of the GRASS GIS version used, you can query the {{cmd|helptext|startup script}}:
'''Variant 1 (pure Python solution) - svn_revision:'''
<source lang="python">
import subprocess
cmd = subprocess.Popen('grass78 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.
</source>
'''Variant 2 (GRASS GIS-Python solution) - svn_revision:'''
<source lang="python">
import subprocess
import grass.script as grass
cmd = grass.Popen('grass78 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.
</source>
'''Path to GRASS GIS library (GRASS GIS-Python solution):'''
<source lang="python">
import subprocess
import grass.script as grass
cmd = grass.Popen('grass78 --config path', shell=True, stdout=subprocess.PIPE)
version = cmd.communicate()[0].rstrip()
print(version)
# the result is for example: '/usr/local/grass-7.6.svn'
</source>
=== Creating a new location ===
Use {{pyapi|script|script.core|create_location}} to create a new location.


=== Use Python reserved keyword ===
=== Use Python reserved keyword ===


'''Q:''' ''r.resamp.bspline'' uses 'lambda' as a command line parameter name, but when you try to use it with {{api|namespacepython_1_1core.html#af6691d41ff96f1e0f8c6c1822c6b808c|grass.run_command()}} you get an error as lambda is a python reserved keyword. How to work around that?
'''Q:''' ''r.resamp.bspline'' uses 'lambda' as a command line parameter name, but when you try to use it with {{pyapi|script|script.core|run_command}} or {{pyapi|script|script.core|start_command}} you get an error as lambda is a python reserved keyword. How to work around that?


'''A:''' Prepend an underscore to the name, i.e.:
'''A:''' Append an underscore to the name, i.e.:


<source lang="python">
<source lang="python">
       grass.run_command('r.resamp.bspline', _lambda = ...)
       grass.run_command('r.resamp.bspline', lambda_ = ...)
</source>
</source>
Note that this follows Python [http://legacy.python.org/dev/peps/pep-0008/#descriptive-naming-styles PEP8] style guide. In GRASS GIS version 6, you have to prepend the underscore.


=== Controlling the PNG display driver ===
=== Controlling the PNG display driver ===
Line 634: Line 945:
           for rast in tmp_rast:
           for rast in tmp_rast:
               grass.run_command("g.remove",
               grass.run_command("g.remove",
                                 rast = rast,
                                 flags = 'f',
                                type = 'raster',
                                name = rast,
                                 quiet = True)
                                 quiet = True)


Line 654: Line 967:
There are two possible ways how to define temporary region for raster-based computations within your scripts. First method uses environmental variable WIND_OVERRIDE, the second GRASS_REGION, see {{cmd|variables|desc=GRASS variables}} for more info. The key point is to recover the current region when the script is finished or terminated.
There are two possible ways how to define temporary region for raster-based computations within your scripts. First method uses environmental variable WIND_OVERRIDE, the second GRASS_REGION, see {{cmd|variables|desc=GRASS variables}} for more info. The key point is to recover the current region when the script is finished or terminated.


* ''First method'' (WIND_OVERRIDE) is implemented as {{api|namespacepython_1_1core.html#a80a93a073e9eb56c3b61ba90ccca7c05|grass.use_temp_region()}}
* ''First method'' (WIND_OVERRIDE) is implemented as {{pyapi|script|script.core|use_temp_region}}


<source lang=python>
<source lang=python>
Line 663: Line 976:
grass.use_temp_region()
grass.use_temp_region()


grass.run_command('g.region', region = 'detail')
grass.run_command('g.region', region='detail')
 
grass.mapcalc('map = 1', overwrite=True)


grass.mapcalc('map = 1', overwrite = True)
# after making operations using the temporary region,
# to unset the temporary WIND_OVERRIDE file and remove any
# region named by it, it is possible to use del_temp_region
grass.del_temp_region()
</source>
</source>


* ''Second method'' (GRASS_REGION) doesn't store current region settings to any temporary region, it just defines GRASS_REGION which forces GIS Library to use this settings for raster-based computations instead of the settings stored in WIND file (ie. current region). See {{api|namespacepython_1_1core.html#ac8cd07cf5d70f12b85b1e841a2ac52d2|grass.region_env()}}.
* ''Second method'' (GRASS_REGION) doesn't store current region settings to any temporary region, it just defines GRASS_REGION which forces GIS Library to use this settings for raster-based computations instead of the settings stored in WIND file (ie. current region). See {{pyapi|script|script.core|region_env}}.


<source lang=python>
<source lang=python>
Line 674: Line 992:
import grass.script as grass
import grass.script as grass


# define GRASS_REGION environmental variable
# copy environment and define GRASS_REGION environmental variable
# same as `g.region region=detail`
# same as `g.region region=detail`
os.environ['GRASS_REGION'] = grass.region_env(region = 'detail')
env = os.environ.copy()
env['GRASS_REGION'] = grass.region_env(region='detail')
   
   
grass.mapcalc('map = 1', overwrite = True)
grass.mapcalc('map = 1', overwrite=True, env=env)
</source>


# undefine GRASS_REGION
=== Using predefined constants ===
os.environ.pop('GRASS_REGION')
 
Some constants are wrapped from C to Python through ctypes.
 
Example:
 
<source lang=python>
from grass.lib.gis import GRASS_EPSILON
GRASS_EPSILON
1e-15
</source>
 
=== Getting a list of wrapped C functions and constants ===
 
<source lang=python>
import pprint
import grass.lib.gis as grass_gis
 
# simple list
dir(grass_gis)
 
# pretty printing
pprint.pprint(dir(grass_gis))
</source>
</source>


== Direct Access from wxGUI ==
== Direct Access from wxGUI ==


[[wxGUI]] Layer Manager in GRASS 6.4.3+ comes with "Python shell" which enables users to type and execute python commands directly in wxGUI environment.
[[wxGUI]] Layer Manager in GRASS GIS comes with "Python shell" which enables users to type and execute python commands directly in wxGUI environment.


[[Image:wxgui-pyshell.png|center|400px|Embedded interactive Python Shell in wxGUI Layer Manager]]
[[Image:wxgui-pyshell.png|center|400px|Embedded interactive Python Shell in wxGUI Layer Manager]]
== See also ==
* [[GRASS GIS Jupyter notebooks]]
* [[Working with GRASS without starting it explicitly‎]]
* Many more tutorials under [[:Category:Python]]

Latest revision as of 12:18, 24 October 2024

Python API documentation:

The GRASS Python Scripting Library can be imported by statement

import grass.script as grass

The other packages such as PyGRASS can be imported in a similar way.

The code in lib/python/ provides grass.script and other packages in order to support GRASS scripts written in Python. The scripts directory of GRASS GIS 7 contains a series of examples actually provided to the end users (while the script in GRASS GIS 6 are shell scripts).

For more general info, see also GRASS and Python and see also Converting Bash scripts to Python if you have some Bash scripts you want to rewrite to Python.


Calling a GRASS module in Python

Imagine, you wanted to execute this command in Python:

  r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77

All arguments except the first (which is a flag) are keyword arguments, i.e. arg = val. For the flag, use flags = 'g' (note that "-g" would be the negative of a Python variable named "g"!). So:

       grass.run_command('r.profile',
               input = input_map,
               output = output_file,
               profile = [12244.256,-295112.597,12128.012,-295293.77]

or:

               profile = [(12244.256,-295112.597),(12128.012,-295293.77)]

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function run_command() etc accept lists and tuples.

What is the proper way to include keyword-arguments tuples?

For example, "g.list -f type=rast,vect" translates into:

       import grass.script as grass
       grass.run_command("g.list", flags="f", type="rast,vect")

or:

       import grass.script as grass
       grass.run_command("g.list", flags="f", type=["rast","vect"])

The various *_command() functions accept arbitrary keyword arguments. Any keywords which don't have a specific meaning to either the *_command() function or the Popen constructor are treated as arguments to the GRASS module.

What is the proper way to use multiple flags?

How can I call a module with multiple flags set (e.g., -a and -b) in GRASS-Python?

 flags = "ab"

Example:

       import grass.script as grass
       grass.run_command("r.info", flags="eg", map=["elevation"])


Differences between run_command() and read_command():

  • script.core.run_command() executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
  • script.core.read_command() executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

How to retrieve error messages from read_command():

None of the existing *_command functions redirect stderr. You can do so with e.g.:

import grass.script as grass

def read2_command(*args, **kwargs):
   kwargs['stdout'] = grass.PIPE
   kwargs['stderr'] = grass.PIPE
   ps = grass.start_command(*args, **kwargs)
   return ps.communicate()

This behaves like read_command() except that it returns a tuple of (stdout, stderr) rather than just stdout.

Uses for read, feed and pipe, start and exec commands

All of the *_command functions use script.core.make_command() to construct a command line for a program which uses the GRASS parser. Most of them then pass that command line to subprocess.Popen() via script.core.start_command(), except for script.core.exec_command() which uses os.execvpe().

[To be precise, they use grass.Popen(), which just calls subprocess.Popen() with 'shell=True' on Windows and 'shell=False' otherwise. On Windows, you need to use 'shell=True' to be able to execute scripts (including batch files); 'shell=False' only works with binary executables.]

script.core.start_command() separates the arguments into those which subprocess.Popen() understands and the rest. The rest are passed to make_command() to construct a command line which is passed as the "args" parameter to subprocess.Popen().

In other words, script.core.start_command() is a GRASS-oriented interface to subprocess.Popen(). It should be suitable for any situation where you would use subprocess.Popen() to execute a normal GRASS command (one which uses the GRASS parser, which is almost all of them; the main exception is r.mapcalc in 6.x).

Most of the others are convenience wrappers around start_command(), for common use cases.

  • script.core.run_command() calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to system().
  • script.core.pipe_command() calls start_command() with 'stdout=PIPE' and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").
  • script.core.feed_command() calls start_command() with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")
  • script.core.read_command() calls pipe_command(), reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.
  • script.core.write_command() calls feed_command(), sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".
  • script.core.exec_command() doesn't use start_command() but os.execvpe(). This causes the specified command to replace the current program (i.e. the Python script), so exec_command() never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step. Notes: exec_command() is rarely appropriate. You probably want run_command() instead. On Windows, exec_command() will probably require the ".exe" suffix.

If you have any other questions, you might want to look at the code (lib/python/script/core.py). Most of these functions are only a few lines long.

Hints for parse_command()

To turn this command

       g.rename raster=old_name,new_name

into a g.parse_command() call, you need to consider that it is a function call with three arguments:

  1. "g.rename"
  2. raster=old_name
  3. new_name

The second argument is a keyword argument, the first and third are positional (non-keyword) arguments. Python doesn't allow positional arguments to follow keyword arguments; positional arguments come first, keyword arguments last.

Given the context, it's safe to assume that you want to pass a pair of map names as the value to the rast= option. This requires explicit parentheses so that the comma is treated as forming a tuple rather than as an argument separator:

       g.parse_command("g.rename", raster=(old_name,new_name))

The parentheses in a tuple value can only be omitted if it doesn't result in the comma being ambiguous (as is the case in a function call).

Interfacing

Interfacing with NumPy

The script.array.array() module defines a class array which is a subclass of numpy.memmap that reads/writes the underlying file via r.out.bin/r.in.bin. Metadata can be read with script.raster.raster_info():

Example:

import grass.script as grass
import grass.script.array as garray

def main():
    map = "elevation"

    # read map
    a = garray.array(map)

    # get raster map info
    print(grass.raster_info(map)['datatype'])
    i = grass.raster_info(map)
    
    # get computational region info
    c = grass.region()
    print("rows: %d" % c['rows'])
    print("cols: %d" % c['cols'])

    # new array for result
    b = garray.array()
    # calculate new map from input map and store as GRASS raster map
    b[...] = (a / 50).astype(int) * 50
    b.write("elev.50m")

The size of the array is taken from the current region (computational region).

The main drawback of using numpy is that you're limited by available memory. Using a subclass of numpy.memmap lets you use files which may be much larger, but processing the entire array in one go is likely to produce in-memory results of a similar size.

NULL (no data) management:

For integer maps, the NULL value is -2^31 = -2147483648. For floating-point maps, the NULL value is NaN. Note that the null= parameter for read() and write() specifies the value in the numpy array which is mapped to/from null values in the GRASS raster map.

If you're using floating-point numpy arrays, then use (Note: This assumes that atof() and sscanf("%lf") recognise "nan"; this is the case on Linux, but doesn't appear to work on Windows)

null=numpy.nan

For integer arrays, using

null=-2147483648

will ensure that valid values don't collide with NYLLs.

MASK support:

Reading and writing use r.out.bin and r.in.bin respectively. r.out.bin respects the MASK.

Interfacing with NumPy and SciPy

SciPy offers simple access to complex calculations. Example:

from scipy import stats
import grass.script as grass
import grass.script.array as garray

def main():
    map = "elevation"

    x = garray.array(map)

    # Descriptive Statistics:
    print("max, min, mean, var:")
    print(x.max(), x.min(), x.mean(), x.var())
    print("Skewness test: z-score and 2-sided p-value:")
    print(stats.skewtest(stats.skew(x)))

Interfacing with NumPy, SciPy and Matlab

One may also use the SciPy - Matlab interface:

   r.out.mat input=elevation output=elev.mat
    ### PY ###
    import scipy.io as sio
    # load data
    elev = sio.loadmat('elev.mat')
    # retrive the actual array. the data set contains also the spatial reference
    elev.get('map_data')
    data = elev.get('map_data')
    # a first simple plot
    import pylab
    pylab.plot(data)
    pylab.show()
    # the contour plot
    pylab.contour(data)
    # obviously data needs to ne reversed
    import numpy as np
    data_rev = data[::-1]
    pylab.contour(data_rev)
    # => this is a quick plot. basemap mapping may provide a nicer map!
    #######

Usage Examples

Display example

Example of Python script, which is processed by g.parser:

#!/usr/bin/env python
#
############################################################################
#
# MODULE:      d.shadedmap
# AUTHOR(S):   Unknown; updated to GRASS 5.7 by Michael Barton
#              Converted to Python by Glynn Clements
# PURPOSE:     Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT:   (C) 2004,2008,2009 by the GRASS Development Team
#
#              This program is free software under the GNU General Public
#              License (>=v2). Read the file COPYING that comes with GRASS
#              for details.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#% keyword: display
#% keyword: raster
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
    drape_map = options['drapemap']
    relief_map = options['reliefmap']
    brighten = options['brighten']
    ret = grass.run_command("d.his", h_map = drape_map,  i_map = relief_map, brighten = brighten)
    sys.exit(ret)

if __name__ == "__main__":
    options, flags = grass.parser()
    main()

Parsing the options and flags

script.core.parser() is an interface to g.parser, and allows to parse the options and flags passed to your script on the command line. It is to be called at the top-level:

if __name__ == "__main__":
    options, flags = grass.parser()
    main()

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}

Accessing the --quiet and --verbose flags:

See script.core.verbosity() for the 5 verbosity levels:

from grass.script import core as grass

# to hide non-error messages from subprocesses
if grass.verbosity() <= 2:
    outdev = open(os.devnull, 'w')
else:
    outdev = sys.stdout

Parsing tabular text output

Examples in Python for configurable separator for parsing their tabular text output:

Passing several floats to a single option

Example:

python my.module.py input=input output=output myoption=0.1,0.2,0.5

The values in the "options" dictionary returned from the parser() function are always strings. You can parse the string with:

        myoption = map(float, options['myoption'].split(','))

The option definition in the script should have:

        #% type: double
        #% multiple: yes

This allows g.parser to validate the option syntax, so you can rely upon the string being in the correct format. If the values have a fixed range, you can use e.g.:

        #% options: 0.0-1.0

to have the parser check that the values fall within the range.

For more information on option definitions, see:

https://grass.osgeo.org/programming7/gislib.html#Complete_Structure_Members_Table

Example for embedding r.mapcalc (map algebra)

script.raster.mapcalc() accepts a template string followed by keyword arguments for the substitutions, e.g. (code snippets):

grass.mapcalc("${out} = ${rast1} + ${rast2}",
              out = options['output'],
              rast1 = options['raster1'],
              rast2 = options['raster2'])

Best practice: first copy all of the options[] into separate variables at the beginning of main(), i.e.:

def main():
    output = options['output']
    raster1 = options['raster1']
    raster2 = options['raster2']
 
    ...
 
    grass.mapcalc("${out} = ${rast1} + ${rast2}",
                  out = output,
                  rast1 = raster1,
                  rast2 = raster2)

Performing multiple computations using grass.script.raster.mapcalc():

expr = ";".join([
        "$out.r = r#$first * $frac + (1.0 - $frac) * r#$second",
        "$out.g = g#$first * $frac + (1.0 - $frac) * g#$second",
        "$out.b = b#$first * $frac + (1.0 - $frac) * b#$second"])
grass.mapcalc(expr, out=out, first=first, second=second, frac=percent/100.0)

Hint: multi-line strings can be separated by using a semicolon instead of a newline.

Looping over file names stored in an ASCII file

When looping over file names stored in an ASCII file and getting the error

  WARNING: Illegal filename <map.f1jan.05216.something
         >. Character <
         > not allowed.

then the line terminators may be the reason. When you iterate over a file, the strings include the line terminators (e.g. '\n' or '\r\n'). Use e.g.

    for line in gl:
        renamed = line.rstrip().replace('.','_')
        ...

to remove any trailing whitespace (including newlines) from each line.

Example for parsing raster category labels

How to obtain the text labels

    # dump cats to file to avoid "too many argument" problem:
    p = grass.pipe_command('r.category', map = rastertmp, separator = ';', quiet = True)
    cats = []
    for line in p.stdout:
        cats.append(line.rstrip('\r\n').split(';')[0])
    p.wait()

    number = len(cats)
    if number < 1:
        grass.fatal(_("No categories found in raster map"))

Example for parsing category numbers

Q: How to obtain the number of cells of a certain category?

A: It is recommended to use script.core.pipe_command() and parse the output, e.g.:

       p = grass.pipe_command('r.stats',flags='c',input='map')
       result = {}
       for line in p.stdout:
           val,count = line.strip().split()
           result[int(val)] = int(count)
       p.wait()

Example for parsing the region output of a module

Some of the GRASS GIS modules are delivering region information (e.g. r.in.xyz which scans a LiDAR file for the extent of the point cloud). The retrieved region settings (using -g flag for script style output) can be parsed in Python:

import os
from grass.script import core as gcore

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.modules.shortcuts import raster as r

# scan a LiDAR xyz point file for its extent
compregion = gcore.parse_command("r.in.xyz", input="tmp.xyz", separator="space", flags="sg", output="bbox",
                                  parse=(gcore.parse_key_val, {'sep': '=', 'vsep': ' '}))
print(compregion)
# set computational region from LiDAR extent
# hint: we turn here the dictionary to a region by unpacking the dictionary:
g.region(res="1", flags="p", **compregion)

Note the two * above which unpack the dictionary (see also the related Python manual page).

Example for getting the region's number of rows and columns

Q: How to obtain the number of rows and columns of the current region?

A: It is recommended to use the script.core.region() function which will create a dictionary with values for extents and resolution, e.g.:

#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE:       g.region.resolution
# AUTHOR(S):    based on a post at GRASS-USER mailing list [1]               
# PURPOSE:	Parses "g.region -g", prints out number of rows, cols
# COPYLEFT:     ;-)
# COMMENT:      ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keyword: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():
    
    # #######################################################################
    # the following commented code works but is kept only for learning purposes
     
    ## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
    # return_rows_x_cols = grass.read_command('g.region', flags = 'g')
    
    ## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
    # rows_x_cols = grass.parse_key_val(return_rows_x_cols)
    
    ## selectively print rows, cols from the dictionary "rows_x_cols"
    # print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))
    
    # #######################################################################
    
    # faster/ easier way: use of the "grass.region()" function
    gregion = grass.region()
    rows = gregion['rows']
    cols = gregion['cols']
    
    # print rows, cols properly formatted 
    print 'rows=%d \ncols=%d' % (rows, cols)

    # average resolution (in case of non-square pixels)
    avg_res=(gregion['nsres'] + gregion['ewres']) / 2.0

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly 
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
    options, flags = grass.parser() #
    sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] https://grass.osgeo.org/grass78/manuals/libpython

Managing mapsets

To check if a certain mapset exists in the active location, use script.core.mapsets()

       grass.mapsets(False)

... returns a list of mapsets in the current location.

r.mapcalc example

Example of Python script, which is processed by g.parser:

The shell script line:

  r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"

would be written like this:

       import grass.script as grass

       ...

       grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
                     cloudResampName = cloudResampName)

The first argument to the mapcalc function is a template (see the Python library documentation for string.Template). Any keyword arguments (other than quiet, verbose or overwrite) specify substitutions.

r.mapcalc example: defining a moving window

Moving window of 4 cell in every 8 direction and do a boolean comparison. Boolean value (e.g. the result of a comparison) is an integer, with 1 for true, 0 for false. Then do a r.mapcalc calculation with the moving window.

       import grass.script as grass
           
       # define a moving window of 4 cell in every 8 direction
       #
       # map[4,4]                                    map[4,0]                                    map[4,-4]		
       # 	    map[3,3]                         map[3,0]                         map[3,-3]			
       # 		       map[2,2]              map[2,0]              map[2,-2]				
       #                                  map[1,1]   map[1,0]   map[1,-1]	 				
       # map[0,4]   map[0,3]   map[0,2]   map[0,1]       x      map[0,-1]  map[0,-2]  map[0,-3]  map[0,-4]
       #                                  map[-1,1]  map[-1,0]  map[-1,-1]					
       #                       map[-2,2]             map[-2,0]             map[-2,-2]				
       #            map[-3,3]                        map[-3,0]                        map[-3,-3]			
       # map[-4,4]                                   map[-4,0]                                   map[-4,-4]
       
       # define the offet duplets
       
       offsets = [d
           for j in xrange(1,4+1)
           for i in [j,-j]
           for d in [(i,0),(0,i),(i,i),(i,-i)]]
       	
       # >>>offsets
       # [(1, 0), (0, 1), (1, 1), (1, -1), (-1, 0), (0, -1), (-1, -1), (-1, 1), (2, 0), (0, 2), (2, 2), (2, -2), (-2, 0), (0, -2), \
       # (-2, -2), (-2, 2), (3, 0), (0, 3), (3, 3), (3, -3), (-3, 0), (0, -3), (-3, -3), (-3, 3), (4, 0), (0, 4), (4, 4), (4, -4), \
       # (-4, 0), (0, -4), (-4, -4), (-4, 4)]
       
       # define the calculation term
       
       terms = ["(myelevnc[%d,%d] < myelevnc)" % d
                for d in offsets]
       
       # >>>terms
       # ['(myelevnc[1,0] < myelevnc)', '(myelevnc[0,1] < myelevnc)', '(myelevnc[1,1] < myelevnc)', '(myelevnc[1,-1] < myelevnc)', \
       # '(myelevnc[-1,0] < myelevnc)', '(myelevnc[0,-1] < myelevnc)', '(myelevnc[-1,-1] < myelevnc)', '(myelevnc[-1,1] < myelevnc)',\
       # '(myelevnc[2,0] < myelevnc)', '(myelevnc[0,2] < myelevnc)', '(myelevnc[2,2] < myelevnc)', '(myelevnc[2,-2] < myelevnc)', \
       # '(myelevnc[-2,0] < myelevnc)', '(myelevnc[0,-2] < myelevnc)', '(myelevnc[-2,-2] < myelevnc)', '(myelevnc[-2,2] < myelevnc)', \
       # '(myelevnc[3,0] < myelevnc)', '(myelevnc[0,3] < myelevnc)', '(myelevnc[3,3] < myelevnc)', '(myelevnc[3,-3] < myelevnc)', \
       # '(myelevnc[-3,0] < myelevnc)', '(myelevnc[0,-3] < myelevnc)', '(myelevnc[-3,-3] < myelevnc)', '(myelevnc[-3,3] < myelevnc)', \
       # '(myelevnc[4,0] < myelevnc)', '(myelevnc[0,4] < myelevnc)', '(myelevnc[4,4] < myelevnc)', '(myelevnc[4,-4] < myelevnc)', \
       # '(myelevnc[-4,0] < myelevnc)', '(myelevnc[0,-4] < myelevnc)', '(myelevnc[-4,-4] < myelevnc)', '(myelevnc[-4,4] < myelevnc)']
       
       # define the calculation expression
       
       expr = "elevation_percentile4 = (100.0 / 48.0) * (%s)" % " + ".join(terms)
       
       # >>>expr
       #  elevation_percentile4 = (100.0 / 48.0) * ((myelevnc[1,0] < myelevnc) + (myelevnc[0,1] < myelevnc) + (myelevnc[1,1] < myelevnc) + \
       # (myelevnc[1,-1] < myelevnc) + (myelevnc[-1,0] < myelevnc) + (myelevnc[0,-1] < myelevnc) + (myelevnc[-1,-1] < myelevnc) + \
       # (myelevnc[-1,1] < myelevnc) + (myelevnc[2,0] < myelevnc) + (myelevnc[0,2] < myelevnc) + (myelevnc[2,2] < myelevnc) + \
       # (myelevnc[2,-2] < myelevnc) + (myelevnc[-2,0] < myelevnc) + (myelevnc[0,-2] < myelevnc) + (myelevnc[-2,-2] < myelevnc) + \
       # (myelevnc[-2,2] < myelevnc) + (myelevnc[3,0] < myelevnc) + (myelevnc[0,3] < myelevnc) + (myelevnc[3,3] < myelevnc) + \
       # (myelevnc[3,-3] < myelevnc) + (myelevnc[-3,0] < myelevnc) + (myelevnc[0,-3] < myelevnc) + (myelevnc[-3,-3] < myelevnc) + \
       # (myelevnc[-3,3] < myelevnc) + (myelevnc[4,0] < myelevnc) + (myelevnc[0,4] < myelevnc) + (myelevnc[4,4] < myelevnc) + \
       # (myelevnc[4,-4] < myelevnc) + (myelevnc[-4,0] < myelevnc) + (myelevnc[0,-4] < myelevnc) + (myelevnc[-4,-4] < myelevnc)\
       #  + (myelevnc[-4,4] < myelevnc))
       
       # do the r.mapcalc calculation with the moving window
       
       grass.mapcalc( expr )

Using output from GRASS modules in the script

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in r.mapcalc. Here you can use script.raster.raster_info(), e.g.:

       import grass.script as grass

       max = grass.raster_info(inmap)['max']
       grass.mapcalc("$outmap = $inmap / $max",
                     inmap = inmap, outmap = outmap, max = max)

Using output from r.what

Q: How does one return attribute values from a call to the 'r.what' module running in a python script?

A: If you use grass.script.raster_what(), it returns a list of dictionaries.

PyGRASS which requires you to add stdout_=PIPE, then you can get the output as a string from module.outputs.stdout.

Or using directly the C API through python with (North Carolina dataset example):

from grass.pygrass.vector import VectorTopo
from grass.pygrass.raster import RasterRow
from grass.pygrass.gis.region import Region

with RasterRow('elevation', mode='r') as rast:
    with VectorTopo('hospitals', mode='r') as hospitals:
        region = Region()
        for hosp in hospitals:
            value = rast.get_value(hosp, region)
            if value is not None:
                print(hosp.cat, value)

Avoiding a syntax error for r.rescale

Q: How to avoid a syntax error for r.rescale related to "from=" ?

A: "from" is a reserved word, use from_ instead:

grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')

Interface to copying maps (g.copy)

Copy a raster map (for vector, replace "rast" with "vect"):

       grass.run_command('g.copy', rast = (input, output))

To generalize it, "datatype" is the form of grass data to copy (eg, rast, vect, etc)

       grass.run_command('g.copy', **{datatype: (input, output)})

Interface to listing maps (g.list)

You may use the functions in script.core.list_grouped():

# list all
list_grouped('raster')['PERMANENT']
[..., 'lakes', ..., 'slope', ...

# list with pattern
list_grouped('vect', pattern='*roads*')['PERMANENT']
['railroads', 'roadsmajor']

For temporal data, see likewise temporal.gui_support.tlist_grouped()

See also Sample PyGRASS scripts for an alternative solution.

i.group with patterns as name for input

Imagery groups can be populated like this:

from grass.pygrass.gis import Mapset

run_command("i.group", group="mygroup", input=mset.glist("raster", pattern="mypattern_*"))

Percentage output for progress of computation

A) Within a Python script, the script.core.percent() module method wraps the g.message -p command.

B) If you call a GRASS command within the Python code, you have to parse the output by setting GRASS_MESSAGE_FORMAT=gui in the environment when running the command and read from the command's stderr; e.g.

       import grass.script as grass
       env = os.environ.copy()
       env['GRASS_MESSAGE_FORMAT'] = 'gui'
       p = grass.start_command(..., stderr = grass.PIPE, env = env)
       # read from p.stderr
       p.wait()

If you need to capture both stdout and stderr, you need to use threads, select, or non-blocking I/O to consume data from both streams as it is generated in order to avoid deadlock.

ALTERNATIVE:

Redirect both stdout and stderr to the same pipe (and hope that the normal output doesn't include anything which will be mistaken for progress/error/etc messages):

       p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)

NULL data management

How to analyse if there are only NULL cells in a map:

If a map contains only null cells, its minimum and maximum will be "NULL":

       $ r.mapcalc 'foo = null()'
       $ r.info -r foo
       min=NULL
       max=NULL

Using the Python API, The 'min' and 'max' values in the result of the script.raster.raster_info() function will be None.

Counting cells

Counting cells is far more expensive than simply determining whether there are any non-null cells. Counting cells requires reading the entire map, while the r.info approach only needs to read the metadata files.

If you do need to count cells, r.stats is likely to be more efficient than r.univar.

A count loop:

       while grass.raster_info(inmap)['max'] is not None:
           ...

Display: overlayed map display with labels

Example: display a vector map and overlay its labels on top of the map.

If the environment contains the setting GRASS_PNG_READ=TRUE, d.* commands should overlay their output on an existing image (otherwise the first command creates the file map.png but the second command overwrites the file with only the labels). So the following should work:

       grass.run_command('d.vect', map='my_shape')
       env = os.environ.copy()
       env['GRASS_PNG_READ'] = 'TRUE'
       grass.run_command('d.labels', labels='my_shape_labels', env = env)

Path to GISDBASE

In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:

       import grass.script as grass
       import os.path

       env = grass.gisenv()

       gisdbase = env['GISDBASE']
       location = env['LOCATION_NAME']
       mapset = env['MAPSET']

       path = os.path.join(gisdbase, location, mapset, 'sqlite.db')

Parse the GRASS GIS version or revision or path to library

In order to a avoid hardcoded versions or to scan the SVN revision of the GRASS GIS version used, you can query the helptext:

Variant 1 (pure Python solution) - svn_revision:

import subprocess
cmd = subprocess.Popen('grass78 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.

Variant 2 (GRASS GIS-Python solution) - svn_revision:

import subprocess
import grass.script as grass
cmd = grass.Popen('grass78 --config svn_revision', shell=True, stdout=subprocess.PIPE)
revision = cmd.communicate()[0].rstrip()
print(revision)
# the result is for example: '72327'.


Path to GRASS GIS library (GRASS GIS-Python solution):

import subprocess
import grass.script as grass
cmd = grass.Popen('grass78 --config path', shell=True, stdout=subprocess.PIPE)
version = cmd.communicate()[0].rstrip()
print(version)
# the result is for example: '/usr/local/grass-7.6.svn'

Creating a new location

Use script.core.create_location() to create a new location.

Use Python reserved keyword

Q: r.resamp.bspline uses 'lambda' as a command line parameter name, but when you try to use it with script.core.run_command() or script.core.start_command() you get an error as lambda is a python reserved keyword. How to work around that?

A: Append an underscore to the name, i.e.:

       grass.run_command('r.resamp.bspline', lambda_ = ...)

Note that this follows Python PEP8 style guide. In GRASS GIS version 6, you have to prepend the underscore.

Controlling the PNG display driver

Code fragment to control the pngdriver in Python:

import os
import sys
from grass.script import core as grass
def main():
       os.environ['GRASS_PNGFILE'] = filename
       os.environ['GRASS_WIDTH'] = str(width)
       os.environ['GRASS_HEIGHT'] = str(height)
       grass.run_command('d.his', i='elevation_shade', h='elevation')

Sophisticated cleanup procedure

Scripts which create several temporary files need a more sophisticated cleanup procedure which deletes all the tmp maps which have been created. This procedure should also work if the script stops (e.g due to an error).

Solution: Define a list of map names which starts out empty and has names appended to it as the names are generated. Code fragment:

       import atexit, sys
       import grass.script as grass

       tmp_rast = []

       def cleanup():
           for rast in tmp_rast:
               grass.run_command("g.remove",
                                 flags = 'f',
                                 type = 'raster',
                                 name = rast,
                                 quiet = True)

       def main():
           ...
           while ...:
               next_rast = ...
               tmp_rast.append(next_rast)
               ...

       if __name__ == "__main__":
           options, flags = grass.parser()
           atexit.register(cleanup)
           sys.exit(main())

Using temporary region for computations

There are two possible ways how to define temporary region for raster-based computations within your scripts. First method uses environmental variable WIND_OVERRIDE, the second GRASS_REGION, see GRASS variables for more info. The key point is to recover the current region when the script is finished or terminated.

import grass.script as grass

# store the current region settings and installs an atexit
# handler to recover the current region on script termination
grass.use_temp_region()

grass.run_command('g.region', region='detail')

grass.mapcalc('map = 1', overwrite=True)

# after making operations using the temporary region,
# to unset the temporary WIND_OVERRIDE file and remove any 
# region named by it, it is possible to use del_temp_region
grass.del_temp_region()
  • Second method (GRASS_REGION) doesn't store current region settings to any temporary region, it just defines GRASS_REGION which forces GIS Library to use this settings for raster-based computations instead of the settings stored in WIND file (ie. current region). See script.core.region_env().
import os
import grass.script as grass

# copy environment and define GRASS_REGION environmental variable
# same as `g.region region=detail`
env = os.environ.copy()
env['GRASS_REGION'] = grass.region_env(region='detail')
 
grass.mapcalc('map = 1', overwrite=True, env=env)

Using predefined constants

Some constants are wrapped from C to Python through ctypes.

Example:

from grass.lib.gis import GRASS_EPSILON
GRASS_EPSILON
1e-15

Getting a list of wrapped C functions and constants

import pprint
import grass.lib.gis as grass_gis

# simple list
dir(grass_gis)

# pretty printing
pprint.pprint(dir(grass_gis))

Direct Access from wxGUI

wxGUI Layer Manager in GRASS GIS comes with "Python shell" which enables users to type and execute python commands directly in wxGUI environment.

Embedded interactive Python Shell in wxGUI Layer Manager
Embedded interactive Python Shell in wxGUI Layer Manager

See also