[GRASS-SVN] r63369 - grass/trunk/lib/python/docs/src
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Dec 4 17:50:24 PST 2014
Author: wenzeslaus
Date: 2014-12-04 17:50:24 -0800 (Thu, 04 Dec 2014)
New Revision: 63369
Added:
grass/trunk/lib/python/docs/src/script_intro.rst
Modified:
grass/trunk/lib/python/docs/src/index.rst
Log:
pythonlib: add basic intro for grass.script (it is more basic tutorial then intro in GRASS sense, can be renamed later), improve list of libraries
* converted from python.html from https://github.com/ncsu-osgeorel/grass-intro-workshop (be23f71d3cfaf3ed)
* converted using pandoc --from=html --to=rst < python.html > script_intro.rst (no sphinx-related improvements done)
Modified: grass/trunk/lib/python/docs/src/index.rst
===================================================================
--- grass/trunk/lib/python/docs/src/index.rst 2014-12-04 21:52:06 UTC (rev 63368)
+++ grass/trunk/lib/python/docs/src/index.rst 2014-12-05 01:50:24 UTC (rev 63369)
@@ -12,24 +12,24 @@
A set of packages is provided to the user in order to provide functionality
at various levels:
-* **script package**: Python interface to launch GRASS GIS modules in scripts
-* **PyGRASS documentation**: PyGRASS is an object-oriented Python Application
+* **script package** provides Python interface to launch GRASS GIS modules in scripts
+* **PyGRASS** is an object-oriented Python Application
Programming Interface (API) for GRASS GIS which uses the GRASS C API as
backend but additionally offers a convenient interface to the GRASS GIS
modules
-* **GRASS GIS Temporal Framework**: implements the temporal GIS functionality
+* **GRASS GIS Temporal Framework** implements the temporal GIS functionality
of GRASS GIS and provides an API to implement spatio-temporal processing modules
-* **exceptions package**: FIXME
-* **imaging package**: library to create animated images and films
-* **Testing GRASS GIS source code and modules**: (gunittest package
-* **pydispatch package**: Multiple-producer-multiple-consumer signal-dispatching
+* **Testing GRASS GIS source code and modules** using gunittest package
+* **exceptions package** contains exceptions used by other packages
+* **imaging package** is a library to create animated images and films
+* **pydispatch package** is a library for signal-dispatching
Contents:
.. toctree::
:maxdepth: 3
- script
+ script_intro
pygrass_index
temporal_framework
exceptions
Added: grass/trunk/lib/python/docs/src/script_intro.rst
===================================================================
--- grass/trunk/lib/python/docs/src/script_intro.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/script_intro.rst 2014-12-05 01:50:24 UTC (rev 63369)
@@ -0,0 +1,138 @@
+GRASS GIS Python scripting with script package
+==============================================
+
+Parts of the API
+----------------
+
+.. toctree::
+ :maxdepth: 2
+
+ script
+
+
+Syntax
+------
+
+First, try a standard command in Command console in Layer Manager::
+
+ r.info map=elevation -g
+
+We are running *r.info* with an option ``map`` set to ``elevation`` Now,
+switch to Python shell and type the same command but in Python syntax::
+
+ grass.read_command('r.info', map='elevation', flags='g')
+
+We used function ``read_command()`` from the ``grass.script`` package
+which is imported under the name ``grass`` in the Python shell in GRASS
+GUI. There are also other functions besides ``read_command()`` most
+notably ``run_command()``, ``write_command()`` and ``parse_command()``.
+The first parameter for functions from this group is the name of the
+GRASS module as string. Other parameters are options of the module.
+Python keyword arguments syntax is used for the options. Flags can be
+passed in a parameter ``flags`` where value of the parameter is a string
+containing all the flags we want to set. The general syntax is the
+following::
+
+ function_name('module.name', option1=value1, option2=..., flags='flagletters')
+
+The function parameters are the same as module options, so you can just
+use standard module manual page to learn about the interface.
+
+Most of the GRASS functionality is available through modules and all of
+them can be called using the functions above. However, in some cases, it
+is more advantageous to use specialized Python functions. This is the
+case for ``mapcalc()`` function (wrapper for *r.mapcalc* module) and
+``list_strings()`` function (wrapper for *g.list* module).
+
+
+Combining multiple modules
+--------------------------
+
+To launch a Python script from GUI, use File -> Launch Python script.
+
+::
+
+ import grass.script as gscript
+
+ def main():
+ input_raster = 'elevation'
+ output_raster = 'high_areas'
+ stats = gscript.parse_command('r.univar', map='elevation', flags='g')
+ raster_mean = float(stats['mean'])
+ raster_stddev = float(stats['stddev'])
+ raster_high = raster_mean + raster_stddev
+ gscript.mapcalc('{r} = {a} > {m}'.format(r=output_raster, a=input_raster,
+ m=raster_high))
+
+ if __name__ == "__main__":
+ main()
+
+
+Processing many maps
+--------------------
+
+::
+
+ import grass.script as gscript
+
+ def main():
+ rasters = ['lsat7_2002_10', 'lsat7_2002_20', 'lsat7_2002_30', 'lsat7_2002_40']
+ max_min = None
+ for raster in rasters:
+ stats = gscript.parse_command('r.univar', map=raster, flags='g')
+ if max_min is None or max_min < stats['min']:
+ max_min = stats['min']
+ print max_min
+
+ if __name__ == "__main__":
+ main()
+
+Providing GRASS module interface to a script
+---------------------------------------------
+
+
+::
+
+ #!/usr/bin/env python
+
+ #%module
+ #% description: Adds the values of two rasters (A + B)
+ #% keywords: raster
+ #% keywords: algebra
+ #% keywords: sum
+ #%end
+ #%option G_OPT_R_INPUT
+ #% key: araster
+ #% description: Name of input raster A in an expression A + B
+ #%end
+ #%option G_OPT_R_INPUT
+ #% key: braster
+ #% description: Name of input raster B in an expression A + B
+ #%end
+ #%option G_OPT_R_OUTPUT
+ #%end
+
+
+ import sys
+
+ import grass.script as gscript
+
+
+ def main():
+ options, flags = gscript.parser()
+ araster = options['araster']
+ braster = options['braster']
+ output = options['output']
+
+ gscript.mapcalc('{r} = {a} + {b}'.format(r=output, a=araster, b=braster))
+
+ return 0
+
+
+ if __name__ == "__main__":
+ sys.exit(main())
+
+Note that the previous code samples were missing some whitespace which
+Python PEP8 style guide requires but this last sample fulfills all the
+requirements. You should always use *pep8* tool to check your syntax and
+style or set your editor to do it for you.
More information about the grass-commit
mailing list