GRASS-Wiki - User contributions [en]

Open-Source Ecosystem Working Group

2023-10-13T03:46:53Z

⚠️Baharmon:

Open-source ecosystem working group is established to foster relations with other software communities and collaborate with them on improving the software integrations.

== Scope ==
* foster relation with other software communities such as R and QGIS
* provide guidance to communities how to best integrate GRASS GIS
* identify issues other communities are facing when integrating GRASS GIS
* lower maintenance of GRASS integrations with other software

== Members ==
Let us know who you are and what are your interests and topics you want to discuss and develop as part of this group.

; [https://wiki.osgeo.org/wiki/Anna_Petrasova Anna Petrasova] (working group coordinator)
: Researcher, educator and software developer at North Carolina State University
: Topics of interest include lowering maintenance of R-GRASS and QGIS-GRASS integrations.

; [https://wiki.osgeo.org/wiki/User:Wenzeslaus Vaclav (Vashek) Petras]
: Researcher and software developer at North Carolina State University
: Interested in ...

; Loïc Bartoletti
:
:

; Florian Betz
:
:

; Hernán De Angelis
:
:

; Micha Silver
:
:

; Helmut Kudrnovsky
:
:

; Stefan Blumentrath
:

; Arnd Weber
:

; [https://grasswiki.osgeo.org/wiki/User:Baharmon Brendan Harmon]
: Researcher and educator at Louisiana State University
: Topics of interest include the QGIS-GRASS integration

To be added to this working group, please contact the group coordinator.

== Communication Channels ==
* [https://lists.osgeo.org/mailman/listinfo/grass-user grass-user] and [https://lists.osgeo.org/mailman/listinfo/grass-dev grass-dev] mailing lists
* [https://github.com/OSGeo/grass OSGeo/grass GitHub issues and pull requests]

[[Category:Community]]
[[Category:Working_Groups]]

User:Baharmon

2023-10-13T03:45:50Z

⚠️Baharmon:

=== Brendan Harmon ===

* Position: Assistant Professor
* Institution: Louisiana State University
* Location: Baton Rouge, Louisiana, USA
* Email: baharmon@lsu.edu
* Website: https://baharmon.github.io/
* Github: https://github.com/baharmon
* Orcid: 0000-0002-6218-9318

;Profile last updated: October 2023

User:Baharmon

2023-10-13T03:44:05Z

⚠️Baharmon:

{{OSGeo Member
|Name=Brendan Harmon
|JobTitle=Assistant Professor
|Company=Louisiana State University
|Country=USA
|State=LA
|City=Baton Rouge
|Coordinate=30.411777, -91.180905
|LocalChapter=North America
|Email=baharmon@lsu.edu
|Website=https://baharmon.github.io/
|Languages=English
}}

=== Brendan Harmon ===

* Orcid: 0000-0002-6218-9318
* Github: https://github.com/baharmon
* Web: https://baharmon.github.io/

;Profile last updated: October 2023

User:Baharmon

2023-10-13T03:40:54Z

⚠️Baharmon:

{{OSGeo Member
|Name=Brendan Harmon
|JobTitle=Assistant Professor
|Company=Louisiana State University
|Country=USA
|State=LA
|City=Baton Rouge
|Coordinate=30.411777, -91.180905
|LocalChapter=North America
|Email=baharmon@lsu.edu
|Website=https://baharmon.github.io/
|Languages=English
}}
{{OSGeo Experience
|User=Yes
|Committee=No
|Board=No
|Coder=No
|Translate=No
|PSC=No
|ExBoard=No
|Charter=No
|Chair=No
|SolKatz=No
|Committer=No
}}
=== Brendan Harmon ===

* Orcid: 0000-0002-6218-9318
* Github: https://github.com/baharmon
* Web: https://baharmon.github.io/

;Profile last updated: October 2023

Open-Source Ecosystem Working Group

2023-10-13T03:07:54Z

⚠️Baharmon:

Open-source ecosystem working group is established to foster relations with other software communities and collaborate with them on improving the software integrations.

== Scope ==
* foster relation with other software communities such as R and QGIS
* provide guidance to communities how to best integrate GRASS GIS
* identify issues other communities are facing when integrating GRASS GIS
* lower maintenance of GRASS integrations with other software

== Members ==
Let us know who you are and what are your interests and topics you want to discuss and develop as part of this group.

; [https://wiki.osgeo.org/wiki/Anna_Petrasova Anna Petrasova] (working group coordinator)
: Researcher, educator and software developer at North Carolina State University
: Topics of interest include lowering maintenance of R-GRASS and QGIS-GRASS integrations.

; [https://wiki.osgeo.org/wiki/User:Wenzeslaus Vaclav (Vashek) Petras]
: Researcher and software developer at North Carolina State University
: Interested in ...

; Loïc Bartoletti
:
:

; Florian Betz
:
:

; Hernán De Angelis
:
:

; Micha Silver
:
:

; Helmut Kudrnovsky
:
:

; Stefan Blumentrath
:

; Arnd Weber
:

; Brendan Harmon
: Researcher and educator at Louisiana State University
: Topics of interest include the QGIS-GRASS integration

To be added to this working group, please contact the group coordinator.

== Communication Channels ==
* [https://lists.osgeo.org/mailman/listinfo/grass-user grass-user] and [https://lists.osgeo.org/mailman/listinfo/grass-dev grass-dev] mailing lists
* [https://github.com/OSGeo/grass OSGeo/grass GitHub issues and pull requests]

[[Category:Community]]
[[Category:Working_Groups]]

GRASS Community Meeting Prague 2023

2023-05-29T19:27:04Z

⚠️Baharmon: /* Via chat or hangout */

{{toc|right}}
The GRASS GIS team is organizing the ''GRASS GIS Community Meeting with contributors, power users and developers'' from '''June 2 to June 6, 2023''' to celebrate GRASS GIS '''40th birthday''' (by contributing to GRASS GIS of course).

<gallery mode="slideshow">
Image:grass-sprint-prague.jpg|Prague 2013
Image:Grass_sprint2018_bonn_fotowall.jpg|Bonn 2018
</gallery>

== Purpose ==

GRASS GIS Community Meeting is a great occasion for folks to support the development by actively contributing to the source code, documentation (manuals, wiki, tutorials), translations, website or likewise. The '''community''' meeting is also a get-together where supporters, contributors, power users and developers make decisions and tackle larger problems related to the project, discuss and collaboratively resolve bugs, plan the direction for the project and work on new features. We welcome people committed to improving the GRASS GIS project and the interfaces to QGIS, GDAL, PostGIS, R, OGC Services and desiring to '''celebrate with us the 40th GRASS GIS birthday!!'''

In this meeting, we will work on GRASS GIS and integrations with related OSGeo projects. We will revise connection to QGIS to make it easier to maintain, and we will work on migration of the build to CMake to improve Windows builds including PDAL support. Furthermore, we will start moving documentation to Markdown to make it easier to contribute to and we will add images and examples for tools and workflows which still miss them. Finally, we will automate and document maintenance processes to reduce the burden on maintainers and thus improve the project sustainability.

Note that while we have our general plan, we can't accept any earmarked donations, i.e., we can't make any promises for a specific work to be done. We do require participants to work on GRASS GIS or connections to other projects. However, we leave them the freedom to work on what they think is the best contribution to the project at that time given their skills and time available.

For the detailed agenda and individual's plans, see below.

== Sponsors ==

We welcome '''financial contributions''' to support the meeting and we are looking for sponsors to cover costs such as meals or to help reducing travel and accommodation expenses for GRASS developers who volunteer their time. If you are interested in sponsoring the GRASS Community Meeting, please see our

::: '''[https://opencollective.com/osgeo/projects/grass/contribute/grass-community-meeting-prague-2023-55074 OpenCollective GRASS Community Meeting Prague 2023 Tier]'''

Any surplus at the end of the event will used for future activities of the GRASS GIS project such as the successful [[Student Grants|student mini grant program]].

This GRASS Community Meeting is a great occasion for you to support the development of GRASS. With your contribution you'll enable more developers to meet. Community meetings are important opportunities for developers to discuss, fix bugs, plan the direction for the project and work on new features. Please see below for the detailed agenda. The developers and contributors are donating their valuable time, so it would be great if in-kind funding can be made available from within the community to cover out-of-pocket expenses. All of the work that takes place at the community meeting will be directly contributed back into the GRASS project to the benefit of everyone who uses it.

=== Thanks to our sponsors ===

We are grateful for the support which we have received to organize this GRASS Community Meeting:

[[File:Osgeo logo.png|none|left|alt=Light and dark green logo of OSGeo saying Your Open Source Compass|Open Source Geospatial Foundation]]
* [https://www.osgeo.org/ OSGeo]: 7303 USD (approved budget contribution, [https://www.loomio.com/p/2m75BZkL/motion-to-approve-7303-to-support-grass-gis-community-meeting motion])

[[File:FOSSGIS_eV_logo.png|none|left|400px|alt=Logo of FOSSGIS e.V.|FOSSGIS e.V.]]
* [https://www.fossgis.de/ FOSSGIS e.V.]: 5000 EUR (approved budget contribution, [https://www.fossgis.de/wiki/F%C3%B6rderantr%C3%A4ge/GRASS_GIS_Community_Meeting_2023 request])

[[File:OSGeo JP logo for web.png|none|left|400px|alt=OSGeo.JP]]
* [https://www.osgeo.jp/ OSGeo Japan]: 550 USD (through Open Collective)

Individuals:
* MarWe 50 USD
* Nick Brady 50 USD
* José Ramón 50 USD
* Johannes Brauner 30 USD
* Peter Löwe 30 USD
* Evan Kay 10 USD
* Joaquin Perez Valera 5 USD
* Anonymous sponsors 2750 USD

In-kind contributions:

* Faculty of Civil Engineering Czech Technical University in Prague (FCE CTU) - space and personnel time (planning, preparation)
* North Carolina State University - personnel time (planning, preparation)
* mundialis GmbH & Co. KG - personnel time (planning, preparation)
* CONICET - personnel time (planning, preparation)

== Timing ==

'''When''': June 2-6, 2023

Of course you are invited to join or leave the meeting whenever you want.

== Venue ==

[[Image:logo_cvut.jpg|130px|left]]
Department of Geomatics 
[https://www.fsv.cvut.cz/?lang=en Faculty of Civil Engineering] 
[https://www.cvut.cz/en Czech Technical University in Prague], {{wikipedia|Czech Republic}} 
Thákurova 7/2077, Prague 
Room B868 
[https://en.mapy.cz/s/debazefuse Map] 

Prague has an international [http://www.prg.aero/en/ airport] and is also reachable by train, bus or car.

== Accommodation and Costs ==

Participants should plan for the following costs:

* The participation is free of charge
* Travel to Prague, variable depending on where you come from, reimbursements depending on the financial contributions provided by the community
* Accommodation and meals (with the donated sponsorship money we will try to cover some expenses of the participants)
'''Please note''': The currency in Czech Republic is {{wikipedia|Czech crown}} (CZK, koruna, Kč). 100 Czech crowns are about 4 Euros (see [https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/ current rates]).

Please let us know your time of arrival and departure, so we can book accommodations and organize the logistics.

Financial support: (partial) travel grants can be payed upon request thanks to our sponsors!

== Agenda - What we plan to do ==

'''Note:''' The program is generally open for your ideas. Please write an email to the [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developer list] to discuss your contribution.

During the meeting we will work on GRASS GIS on these tasks (please add more!):

* We will update and revise the [https://github.com/qgis/QGIS/tree/master/python/plugins/grassprovider GRASS GIS Integration with QGIS] to simplify maintenance.
* Furthermore, we will migrate the compilation technology to CMake to significantly improve the Windows builds including PDAL support and become binary compatible with OSGeo4W.
* The extensive GRASS documentation will be converted from HTML to Markdown to facilitate future collaboration.
* Pictures, examples and workflows will be added to the documentation where they are still missing.
* Software maintenance processes are automated and documented to reduce the burden on maintainers and thus improve the sustainability of the project.

This means that there are tasks from both the programming and documentation areas to appeal to a wide range of interested parties.

Further details about the action items you '''find [[Talk:GRASS Community Meeting Prague 2023|here]]''' and below. Topics cover non-technical, semi-technical, and technical issues.

=== Timeline ===

(agenda is under development, but also flexible)

==== Thursday, 1 June ====

* Arrival

==== Friday, 2 June ====

* 10:00 meeting starts in the room B-868
* Review the plan for the next days
* API for use in Python and in other projects (e.g., QGIS)
* Parallelizations

==== Saturday, 3 June ====

* Reducing cost of distribution on Windows
* Group photo 1

==== Sunday, 4 June ====

* Compilation CMake (Windows, Linux)
* Connections in general, rgrass, qgisprocess
* Group photo 2

==== Monday, 5 June ====

* Connections in general, QGIS, rgrass, qgisprocess
* Parallelizations
* grass.jupyter

==== Tuesday, 6 June ====

* Connections in general, QGIS
* Parallelizations
* grass.jupyter

==== Wednesday, 7 June ====

* Departure

== Participation ==

We are planning for an attendance of 20 people (i.e., coding places) but of course you are welcome to join us and bring new ideas with you: we'll make more places available. Please add your name here or contact [[User:Landa|Martin Landa]] <tt><landa.martin at gmail.com></tt>:

=== In person ===

{|class="wikitable sortable" border="2" cellspacing="0" cellpadding="4" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse; background-color:#edf9c7; font-size:95%; empty-cells:show;"
!width=50px|'''Number'''
!width=130px|'''Participant '''
!width=100px|'''Country'''
!width=100px|'''Arrival'''
!width=100px|'''Departure'''
!'''Topics'''
!'''Notes'''
|-
|1
|[[User:Landa|Martin Landa]]
| Czech Republic
| June 1
| June 7
| Python: create_location ([https://github.com/OSGeo/grass/issues/1987 #1987]), Graphical Modeler improvements and single window layout integration
|
|-
|2
| Micha Silver
| Israel
| June 2
| June 6
| Addon to derive soil moisture from Sentinel 2
|
|-
|3
|[https://www.osgeo.org/member/kudrnovsky/ Helmut Kudrnovsky]
| Austria
| June 2 (18:37) by train
| June 4 (18:24) by train
| support CMake transition
|
|-
|4
|[[User:Neteler|Markus Neteler]]
| Germany
| June 2 (17:17)
| June 6 (12:43)
| translations, manual pages, ..., see [[Talk:GRASS_Community_Meeting_Prague_2023#Markus_Neteler|my list in "Discussion" page]]
|
|-
|5
|[[User:pesekon2|Ondřej Pešek]]
| Czech Republic
| June 2 (17:17)
| June 6 (12:43)
| Python 3.12-connected issues, gmodeler
|
|-
|6
| [[User:helena|Helena Mitasova]]
| United States
| June 2
| June 6
|
|
|-
|7
| [[User:wenzeslaus|Vaclav Petras]]
| United States
| June 1
| June 7
| init and other Python API topics, support CMake transition, revise connection with QGIS and other tools, funding
|
|-
|8
| [[User:Annakrat|Anna Petrasova]]
| United States
| June 1
| June 7
| parallelization documentation, grass.jupyter, R and QGIS integration
|
|-
|9
| [[User:Ctwhite|Corey White]]
| United States
| June 2 (10:55)
| June 7
| Connections with other tools, OpenPlains, JSON outputs
|
|-
|10
| [[User:MarisN|Maris Nartiss]]
| Latvia
| June 2 (14:30)
| June 6 (12:00)
| Improvements of imagery modules (push i.svm.*; i.signatures; ?)
|-
|11
| [[User:Aaronsms|Aaron Saw Min Sern]]
| Singapore
| June 1
| June 7
| Support CMake transition, r.mapcalc parallelization
|
|-
|12
| [[User:Ldesousa|Luís de Sousa]]
| The Netherlands
| June 1 (20:00)
| June 5 (20:45)
| Update r.mblend add-on; test CMake transition.
|
|-
|13
| Caitlin Haedrich
| United States
| June 1
| June 7
| grass.jupyter
|
|-
|14
| Linda Kladivová
| Czech Republic
| June 2
| June 6
| Single-Window layout issues and improvements
|
|-
|15
| Carmen Tawalika
| Germany
| June 2 (17:17)
| June 6 (12:43)
| Happy to assist with general topics like documentation + automation, in doubt something related to actinia
|
|-
|16
| Floris Vanderhaeghe
| Belgium
| June 3 (train 19:17)
| June 6 (train 8:25)
| Helping in interfacing GRASS from R (rgrass & qgisprocess packages)
|
|-
|}

If you are arriving or departing on the days of the event, please specify the time, too.

=== Via chat or hangout ===

Join our [https://app.gitter.im/#/room/#grassgis_community:gitter.im Gitter chatroom]

Gitter has a video (and backup will be Zoom).

Participating virtually:

{|class="wikitable sortable" border="2" cellspacing="0" cellpadding="4" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse; background-color:#edf9c7; font-size:95%; empty-cells:show;"
!width=50px|'''Number'''
!width=130px|'''Participant '''
!width=100px|'''Country'''
!'''Topics'''
!'''Times, synchronous or fully asynchronous'''
!'''Notes'''
|-
|1
|[[User:Baharmon|Brendan Harmon]]
| United States
| Update integration with QGIS
| Available 8:00 AM CST (UTC-6) onwards
|
|-
|2
|[[User:veroandreo|Veronica Andreo]]
| Argentina
| Mission and vision, interfaces with QGIS and R, sponsoring, ... [https://grasswiki.osgeo.org/wiki/Talk:GRASS_Community_Meeting_Prague_2023#Vero see discussion tab]
| available from 8:00 AM ART (UTC-3) onward
|
|-
|3
|[[User:Nobeeakon|Daniel T]]
| Mexico
|
| some availability through the days :/
|
|-
|4
|[[User:LBartoletti|Loïc Bartoletti]]
| France
| QGIS Integration, support CMake transition
|
|-
|}

==== Timing of hangout meetings ====

Vero: available from 8:00 AM ART (UTC-3) onward

=== Collaborative document scratching ===

TBD

== Individual Preparation ==

* Bring your own computer
* Bring {{wikipedia|AC adapter|power connector adapter}} if needed (Czech Republic: 230V, 50Hz, {{wikipedia|File:Euro-Flachstecker_2.jpg|Type C Europlugs}} are common and also {{wikipedia|File:French_plug_and_socket.jpg|Type E}})
* Install git and the compiler tools, and come with a working GRASS development environment if possible.

== Broadcast & Video ==

During the event :)

== Photos ==

Also during the event :)

== FAQ ==

* '''How was it last time?'''
** Very nice, see [[GRASS_GIS at OSGeo Virtual Community Sprint 2020]]!
* ''Is the GRASS Community Meeting just a coding event?''
** It is mainly a coding and documentation event. It is a working session for people who are already participants in the GRASS project and/or are committed to improving the GRASS project.
** On demand we can do some presentations of current working GRASS implementation and new upcoming features to spread the idea of Open Source GIS software.
* ''Is the GRASS Community Meeting for developers only?''
** No: anybody can help, with testing, checking out bugs and fixes, documentation and more.
* ''Where can I get help and more information about the community meeting?''
** Contact [[User:Landa|Martin Landa]] <tt><landa.martin at gmail.com></tt>

== Report and press release ==

TBD: After the event :-)

We'll esp. craft a report for our sponsors.

[[Category: Workshops]]
[[Category: Code Sprint]]
[[Category: 2023]]

GRASS Community Meeting Prague 2023

2023-04-04T02:23:17Z

⚠️Baharmon: /* Via chat or hangout */

GRASS Community Meeting Prague 2023

2023-04-04T02:22:34Z

⚠️Baharmon: /* Via chat or hangout */

GRASS Python Scripting Library

2022-11-23T20:40:02Z

⚠️Baharmon: /* Interfacing with NumPy */

{{Python}}
Python API documentation:

* [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)

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()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{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.

'''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

def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</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 ==

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
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
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
<tt>subprocess.Popen()</tt> 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.]

{{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>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

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
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

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

* {{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>.

* {{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").

* {{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")

* {{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.

* {{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".

* {{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.

* {{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/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 with NumPy ===

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:

<source lang="python">
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")
</source>

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 <code>numpy.memmap</code> 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 ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
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)))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### 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!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/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()

</source>

=== Parsing the options and flags ===

{{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">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

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.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</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>

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

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

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

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

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.:

<source lang="python">
#% options: 0.0-1.0
</source>

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) ===

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

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

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

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</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 ===

How to obtain the text labels
<source lang="python">
# 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"))
</source>

=== Example for parsing category numbers ===

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

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
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()
</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 ===

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

'''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">
#!/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
</source>

=== Managing mapsets ===

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

<source lang="python">
grass.mapsets(False)
</source>

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

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

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

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 ===

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 {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

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

=== 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 <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

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>.

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

<source lang="python">
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)
</source>

=== 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:

<source lang="python">
grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')
</source>

=== Interface to copying maps (g.copy) ===

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

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

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

<source lang="python">
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>

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

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.

<source lang="python">
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()
</source>

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):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== 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":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

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 is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

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

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== 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:

<source lang="python">
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)
</source>

=== 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:
<source lang="python">
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')
</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 ===

'''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:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</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 ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="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')
</source>

=== 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:

<source lang="python">
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())
</source>

=== 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 {{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 {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
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()
</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 {{pyapi|script|script.core|region_env}}.

<source lang=python>
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)
</source>

=== Using predefined constants ===

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>

== 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.

[[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]]

GRASS Python Scripting Library

2022-11-23T20:39:33Z

⚠️Baharmon: /* Interfacing with NumPy and SciPy */

{{Python}}
Python API documentation:

* [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)

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()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{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.

'''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

def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</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 ==

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
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
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
<tt>subprocess.Popen()</tt> 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.]

{{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>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

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
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

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

* {{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>.

* {{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").

* {{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")

* {{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.

* {{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".

* {{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.

* {{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/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 with NumPy ===

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:

<source lang="python">
import grass.script as grass
import grass.script.array as garray

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

# 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")
</source>

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 <code>numpy.memmap</code> 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 ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
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)))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### 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!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/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()

</source>

=== Parsing the options and flags ===

{{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">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

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.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</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>

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

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

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

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

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.:

<source lang="python">
#% options: 0.0-1.0
</source>

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) ===

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

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

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

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</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 ===

How to obtain the text labels
<source lang="python">
# 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"))
</source>

=== Example for parsing category numbers ===

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

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
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()
</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 ===

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

'''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">
#!/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
</source>

=== Managing mapsets ===

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

<source lang="python">
grass.mapsets(False)
</source>

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

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

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

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 ===

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 {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

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

=== 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 <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

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>.

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

<source lang="python">
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)
</source>

=== 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:

<source lang="python">
grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')
</source>

=== Interface to copying maps (g.copy) ===

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

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

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

<source lang="python">
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>

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

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.

<source lang="python">
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()
</source>

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):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== 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":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

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 is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

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

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== 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:

<source lang="python">
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)
</source>

=== 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:
<source lang="python">
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')
</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 ===

'''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:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</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 ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="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')
</source>

=== 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:

<source lang="python">
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())
</source>

=== 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 {{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 {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
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()
</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 {{pyapi|script|script.core|region_env}}.

<source lang=python>
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)
</source>

=== Using predefined constants ===

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>

== 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.

[[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]]

GRASS Python Scripting Library

2022-11-23T20:38:59Z

⚠️Baharmon: /* Interfacing with NumPy */

{{Python}}
Python API documentation:

* [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)

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()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{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.

'''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

def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</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 ==

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
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
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
<tt>subprocess.Popen()</tt> 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.]

{{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>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

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
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

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

* {{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>.

* {{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").

* {{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")

* {{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.

* {{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".

* {{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.

* {{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/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 with NumPy ===

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:

<source lang="python">
import grass.script as grass
import grass.script.array as garray

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

# 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")
</source>

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 <code>numpy.memmap</code> 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 ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
from scipy import stats
import grass.script as grass
import grass.script.array as garray

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

x = garray.array()
x.read(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)))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### 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!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/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()

</source>

=== Parsing the options and flags ===

{{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">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

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.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</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>

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

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

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

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

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.:

<source lang="python">
#% options: 0.0-1.0
</source>

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) ===

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

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

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

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</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 ===

How to obtain the text labels
<source lang="python">
# 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"))
</source>

=== Example for parsing category numbers ===

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

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
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()
</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 ===

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

'''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">
#!/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
</source>

=== Managing mapsets ===

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

<source lang="python">
grass.mapsets(False)
</source>

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

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

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

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 ===

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 {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

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

=== 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 <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

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>.

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

<source lang="python">
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)
</source>

=== 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:

<source lang="python">
grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')
</source>

=== Interface to copying maps (g.copy) ===

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

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

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

<source lang="python">
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>

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

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.

<source lang="python">
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()
</source>

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):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== 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":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

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 is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

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

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== 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:

<source lang="python">
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)
</source>

=== 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:
<source lang="python">
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')
</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 ===

'''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:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</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 ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="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')
</source>

=== 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:

<source lang="python">
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())
</source>

=== 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 {{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 {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
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()
</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 {{pyapi|script|script.core|region_env}}.

<source lang=python>
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)
</source>

=== Using predefined constants ===

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>

== 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.

[[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]]

User:Baharmon

2022-11-22T03:59:55Z

⚠️Baharmon: Blanked the page

GRASS Python Scripting Library

2022-03-31T01:09:31Z

⚠️Baharmon: Updated print statements to Python 3 in the Interfacing section

{{Python}}
Python API documentation:

* [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)

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()'':'''

* {{pyapi|script|script.core|run_command}} executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* {{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.

'''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

def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</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 ==

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
that command line to <tt>subprocess.Popen()</tt> via {{pyapi|script|script.core|start_command}}, except
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
<tt>subprocess.Popen()</tt> 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.]

{{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>make_command()</tt> to construct a command line which is passed as the
"args" parameter to <tt>subprocess.Popen()</tt>.

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
would use <tt>subprocess.Popen()</tt> to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is {{cmd|r.mapcalc}} in 6.x).

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

* {{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>.

* {{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").

* {{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")

* {{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.

* {{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".

* {{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.

* {{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/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 with NumPy ===

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] 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 {{pyapi|script|script.raster|raster_info}}:

Example:

<source lang="python">
import grass.script as grass
import grass.script.array as garray

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

# read map
a = garray.array()
a.read(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")
</source>

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 <code>numpy.memmap</code> 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:'''

The function grass.script.array.read() and ...write() use r.out.bin and r.in.bin respectively. r.out.bin respects the MASK.

=== Interfacing with NumPy and SciPy ===

[http://docs.scipy.org/doc/scipy/reference/index.html SciPy] offers simple access to complex calculations. Example:

<source lang="python">
from scipy import stats
import grass.script as grass
import grass.script.array as garray

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

x = garray.array()
x.read(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)))
</source>

=== Interfacing with NumPy, SciPy and Matlab ===

One may also use the SciPy - Matlab interface:

r.out.mat input=elevation output=elev.mat

<source lang="python">
### 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!
#######
</source>

== Usage Examples ==

=== Display example ===
Example of Python script, which is processed by {{cmd|g.parser}}:

<source lang="python">
#!/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()

</source>

=== Parsing the options and flags ===

{{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">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

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.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</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>

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

Example:
<source lang="bash">
python my.module.py input=input output=output myoption=0.1,0.2,0.5
</source>

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

<source lang="python">
myoption = map(float, options['myoption'].split(','))
</source>

The option definition in the script should have:

<source lang="python">
#% type: double
#% multiple: yes
</source>

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.:

<source lang="python">
#% options: 0.0-1.0
</source>

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) ===

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

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

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

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</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 ===

How to obtain the text labels
<source lang="python">
# 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"))
</source>

=== Example for parsing category numbers ===

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

'''A:''' It is recommended to use {{pyapi|script|script.core|pipe_command}} and parse the output, e.g.:

<source lang="python">
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()
</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 ===

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

'''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">
#!/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
</source>

=== Managing mapsets ===

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

<source lang="python">
grass.mapsets(False)
</source>

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

=== r.mapcalc example ===

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

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

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 ===

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 {{pyapi|script|script.raster|raster_info}}, e.g.:

<source lang="python">
import grass.script as grass

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

=== 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 <tt>grass.script.raster_what()</tt>, it returns a list of dictionaries.

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>.

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

<source lang="python">
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)
</source>

=== 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:

<source lang="python">
grass.run_command('r.rescale', input=mis1, output=mis1_8bit, from_='0,2048', to='0,255')
</source>

=== Interface to copying maps (g.copy) ===

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

<source lang="python">
grass.run_command('g.copy', rast = (input, output))
</source>

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

<source lang="python">
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>

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

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.

<source lang="python">
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()
</source>

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):

<source lang="python">
p = grass.start_command(..., stdout = grass.PIPE, stderr = grass.STDOUT, env = env)
</source>

=== 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":

<source lang="bash">
$ r.mapcalc 'foo = null()'
$ r.info -r foo
min=NULL
max=NULL
</source>

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 is far more expensive than simply determining whether
there are any non-null cells. Counting cells requires reading the
entire map, while the {{cmd|r.info}} approach only needs to read the metadata
files.

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

A count loop:

<source lang="python">
while grass.raster_info(inmap)['max'] is not None:
...
</source>

=== 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:

<source lang="python">
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)
</source>

=== 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:
<source lang="python">
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')
</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 ===

'''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:''' Append an underscore to the name, i.e.:

<source lang="python">
grass.run_command('r.resamp.bspline', lambda_ = ...)
</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 ===

Code fragment to control the {{cmd|pngdriver}} in Python:

<source lang="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')
</source>

=== 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:

<source lang="python">
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())
</source>

=== 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 {{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 {{pyapi|script|script.core|use_temp_region}}

<source lang=python>
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()
</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 {{pyapi|script|script.core|region_env}}.

<source lang=python>
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)
</source>

=== Using predefined constants ===

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>

== 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.

[[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]]

GRASS GIS Raleigh meetups 2016

2016-09-23T15:23:29Z

⚠️Baharmon: Added participants

A group of people contributing or interested in contributing to GRASS GIS met [[Christmas GRASS GIS potential contributors meeting in Raleigh|at the end of 2015 in Raleigh]], NC and decided to meet regularly in the following year. This is a page to organize meetings and to record what was done or discussed during the meetings.

Contact person: [[User:Wenzeslaus|Vaclav Petras]] (Vashek, wenzeslaus gmail com)

== October 1 ==

* date: October 1 (Saturday)
* time: 1:30pm - 6:00pm (feel free to come and leave anytime)
* place: Hunt library (see below)
* room: will be specified later, likely 4411 (note that the elevator from the 1st floor will take you just to the 2nd floor, use the yellow stairs for simplicity if you can)
* participants:
** Brendan Harmon

== August 20 ==

* date: August 20 (Saturday)
* time: 1:30pm - 6:00pm (feel free to come and leave anytime)
* place: Hunt library (see below)
* room: 4502 The Fishbowl (note that the elevator from the 1st floor will take you just to the 2nd floor, use the yellow stairs for simplicity if you can)
* participants:
** ''add your name here''
* suggested topics (plus any you come up with):
** getting started with developing custom modules for GRASS GIS
** testing releases 7.2.0 (scheduled for September 1) and 7.0.5 (scheduled for August 21), see [https://trac.osgeo.org/grass/roadmap Roadmap at Trac]
** testing results of 4 GSoC projects (GSoC finishes August 15), see [https://trac.osgeo.org/grass/wiki/GSoC#a2016 GSoC 2016 Projects at Trac] (Cartography, New image segmentation algorithms, Web interface, Qt interface)
** fix tests, code or report an issue: [http://fatra.cnr.ncsu.edu/grassgistests/reports_for_date-2016-06-30-14-51/report_for_nc_basic_spm_grass7_nc/raster/r.mapcalc/test_row_above_below_bug/index.html r.mapcalc/test_row_above_below_bug], [http://fatra.cnr.ncsu.edu/grassgistests/reports_for_date-2016-05-24-07-00/report_for_nc_basic_spm_grass7_nc/raster/r.mapcalc/test_r3_mapcalc/index.html r.mapcalc/test_r3_mapcalc], [http://fatra.cnr.ncsu.edu/grassgistests/reports_for_date-2016-06-30-14-51/report_for_nc_basic_spm_grass7_nc/lib/python/pygrass/raster/test_history/index.html pygrass/raster/test_history], [http://fatra.cnr.ncsu.edu/grassgistests/reports_for_date-2016-06-30-14-51/report_for_nc_basic_spm_grass7_nc/lib/python/pygrass/vector/test_doctests/index.html pygrass/vector/test_doctests]
** ...

== July 9 ==

* date: July 9 (Saturday)
* time: 1:00pm - 6:00pm (feel free to come and leave anytime, library closes at 6:00pm)
* place: Hunt library (see below)
* room: 4502 The Fishbowl (note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* participants:
** Vaclav Petras ([https://trac.osgeo.org/grass/timeline?from=July+9%2C+2016&daysback=1&authors=wenzeslaus&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update changes at Trac])
** Anna Petrasova ([https://trac.osgeo.org/grass/timeline?from=July+9%2C+2016&daysback=1&authors=annakrat&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update changes at Trac])
* topics:
** backports for 7.2 release
** cartography in GRASS GIS: testing
** new features and refactoring of overlays (legend, text, ...) in Map Display in wGUI
** unicode support for Python scripts

== June 4 ==

[[File:Hunt_library_spaces.jpg|thumbnail|right|Spaces in the Hunt library, almost empty during the summer and the Fishbowl empty after the meetup]]

* date: June 4 (Saturday)
* time: 1:30pm - 6:00pm (feel free to come and leave anytime, library closes at 6:00pm)
* place: Hunt library (see below)
* room: 4502 The Fishbowl (note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* participants:
** Vaclav Petras
*** documentation improvements (content, style, consistency), color table modules in addons, .... ([https://trac.osgeo.org/grass/timeline?from=June+4%2C+2016&daysback=1&authors=wenzeslaus&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update list of all changesets at Trac])
** Anna Petrasova
*** fixed {{trac|3010}} (PyGRASS vector attributes issue), ... ([https://trac.osgeo.org/grass/timeline?from=June+4%2C+2016&daysback=1&authors=annakrat&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update list of all changesets at Trac])
** and 2 others
* other topics:
** contributing to GRASS GIS (commit rights, addons versus core)
** GRASS GIS compilation, updating older source code
** writing GRASS GIS module in C

== May 6-7 ==

[[File:Red_hat_raleigh.jpg|thumbnail|right|Red Hat Tower in Downtown Raleigh]]

* For April and May we are meeting for two days at [https://2016.foss4g-na.org/ FOSS4G NA] Code Sprint and Unconference.
* date: May 6 (Friday) - May 7 (Saturday)
* time: starts at 10:00am on Friday, ends at 5:00pm on Saturday
* place: Red Hat Inc. - 100 East Davie Street, Raleigh, NC 27601
* participants:
** Brendan Harmon
** Vaclav Petras (Vashek)
*** Simple Python Editor, GSoC 2016, ... ([https://trac.osgeo.org/grass/timeline?from=May+8%2C+2016&daysback=3&authors=wenzeslaus&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update list of all changes at Trac])
** Anna Petrasova
*** Data Catalog, GSoC 2016, d.polar, ... ([https://trac.osgeo.org/grass/timeline?from=May+8%2C+2016&daysback=3&authors=annakrat&milestone=on&ticket=on&changeset=on&wiki=on&sfp_email=&sfph_mail=&update=Update list of all changes at Trac])
** and 2 others

== March 19 ==

[[File:Grass_meetup_2016_03_19.jpg|thumbnail|right|In the Fishbowl on March 19]]

* date: March 19 (Saturday)
* time: 1:30pm - 5:30pm (feel free to come and leave anytime)
* place: Hunt library (see below)
* room: 4502 The Fishbowl (note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* participants:
** Vaclav Petras
** Anna Petrasova
** Brendan Harmon
** Doug Newcomb
** Makiko Shukunobe
** and 3 others
* topics:
** fix {{cmd|r.in.lidar}} and large rasters ({{rev|68083}})
** turning a Python script into a GRASS addon module
** planning next two meetings in relation to [https://2016.foss4g-na.org/ FOSS4G NA 2016] which is in Raleigh on May 2-5. and related possible code sprint (May 6-7)
** discussing needed graphic improvements of GRASS manual pages (index, graphical index, module man page)
** and several other things
** [[Introduction to GRASS GIS with terrain analysis examples]] wiki page

== February 20 ==

[[File:Grass gis raleigh meetup feb20 2016.png|thumbnail|right|In the Fishbowl on February 20]]

* date: February 20 (Saturday)
* time: 1:30pm - 5:30pm (feel free to come and leave anytime)
* place: Hunt library (see below)
* room: 4502 The Fishbowl (note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* participants:
** Vaclav Petras
** Anna Petrasova
** Makiko Shukunobe
** and 2 others
* topics: [https://grass.osgeo.org/grass64/manuals/addons/r.wind.sun.py.html r.wind.sun] port to version 7 as possible beginners topic ([https://trac.osgeo.org/grass/browser/grass-addons/grass6/raster/r.wind.sun/r.wind.sun.py?rev=67404 source code]), {{Cmd|v.overlay}} interface and possible v.clip, [https://trac.osgeo.org/grass/ticket/2663 submitting code through a ticket], GRASS GIS in QGIS, GRASS Story video ([http://dx.doi.org/10.5446/12963 HD], [https://www.youtube.com/watch?v=U3Hf0qI4JLc YouTube], [https://grass.osgeo.org/uploads/grass/history_docs/grass_movie_CERL_1987.mov MOV]), [https://2016.foss4g-na.org FOSS4G NA]

== January 30 ==

[[Image:Room3208 jan30.jpg|thumb|400px|The room 3208 on January 30 with GRASS GIS logo on whiteboard to make the room easy to find]]

* date: January 30 (moved from January 23 because of the weather)
* time: 1:00pm - 6:30pm (feel free to come and leave anytime)
* place: Hunt library (see [[#Location|below]])
* room: 3208 (Large Group Study Room; close to the Game Lab and the wide yellow stairs; note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* food: your own supplies, [http://dining.ncsu.edu/locations/restaurants-cafes/hunt-library/ Common Grounds Café] at Hunt (closes at 5pm), [http://dining.ncsu.edu/locations/restaurants-cafes/on-the-oval/ On The Oval] (closes at 8pm)
* participants:
** Vaclav Petras
** Anna Petrasova
** Doug Newcomb
** Brendan Harmon
** Makiko Shukunobe
** and 2 others
* some of the topics:
** starting with Python API and running scripts in command line on Linux
** [[Compiling on MacOSX]] (ended up using brew because of problems with separately installed GDAL)
** debugging missing APPDATA on MS Windows, improved in {{rev|67709}}
** automated testing with Python and generating artificial data, e.g. <tt>r.mapcalc "plane = row()"</tt> or <tt>r.mapcalc "surface = sin(2)"</tt>
** discussing some GRASS concepts and more

== Location ==

[[Image:Hunt 2015 2.jpg|thumb|400px|The Hunt Library]]

* Raleigh, North Carolina, USA
* Centennial Campus of North Carolina State University
* [https://www.lib.ncsu.edu/huntlibrary James B. Hunt Jr. Library], 1070 Partners Way, Raleigh, NC 27606 ([http://www.openstreetmap.org/way/177166351 map])
** [https://www.lib.ncsu.edu/huntlibrary/explorespaces Floor plan].
*** The building is vertically split into two sections (library and another partially private space) and that the floor with the main desk and access to Oval is 2nd floor.
*** The elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can.
** Info about [https://www.lib.ncsu.edu/spaces/fishbowl Fishbowl]
** Info about [https://www.lib.ncsu.edu/spaces/group-study-rooms-large Group Study Rooms - Large]
* free parking on Saturdays: Oval West Parking Deck, Partners Way ([https://www.openstreetmap.org/way/164125158 map])



[[Category: Workshops]]
[[Category: Code Sprint]]
[[Category: 2016]]

GRASS GIS ISPRS Prague meetup 2016

2016-07-08T17:23:12Z

⚠️Baharmon: /* People */

People contributing or interested in contributing to GRASS GIS are welcome to meet during [http://www.isprs2016-prague.com/ ISPRS Congress] held in Prague 12-19th July 2016, Czech Republic.

Details will be published later or during the congress.

Contact person: [[User:Landa|Martin Landa]] (landa.martin gmail com)

== Meetings ==

We are doing more than one meeting to discuss everything from GSoC to general visions.

=== Tuesday July 12 ===

When: evening

Where:

Topics:
* GSoC
** vector legend implementation

== People ==

Are you going to ISPRS Congress, or you are just in Prague and willing to meet? Please put your name to the table bellow.

{| class="wikitable sortable" border="2" cellspacing="0" cellpadding="4" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse; background-color:#edf9c7; font-size:95%; empty-cells:show;"
|-
! No
! Participant
! Arrival
! Departure
! Country
! ISPRS participation
! Note
|-
| 1
| Martin Landa
| 12/7
| 19/7
| CZ
| yes
| Contact person
|-
| 2
| Helena Mitasova
| 15/7
| 19/7
| US
| yes
|
|-
| 3
| Vaclav Petras
| 12/7
| 19/7
| US
| yes
|
|-
| 4
| Anna Petrasova
| 12/7
| 19/7
| US
| yes
|
|-
| 5
| Yasuharu Yamada
| 16/7
| 18/7
| JP
| yes
|
|-
| 6
| Adam Laza
| 12/7
| 19/7
| CZ
| no
|
|-
| 7
| Ondrej Pesek
| 12/7
| 19/7
| CZ
| no
|
|-
| 8
| Stepan Turek
| 12/7
| 15/7 or 19/7
| CZ
| no
|
|-
|-
| 9
| Zofie Cimburova
| 14/7
| 18/7 or 19/7
| CZ
| no
|
|-
| 10
| Brendan Harmon
| 12/7
| 19/7
| US
| yes
|
|-}

[[Category: Workshops]]
[[Category: Code Sprint]]
[[Category: 2016]]

Using GRASS GIS through Python and tangible interfaces (workshop at FOSS4G NA 2016)

2016-05-02T13:09:06Z

⚠️Baharmon: /* Tangible Landscape */

[[File:FOSS4G NA 2016.png|center|none]]

This is material for FOSS4G NA 2016 workshop Using GRASS GIS through Python and tangible interfaces held in Raleigh May 2, 2016 - 09:00 to 13:00.

Learn about scripting, graphical and tangible (!) interfaces for GRASS GIS, the powerful desktop GIS and geoprocessing backend. We will start with the Python interface and finish with [https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html Tangible Landscape], a new tangible interface for GRASS GIS.
Python is the primary scripting language for GRASS GIS. We will demonstrate how to use Python to automate your geoprocessing workflows with GRASS GIS modules and develop custom algorithms using a Pythonic interface to access low level GRASS GIS library functions. We will also review several tips and tricks for parallelization.
[https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html Tangible Landscape] is an example of how the GRASS GIS Python API can be used to build new, cutting edge tools and advanced applications. Tangible Landscape is a collaborative 3D sketching tool which couples a 3D scanner, a projector and a physical 3D model with GRASS GIS. The workshop will be a truly hands-on experience – you will play with Tangible Landscape, using your hands to shape a sand model and drive geospatial processes.

'''Software''': [https://grass.osgeo.org GRASS GIS 7]

'''Data''': Download [https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip complete North Carolina sample dataset].

= GRASS GIS introduction =
You need to create a GRASS database we will use for the tutorial. Please download the [https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip dataset] for the workshop, noting where the files are located on your local directory.
Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>nc_spm_08_grass7</tt> in grassdata. Start GRASS GIS in Mapset <tt>user1</tt>.

GRASS GUI introduction
* [http://www4.ncsu.edu/~akratoc/GRASS_intro/ Basic screenshot tutorial] how to use GRASS GIS GUI
* [[Workshop_on_urban_growth_modeling_with_FUTURES#GRASS_GIS_introduction|Introduction from Workshop on urban growth modeling with FUTURES]]

= GRASS GIS Python API =

== Python Scripting library ==
[[File:GRASS GUI Python shell.png|thumbnail|right|Python shell in GRASS GIS GUI]]
The GRASS GIS 7 Python Scripting Library provides functions to call GRASS modules within scripts as subprocesses. The most often used functions include:
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.run_command run_command]''': most often used with modules which output raster/vector data where text output is not expected
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.read_command read_command]''': used when we are interested in text output
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.parse_command parse_command]''': used with modules producing text output as key=value pair
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.write_command write_command]''': for modules expecting text input from either standard input or file

Besides, this library provides several wrapper functions for often called modules.

=== Calling GRASS GIS modules ===
We will use GRASS GUI Python Shell to run the commands. For longer scripts, you can create a text file, save it into your current working directory and run it with <tt>python myscript.py</tt> from the GUI command console or terminal.

'''Tip''': When copying Python code snippets to GUI Python shell, right click at the position and select '''Paste Plus''' in the context menu. Otherwise multiline code snippets won't work.

We start by importing GRASS GIS Python Scripting Library:
<source lang="python">
import grass.script as gscript
</source>

Before running any GRASS raster modules, you need to set the computational region using {{cmd|g.region}}. In this example, we set the computational extent and resolution to the raster layer <tt>elevation</tt>.
<source lang="python">
gscript.run_command('g.region', raster='elevation')
</source>

The run_command() function is the most commonly used one. Here, we apply the focal operation average ({{cmd|r.neighbors}}) to smooth the elevation raster layer. Note that the syntax is similar to bash syntax, just the flags are specified in a parameter.
<source lang="python">
gscript.run_command('r.neighbors', input='elevation', output='elev_smoothed', method='average', flags='c')
</source>
If we run the Python commands from GUI Python console, we can use <tt>AddLayer</tt> to add the newly created layer:
<source lang="python">
AddLayer('elev_smoothed')
</source>

=== Calling GRASS GIS modules with textual input or output ===
Textual output from modules can be captured using the read_command() function.
<source lang="python">
gscript.read_command('g.region', flags='p')
</source>
<source lang="python">
gscript.read_command('r.univar', map='elev_smoothed', flags='g')
</source>

Certain modules can produce output in key-value format which is enabled by the '''-g''' flag. The parse_command() function automatically parses this output and returns a dictionary. In this example, we call {{cmd|g.proj}} to display the projection parameters of the actual location.
<source lang="python">
gscript.parse_command('g.proj', flags='g')
</source>

For comparison, below is the same example, but using the read_command() function.
<source lang="python">
gscript.read_command('g.proj', flags='g')
</source>

Certain modules require the text input be in a file or provided as standard input. Using the write_command() function we can conveniently pass the string to the module. Here, we are creating a new vector with one point with {{cmd|v.in.ascii}}. Note that ''stdin'' parameter is not used as a module parameter, but its content is passed as standard input to the subprocess.
<source lang="python">
gscript.write_command('v.in.ascii', input='-', stdin='%s|%s' % (635818, 221342), output='point')
</source>

If we run the Python commands from GUI Python console, we can use <tt>AddLayer</tt> to add the newly created layer:
<source lang="python">
AddLayer('point')
</source>

=== Convenient wrapper functions ===
Some modules have wrapper functions to simplify frequent tasks.
For example we can obtain the information about a raster layer with [https://grass.osgeo.org/grass70/manuals/libpython/script.html?highlight=mapcalc#script.raster.raster_info raster_info] which is a wrapper of {{cmd|r.info}},
or a vector layer with [https://grass.osgeo.org/grass70/manuals/libpython/script.html?script.vector.vector_info vector_info].
<source lang="python">
gscript.raster_info('elevation')
gscript.vector_info('point')
</source>

Another example is using [https://grass.osgeo.org/grass70/manuals/libpython/script.html?highlight=mapcalc#script.raster.mapcalc r.mapcalc wrapper] for raster algebra:
<source lang="python">
gscript.mapcalc("elev_strip = if(elevation > 100 && elevation < 125, elevation, null())")
gscript.read_command('r.univar', map='elev_strip', flags='g')
</source>

Function [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.region region] is a convenient way to retrieve the current region settings (i.e., computational region). It returns a dictionary with values converted to appropriate types (floats and ints).
<source lang="python">
region = gscript.region()
print region
# cell area in map units (in projected Locations)
region['nsres'] * region['ewres']
</source>

We can list data stored in a GRASS GIS location with {{cmd|g.list}} wrappers. With [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.list_grouped list_grouped], the map layers are grouped by mapsets (in this example, raster layers):
<source lang="python">
gscript.list_grouped(type=['raster'])
gscript.list_grouped(type=['raster'], pattern="landuse*")
</source>

Here is an example of a different {{cmd|g.list}} wrapper [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.list_pairs list_pairs] which structures the output as list of pairs (name, mapset). We obtain current mapset with {{cmd|g.gisenv}} wrapper.
<source lang="python">
current_mapset = gscript.gisenv()['MAPSET']
gscript.list_pairs('raster', mapset=current_mapset)
</source>

=== Exercise ===
Export all raster layers from your mapset with a name prefix "elev_*" as GeoTiff (see {{cmd|r.out.gdal}}). Don't forget to set the current region ({{cmd|g.region}}) for each map in order to match the individual exported raster layer extents and resolutions since they may differ from each other.

== PyGRASS ==
PyGRASS is a library originally developed during the Google Summer of Code 2012. PyGRASS library adds two main functionalities:
* Python interface through the ctypes binding of the C API of GRASS, to read and write natively GRASS GIS 7 data structures,
* GRASS GIS module interface using objects to check the parameters and execute the respective modules.
For further discussion about the implementation ideas and performance are presented in the article:
''[http://www.mdpi.com/2220-9964/2/1/201 Zambelli, P.; Gebbert, S.; Ciolli, M. Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS). ISPRS Int. J. Geo-Inf. 2013, 2, 201-219.]''

Standard scripting with GRASS modules in Python may sometime seem discouraging especially when you have to do conceptually simple things like: iterate over vector features or raster rows/columns.
Using the C API (most of GRASS GIS is written in C), all this is much more simple since you can directly work on GRASS GIS data and do just what you need to do.
However, you perhaps want to stick to Python. Here, the PyGRASS library introduced several objects that allow to interact directly with the data using the underlying C API of GRASS GIS.

=== Working with vector data (see [https://grass.osgeo.org/grass70/manuals/libpython/pygrass_vector.html manual page]) ===
Create a new vector map. Import the necessary classes:
<source lang="python">
from grass.pygrass.vector import VectorTopo
from grass.pygrass.vector.geometry import Point
</source>

Create an instance of a vector map:
<source lang="python">
my_points = VectorTopo('my_points')
</source>

Open the map in write mode:
<source lang="python">
my_points.open(mode='w')
</source>

Create some vector geometry features, like two points:
<source lang="python">
point1 = Point(635818.8, 221342.4)
point2 = Point(633627.7, 227050.2)
</source>

Add the above two points to the new vector map:
<source lang="python">
my_points.write(point1)
my_points.write(point2)
</source>

Finally close the vector map:
<source lang="python">
my_points.close()
</source>

Display the newly created vector (from GUI Python Shell):
<source lang="python">
AddLayer('my_points')
</source>

Now do the same thing using the context manager syntax and set also the attribute table:
<source lang="python">
# Define the columns of the new vector map
cols = [(u'cat', 'INTEGER PRIMARY KEY'),
(u'name', 'TEXT')]

with VectorTopo('my_points', mode='w', tab_cols=cols, overwrite=True) as my_points:
# save the point and the attribute
my_points.write(point1, ('pub', ))
my_points.write(point2, ('restaurant', ))
# save the changes to the database
my_points.table.conn.commit()
</source>
Note: we don't need to close the vector map because it is already closed by the context manager.

Go to Layer Manager, right click on 'my_points' and ''Show attribute data''.

Read an existing vector map:
<source lang="python">
with VectorTopo('my_points', mode='r') as points:
for point in points:
print(point, point.attrs['name'])
</source>

=== Working with raster data (see [https://grass.osgeo.org/grass70/manuals/libpython/pygrass_raster.html manual page]) ===
Create a new raster map and derive it's new values from <tt>elevation</tt> raster. Import the necessary classes:
<source lang="python">
from grass.pygrass.raster import RasterRow
</source>
Open the existing raster in read mode and print first 5 values of the first row (indices from S to N):
<source lang="python">
elev = RasterRow('elevation')
print elev.exist()
print elev.mapset
elev.open('r')
print elev[0][:5]
elev.close()
</source>

Create a new raster and write value 1 for cells with elevation < 120 and 0 otherwise:
<source lang="python">
new = RasterRow('new')
new.open('w', overwrite=True)
for row in elev:
new.put_row(row < 120)
new.close()
print new.exist()
</source>
Query old and new raster maps:
<source lang="python">
from grass.pygrass.vector import geometry

new.open('r')
elev.open('r')
poi1 = geometry.Point(632942, 225757)
poi2 = geometry.Point(641780, 217455)
print elev.get_value(poi1), new.get_value(poi1)
print elev.get_value(poi2), new.get_value(poi2)
new.close()
elev.close()
</source>

For more examples of using PyGRASS, please look at [https://github.com/wenzeslaus/python-grass-addon How to write a Python GRASS GIS 7 addon] workshop from FOSS4G-Europe 2015 and additional tutorials can be found [[Python/pygrass|on a PyGRASS wiki page]].

= Parallelization examples =
A simple way to execute several modules in parallel (developed by Sören Gebbert)
is the [https://grass.osgeo.org/grass71/manuals/libpython/pygrass.modules.interface.html?highlight=parallelmodulequeue#pygrass.modules.interface.module.ParallelModuleQueue ParallelModuleQueue class]. The basic idea is to create a queue with all the modules that must be execute in parallel. The ParallelModuleQueue class is based on the Module class of the pygrass library, here is a small example for computation of solar irradiance during day:
<source lang="python">
from copy import deepcopy
from grass.pygrass.modules import Module, ParallelModuleQueue

def main(elevation):
# compute slope and aspect for r.sun
Module('r.slope.aspect', elevation=elevation, aspect='aspect', slope='slope', overwrite=True)
# initialize an empty queue and list
queue = ParallelModuleQueue(nprocs=4)
sun_name = 'sun_{}'
# set computational region
Module('g.region', raster=elevation)
# initialize a module instance with shared inputs
sun = Module('r.sun', elevation=elevation, slope='slope', aspect='aspect',
beam_rad='beam', step=1, day=123, run_=False, overwrite=True)

for t in range(6, 22):
# create a copy of the module and set the remaining parameters
print t
m = deepcopy(sun)(beam_rad=sun_name.format(t), time=t)
queue.put(m)
queue.wait()

# set color table
Module('r.colors', map=[sun_name.format(t) for t in range(6, 22)], color='grey', flags='e')

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
main(elevation)
</source>

This simple parallel implementation uses Python class Pool:

<source lang="python">
from multiprocessing import Pool
import grass.script as gscript

def rsun(params):
gscript.run_command('r.sun', **params)

def main(elevation):
parameters = []
sun_name = 'sun_{}'
for t in range(6, 22):
params = dict(elevation=elevation, slope='slope', aspect='aspect',
step=1, day=123, beam_rad=sun_name.format(t), time=t, overwrite=True)
parameters.append(params)
pool = Pool(4)
p = pool.map_async(rsun, parameters)
p.get()

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
main(elevation)
</source>

This example shows parallelization by splitting computation into tiles using [https://grass.osgeo.org/grass71/manuals/libpython/pygrass.modules.grid.html?highlight=gridmodule#pygrass.modules.grid.grid.GridModule GridModule]:
<source lang="python">
import grass.script as gscript
from grass.pygrass.modules.grid import GridModule

def main(elevation):
region = gscript.region()
width = region['cols'] // 2 + 1
height = region['rows'] // 2 + 1

grd = GridModule('r.slope.aspect', elevation=elevation, slope='slope',
debug=False, width=width, height=height,
overlap=10, processes=4, overwrite=True)
grd.run()

if __name__ == '__main__':
elevation = 'elevation'
gscript.run_command('g.region', raster=elevation)
main(elevation)
</source>

= Tangible Landscape =
[[File:Tangible landscape setup.jpg|400px|thumbnail|right|Tangible Landscape setup]]

[http://baharmon.github.io/foss4g-na-2016-workshop/ A brief introduction to Tangible Landscape]

Tangible Landscape is a collaborative modeling environment for analysis of terrain changes.
We couple a scanner, projector and a physical 3D model with GRASS GIS.
We can analyze the impact of terrain changes by capturing the changes on the model,
bringing them into the GIS, performing desired analysis or simulation and projecting the results back on the model in real-time.
Tangible Landscape, as an easy-to-use 3D sketching tool, enables rapid design and scenarios testing for people with different backgrounds
and computer knowledge, as well as support for decision-making process.

Tangible Landscape has been used for a variety of applications supported by the extensive set of geospatial analysis and modeling tools available in GRASS GIS. We have explored how dune breaches affect the extent of coastal flooding, the impact of different building configurations on cast shadows and solar energy potential, and the effectiveness of various landscape designs for controlling runoff and erosion. Have a look at our [http://www.springer.com/us/book/9783319257730 book], [https://www.youtube.com/channel/UCc37pVh-WE46Xkqeq-KZQsA Youtube channel], and [https://plus.google.com/112857255995703553144/photos Google+ photos].

The software is free and open source and you can [https://github.com/ncsu-osgeorel/grass-tangible-landscape download it] and use it in your own setup of Tangible Landscape.

== Running examples ==
We will use a Titanpad to collect code samples from workshop participants and then run them in Tangible Landscape environment.
Whenever a scanning cycle is complete, a specified Python file is imported and all analyses in that file are computed.
Analyses are organized into functions with defined interface - each function has to start with <tt>run_</tt>.
Input parameter <tt>scanned_elev</tt> is the scanned raster (our DEM) and <tt>env</tt> is the environment which needs to be passed to individual subprocesses to correctly handle the region of the analysis.

Since participants will develop and test the analyses on their computers before we apply them to Tangible Landscape,
we add here the 'main' function with predefined parameters and participants will run it as a script.

<source lang="python">
import grass.script as gscript

def run_slope(scanned_elev, env, **kwargs):
# compute the analysis
gscript.run_command('r.slope.aspect', ..., env=env)

if __name__ == '__main__':
import os
os.environ['GRASS_OVERWRITE'] = '1'
elevation = 'elev_lid792_1m'
run_slope(scanned_elev=elevation, env=None)
</source>

Scripts can be run from terminal or GUI command console:
<pre>
python /path/to/my/script.py
</pre>

On Windows the path will look differently, for example:
<pre>
python C:\Users\yourname\path\to\my\script.py
</pre>

Make sure you set computational region to match your DEM. We will use raster DEM <tt>elev_lid792_1m</tt> from the sample dataset.
<pre>
g.region raster=elev_lid792_1m -p
</pre>

Here follow some basic examples of geospatial analyses we can do with Tangible Landscape.
At the end of this section you can find additional tasks, some of them combining multiple analyses.

== Modeling topography ==
=== Computing slope ===
[[File:tangible landscape slope.jpg|400px|thumbnail|right|Tangible Landscape: topographic slope]]
Basic example how we can compute topographic slope in degrees:
<source lang="python">
import grass.script as gscript

def run_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
env = None
run_slope(scanned_elev=elevation, env=env)
</source>

We can compute slope in percent and reclassify the values into discrete intervals:
<source lang="python">
def run_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope',
format='percent', env=env)
# reclassify using rules passed as a string to standard input
# 0:2:1 means reclassify interval 0 to 2 percent of slope to category 1
rules = ['0:2:1', '2:5:2', '5:8:3', '8:15:4', '15:30:5', '30:*:6']
gscript.write_command('r.recode', input='slope', output='slope_class',
rules='-', stdin='\n'.join(rules), env=env)
# set new color table: green - yellow - red
gscript.run_command('r.colors', map='slope_class', color='gyr', env=env)
</source>

=== Curvatures ===
Explore concavity/convexity of terrain with curvatures computed by {{cmd|r.param.scale}}:

<source lang="python">
def run_curvatures(scanned_elev, env, **kwargs):
gscript.run_command('r.param.scale', input=scanned_elev, output='profile_curv',
method='profc', size=11, env=env)
gscript.run_command('r.param.scale', input=scanned_elev, output='tangential_curv',
method='crosc', size=11, env=env)
gscript.run_command('r.colors', map=['profile_curv', 'tangential_curv'], color='curvature', env=env)
</source>
Change window size and see how it influences the result.

=== Landform identification ===
[[File:Tangible landscape geomorphons.jpg|400px|thumbnail|right|Tangible Landscape: Landforms computed with {{AddonCmd|r.geomorphon}}]]
There are 2 different methods for landform (ridge, valley, ...) identification in GRASS GIS.
First one is implemented in {{cmd|r.param.scale}} and uses curvatures.
The second is implemented in an addon {{AddonCmd|r.geomorphon}} which uses multiscale line-of-sight approach. This addon can be installed
from GUI command line:
<source lang="bash">
g.extension r.geomorphon
</source>
or follow
[https://grasswiki.osgeo.org/wiki/Introduction_to_GRASS_GIS_with_terrain_analysis_examples#Step_5:_Adding_the_r.geomorphon_Addon this tutorial].

<source lang="python">
def run_curvatures(scanned_elev, env, **kwargs):
gscript.run_command('r.param.scale', input=scanned_elev, output='landforms1',
method='feature', size=10, env=env)
gscript.run_command('r.geomorphon', dem=scanned_elev, forms='landforms2',
search=16, skip=6, env=env)
</source>

=== Building model based on difference raster ===
When building a model by hands based on a defined DEM, we can compute the difference between the scanned model and the original DEM.
By color-coding the difference, we can see where to add sand or remove it.

If you are running this outside of Tangible Landscape, you can generate a raster (our hypothetical pile of sand)
and compute the difference. In this example we also vertically rescale and translate the scanned raster to match
the original DEM using {{cmd|r.regression.line}}.
<source lang="python">
import grass.script as gscript

def run_difference(real_elev, scanned_elev, env, **kwargs):
regression_params = gscript.parse_command('r.regression.line', flags='g', mapx=scanned_elev, mapy=real_elev, env=env)
gscript.mapcalc('{regression} = {a} + {b} * {before}'.format(a=regression_params['a'], b=regression_params['b'],
before=scanned_elev, regression='regression'), env=env)
gscript.mapcalc('{difference} = {regression} - {after}'.format(regression='regression', after=real_elev, difference='diff'), env=env)
gscript.write_command('r.colors', map='diff', rules='-', stdin="-100 black\n-20 red\n0 white\n20 blue\n100 black", env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
sand_pile = 'sand_pile'
env = None
gscript.run_command('r.surf.fractal', output=sand_pile)
run_difference(real_elev=elevation, scanned_elev=sand_pile, env=env)
</source>

== Hydrology ==
=== Flooding with {{cmd|r.lake}} ===
[[File:tangible landscape rlake.jpg|200px|thumbnail|right|Example of simple flooding simulation with Tangible Landscape and {{cmd|r.lake}} module.]]

Module {{cmd|r.lake}} fills a lake to a target water level from a given start point or seed raster.
The resulting raster map contains cells with values representing lake depth and NULL for all other cells beyond the lake.

Example showing basic usage:
<source lang="python">
def run_lake(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
gscript.run_command('r.lake', elevation=scanned_elev, lake='output_lake',
coordinates=coordinates, water_level=120, env=env)
</source>

Create a lake where water level is relative to the altitude of the seed cell. Use function [https://grass.osgeo.org/grass70/manuals/libpython/script.html?script.raster.raster_what raster_what] to obtain the elevation value of the DEM and create a lake with water level being for example 5 m higher.

<source lang="python">
def run_lake(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
res = gscript.raster_what(map=scanned_elev, coord=[coordinates])
elev_value = float(res[0][scanned_elev]['value'])
gscript.run_command('r.lake', elevation=scanned_elev, lake='output_lake',
coordinates=coordinates, water_level=elev_value + 5, env=env)
</source>


=== Flow accumulation and watersheds ===
We can derive watersheds and flow accumulation using module {{cmd|r.watershed}} in one command:
<source lang="python">
def run_hydro(scanned_elev, env, **kwargs):
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum',
basin='watersheds', threshold=1000, flags='a', env=env)
</source>

Compute average slope value for each watershed. To do that use zonal statistics using {{cmd|r.stats.zonal}}:
<source lang="python">
def run_watershed_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum',
basin='watersheds', threshold=1000, env=env)
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)
gscript.run_command('r.stats.zonal', base='watersheds', cover='slope', method='average',
output='watersheds_slope', env=env)
gscript.run_command('r.colors', map='watersheds_slope', color='bgyr', env=env)
</source>

=== Depression filling ===
[[File:tangible_landscape_r_fill_dir.jpg|400px|thumbnail|right|Tangible Landscape: example of using {{cmd|r.fill.dir}} to create ponds]]
We will use depression filling algorithm implemented in {{cmd|r.fill.dir}} not as preprocessing step for flow accumulation analysis, but for creating ponds.
Because depressions are often nested, we will run depression filling several times:
<source lang="python">
def run_ponds(scanned_elev, env, **kwargs):
repeat = 2
input_dem = scanned_elev
output = "tmp_filldir"
for i in range(repeat):
gscript.run_command('r.fill.dir', input=input_dem, output=output, direction="tmp_dir", env=env)
input_dem = output
# filter depression deeper than 0.1 m to
gscript.mapcalc('{new} = if({out} - {scan} > 0.1, {out} - {scan}, null())'.format(new='ponds', out=output,
scan=scanned_elev), env=env)
gscript.write_command('r.colors', map='ponds', rules='-', stdin='0% aqua\n100% blue', env=env)
</source>

=== Overland water flow simulation ===
Module {{cmd|r.sim.water}} is an overland flow hydrology simulation using path sampling method.
<source lang="python">
def run_waterflow(scanned_elev, env, **kwargs):
# first we need to compute x- and y-derivatives
gscript.run_command('r.slope.aspect', elevation=scanned_elev, dx='scan_dx', dy='scan_dy', env=env)
gscript.run_command('r.sim.water', elevation=scanned_elev, dx='scan_dx', dy='scan_dy',
rain_value=150, depth='flow', env=env)
</source>

=== Erosion modeling ===
Landscape potential for soil erosion and deposition can be estimated and mapped using Unit Stream Power Based Erosion Deposition model (USPED). In this example we will use uniform land cover (c factor) and soil erodibility (K factor). Install addon {{AddonCmd|r.divergence}} using {{cmd|g.extension}}.
<source lang="python">
def run_usped(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum', threshold=1000, flags='a', env=env)
# topographic sediment transport factor
resolution = gscript.region()['nsres']
gscript.mapcalc("sflowtopo = pow(flow_accum * {res}.,1.3) * pow(sin(slope),1.2)".format(res=resolution), env=env)
# compute sediment flow by combining the rainfall, soil and land cover factors with the topographic sediment transport factor. We use a constant value of 270 for rainfall intensity factor
gscript.mapcalc("sedflow = 270. * {k_factor} * {c_factor} * sflowtopo".format(c_factor=0.05, k_factor=0.1), env=env)
# compute divergence of sediment flow
gscript.run_command('r.divergence', magnitude='sedflow', direction='aspect', output='erosion_deposition', env=env)
colors = ['0% 100:0:100', '-100 magenta', '-10 red', '-1 orange', '-0.1 yellow', '0 200:255:200',
'0.1 cyan', '1 aqua', '10 blue', '100 0:0:100', '100% black']
gscript.write_command('r.colors', map='erosion_deposition', rules='-', stdin='\n'.join(colors), env=env)
</source>

== Solar radiation and shades ==
We will first compute solar irradiation (daily radiation sum in Wh/m2.day) for a given day using {{cmd|r.sun}}:
<source lang="python">
def run_solar_radiation(scanned_elev, env, **kwargs):
# convert date to day of year
import datetime
doy = datetime.datetime(2016, 5, 2).timetuple().tm_yday
# precompute slope and aspect
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.sun', elevation=scanned_elev, slope='slope', aspect='aspect', beam_rad='beam', step=1, day=doy, env=env)
gscript.run_command('r.colors', map='beam', color='grey', flags='e')
</source>

Then we can also compute solar irradiance (W/m2) for a given day and hour (in local solar time) and extract the shades cast by topography:
<source lang="python">
def run_solar_radiance(scanned_elev, env, **kwargs):
# convert date to day of year
import datetime
doy = datetime.datetime(2016, 5, 2).timetuple().tm_yday
# precompute slope and aspect
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.sun', elevation=scanned_elev, slope='slope', aspect='aspect', beam_rad='beam', day=doy, time=8, env=env)
# extract shade and set color to black and white
gscript.mapcalc("shade = if(beam == 0, 0, 1)", env=env)
gscript.run_command('r.colors', map='beam', color='grey')
</source>

== Visibility analysis ==
First example shows computing viewshed (visibility) from a given coordinate:
<source lang="python">
def run_viewshed(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
gscript.run_command('r.viewshed', input=scanned_elev, output='viewshed', coordinates=coordinates, observer_elevation=1.75, flags='b', env=env)
gscript.run_command('r.colors', map='viewshed', color='grey')
</source>
== Cost surface and least cost path ==
[[File:least_cost_path.jpg|400px|thumbnail|right|Least cost path example where cost is slope]]
This example shows least cost path analysis with slope as cost. Coordinates will be provided by Tangible Landscape.
The resulting path will go through flat areas.

<source lang="python">
import grass.script as gscript
def LCP(elevation, start_coordinate, end_coordinate, env):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)
gscript.run_command('r.cost', input='slope', output='cost', start_coordinates=start_coordinate,
outdir='outdir', flags='k', env=env)
gscript.run_command('r.colors', map='cost', color='gyr', env=env)
gscript.run_command('r.drain', input='cost', output='drain', direction='outdir',
drain='drain', flags='d', start_coordinates=end_coordinate, env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
env = None
start = [638469, 220070]
end = [638928, 220472]
LCP(elevation, start, end, env)
</source>

== Additional tasks ==
# Compute topographic index using {{cmd|r.topidx}}.
# Compute topographic aspect (slope orientation) using {{cmd|r.slope.aspect}} and reclassify it into 8 main directions.
# Show areas with concave profile and tangential curvature (concave forms have negative curvature).
# Derive peaks using either {{AddonCmd|r.geomorphon}} or {{cmd|r.param.scale}} and convert them to points (using {{cmd|r.to.vect}} and {{cmd|v.to.points}}). From each of those points compute visibility with observer height of your choice a derive a cumulative viewshed layer where the value of each cell represents the number of peaks the cell is visible from (use {{cmd|r.series}}).
# Find a least cost path between 2 points (for example from x=638360, y=220030 to x=638888, y=220388) where cost is defined as topographic index (trying avoid areas). Use {{cmd|r.topidx}}.
# Compute erosion with spatially variable landcover and soil erodibility (use rasters <tt>cfactorbare_1m</tt> and <tt>soils_Kfactor</tt> from the provided dataset). Reclassify the result into 7 classes based on severity of erosion and deposition:
<pre>-120000.:-10:1:1
-10.:-5.:2:2
-5.:-0.1:3:3
-0.1:0.1:4:4
0.1:5.:5:5
5.:10.:6:6
10.:150000.:7:7
</pre>

[[Category: Tutorial]]
[[Category: Workshops]]
[[Category: Python]]
[[Category: 2016]]

Using GRASS GIS through Python and tangible interfaces (workshop at FOSS4G NA 2016)

2016-05-02T13:08:03Z

⚠️Baharmon: /* Tangible Landscape */

[[File:FOSS4G NA 2016.png|center|none]]

This is material for FOSS4G NA 2016 workshop Using GRASS GIS through Python and tangible interfaces held in Raleigh May 2, 2016 - 09:00 to 13:00.

Learn about scripting, graphical and tangible (!) interfaces for GRASS GIS, the powerful desktop GIS and geoprocessing backend. We will start with the Python interface and finish with [https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html Tangible Landscape], a new tangible interface for GRASS GIS.
Python is the primary scripting language for GRASS GIS. We will demonstrate how to use Python to automate your geoprocessing workflows with GRASS GIS modules and develop custom algorithms using a Pythonic interface to access low level GRASS GIS library functions. We will also review several tips and tricks for parallelization.
[https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html Tangible Landscape] is an example of how the GRASS GIS Python API can be used to build new, cutting edge tools and advanced applications. Tangible Landscape is a collaborative 3D sketching tool which couples a 3D scanner, a projector and a physical 3D model with GRASS GIS. The workshop will be a truly hands-on experience – you will play with Tangible Landscape, using your hands to shape a sand model and drive geospatial processes.

'''Software''': [https://grass.osgeo.org GRASS GIS 7]

'''Data''': Download [https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip complete North Carolina sample dataset].

= GRASS GIS introduction =
You need to create a GRASS database we will use for the tutorial. Please download the [https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip dataset] for the workshop, noting where the files are located on your local directory.
Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents), unzip the downloaded data into this directory. You should now have a Location <tt>nc_spm_08_grass7</tt> in grassdata. Start GRASS GIS in Mapset <tt>user1</tt>.

GRASS GUI introduction
* [http://www4.ncsu.edu/~akratoc/GRASS_intro/ Basic screenshot tutorial] how to use GRASS GIS GUI
* [[Workshop_on_urban_growth_modeling_with_FUTURES#GRASS_GIS_introduction|Introduction from Workshop on urban growth modeling with FUTURES]]

= GRASS GIS Python API =

== Python Scripting library ==
[[File:GRASS GUI Python shell.png|thumbnail|right|Python shell in GRASS GIS GUI]]
The GRASS GIS 7 Python Scripting Library provides functions to call GRASS modules within scripts as subprocesses. The most often used functions include:
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.run_command run_command]''': most often used with modules which output raster/vector data where text output is not expected
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.read_command read_command]''': used when we are interested in text output
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.parse_command parse_command]''': used with modules producing text output as key=value pair
* '''[https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.write_command write_command]''': for modules expecting text input from either standard input or file

Besides, this library provides several wrapper functions for often called modules.

=== Calling GRASS GIS modules ===
We will use GRASS GUI Python Shell to run the commands. For longer scripts, you can create a text file, save it into your current working directory and run it with <tt>python myscript.py</tt> from the GUI command console or terminal.

'''Tip''': When copying Python code snippets to GUI Python shell, right click at the position and select '''Paste Plus''' in the context menu. Otherwise multiline code snippets won't work.

We start by importing GRASS GIS Python Scripting Library:
<source lang="python">
import grass.script as gscript
</source>

Before running any GRASS raster modules, you need to set the computational region using {{cmd|g.region}}. In this example, we set the computational extent and resolution to the raster layer <tt>elevation</tt>.
<source lang="python">
gscript.run_command('g.region', raster='elevation')
</source>

The run_command() function is the most commonly used one. Here, we apply the focal operation average ({{cmd|r.neighbors}}) to smooth the elevation raster layer. Note that the syntax is similar to bash syntax, just the flags are specified in a parameter.
<source lang="python">
gscript.run_command('r.neighbors', input='elevation', output='elev_smoothed', method='average', flags='c')
</source>
If we run the Python commands from GUI Python console, we can use <tt>AddLayer</tt> to add the newly created layer:
<source lang="python">
AddLayer('elev_smoothed')
</source>

=== Calling GRASS GIS modules with textual input or output ===
Textual output from modules can be captured using the read_command() function.
<source lang="python">
gscript.read_command('g.region', flags='p')
</source>
<source lang="python">
gscript.read_command('r.univar', map='elev_smoothed', flags='g')
</source>

Certain modules can produce output in key-value format which is enabled by the '''-g''' flag. The parse_command() function automatically parses this output and returns a dictionary. In this example, we call {{cmd|g.proj}} to display the projection parameters of the actual location.
<source lang="python">
gscript.parse_command('g.proj', flags='g')
</source>

For comparison, below is the same example, but using the read_command() function.
<source lang="python">
gscript.read_command('g.proj', flags='g')
</source>

Certain modules require the text input be in a file or provided as standard input. Using the write_command() function we can conveniently pass the string to the module. Here, we are creating a new vector with one point with {{cmd|v.in.ascii}}. Note that ''stdin'' parameter is not used as a module parameter, but its content is passed as standard input to the subprocess.
<source lang="python">
gscript.write_command('v.in.ascii', input='-', stdin='%s|%s' % (635818, 221342), output='point')
</source>

If we run the Python commands from GUI Python console, we can use <tt>AddLayer</tt> to add the newly created layer:
<source lang="python">
AddLayer('point')
</source>

=== Convenient wrapper functions ===
Some modules have wrapper functions to simplify frequent tasks.
For example we can obtain the information about a raster layer with [https://grass.osgeo.org/grass70/manuals/libpython/script.html?highlight=mapcalc#script.raster.raster_info raster_info] which is a wrapper of {{cmd|r.info}},
or a vector layer with [https://grass.osgeo.org/grass70/manuals/libpython/script.html?script.vector.vector_info vector_info].
<source lang="python">
gscript.raster_info('elevation')
gscript.vector_info('point')
</source>

Another example is using [https://grass.osgeo.org/grass70/manuals/libpython/script.html?highlight=mapcalc#script.raster.mapcalc r.mapcalc wrapper] for raster algebra:
<source lang="python">
gscript.mapcalc("elev_strip = if(elevation > 100 && elevation < 125, elevation, null())")
gscript.read_command('r.univar', map='elev_strip', flags='g')
</source>

Function [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.region region] is a convenient way to retrieve the current region settings (i.e., computational region). It returns a dictionary with values converted to appropriate types (floats and ints).
<source lang="python">
region = gscript.region()
print region
# cell area in map units (in projected Locations)
region['nsres'] * region['ewres']
</source>

We can list data stored in a GRASS GIS location with {{cmd|g.list}} wrappers. With [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.list_grouped list_grouped], the map layers are grouped by mapsets (in this example, raster layers):
<source lang="python">
gscript.list_grouped(type=['raster'])
gscript.list_grouped(type=['raster'], pattern="landuse*")
</source>

Here is an example of a different {{cmd|g.list}} wrapper [https://grass.osgeo.org/grass70/manuals/libpython/script.html#script.core.list_pairs list_pairs] which structures the output as list of pairs (name, mapset). We obtain current mapset with {{cmd|g.gisenv}} wrapper.
<source lang="python">
current_mapset = gscript.gisenv()['MAPSET']
gscript.list_pairs('raster', mapset=current_mapset)
</source>

=== Exercise ===
Export all raster layers from your mapset with a name prefix "elev_*" as GeoTiff (see {{cmd|r.out.gdal}}). Don't forget to set the current region ({{cmd|g.region}}) for each map in order to match the individual exported raster layer extents and resolutions since they may differ from each other.

== PyGRASS ==
PyGRASS is a library originally developed during the Google Summer of Code 2012. PyGRASS library adds two main functionalities:
* Python interface through the ctypes binding of the C API of GRASS, to read and write natively GRASS GIS 7 data structures,
* GRASS GIS module interface using objects to check the parameters and execute the respective modules.
For further discussion about the implementation ideas and performance are presented in the article:
''[http://www.mdpi.com/2220-9964/2/1/201 Zambelli, P.; Gebbert, S.; Ciolli, M. Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS). ISPRS Int. J. Geo-Inf. 2013, 2, 201-219.]''

Standard scripting with GRASS modules in Python may sometime seem discouraging especially when you have to do conceptually simple things like: iterate over vector features or raster rows/columns.
Using the C API (most of GRASS GIS is written in C), all this is much more simple since you can directly work on GRASS GIS data and do just what you need to do.
However, you perhaps want to stick to Python. Here, the PyGRASS library introduced several objects that allow to interact directly with the data using the underlying C API of GRASS GIS.

=== Working with vector data (see [https://grass.osgeo.org/grass70/manuals/libpython/pygrass_vector.html manual page]) ===
Create a new vector map. Import the necessary classes:
<source lang="python">
from grass.pygrass.vector import VectorTopo
from grass.pygrass.vector.geometry import Point
</source>

Create an instance of a vector map:
<source lang="python">
my_points = VectorTopo('my_points')
</source>

Open the map in write mode:
<source lang="python">
my_points.open(mode='w')
</source>

Create some vector geometry features, like two points:
<source lang="python">
point1 = Point(635818.8, 221342.4)
point2 = Point(633627.7, 227050.2)
</source>

Add the above two points to the new vector map:
<source lang="python">
my_points.write(point1)
my_points.write(point2)
</source>

Finally close the vector map:
<source lang="python">
my_points.close()
</source>

Display the newly created vector (from GUI Python Shell):
<source lang="python">
AddLayer('my_points')
</source>

Now do the same thing using the context manager syntax and set also the attribute table:
<source lang="python">
# Define the columns of the new vector map
cols = [(u'cat', 'INTEGER PRIMARY KEY'),
(u'name', 'TEXT')]

with VectorTopo('my_points', mode='w', tab_cols=cols, overwrite=True) as my_points:
# save the point and the attribute
my_points.write(point1, ('pub', ))
my_points.write(point2, ('restaurant', ))
# save the changes to the database
my_points.table.conn.commit()
</source>
Note: we don't need to close the vector map because it is already closed by the context manager.

Go to Layer Manager, right click on 'my_points' and ''Show attribute data''.

Read an existing vector map:
<source lang="python">
with VectorTopo('my_points', mode='r') as points:
for point in points:
print(point, point.attrs['name'])
</source>

=== Working with raster data (see [https://grass.osgeo.org/grass70/manuals/libpython/pygrass_raster.html manual page]) ===
Create a new raster map and derive it's new values from <tt>elevation</tt> raster. Import the necessary classes:
<source lang="python">
from grass.pygrass.raster import RasterRow
</source>
Open the existing raster in read mode and print first 5 values of the first row (indices from S to N):
<source lang="python">
elev = RasterRow('elevation')
print elev.exist()
print elev.mapset
elev.open('r')
print elev[0][:5]
elev.close()
</source>

Create a new raster and write value 1 for cells with elevation < 120 and 0 otherwise:
<source lang="python">
new = RasterRow('new')
new.open('w', overwrite=True)
for row in elev:
new.put_row(row < 120)
new.close()
print new.exist()
</source>
Query old and new raster maps:
<source lang="python">
from grass.pygrass.vector import geometry

new.open('r')
elev.open('r')
poi1 = geometry.Point(632942, 225757)
poi2 = geometry.Point(641780, 217455)
print elev.get_value(poi1), new.get_value(poi1)
print elev.get_value(poi2), new.get_value(poi2)
new.close()
elev.close()
</source>

For more examples of using PyGRASS, please look at [https://github.com/wenzeslaus/python-grass-addon How to write a Python GRASS GIS 7 addon] workshop from FOSS4G-Europe 2015 and additional tutorials can be found [[Python/pygrass|on a PyGRASS wiki page]].

= Parallelization examples =
A simple way to execute several modules in parallel (developed by Sören Gebbert)
is the [https://grass.osgeo.org/grass71/manuals/libpython/pygrass.modules.interface.html?highlight=parallelmodulequeue#pygrass.modules.interface.module.ParallelModuleQueue ParallelModuleQueue class]. The basic idea is to create a queue with all the modules that must be execute in parallel. The ParallelModuleQueue class is based on the Module class of the pygrass library, here is a small example for computation of solar irradiance during day:
<source lang="python">
from copy import deepcopy
from grass.pygrass.modules import Module, ParallelModuleQueue

def main(elevation):
# compute slope and aspect for r.sun
Module('r.slope.aspect', elevation=elevation, aspect='aspect', slope='slope', overwrite=True)
# initialize an empty queue and list
queue = ParallelModuleQueue(nprocs=4)
sun_name = 'sun_{}'
# set computational region
Module('g.region', raster=elevation)
# initialize a module instance with shared inputs
sun = Module('r.sun', elevation=elevation, slope='slope', aspect='aspect',
beam_rad='beam', step=1, day=123, run_=False, overwrite=True)

for t in range(6, 22):
# create a copy of the module and set the remaining parameters
print t
m = deepcopy(sun)(beam_rad=sun_name.format(t), time=t)
queue.put(m)
queue.wait()

# set color table
Module('r.colors', map=[sun_name.format(t) for t in range(6, 22)], color='grey', flags='e')

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
main(elevation)
</source>

This simple parallel implementation uses Python class Pool:

<source lang="python">
from multiprocessing import Pool
import grass.script as gscript

def rsun(params):
gscript.run_command('r.sun', **params)

def main(elevation):
parameters = []
sun_name = 'sun_{}'
for t in range(6, 22):
params = dict(elevation=elevation, slope='slope', aspect='aspect',
step=1, day=123, beam_rad=sun_name.format(t), time=t, overwrite=True)
parameters.append(params)
pool = Pool(4)
p = pool.map_async(rsun, parameters)
p.get()

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
main(elevation)
</source>

This example shows parallelization by splitting computation into tiles using [https://grass.osgeo.org/grass71/manuals/libpython/pygrass.modules.grid.html?highlight=gridmodule#pygrass.modules.grid.grid.GridModule GridModule]:
<source lang="python">
import grass.script as gscript
from grass.pygrass.modules.grid import GridModule

def main(elevation):
region = gscript.region()
width = region['cols'] // 2 + 1
height = region['rows'] // 2 + 1

grd = GridModule('r.slope.aspect', elevation=elevation, slope='slope',
debug=False, width=width, height=height,
overlap=10, processes=4, overwrite=True)
grd.run()

if __name__ == '__main__':
elevation = 'elevation'
gscript.run_command('g.region', raster=elevation)
main(elevation)
</source>

= Tangible Landscape =
[[File:Tangible landscape setup.jpg|400px|thumbnail|right|Tangible Landscape setup]]

A brief introduction to Tangible Landscape: [http://baharmon.github.io/foss4g-na-2016-workshop/]

Tangible Landscape is a collaborative modeling environment for analysis of terrain changes.
We couple a scanner, projector and a physical 3D model with GRASS GIS.
We can analyze the impact of terrain changes by capturing the changes on the model,
bringing them into the GIS, performing desired analysis or simulation and projecting the results back on the model in real-time.
Tangible Landscape, as an easy-to-use 3D sketching tool, enables rapid design and scenarios testing for people with different backgrounds
and computer knowledge, as well as support for decision-making process.

Tangible Landscape has been used for a variety of applications supported by the extensive set of geospatial analysis and modeling tools available in GRASS GIS. We have explored how dune breaches affect the extent of coastal flooding, the impact of different building configurations on cast shadows and solar energy potential, and the effectiveness of various landscape designs for controlling runoff and erosion. Have a look at our [http://www.springer.com/us/book/9783319257730 book], [https://www.youtube.com/channel/UCc37pVh-WE46Xkqeq-KZQsA Youtube channel], and [https://plus.google.com/112857255995703553144/photos Google+ photos].

The software is free and open source and you can [https://github.com/ncsu-osgeorel/grass-tangible-landscape download it] and use it in your own setup of Tangible Landscape.

== Running examples ==
We will use a Titanpad to collect code samples from workshop participants and then run them in Tangible Landscape environment.
Whenever a scanning cycle is complete, a specified Python file is imported and all analyses in that file are computed.
Analyses are organized into functions with defined interface - each function has to start with <tt>run_</tt>.
Input parameter <tt>scanned_elev</tt> is the scanned raster (our DEM) and <tt>env</tt> is the environment which needs to be passed to individual subprocesses to correctly handle the region of the analysis.

Since participants will develop and test the analyses on their computers before we apply them to Tangible Landscape,
we add here the 'main' function with predefined parameters and participants will run it as a script.

<source lang="python">
import grass.script as gscript

def run_slope(scanned_elev, env, **kwargs):
# compute the analysis
gscript.run_command('r.slope.aspect', ..., env=env)

if __name__ == '__main__':
import os
os.environ['GRASS_OVERWRITE'] = '1'
elevation = 'elev_lid792_1m'
run_slope(scanned_elev=elevation, env=None)
</source>

Scripts can be run from terminal or GUI command console:
<pre>
python /path/to/my/script.py
</pre>

On Windows the path will look differently, for example:
<pre>
python C:\Users\yourname\path\to\my\script.py
</pre>

Make sure you set computational region to match your DEM. We will use raster DEM <tt>elev_lid792_1m</tt> from the sample dataset.
<pre>
g.region raster=elev_lid792_1m -p
</pre>

Here follow some basic examples of geospatial analyses we can do with Tangible Landscape.
At the end of this section you can find additional tasks, some of them combining multiple analyses.

== Modeling topography ==
=== Computing slope ===
[[File:tangible landscape slope.jpg|400px|thumbnail|right|Tangible Landscape: topographic slope]]
Basic example how we can compute topographic slope in degrees:
<source lang="python">
import grass.script as gscript

def run_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
env = None
run_slope(scanned_elev=elevation, env=env)
</source>

We can compute slope in percent and reclassify the values into discrete intervals:
<source lang="python">
def run_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope',
format='percent', env=env)
# reclassify using rules passed as a string to standard input
# 0:2:1 means reclassify interval 0 to 2 percent of slope to category 1
rules = ['0:2:1', '2:5:2', '5:8:3', '8:15:4', '15:30:5', '30:*:6']
gscript.write_command('r.recode', input='slope', output='slope_class',
rules='-', stdin='\n'.join(rules), env=env)
# set new color table: green - yellow - red
gscript.run_command('r.colors', map='slope_class', color='gyr', env=env)
</source>

=== Curvatures ===
Explore concavity/convexity of terrain with curvatures computed by {{cmd|r.param.scale}}:

<source lang="python">
def run_curvatures(scanned_elev, env, **kwargs):
gscript.run_command('r.param.scale', input=scanned_elev, output='profile_curv',
method='profc', size=11, env=env)
gscript.run_command('r.param.scale', input=scanned_elev, output='tangential_curv',
method='crosc', size=11, env=env)
gscript.run_command('r.colors', map=['profile_curv', 'tangential_curv'], color='curvature', env=env)
</source>
Change window size and see how it influences the result.

=== Landform identification ===
[[File:Tangible landscape geomorphons.jpg|400px|thumbnail|right|Tangible Landscape: Landforms computed with {{AddonCmd|r.geomorphon}}]]
There are 2 different methods for landform (ridge, valley, ...) identification in GRASS GIS.
First one is implemented in {{cmd|r.param.scale}} and uses curvatures.
The second is implemented in an addon {{AddonCmd|r.geomorphon}} which uses multiscale line-of-sight approach. This addon can be installed
from GUI command line:
<source lang="bash">
g.extension r.geomorphon
</source>
or follow
[https://grasswiki.osgeo.org/wiki/Introduction_to_GRASS_GIS_with_terrain_analysis_examples#Step_5:_Adding_the_r.geomorphon_Addon this tutorial].

<source lang="python">
def run_curvatures(scanned_elev, env, **kwargs):
gscript.run_command('r.param.scale', input=scanned_elev, output='landforms1',
method='feature', size=10, env=env)
gscript.run_command('r.geomorphon', dem=scanned_elev, forms='landforms2',
search=16, skip=6, env=env)
</source>

=== Building model based on difference raster ===
When building a model by hands based on a defined DEM, we can compute the difference between the scanned model and the original DEM.
By color-coding the difference, we can see where to add sand or remove it.

If you are running this outside of Tangible Landscape, you can generate a raster (our hypothetical pile of sand)
and compute the difference. In this example we also vertically rescale and translate the scanned raster to match
the original DEM using {{cmd|r.regression.line}}.
<source lang="python">
import grass.script as gscript

def run_difference(real_elev, scanned_elev, env, **kwargs):
regression_params = gscript.parse_command('r.regression.line', flags='g', mapx=scanned_elev, mapy=real_elev, env=env)
gscript.mapcalc('{regression} = {a} + {b} * {before}'.format(a=regression_params['a'], b=regression_params['b'],
before=scanned_elev, regression='regression'), env=env)
gscript.mapcalc('{difference} = {regression} - {after}'.format(regression='regression', after=real_elev, difference='diff'), env=env)
gscript.write_command('r.colors', map='diff', rules='-', stdin="-100 black\n-20 red\n0 white\n20 blue\n100 black", env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
sand_pile = 'sand_pile'
env = None
gscript.run_command('r.surf.fractal', output=sand_pile)
run_difference(real_elev=elevation, scanned_elev=sand_pile, env=env)
</source>

== Hydrology ==
=== Flooding with {{cmd|r.lake}} ===
[[File:tangible landscape rlake.jpg|200px|thumbnail|right|Example of simple flooding simulation with Tangible Landscape and {{cmd|r.lake}} module.]]

Module {{cmd|r.lake}} fills a lake to a target water level from a given start point or seed raster.
The resulting raster map contains cells with values representing lake depth and NULL for all other cells beyond the lake.

Example showing basic usage:
<source lang="python">
def run_lake(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
gscript.run_command('r.lake', elevation=scanned_elev, lake='output_lake',
coordinates=coordinates, water_level=120, env=env)
</source>

Create a lake where water level is relative to the altitude of the seed cell. Use function [https://grass.osgeo.org/grass70/manuals/libpython/script.html?script.raster.raster_what raster_what] to obtain the elevation value of the DEM and create a lake with water level being for example 5 m higher.

<source lang="python">
def run_lake(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
res = gscript.raster_what(map=scanned_elev, coord=[coordinates])
elev_value = float(res[0][scanned_elev]['value'])
gscript.run_command('r.lake', elevation=scanned_elev, lake='output_lake',
coordinates=coordinates, water_level=elev_value + 5, env=env)
</source>


=== Flow accumulation and watersheds ===
We can derive watersheds and flow accumulation using module {{cmd|r.watershed}} in one command:
<source lang="python">
def run_hydro(scanned_elev, env, **kwargs):
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum',
basin='watersheds', threshold=1000, flags='a', env=env)
</source>

Compute average slope value for each watershed. To do that use zonal statistics using {{cmd|r.stats.zonal}}:
<source lang="python">
def run_watershed_slope(scanned_elev, env, **kwargs):
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum',
basin='watersheds', threshold=1000, env=env)
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)
gscript.run_command('r.stats.zonal', base='watersheds', cover='slope', method='average',
output='watersheds_slope', env=env)
gscript.run_command('r.colors', map='watersheds_slope', color='bgyr', env=env)
</source>

=== Depression filling ===
[[File:tangible_landscape_r_fill_dir.jpg|400px|thumbnail|right|Tangible Landscape: example of using {{cmd|r.fill.dir}} to create ponds]]
We will use depression filling algorithm implemented in {{cmd|r.fill.dir}} not as preprocessing step for flow accumulation analysis, but for creating ponds.
Because depressions are often nested, we will run depression filling several times:
<source lang="python">
def run_ponds(scanned_elev, env, **kwargs):
repeat = 2
input_dem = scanned_elev
output = "tmp_filldir"
for i in range(repeat):
gscript.run_command('r.fill.dir', input=input_dem, output=output, direction="tmp_dir", env=env)
input_dem = output
# filter depression deeper than 0.1 m to
gscript.mapcalc('{new} = if({out} - {scan} > 0.1, {out} - {scan}, null())'.format(new='ponds', out=output,
scan=scanned_elev), env=env)
gscript.write_command('r.colors', map='ponds', rules='-', stdin='0% aqua\n100% blue', env=env)
</source>

=== Overland water flow simulation ===
Module {{cmd|r.sim.water}} is an overland flow hydrology simulation using path sampling method.
<source lang="python">
def run_waterflow(scanned_elev, env, **kwargs):
# first we need to compute x- and y-derivatives
gscript.run_command('r.slope.aspect', elevation=scanned_elev, dx='scan_dx', dy='scan_dy', env=env)
gscript.run_command('r.sim.water', elevation=scanned_elev, dx='scan_dx', dy='scan_dy',
rain_value=150, depth='flow', env=env)
</source>

=== Erosion modeling ===
Landscape potential for soil erosion and deposition can be estimated and mapped using Unit Stream Power Based Erosion Deposition model (USPED). In this example we will use uniform land cover (c factor) and soil erodibility (K factor). Install addon {{AddonCmd|r.divergence}} using {{cmd|g.extension}}.
<source lang="python">
def run_usped(scanned_elev, env, **kwargs):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.watershed', elevation=scanned_elev, accumulation='flow_accum', threshold=1000, flags='a', env=env)
# topographic sediment transport factor
resolution = gscript.region()['nsres']
gscript.mapcalc("sflowtopo = pow(flow_accum * {res}.,1.3) * pow(sin(slope),1.2)".format(res=resolution), env=env)
# compute sediment flow by combining the rainfall, soil and land cover factors with the topographic sediment transport factor. We use a constant value of 270 for rainfall intensity factor
gscript.mapcalc("sedflow = 270. * {k_factor} * {c_factor} * sflowtopo".format(c_factor=0.05, k_factor=0.1), env=env)
# compute divergence of sediment flow
gscript.run_command('r.divergence', magnitude='sedflow', direction='aspect', output='erosion_deposition', env=env)
colors = ['0% 100:0:100', '-100 magenta', '-10 red', '-1 orange', '-0.1 yellow', '0 200:255:200',
'0.1 cyan', '1 aqua', '10 blue', '100 0:0:100', '100% black']
gscript.write_command('r.colors', map='erosion_deposition', rules='-', stdin='\n'.join(colors), env=env)
</source>

== Solar radiation and shades ==
We will first compute solar irradiation (daily radiation sum in Wh/m2.day) for a given day using {{cmd|r.sun}}:
<source lang="python">
def run_solar_radiation(scanned_elev, env, **kwargs):
# convert date to day of year
import datetime
doy = datetime.datetime(2016, 5, 2).timetuple().tm_yday
# precompute slope and aspect
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.sun', elevation=scanned_elev, slope='slope', aspect='aspect', beam_rad='beam', step=1, day=doy, env=env)
gscript.run_command('r.colors', map='beam', color='grey', flags='e')
</source>

Then we can also compute solar irradiance (W/m2) for a given day and hour (in local solar time) and extract the shades cast by topography:
<source lang="python">
def run_solar_radiance(scanned_elev, env, **kwargs):
# convert date to day of year
import datetime
doy = datetime.datetime(2016, 5, 2).timetuple().tm_yday
# precompute slope and aspect
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', aspect='aspect', env=env)
gscript.run_command('r.sun', elevation=scanned_elev, slope='slope', aspect='aspect', beam_rad='beam', day=doy, time=8, env=env)
# extract shade and set color to black and white
gscript.mapcalc("shade = if(beam == 0, 0, 1)", env=env)
gscript.run_command('r.colors', map='beam', color='grey')
</source>

== Visibility analysis ==
First example shows computing viewshed (visibility) from a given coordinate:
<source lang="python">
def run_viewshed(scanned_elev, env, **kwargs):
coordinates = [638830, 220150]
gscript.run_command('r.viewshed', input=scanned_elev, output='viewshed', coordinates=coordinates, observer_elevation=1.75, flags='b', env=env)
gscript.run_command('r.colors', map='viewshed', color='grey')
</source>
== Cost surface and least cost path ==
[[File:least_cost_path.jpg|400px|thumbnail|right|Least cost path example where cost is slope]]
This example shows least cost path analysis with slope as cost. Coordinates will be provided by Tangible Landscape.
The resulting path will go through flat areas.

<source lang="python">
import grass.script as gscript
def LCP(elevation, start_coordinate, end_coordinate, env):
gscript.run_command('r.slope.aspect', elevation=scanned_elev, slope='slope', env=env)
gscript.run_command('r.cost', input='slope', output='cost', start_coordinates=start_coordinate,
outdir='outdir', flags='k', env=env)
gscript.run_command('r.colors', map='cost', color='gyr', env=env)
gscript.run_command('r.drain', input='cost', output='drain', direction='outdir',
drain='drain', flags='d', start_coordinates=end_coordinate, env=env)

if __name__ == '__main__':
elevation = 'elev_lid792_1m'
env = None
start = [638469, 220070]
end = [638928, 220472]
LCP(elevation, start, end, env)
</source>

== Additional tasks ==
# Compute topographic index using {{cmd|r.topidx}}.
# Compute topographic aspect (slope orientation) using {{cmd|r.slope.aspect}} and reclassify it into 8 main directions.
# Show areas with concave profile and tangential curvature (concave forms have negative curvature).
# Derive peaks using either {{AddonCmd|r.geomorphon}} or {{cmd|r.param.scale}} and convert them to points (using {{cmd|r.to.vect}} and {{cmd|v.to.points}}). From each of those points compute visibility with observer height of your choice a derive a cumulative viewshed layer where the value of each cell represents the number of peaks the cell is visible from (use {{cmd|r.series}}).
# Find a least cost path between 2 points (for example from x=638360, y=220030 to x=638888, y=220388) where cost is defined as topographic index (trying avoid areas). Use {{cmd|r.topidx}}.
# Compute erosion with spatially variable landcover and soil erodibility (use rasters <tt>cfactorbare_1m</tt> and <tt>soils_Kfactor</tt> from the provided dataset). Reclassify the result into 7 classes based on severity of erosion and deposition:
<pre>-120000.:-10:1:1
-10.:-5.:2:2
-5.:-0.1:3:3
-0.1:0.1:4:4
0.1:5.:5:5
5.:10.:6:6
10.:150000.:7:7
</pre>

[[Category: Tutorial]]
[[Category: Workshops]]
[[Category: Python]]
[[Category: 2016]]

FOSS4G NA 2016: GRASS related workshops and presentations

2016-04-28T18:50:37Z

⚠️Baharmon:

[[File:Tangible landscape termite game.jpg|300px|thumb|right|Playing termites game during Coffee and Viz in NC State Hunt library (''Tangible interaction for GIS and Using GRASS GIS through Python and tangible interfaces'')]]

[[File:Simple python editor v buffer.png|300px|thumb|right|Python interactive console and simple editor are one option how to interact with GRASS GIS (at the figure) the other is to touch it (''Using GRASS GIS through Python and tangible interfaces'')]]

FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016, https://2016.foss4g-na.org/

List of sessions labeled GRASS GIS: https://2016.foss4g-na.org/session/grass-gis

There is also a Code Sprint and Unconference and GRASS GIS developers and users will be there.

== Workshops ==

* Anna Petrasova, Vaclav Petras, Brendan Harmon, Helena Mitasova (2016): ''[https://2016.foss4g-na.org/session/using-grass-gis-through-python-and-tangible-interfaces Using GRASS GIS through Python and tangible interfaces]'', FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Come and learn about scripting, graphical and tangible (!) interfaces for GRASS GIS, the powerful desktop GIS and geoprocessing backend. We will start with the Python interface and finish with Tangible Landscape, a new tangible interface for GRASS GIS. Python is the primary scripting language for GRASS GIS. We will demonstrate how to use Python to automate your geoprocessing workflows with GRASS GIS modules and develop custom algorithms using a Pythonic interface to access low level GRASS GIS library functions. We will also review several tips and tricks for parallelization. Tangible Landscape is an example of how the GRASS GIS Python API can be used to build new, cutting edge tools and advanced applications. Tangible Landscape is a collaborative 3D sketching tool which couples a 3D scanner, a projector and a physical 3D model with GRASS GIS. The workshop will be a truly hands-on experience – you will play with Tangible Landscape, using your hands to shape a sand model and drive geospatial processes. This workshop is open to beginners. There will be opportunities, however, to discuss more advanced topics tailored to individual interests in breakout sessions during the workshop. Participants should bring laptops with GRASS GIS 7 and their favorite Python editor. Beginners may consider using the latest OSGeo-Live virtual machine.
** Website: https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html
** Workshop material: [[Using GRASS GIS through Python and tangible interfaces (workshop at FOSS4G NA 2016)|Using GRASS GIS through Python and tangible interfaces]]

== Presentations ==

[[File:Range on ground from north.png|300px|thumb|right|Range of z coordinates displayed on ground (''GRASS GIS loves lidar'')]]
[[File:Jeziorska uav grass puddle mar 18.png|300px|thumb|right|Comparison of simulated surface water flow and puddle in orthophoto (''Open the classroom window for... DRONES!'')]]

* Brendan Harmon, Anna Petrasova, Vaclav Petras (2016): ''[https://2016.foss4g-na.org/session/tangible-interaction-gis Tangible interaction for GIS]'', Full talk in Other Cool Stuff track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Imagine being able to hold a GIS in your hands, feeling the shape of the earth, sculpting its topography, and directing the flow of water. We present Tangible Landscape, an open source tangible interface powered by GRASS GIS. Tangible Landscape physically, interactively manifests geospatial data so that you can naturally feel it, see it, and shape it. This makes GIS far more intuitive and accessible for beginners, empowers geospatial experts, and creates new exciting opportunities for developers - like gaming with GIS. In this talk we will introduce tangible interaction and why it matters for all things spatial, demonstrate a few applications such as disaster management and gaming, discuss how to digitally fabricate models, and show you how to implement and build your own system.
** Slides: http://baharmon.github.io/foss4g-na-2016/
** Website: https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html
* Vaclav Petras, Anna Petrasova, Helena Mitasova (2016): ''[https://2016.foss4g-na.org/session/grass-gis-loves-lidar GRASS GIS loves lidar]'', Full talk in Using FOSS4G track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Lidar and UAV measurements produce huge point clouds which cannot be handled by classic GIS tools. Not true! New GRASS GIS version offers several tools which are specifically designed for processing of lidar data and point clouds in general. Lidar devices and structure from motion (SfM) processing of UAV imagery are generating large and dense points clouds which are hard to handle as classic GIS vectors. Fortunately, GRASS GIS, a powerful desktop and backend GIS, has a selection of tools which can handle this kind of data. For example, various point cloud decimations are useful as a pre-processing step before interpolation. However, the most significant group of provided analyses uses 2D and 3D binning for highly efficient digital terrain model creation and also for various vegetation and surface analyses. Additionally, we will explore old and new ground classification techniques in GRASS GIS and which analyses PDAL has to offer in connection with GRASS GIS. In this talk we will also look at point clouds from small scanners, namely Kinect, and how these can be processed in GRASS GIS in combination with PCL to couple digital elevation models with scaled physical models. The tools available in GRASS GIS can be used through a graphical user interface or in Bash and Python scripts which can accommodate individual user workflows as well as specific developer needs. We will see how these relate and how to take advantage of all of them.
** Slides: http://wenzeslaus.github.io/grass-lidar-talks/
** Related modules: {{cmd|v.in.lidar}}, {{cmd|r.in.lidar}}, {{cmd|version=71|v.decimate}}, {{cmd|v.lidar.edgedetection}}, {{AddonCmd|v.lidar.mcc}}, ...
* Justyna Jeziorska, Helena Mitasova, Anna Petrasova, Vaclav Petras, Brendan Harmon (2016): ''[https://2016.foss4g-na.org/session/open-classroom-window-drones Open the classroom window for... DRONES!]'', Short talk in Education and Research track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Drones have recently moved from the battlefields to our backyards. Their use is exploding across the U.S. and the rest of the world. Engineers, photographers, journalists, surveyors, researchers and… Amazon, all speak with one voice: drones are here to stay. How does the open source software handle this attack? Can they win the battle with the proprietary solutions for geoprocessing the data from Unmanned Aerial Vehicles? We faced the problem designing innovative graduate level course “Spatiotemporal Analysis with UAV and LiDAR Data” at NC State. In this talk we will present our findings and the results of the processing combining proprietary and open source photogrammetric and GIS solutions. Turning photo imagery into very high resolution digital terrain models (couple cm/pix) gave us opportunity took the investigation various spatial phenomena on a new level. What challenges needed to be overcame for the open source to reach this level? We take our data to OpenDroneMap and Grass GIS, but why do we use proprietary software in some stages of the processing? Those are only some of the problems that we will tackle in this talk.

== Community sprint ==

We are meeting at the FOSS4G NA Code Sprint and Unconference on May 6 and May 7. See the dedicated [[GRASS GIS Raleigh meetups 2016|Raleigh meetups]] page for details.

[[Category: Workshops]]
[[Category: Conferences]]
[[Category: 2016]]

FOSS4G NA 2016: GRASS related workshops and presentations

2016-04-28T15:38:23Z

⚠️Baharmon: /* Presentations */

[[File:Tangible landscape termite game.jpg|300px|thumb|right|Playing termites game during Coffee and Viz in NC State Hunt library (''Tangible interaction for GIS and Using GRASS GIS through Python and tangible interfaces'')]]

[[File:Simple python editor v buffer.png|300px|thumb|right|Python interactive console and simple editor are one option how to interact with GRASS GIS (at the figure) the other is to touch it (''Using GRASS GIS through Python and tangible interfaces'')]]

FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016, https://2016.foss4g-na.org/

List of sessions labeled GRASS GIS: https://2016.foss4g-na.org/session/grass-gis

There is also a Code Sprint and Unconference and GRASS GIS developers and users will be there.

== Workshops ==

* Anna Petrasova, Vaclav Petras, Brendan Harmon, Helena Mitasova (2016): ''[https://2016.foss4g-na.org/session/using-grass-gis-through-python-and-tangible-interfaces Using GRASS GIS through Python and tangible interfaces]'', US-IALE 2016 Annual Meeting, April 3, 2016, Asheville, NC, USA, Full-day workshop
** Description: Come and learn about scripting, graphical and tangible (!) interfaces for GRASS GIS, the powerful desktop GIS and geoprocessing backend. We will start with the Python interface and finish with Tangible Landscape, a new tangible interface for GRASS GIS. Python is the primary scripting language for GRASS GIS. We will demonstrate how to use Python to automate your geoprocessing workflows with GRASS GIS modules and develop custom algorithms using a Pythonic interface to access low level GRASS GIS library functions. We will also review several tips and tricks for parallelization. Tangible Landscape is an example of how the GRASS GIS Python API can be used to build new, cutting edge tools and advanced applications. Tangible Landscape is a collaborative 3D sketching tool which couples a 3D scanner, a projector and a physical 3D model with GRASS GIS. The workshop will be a truly hands-on experience – you will play with Tangible Landscape, using your hands to shape a sand model and drive geospatial processes. This workshop is open to beginners. There will be opportunities, however, to discuss more advanced topics tailored to individual interests in breakout sessions during the workshop. Participants should bring laptops with GRASS GIS 7 and their favorite Python editor. Beginners may consider using the latest OSGeo-Live virtual machine.
** Website: https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html
** Workshop material: [[Using GRASS GIS through Python and tangible interfaces (workshop at FOSS4G NA 2016)|Using GRASS GIS through Python and tangible interfaces]]

== Presentations ==

[[File:Range on ground from north.png|300px|thumb|right|Range of z coordinates displayed on ground (''GRASS GIS loves lidar'')]]
[[File:Jeziorska uav grass puddle mar 18.png|300px|thumb|right|Comparison of simulated surface water flow and puddle in orthophoto (''Open the classroom window for... DRONES!'')]]

* Brendan Harmon, Anna Petrasova, Vaclav Petras (2016): ''[https://2016.foss4g-na.org/session/tangible-interaction-gis Tangible interaction for GIS]'', Full talk in Other Cool Stuff track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Imagine being able to hold a GIS in your hands, feeling the shape of the earth, sculpting its topography, and directing the flow of water. We present Tangible Landscape, an open source tangible interface powered by GRASS GIS. Tangible Landscape physically, interactively manifests geospatial data so that you can naturally feel it, see it, and shape it. This makes GIS far more intuitive and accessible for beginners, empowers geospatial experts, and creates new exciting opportunities for developers - like gaming with GIS. In this talk we will introduce tangible interaction and why it matters for all things spatial, demonstrate a few applications such as disaster management and gaming, discuss how to digitally fabricate models, and show you how to implement and build your own system.
** Slides: http://baharmon.github.io/foss4g-na-2016/
** Website: https://geospatial.ncsu.edu/osgeorel/tangible-landscape.html
* Vaclav Petras, Anna Petrasova, Helena Mitasova (2016): ''[https://2016.foss4g-na.org/session/grass-gis-loves-lidar GRASS GIS loves lidar]'', Full talk in Using FOSS4G track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Lidar and UAV measurements produce huge point clouds which cannot be handled by classic GIS tools. Not true! New GRASS GIS version offers several tools which are specifically designed for processing of lidar data and point clouds in general. Lidar devices and structure from motion (SfM) processing of UAV imagery are generating large and dense points clouds which are hard to handle as classic GIS vectors. Fortunately, GRASS GIS, a powerful desktop and backend GIS, has a selection of tools which can handle this kind of data. For example, various point cloud decimations are useful as a pre-processing step before interpolation. However, the most significant group of provided analyses uses 2D and 3D binning for highly efficient digital terrain model creation and also for various vegetation and surface analyses. Additionally, we will explore old and new ground classification techniques in GRASS GIS and which analyses PDAL has to offer in connection with GRASS GIS. In this talk we will also look at point clouds from small scanners, namely Kinect, and how these can be processed in GRASS GIS in combination with PCL to couple digital elevation models with scaled physical models. The tools available in GRASS GIS can be used through a graphical user interface or in Bash and Python scripts which can accommodate individual user workflows as well as specific developer needs. We will see how these relate and how to take advantage of all of them.
** Slides: http://wenzeslaus.github.io/grass-lidar-talks/
** Related modules: {{cmd|v.in.lidar}}, {{cmd|r.in.lidar}}, {{cmd|version=71|v.decimate}}, {{cmd|v.lidar.edgedetection}}, {{AddonCmd|v.lidar.mcc}}, ...
* Justyna Jeziorska, Helena Mitasova, Anna Petrasova, Vaclav Petras, Brendan Harmon (2016): ''[https://2016.foss4g-na.org/session/open-classroom-window-drones Open the classroom window for... DRONES!]'', Short talk in Education and Research track, FOSS4G North America 2016, Raleigh, NC, USA, May 2-5, 2016
** Description: Drones have recently moved from the battlefields to our backyards. Their use is exploding across the U.S. and the rest of the world. Engineers, photographers, journalists, surveyors, researchers and… Amazon, all speak with one voice: drones are here to stay. How does the open source software handle this attack? Can they win the battle with the proprietary solutions for geoprocessing the data from Unmanned Aerial Vehicles? We faced the problem designing innovative graduate level course “Spatiotemporal Analysis with UAV and LiDAR Data” at NC State. In this talk we will present our findings and the results of the processing combining proprietary and open source photogrammetric and GIS solutions. Turning photo imagery into very high resolution digital terrain models (couple cm/pix) gave us opportunity took the investigation various spatial phenomena on a new level. What challenges needed to be overcame for the open source to reach this level? We take our data to OpenDroneMap and Grass GIS, but why do we use proprietary software in some stages of the processing? Those are only some of the problems that we will tackle in this talk.

== Community sprint ==

We are meeting at the FOSS4G NA Code Sprint and Unconference on May 6 and May 7. See the dedicated [[GRASS GIS Raleigh meetups 2016|Raleigh meetups]] page for details.

[[Category: Workshops]]
[[Category: Conferences]]
[[Category: 2016]]

GRASS GIS Raleigh meetups 2016

2016-04-21T14:35:01Z

⚠️Baharmon:

GRASS GIS Raleigh meetups 2016

2016-02-28T14:00:25Z

⚠️Baharmon:

GRASS GIS Raleigh meetups 2016

2016-01-29T20:01:55Z

⚠️Baharmon: Added name

A group of people contributing or interested in contributing to GRASS GIS met [[Christmas GRASS GIS potential contributors meeting in Raleigh|at the end of 2015 in Raleigh]] and decided to meet regularly in the following months. This is a page to organize meetings and record what was done or discussed during them

Contact person: [[User:Wenzeslaus|Vaclav Petras (Vashek, wenzeslaus gmail com)]]

== January 30 ==

* date: January 30 (moved from January 23 because of the weather)
* time: 1:00pm - 6:30pm (feel free to come and leave anytime)
* place: Hunt (see [[#Location|below]])
* food: your own supplies, [http://dining.ncsu.edu/locations/restaurants-cafes/hunt-library/ Common Grounds Café] at Hunt (closes at 5pm), [http://dining.ncsu.edu/locations/restaurants-cafes/on-the-oval/ On The Oval] (closes at 8pm)
* room: 3208 (Large Group Study Room; close to the Game Lab and the wide yellow stairs; note that the elevator from the 1st floor will take you just to the 2nd floor, use the stairs if you can)
* coming:
** Vaclav Petras
** Anna Petrasova
** Doug Newcomb
** Brendan Harmon

== Location ==

[[Image:Hunt 2015 2.jpg|thumb|400px]]

* Raleigh, North Carolina, USA
* Centennial Campus of North Carolina State University
* [https://www.lib.ncsu.edu/huntlibrary James B. Hunt Jr. Library], 1070 Partners Way, Raleigh, NC 27606 ([http://www.openstreetmap.org/way/177166351 map])
** [https://www.lib.ncsu.edu/huntlibrary/explorespaces Floor plan] (note that building is vertically split into two sections (library and another partially private space) and that the floor with the main desk and access to Oval is 2nd floor)
** Info about [https://www.lib.ncsu.edu/spaces/group-study-rooms-large Group Study Rooms - Large]
* free parking on Saturdays: Oval West Parking Deck, Partners Way ([https://www.openstreetmap.org/way/164125158 map])



[[Category: Workshops]]
[[Category: Code Sprint]]

Christmas GRASS GIS potential contributors meeting in Raleigh

2015-12-30T22:29:09Z

⚠️Baharmon:

[[Image:Hunt fishbowl 2015 1.jpg|thumb|400px]]
[[Image:Hunt 2015 2.jpg|thumb|400px]]

A group of people contributing or interested in contributing to GRASS GIS met on December 19, 2015 at the Hunt library, which is a quite inspiring place located on NC State University Centennial campus.

Contact person: [[User:Wenzeslaus|Vaclav Petras (Vashek)]]

== Discussed topics ==

* How tickets work, example: [https://trac.osgeo.org/grass/ticket/2750 #2750]
* [https://github.com/wenzeslaus/python-grass-addon/blob/master/04_script_to_grass_module.ipynb Writing a GRASS module]
** [https://trac.osgeo.org/grass/browser/grass/trunk/scripts/r.shade Example Python module (r.shade)]
** [https://trac.osgeo.org/grass/browser/grass/trunk/raster/r.patch Example C module (r.patch)]
* [http://gis.stackexchange.com/questions/172162/grass-gis-number-of-cpu-cores-to-use/173555#173555 Parallelizing (GIS SE)], [[Parallelizing Scripts]], [[Parallel GRASS jobs]], [[OpenMP]]
* [https://grass.osgeo.org/support/mailing-lists/ Mailing list]
* [https://grass.osgeo.org/documentation/manuals/ Manuals]
* Review and testing
** Continuous integration (builds) on [https://travis-ci.org/GRASS-GIS/grass-ci/builds Travis]
** Automated testing ([http://fatra.cnr.ncsu.edu/grassgistests/ results on NCSU server fatra], [http://fatra.cnr.ncsu.edu/grassgistests/reports_for_date-2015-12-19-08-00/report_for_nc_basic_spm_grass7_nc/testfiles.html example result for one day], [https://grass.osgeo.org/grass71/manuals/libpython/gunittest_testing.html documenation])
*** [https://trac.osgeo.org/grass/changeset/65145 example test contribution]
** [https://trac.osgeo.org/grass/timeline GRASS GIS Trac Timeline]
** Example of file history: wxGUI mapcalc [https://trac.osgeo.org/grass/log/grass/trunk/gui/wxpython/modules/mcalc_builder.py change log] and [https://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/modules/mcalc_builder.py?annotate=blame authorship per line]
** [https://www.openhub.net/p/grass_gis Open Hub statistics]
* GRASS GIS Database with maps in native format versus linked files, e.g. using [https://grass.osgeo.org/grass71/manuals/r.external.html r.external]
* [https://grass.osgeo.org/download/logos/ Logo resources]
* Installation versus compilation on Ubuntu
** [https://grass.osgeo.org/download/software/linux/ installation from PPA]
* Suggestion for starting with C development
** fix [https://grass.osgeo.org/grass71/manuals/r.cross.html r.cross] problems when overlaying layers with no-data [https://trac.osgeo.org/grass/ticket/1674 #1674]
** fix [https://trac.osgeo.org/grass/ticket/2310 #2310]
** Some modules are setting color tables which are the same as the predefined ones available through r.colors but these modules have the values hardcoded, thus causing duplication (e.g. [https://trac.osgeo.org/grass/browser/grass/trunk/lib/rst/interp_float/output2d.c#L214 v.surf.rst in lib/rst] and [https://trac.osgeo.org/grass/browser/grass/trunk/raster/r.slope.aspect/main.c#L1054 r.slope.aspect]). Solution is to move the code for creating color tables from the r.color module to the library.

== Participants ==

* Vaclav Petras (Vashek)
* Anna Petrasova
* Michael Reno
* Makiko Shukunobe
* Brendan Harmon
* and 2 others

== Location ==

[[Image:Hunt 2015 1.jpg|thumb|200px]]

* Raleigh, North Carolina, USA
* [https://www.lib.ncsu.edu/huntlibrary James B. Hunt Jr. Library], 1070 Partners Way, Raleigh, NC 27606 ([http://www.openstreetmap.org/way/177166351 map])
* free parking (Saturdays): Oval West Parking Deck, Partners Way ([https://www.openstreetmap.org/way/164125158 map])

== Press release ==

''Prepared upon request from the [http://www.geoforall.org/newsletters/ GeoForAll Newsletter] (international audience).''

The local GRASS GIS community in Raleigh, North Carolina, USA is pleased to announce a successful meeting, held on Saturday December 19, 2015, dedicated to learning about how to contribute to GRASS GIS. The meeting took place at the inspiring James B. Hunt Jr. Library at the North Carolina State University Centennial Campus. Though it is true that a libre and open source project such as GRASS GIS necessitates many types of non-coding contributions, including documentation and tests, this event focused on describing the tools and processes associated with making contributions to the codebase itself. Bug fixes and enhancements, both in C and Python, were generally considered. These themes and others will continue to be discussed at the first follow up meeting of 2016, planned for late January.

== Photos ==

[[Image:Hunt fishbowl 2015 3.jpg|center|thumb|400px]]
[[Image:Hunt fishbowl 2015 2.jpg|center|thumb|400px]]

For higher resolution images contact [[User:Wenzeslaus|Vaclav Petras]].

[[Category: Workshops]]
[[Category: Code Sprint]]