GRASS GIS APIs - Revision history

Neteler: update to GitHub URLs; grass7x -> grass-stable

2020-08-31T19:40:53Z

update to GitHub URLs; grass7x -> grass-stable

⚠️Mlennert: /* Third-Party APIs */

2020-05-20T08:43:34Z

Third-Party APIs

← Older revision		Revision as of 08:43, 20 May 2020
Line 347:		Line 347:
	Other software projects have developed APIs that allow using GRASS GIS in their context. The two most prominent are:		Other software projects have developed APIs that allow using GRASS GIS in their context. The two most prominent are:

	* [~~http~~://~~r-forge~~.r-project.org/~~projects~~/~~spgrass~~/ ~~spgrass~~]: R-package to access GRASS data and modules from inside R-code		* [https://cran.r-project.org/web/packages/rgrass7/index.html rgrass]: R-package to access GRASS data and modules from inside R-code
	* [~~http~~://docs.qgis.org/2.6/en/docs/user_manual/processing/~~3rdParty~~.html QGIS processing toolbox]: QGIS ~~extension~~ that allows accessing commands from other programs, including GRASS GIS.		* [https://docs.qgis.org/3.10/en/docs/user_manual/processing/index.html QGIS processing toolbox]: QGIS toolbox that allows accessing commands from other programs, including GRASS GIS.

	== See also ==		== See also ==

Neteler: updated PyGRASS urls, a wiki template would be better

2017-08-31T19:41:56Z

updated PyGRASS urls, a wiki template would be better

← Older revision		Revision as of 19:41, 31 August 2017
Line 1:		Line 1:
	== Introduction to this document ==		== Introduction to this document ==

	GRASS GIS is in continues development and this development is what keeps GRASS GIS alive and at the forefront of GIS evolution. From users stringing together a series of modules to build a novel processing chain to developers implementing new cutting-edge algorithms in the core of the GRASS GIS C source code there are many different ways to develop with and for GRASS GIS. This document aims at clarifying the role of the different application programming interfaces (APIs) available. For each of the different APIs, it presents typical use cases and introduces the basic logic of the API. For more detailed information, please look at more detailed introduction on [http://grasswiki.osgeo.org/wiki/Development GRASS GIS and Development ] and [http://grasswiki.osgeo.org/wiki/GRASS_and_Python GRASS GIS and Python] as well as the programming manuals for the [http://grass.osgeo.org/programming7/ C] and [http://grass.osgeo.org/~~grass71~~/manuals/libpython/ Python] APIs.		GRASS GIS is in continues development and this development is what keeps GRASS GIS alive and at the forefront of GIS evolution. From users stringing together a series of modules to build a novel processing chain to developers implementing new cutting-edge algorithms in the core of the GRASS GIS C source code there are many different ways to develop with and for GRASS GIS. This document aims at clarifying the role of the different application programming interfaces (APIs) available. For each of the different APIs, it presents typical use cases and introduces the basic logic of the API. For more detailed information, please look at more detailed introduction on [http://grasswiki.osgeo.org/wiki/Development GRASS GIS and Development ] and [http://grasswiki.osgeo.org/wiki/GRASS_and_Python GRASS GIS and Python] as well as the programming manuals for the [http://grass.osgeo.org/programming7/ C] and [http://grass.osgeo.org/grass73/manuals/libpython/ Python] APIs.

	=== The GRASS GIS environment ===		=== The GRASS GIS environment ===
Line 95:		Line 95:
	== The PyGRASS API ==		== The PyGRASS API ==

	The [http://grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_index.html PyGRASS] API provides two layers of access to GRASS:		The [http://grass.osgeo.org/grass73/manuals/libpython/pygrass_index.html PyGRASS] API provides two layers of access to GRASS:

	# An access to GRASS modules in the same line as the Python scripting library		# An access to GRASS modules in the same line as the Python scripting library
Line 102:		Line 102:
	=== Accessing GRASS modules ===		=== Accessing GRASS modules ===

	The first layer, the [http://grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_modules.html interface to GRASS GIS modules] provides a unified, object-oriented access to GRASS GIS modules. Through its design modules can be called quite similarly to how they would be called on the command line:		The first layer, the [http://grass.osgeo.org/grass73/manuals/libpython/pygrass_modules.html interface to GRASS GIS modules] provides a unified, object-oriented access to GRASS GIS modules. Through its design modules can be called quite similarly to how they would be called on the command line:

	<source lang="Python">		<source lang="Python">
Line 169:		Line 169:
	It is the second layer of the PyGRASS library that sets it completely apart from the GRASS GIS Python scripting library. This makes it possible to directly access geometry features and a selection of low-level C-functions and thus to program a complex GRASS GIS application in Python.		It is the second layer of the PyGRASS library that sets it completely apart from the GRASS GIS Python scripting library. This makes it possible to directly access geometry features and a selection of low-level C-functions and thus to program a complex GRASS GIS application in Python.

	In addition to the modules class mentioned above, the library is divided into different packages. The most important are [http://grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_raster.html raster], [http://grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_vector.html vector] and [http://grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_gis.html gis]. The latter offers the possibility to manage the GRASS database (location, mapset, etc) as well as the working region. The two other packages offer functions to handle the respective map types, but also a direct access to the content of such maps.		In addition to the modules class mentioned above, the library is divided into different packages. The most important are [http://grass.osgeo.org/grass73/manuals/libpython/pygrass_raster.html raster], [http://grass.osgeo.org/grass73/manuals/libpython/pygrass_vector.html vector] and [http://grass.osgeo.org/grass73/manuals/libpython/pygrass_gis.html gis]. The latter offers the possibility to manage the GRASS database (location, mapset, etc) as well as the working region. The two other packages offer functions to handle the respective map types, but also a direct access to the content of such maps.

	Here is an example of accessing a vector point map and adding a new point:		Here is an example of accessing a vector point map and adding a new point:
Line 200:		Line 200:
	>>> schools.close()		>>> schools.close()

	The [grass.osgeo.org/~~grass71~~/manuals/libpython/pygrass_raster.html raster package] of the library offers different access types to raster maps: by row, by segment, read-only, read-and-write, as [http://www.numpy.org/ NumPy] array. One can then treat the raster map as any matrix of numbers and write the results of treatments into a new, or the same raster map.		The [grass.osgeo.org/grass73/manuals/libpython/pygrass_raster.html raster package] of the library offers different access types to raster maps: by row, by segment, read-only, read-and-write, as [http://www.numpy.org/ NumPy] array. One can then treat the raster map as any matrix of numbers and write the results of treatments into a new, or the same raster map.

	The PyGRASS library thus offers a more sophisticated access to GRASS GIS data and GRASS GIS functions. It contains the necessary functions to read and write raster and vector data that can then be treated with any Python tools the developer wants. It is conceived in a pythonic logic and thus allows a quite seamless integration of GRASS GIS into Python applications.		The PyGRASS library thus offers a more sophisticated access to GRASS GIS data and GRASS GIS functions. It contains the necessary functions to read and write raster and vector data that can then be treated with any Python tools the developer wants. It is conceived in a pythonic logic and thus allows a quite seamless integration of GRASS GIS into Python applications.

⚠️Mlennert: /* Easy user interace creation */

2015-06-01T08:19:22Z

Easy user interace creation

← Older revision		Revision as of 08:19, 1 June 2015
Line 278:		Line 278:
	The C-API is thus meant for people who are willing to learn C-language programming and to spend some time understanding the functions and data structures of the API. The big advantage of the use of this API is to be able access the data directly and to program fast routines for their processing, allowing the implementation of new algorithms, or avoiding a possible performance penalty that chaining existing modules might entail.		The C-API is thus meant for people who are willing to learn C-language programming and to spend some time understanding the functions and data structures of the API. The big advantage of the use of this API is to be able access the data directly and to program fast routines for their processing, allowing the implementation of new algorithms, or avoiding a possible performance penalty that chaining existing modules might entail.

	== Easy user ~~interace~~ creation ==		== Easy user interface creation ==

	Whatever the API you chose, when writing GRASS GIS scripts it is very easy to create a user interface, including a graphical user interface, to your script in a semi-automatic way. This interface will then handle all the input (choice of maps, values of parameters, names of outputs, etc) expected from the user. To see the details and examples for the use of this function, see the [http://grass.osgeo.org/grass70/manuals/g.parser.html manual page].		Whatever the API you chose, when writing GRASS GIS scripts it is very easy to create a user interface, including a graphical user interface, to your script in a semi-automatic way. This interface will then handle all the input (choice of maps, values of parameters, names of outputs, etc) expected from the user. To see the details and examples for the use of this function, see the [http://grass.osgeo.org/grass70/manuals/g.parser.html manual page].

⚠️Wenzeslaus: syntax highlight for first part of the page

2015-03-04T16:35:39Z

syntax highlight for first part of the page

Show changes

⚠️Mlennert: /* GRASS GIS Modules as "functions" */

2015-02-03T18:03:45Z

GRASS GIS Modules as "functions"

← Older revision		Revision as of 18:03, 3 February 2015
Line 38:		Line 38:
	import subprocess		import subprocess
	subprocess.call(['r.watershed', 'elevation=elevation', 'threshold=10000', 'stream=raster_streams'])		subprocess.call(['r.watershed', 'elevation=elevation', 'threshold=10000', 'stream=raster_streams'])

	* C

	~~void main()~~
	{
	~~system("r.watershed elevation=elevation threshold=10000 stream=raster_streams");~~
	}

	* Perl		* Perl

	~~system~~ "r.watershed elevation=elevation threshold=10000 stream=raster_streams";		@args = ("r.watershed", "elevation=elevation", "threshold=10000", "stream=raster_streams");
			system(@args);

	These system calls are easy to handle when no output is expected from the GRASS module. When output needs to be collected then the programming task already becomes a little harder unless you know what you are doing. Equally, they can be tricky when introducing variable arguments and special characters. It is for this reason that the Python GRASS libraries where developed that are explained in the next section.		These system calls are easy to handle when no output is expected from the GRASS module. When output needs to be collected then the programming task already becomes a little harder unless you know what you are doing. Equally, they can be tricky when introducing variable arguments and special characters. It is for this reason that the Python GRASS libraries where developed that are explained in the next section.

⚠️Mlennert: /* GRASS GIS Modules as "functions" */

2015-02-03T07:51:21Z

GRASS GIS Modules as "functions"

← Older revision		Revision as of 07:51, 3 February 2015
Line 32:		Line 32:
	However, in this form one is limited to just chaining modules without any control flow such as conditional execution of repeated execution of certain parts of the code. It can, thus be interesting to embed the calls to GRASS GIS modules in a program written in a programming language. Many programming language allow system calls which enable the programmer to call the GRASS GIS modules while having at the same time all the functions of the language at hand.		However, in this form one is limited to just chaining modules without any control flow such as conditional execution of repeated execution of certain parts of the code. It can, thus be interesting to embed the calls to GRASS GIS modules in a program written in a programming language. Many programming language allow system calls which enable the programmer to call the GRASS GIS modules while having at the same time all the functions of the language at hand.

	Here are some examples of such system calls (using the second line of the above example) in different programming languages. ['''Warning: In many cases, system calls such as these demand that you really know what you are doing. ~~You~~ are ~~thus~~ encouraged to rather use the existing Python APIs explained below instead of such system calls.''']:		Here are some examples of such system calls (using the second line of the above example) in different programming languages. ['''Warning: In many cases, system calls such as these demand that you really know what you are doing. If you want to program in Python, you are encouraged to rather use the existing Python APIs explained below instead of such system calls.''']:

	* Python		* Python

	import subprocess		import subprocess
	subprocess.~~Popen~~(['r.watershed', 'elevation=elevation', 'threshold=10000', 'stream=raster_streams'])		subprocess.call(['r.watershed', 'elevation=elevation', 'threshold=10000', 'stream=raster_streams'])

	* C		* C
Line 50:		Line 50:
	system "r.watershed elevation=elevation threshold=10000 stream=raster_streams";		system "r.watershed elevation=elevation threshold=10000 stream=raster_streams";

	These system calls are easy to handle when no output is expected from the GRASS module. When output needs to be collected then the programming task already becomes a little harder unless you know what you are doing. It is for this reason that the Python GRASS libraries where developed that are explained in the next section.		These system calls are easy to handle when no output is expected from the GRASS module. When output needs to be collected then the programming task already becomes a little harder unless you know what you are doing. Equally, they can be tricky when introducing variable arguments and special characters. It is for this reason that the Python GRASS libraries where developed that are explained in the next section.

	== The Python scripting library ==		== The Python scripting library ==

⚠️Mlennert: /* GRASS GIS Modules as "functions" */

2015-02-02T13:30:31Z

GRASS GIS Modules as "functions"

← Older revision		Revision as of 13:30, 2 February 2015
Line 37:		Line 37:

	import subprocess		import subprocess
	subprocess.~~call~~('r.watershed elevation=elevation threshold=10000 stream=raster_streams'~~, shell=True~~)		subprocess.Popen(['r.watershed', 'elevation=elevation', 'threshold=10000', 'stream=raster_streams'])

	* C		* C

⚠️Mlennert: added warning about system calls and additional section on 3rd-party APIs

2015-02-02T08:22:31Z

added warning about system calls and additional section on 3rd-party APIs

← Older revision		Revision as of 08:22, 2 February 2015
Line 32:		Line 32:
	However, in this form one is limited to just chaining modules without any control flow such as conditional execution of repeated execution of certain parts of the code. It can, thus be interesting to embed the calls to GRASS GIS modules in a program written in a programming language. Many programming language allow system calls which enable the programmer to call the GRASS GIS modules while having at the same time all the functions of the language at hand.		However, in this form one is limited to just chaining modules without any control flow such as conditional execution of repeated execution of certain parts of the code. It can, thus be interesting to embed the calls to GRASS GIS modules in a program written in a programming language. Many programming language allow system calls which enable the programmer to call the GRASS GIS modules while having at the same time all the functions of the language at hand.

	Here are some examples of such system calls (using the second line of the above example) in different programming languages:		Here are some examples of such system calls (using the second line of the above example) in different programming languages. ['''Warning: In many cases, system calls such as these demand that you really know what you are doing. You are thus encouraged to rather use the existing Python APIs explained below instead of such system calls.''']:

	* Python		* Python
Line 330:		Line 330:

	A final word about coding standards: in order to keep the large code-base of GRASS GIS in a readable and understandable state, the GRASS GIS Development Team has developed over the time a [http://trac.osgeo.org/grass/wiki/Submitting series of coding standards] that any submission of code into the GRASS GIS code base should follow. These coding standards are defined for several different languages, but notably for C and Python code and you are encouraged to read and integrate them into your coding from the start in order to avoid the drag of cleanup later own.		A final word about coding standards: in order to keep the large code-base of GRASS GIS in a readable and understandable state, the GRASS GIS Development Team has developed over the time a [http://trac.osgeo.org/grass/wiki/Submitting series of coding standards] that any submission of code into the GRASS GIS code base should follow. These coding standards are defined for several different languages, but notably for C and Python code and you are encouraged to read and integrate them into your coding from the start in order to avoid the drag of cleanup later own.

			== Third-Party APIs ==

			Other software projects have developed APIs that allow using GRASS GIS in their context. The two most prominent are:

			* [http://r-forge.r-project.org/projects/spgrass/ spgrass]: R-package to access GRASS data and modules from inside R-code
			* [http://docs.qgis.org/2.6/en/docs/user_manual/processing/3rdParty.html QGIS processing toolbox]: QGIS extension that allows accessing commands from other programs, including GRASS GIS.

	== See also ==		== See also ==

Neteler: minor shell fixes for G7; no need to use --o

2015-01-31T18:42:53Z

minor shell fixes for G7; no need to use --o

← Older revision		Revision as of 18:42, 31 January 2015
Line 19:		Line 19:
	Here is a simple example of such an application that extracts estimated stream locations from a digital elevation model, transforms them to vector format and the creates a 500m buffer around them:		Here is a simple example of such an application that extracts estimated stream locations from a digital elevation model, transforms them to vector format and the creates a 500m buffer around them:

	g.region ~~rast~~=elevation		g.region raster=elevation -p
	r.watershed elevation=elevation threshold=10000 stream=raster_streams ~~--o~~		r.watershed elevation=elevation threshold=10000 stream=raster_streams
	r.to.vect intput=raster_streams output=vector_streams type=line ~~--o~~		r.to.vect intput=raster_streams output=vector_streams type=line
	v.buffer input=vector_streams output=stream_buffers distance=500 ~~--o~~		v.buffer input=vector_streams output=stream_buffers distance=500

	Just putting the above lines into one file that the operating system can read at the command line can already be considered "programming an application" and by just changing the name of the raster used as input the same program can be launched on different data. There are many advantages of creating such application instead of clicking through the different commands in a graphical user interface:		Just putting the above lines into one file that the operating system can read at the command line can already be considered "programming an application" and by just changing the name of the raster used as input the same program can be launched on different data. There are many advantages of creating such application instead of clicking through the different commands in a graphical user interface:
Line 63:		Line 63:

	import grass.script as grass		import grass.script as grass
	grass.run_command('g.region', ~~rast~~='elevation')		grass.run_command('g.region', raster='elevation')
	grass.run_command('r.watershed', elevation='elevation', threshold=10000, stream='raster_streams', overwrite=True)		grass.run_command('r.watershed', elevation='elevation', threshold=10000, stream='raster_streams', overwrite=True)
	grass.run_command('r.to.vect', input='raster_streams', output='vector_streams', type='line', overwrite=True		grass.run_command('r.to.vect', input='raster_streams', output='vector_streams', type='line', overwrite=True