GRASS-Wiki - User contributions [en]

Working with GRASS without starting it explicitly

2018-04-03T13:26:37Z

⚠️Pietro: Add ctypes examples using grass-session

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

== GRASS sessions ==

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

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

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

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

=== Batch jobs ===

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

See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.

=== Starting a GRASS session and terminating it automatically ===

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

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

Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:
<source lang="bash">
grass72 -c elevation.tiff -e /path/to/grassdata/test1/
</source>

Linking external raster data to PERMANENT Mapset:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=basins.tiff output=basins
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=elevation.tiff output=elevation
</source>

Get statistics for one raster map:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.univar map=elevation
</source>

==== Start a GRASS session but do not terminate it automatically ====

Compare the rasters visually:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
</source>

Read more in the [https://grass.osgeo.org/grass72/manuals/grass7.html#batch-jobs-with-the-exec-interface manual].

==== Python examples ====

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

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

The [https://github.com/zarch/grass-session "grass-session" Python library] is under development. To contribute at the code, documentation and testing it is possible to install the current version with:

<source lang="bash">
pip install grass-session
# for the latest development version use:
# pip install git+https://github.com/zarch/grass-session.git
</source>

Then write
<source lang="python">
#!/usr/bin/env python
# filename: test_session.py

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

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

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

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

<source lang="bash">
GRASSBIN=$HOME/bin/grass75 python test_session.py
</source>

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

<source lang="python">
# file: test_session_ctypes.py
import grass_session
from grass.pygrass.vector import VectorTopo

print('DONE!')
</source>

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

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

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

<source lang="bash">
$ LD_LIBRARY_PATH=/home/pietro/.local/grass-7.5.svn/lib \
GRASSBIN=/home/pietro/.local/bin/grass75 \
python test_session_ctypes.py
GRASSBIN: /home/pietro/.local/bin/grass75
GISBASE: /home/pietro/.local/grass-7.5.svn
DONE!
</source>

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

<source lang="bash">
import os

# import grass_session
from grass_session import Session

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

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

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

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

# exit from PERMANENT
PERMANENT.close()

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

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

# exit from user
user.close()
</source>

===== Hint: find the path to the GRASS GIS package start script =====

Hint: in order to find the '''path to the GRASS GIS package''', launch it with <tt> --config path</tt>:

<source lang="bash">
# Linux
grass72 --config path
/usr/bin/grass-7.2.0

# Windows
C:\>grass72.bat --config path
C:\OSGeo4W\apps\grass\grass-7.2
</source>

===== Python: GRASS GIS 7 with existing location =====

See the example in the [https://grass.osgeo.org/grass72/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:

<source lang="python">
#!/usr/bin/env python

import os
import sys
import subprocess

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

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

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

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

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

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

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

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

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

# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script.setup as gsetup

###########
# launch session
gsetup.init(gisbase,
gisdb, location, mapset)

gscript.message('Current GRASS GIS 7 environment:')
print gscript.gisenv()

gscript.message('Available raster maps:')
for rast in gscript.list_strings(type = 'rast'):
print rast

gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
print vect
</source>

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

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

<source lang=python>
#!/usr/bin/env python

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

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

# some predefined variables

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

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

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

startcmd = grass7bin + ' --config path'

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

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

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

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

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

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

# Now the location with PERMANENT mapset exists.

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

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

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

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

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

#print os.environ

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

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

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

# do something in GRASS now...

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

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

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

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

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

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

sys.exit(0)
</source>

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

'''''Note: see [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]] for a really easy approach.'''''

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

<source lang=bash>
export GISBASE=/usr/local/grass-7.2.svn
export GRASS_VERSION="7.2.svn"

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

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

echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
echo "GRASS_GUI: text" >> "$MYGISRC"

# path to GRASS settings file
export GISRC=$MYGISRC
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=plain
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat

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

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

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

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

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

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

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

######### END below not needed ########
</source>

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

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

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

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

=== Important notes ===

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

<source lang="bash">
strippath()
{
(
oldpath="$1"
newpath=
IFS=:
for dir in $oldpath ; do
case "${dir}" in
*grass*)
;;
*)
newpath="$newpath:$dir"
;;
esac
done
echo "${newpath#:}"
)
}

PATH=`strippath $PATH`

export GISBASE=$PWD/dist.i686-pc-linux-gnu
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export PYTHONPATH="$GISBASE/etc/python"
</source>

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

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

=== Hints and troubleshooting ===

Some hints for MS Windows users:

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

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

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

export GIS_LOCK=$$

in Bash.

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

== GRASS databases ==

(project file structure)

=== Minimal mapsets ===

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

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

=== Minimal locations ===

Within the GISDATABASE (which is simply a subdirectory some where), the minimum LOCATION consists of a directory giving the LOCATION its name, which in turn contains a PERMANENT subdirectory for the PERMANENT mapset. The PERMANENT mapset contains a few special files that regular mapsets don't. These are:
; PROJ_INFO: contains the location's projection information
; PROJ_UNITS: contains the location's map units definition
; DEFAULT_WIND: the default region (WINDow file). The format is identical to the WIND files created by g.region
; WIND: (optional?)

* see also {{src|demolocation}} in the GRASS source code

== See also ==
* [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]]

[[Category: FAQ]]
[[Category: Linking to other languages]]
[[Category: bash]]
[[Category:Scripting]]
[[Category: Python]]

Working with GRASS without starting it explicitly

2018-03-23T14:07:37Z

⚠️Pietro: /* Python: GRASS GIS 7 with an external library: grass-session */

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

== GRASS sessions ==

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

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

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

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

=== Batch jobs ===

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

See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.

=== Starting a GRASS session and terminating it automatically ===

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

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

Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:
<source lang="bash">
grass72 -c elevation.tiff -e /path/to/grassdata/test1/
</source>

Linking external raster data to PERMANENT Mapset:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=basins.tiff output=basins
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.external input=elevation.tiff output=elevation
</source>

Get statistics for one raster map:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ -e --exec r.univar map=elevation
</source>

==== Start a GRASS session but do not terminate it automatically ====

Compare the rasters visually:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
</source>

Read more in the [https://grass.osgeo.org/grass72/manuals/grass7.html#batch-jobs-with-the-exec-interface manual].

==== Python examples ====

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

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

The [https://github.com/zarch/grass-session "grass-session" Python library] is under development. To contribute at the code, documentation and testing it is possible to install the current version with:

<source lang="bash">
pip install grass-session
# for the latest development version use:
# pip install git+https://github.com/zarch/grass-session.git
</source>

Then write
<source lang="python">
#!/usr/bin/env python
# filename: test_session.py

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

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

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

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

<source lang="bash">
GRASSBIN=$HOME/.local/bin/grass75 python test_session.py
</source>

The use of the <tt>with-statement</tt> close automatically the session.
If you have to manage more complex workflow you can manually defined the opening and clossing actions.
For example:

<source lang="bash">
import os

# import grass_session
from grass_session import Session

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

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

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

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

# exit from PERMANENT
PERMANENT.close()

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

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

# exit from user
user.close()
</source>

===== Hint: find the path to the GRASS GIS package start script =====

Hint: in order to find the '''path to the GRASS GIS package''', launch it with <tt> --config path</tt>:

<source lang="bash">
# Linux
grass72 --config path
/usr/bin/grass-7.2.0

# Windows
C:\>grass72.bat --config path
C:\OSGeo4W\apps\grass\grass-7.2
</source>

===== Python: GRASS GIS 7 with existing location =====

See the example in the [https://grass.osgeo.org/grass72/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:

<source lang="python">
#!/usr/bin/env python

import os
import sys
import subprocess

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

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

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

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

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

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

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

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

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

# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script.setup as gsetup

###########
# launch session
gsetup.init(gisbase,
gisdb, location, mapset)

gscript.message('Current GRASS GIS 7 environment:')
print gscript.gisenv()

gscript.message('Available raster maps:')
for rast in gscript.list_strings(type = 'rast'):
print rast

gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
print vect
</source>

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

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

<source lang=python>
#!/usr/bin/env python

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

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

# some predefined variables

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

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

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

startcmd = grass7bin + ' --config path'

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

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

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

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

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

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

# Now the location with PERMANENT mapset exists.

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

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

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

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

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

#print os.environ

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

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

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

# do something in GRASS now...

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

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

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

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

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

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

sys.exit(0)
</source>

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

'''''Note: see [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]] for a really easy approach.'''''

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

<source lang=bash>
export GISBASE=/usr/local/grass-7.2.svn
export GRASS_VERSION="7.2.svn"

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

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

echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
echo "GRASS_GUI: text" >> "$MYGISRC"

# path to GRASS settings file
export GISRC=$MYGISRC
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=plain
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat

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

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

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

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

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

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

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

######### END below not needed ########
</source>

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

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

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

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

=== Important notes ===

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

<source lang="bash">
strippath()
{
(
oldpath="$1"
newpath=
IFS=:
for dir in $oldpath ; do
case "${dir}" in
*grass*)
;;
*)
newpath="$newpath:$dir"
;;
esac
done
echo "${newpath#:}"
)
}

PATH=`strippath $PATH`

export GISBASE=$PWD/dist.i686-pc-linux-gnu
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export PYTHONPATH="$GISBASE/etc/python"
</source>

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

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

=== Hints and troubleshooting ===

Some hints for MS Windows users:

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

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

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

export GIS_LOCK=$$

in Bash.

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

== GRASS databases ==

(project file structure)

=== Minimal mapsets ===

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

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

=== Minimal locations ===

Within the GISDATABASE (which is simply a subdirectory some where), the minimum LOCATION consists of a directory giving the LOCATION its name, which in turn contains a PERMANENT subdirectory for the PERMANENT mapset. The PERMANENT mapset contains a few special files that regular mapsets don't. These are:
; PROJ_INFO: contains the location's projection information
; PROJ_UNITS: contains the location's map units definition
; DEFAULT_WIND: the default region (WINDow file). The format is identical to the WIND files created by g.region
; WIND: (optional?)

* see also {{src|demolocation}} in the GRASS source code

== See also ==
* [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]]

[[Category: FAQ]]
[[Category: Linking to other languages]]
[[Category: bash]]
[[Category:Scripting]]
[[Category: Python]]

Working with GRASS without starting it explicitly

2017-12-15T22:51:12Z

⚠️Pietro: Update how to install and use the current development version of grass-session

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

== GRASS sessions ==

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

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

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

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

=== Batch jobs ===

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

See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.

=== Accessing GRASS modules without starting a GRASS session ===

==== The easiest way: the --exec flag ====

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

Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:
<source lang="bash">
grass72 -c elevation.tiff -e /path/to/grassdata/test1/
</source>

Linking external raster data to PERMANENT Mapset:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
</source>

Get statistics for one raster map:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
</source>

Compare the rasters visually:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
</source>

Read more in the [https://grass.osgeo.org/grass72/manuals/grass7.html#batch-jobs-with-the-exec-interface manual].

==== Python examples ====

See also [[GRASS Python Scripting Library]]

===== Hint: find the path to the GRASS GIS package =====

Hint: in order to find the '''path to the GRASS GIS package''', launch it with <tt> --config path</tt>:

<source lang="bash">
# Linux
grass72 --config path
/usr/bin/grass-7.2.0

# Windows
C:\>grass72.bat --config path
C:\OSGeo4W\apps\grass\grass-7.2
</source>

===== Python: GRASS GIS 7 with existing location =====

See the example in the [https://grass.osgeo.org/grass72/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:

<source lang="python">
#!/usr/bin/env python

import os
import sys
import subprocess

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

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

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

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

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

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

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

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

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

# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script.setup as gsetup

###########
# launch session
gsetup.init(gisbase,
gisdb, location, mapset)

gscript.message('Current GRASS GIS 7 environment:')
print gscript.gisenv()

gscript.message('Available raster maps:')
for rast in gscript.list_strings(type = 'rast'):
print rast

gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
print vect
</source>

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

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

<source lang=python>
#!/usr/bin/env python

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

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

# some predefined variables

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

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

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

startcmd = grass7bin + ' --config path'

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

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

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

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

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

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

# Now the location with PERMANENT mapset exists.

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

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

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

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

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

#print os.environ

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

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

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

# do something in GRASS now...

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

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

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

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

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

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

sys.exit(0)
</source>

===== Python: GRASS GIS 6 =====

The script initializes the session and lists available raster maps:

<source lang=python>
import os
import sys

gisbase = os.environ['GISBASE'] = "/usr/local/src/grass_trunk/dist.x86_64-unknown-linux-gnu"

gisdbase = os.path.join(os.environ['HOME'], "grassdata")
location = "nc_spm_08"
mapset = "user1"

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

gsetup.init(gisbase,
gisdbase, location, mapset)

print grass.gisenv()

grass.message('Raster maps:')
for rast in grass.list_strings(type = 'rast'):
print rast
</source>

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

The grass-session library is under development. To contribute at the code, documentation and testing it is possible to install the current development version using:

<source lang="bash">
pip install git+https://github.com/zarch/grass-session.git
# in the future the stable release would be available with:
# pip install grass-session
</source>

Then write
<source lang="python">
#!/usr/bin/env python
# filename: test_session.py

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

# create a new location
with Session(gisdb="/tmp", location="location",
create_opts="EPSG:4326"):
# do something in permanent
print(gcore.parse_command("g.gisenv", flags="s"))
# {u'GISDBASE': u"'/tmp/';",
# u'LOCATION_NAME': u"'epsg3035';",
# u'MAPSET': u"'PERMANENT';",}

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

The grass-session library look at the GRASSBIN environmental variable if not set by default try to use the current stable release of grass (e.g. grass74).
For instance, to execute the previous example using grass75, write:

<source lang="bash">
GRASSBIN=$HOME/.local/bin/grass75 python test_session.py
</source>

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

'''''Note: see [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]] for a really easy approach.'''''

Below an example of a '''~/.bash_profile''' script to set the required settings in order to access GRASS commands outside of a GRASS-session. Specifically it is for GRASS 7 (commented parts for GRASS 6.4.2):

<source lang=bash>
# example for GRASS 7
export GISBASE=/usr/local/grass-7.2.svn
# example for GRASS 6.4.2
### export GISBASE=/usr/local/grass-6.4.2svn

# GRASS 7
export GRASS_VERSION="7.2.svn"
# GRASS 6.4.2
### export GRASS_VERSION="6.4.2svn"

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

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

echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
echo "GRASS_GUI: text" >> "$MYGISRC"

# path to GRASS settings file
export GISRC=$MYGISRC
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=plain
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat
export GRASS_WISH=wish

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

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

# test a command
g.list rast

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

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

# GRASS 7
cp ~/.grass7/rc "$GISRC"
# GRASS 6.4.2
### cp ~/.grassrc6 "$GISRC"
######### END below not needed ########
</source>

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

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

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

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

=== Important notes ===

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

<source lang="bash">
strippath()
{
(
oldpath="$1"
newpath=
IFS=:
for dir in $oldpath ; do
case "${dir}" in
*grass*)
;;
*)
newpath="$newpath:$dir"
;;
esac
done
echo "${newpath#:}"
)
}

PATH=`strippath $PATH`

export GISBASE=$PWD/dist.i686-pc-linux-gnu
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export PYTHONPATH="$GISBASE/etc/python"
</source>

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

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

=== Hints and troubleshooting ===

Some hints for MS Windows users:

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

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

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

export GIS_LOCK=$$

in Bash.

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

== GRASS databases ==

(project file structure)

=== Minimal mapsets ===

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

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

=== Minimal locations ===

Within the GISDATABASE (which is simply a subdirectory some where), the minimum LOCATION consists of a directory giving the LOCATION its name, which in turn contains a PERMANENT subdirectory for the PERMANENT mapset. The PERMANENT mapset contains a few special files that regular mapsets don't. These are:
; PROJ_INFO: contains the location's projection information
; PROJ_UNITS: contains the location's map units definition
; DEFAULT_WIND: the default region (WINDow file). The format is identical to the WIND files created by g.region
; WIND: (optional?)

* see also {{src|demolocation}} in the GRASS source code

== See also ==
* [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]]

[[Category: FAQ]]
[[Category: Linking to other languages]]
[[Category: bash]]
[[Category:Scripting]]
[[Category: Python]]

Working with GRASS without starting it explicitly

2017-12-11T19:11:24Z

⚠️Pietro: /* Python examples */

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

== GRASS sessions ==

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

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

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

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

=== Batch jobs ===

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

See the [[GRASS_and_Shell#GRASS_Batch_jobs|Batch jobs]] section of the GRASS shell-help wiki page for details.

=== Accessing GRASS modules without starting a GRASS session ===

==== The easiest way: the --exec flag ====

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

Creating a new Location based on a geodata file's projection (-c) and exit (-e) immediately:
<source lang="bash">
grass72 -c elevation.tiff -e /path/to/grassdata/test1/
</source>

Linking external raster data to PERMANENT Mapset:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
</source>

Get statistics for one raster map:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
</source>

Compare the rasters visually:
<source lang="bash">
grass72 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
</source>

Read more in the [https://grass.osgeo.org/grass72/manuals/grass7.html#batch-jobs-with-the-exec-interface manual].

==== Python examples ====

See also [[GRASS Python Scripting Library]]

===== Hint: find the path to the GRASS GIS package =====

Hint: in order to find the '''path to the GRASS GIS package''', launch it with <tt> --config path</tt>:

<source lang="bash">
# Linux
grass72 --config path
/usr/bin/grass-7.2.0

# Windows
C:\>grass72.bat --config path
C:\OSGeo4W\apps\grass\grass-7.2
</source>

===== Python: GRASS GIS 7 with existing location =====

See the example in the [https://grass.osgeo.org/grass72/manuals/libpython/script.html#module-script.setup documentation] or the script which initializes the session and lists available raster and vector maps:

<source lang="python">
#!/usr/bin/env python

import os
import sys
import subprocess

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

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

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

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

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

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

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

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

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

# import GRASS Python bindings (see also pygrass)
import grass.script as gscript
import grass.script.setup as gsetup

###########
# launch session
gsetup.init(gisbase,
gisdb, location, mapset)

gscript.message('Current GRASS GIS 7 environment:')
print gscript.gisenv()

gscript.message('Available raster maps:')
for rast in gscript.list_strings(type = 'rast'):
print rast

gscript.message('Available vector maps:')
for vect in gscript.list_strings(type = 'vect'):
print vect
</source>

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

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

<source lang=python>
#!/usr/bin/env python

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

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

# some predefined variables

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

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

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

startcmd = grass7bin + ' --config path'

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

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

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

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

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

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

# Now the location with PERMANENT mapset exists.

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

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

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

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

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

#print os.environ

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

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

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

# do something in GRASS now...

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

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

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

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

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

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

sys.exit(0)
</source>

===== Python: GRASS GIS 6 =====

The script initializes the session and lists available raster maps:

<source lang=python>
import os
import sys

gisbase = os.environ['GISBASE'] = "/usr/local/src/grass_trunk/dist.x86_64-unknown-linux-gnu"

gisdbase = os.path.join(os.environ['HOME'], "grassdata")
location = "nc_spm_08"
mapset = "user1"

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

gsetup.init(gisbase,
gisdbase, location, mapset)

print grass.gisenv()

grass.message('Raster maps:')
for rast in grass.list_strings(type = 'rast'):
print rast
</source>

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

<source lang="bash">
pip install grass-session
</source>

Then write
<source lang="python">
#!/usr/bin/env python

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

# create a new location
with Session(gisdb="/tmp", location="location",
create_opts="EPSG:4326"):
# do something in permanent
print(gcore.parse_command("g.gisenv", flags="s"))
# {u'GISDBASE': u"'/tmp/';",
# u'LOCATION_NAME': u"'epsg3035';",
# u'MAPSET': u"'PERMANENT';",}

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

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

'''''Note: see [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]] for a really easy approach.'''''

Below an example of a '''~/.bash_profile''' script to set the required settings in order to access GRASS commands outside of a GRASS-session. Specifically it is for GRASS 7 (commented parts for GRASS 6.4.2):

<source lang=bash>
# example for GRASS 7
export GISBASE=/usr/local/grass-7.2.svn
# example for GRASS 6.4.2
### export GISBASE=/usr/local/grass-6.4.2svn

# GRASS 7
export GRASS_VERSION="7.2.svn"
# GRASS 6.4.2
### export GRASS_VERSION="6.4.2svn"

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

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

echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
echo "GRASS_GUI: text" >> "$MYGISRC"

# path to GRASS settings file
export GISRC=$MYGISRC
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=plain
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat
export GRASS_WISH=wish

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

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

# test a command
g.list rast

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

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

# GRASS 7
cp ~/.grass7/rc "$GISRC"
# GRASS 6.4.2
### cp ~/.grassrc6 "$GISRC"
######### END below not needed ########
</source>

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

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

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

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

=== Important notes ===

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

<source lang="bash">
strippath()
{
(
oldpath="$1"
newpath=
IFS=:
for dir in $oldpath ; do
case "${dir}" in
*grass*)
;;
*)
newpath="$newpath:$dir"
;;
esac
done
echo "${newpath#:}"
)
}

PATH=`strippath $PATH`

export GISBASE=$PWD/dist.i686-pc-linux-gnu
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export PYTHONPATH="$GISBASE/etc/python"
</source>

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

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

=== Hints and troubleshooting ===

Some hints for MS Windows users:

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

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

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

export GIS_LOCK=$$

in Bash.

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

== GRASS databases ==

(project file structure)

=== Minimal mapsets ===

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

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

=== Minimal locations ===

Within the GISDATABASE (which is simply a subdirectory some where), the minimum LOCATION consists of a directory giving the LOCATION its name, which in turn contains a PERMANENT subdirectory for the PERMANENT mapset. The PERMANENT mapset contains a few special files that regular mapsets don't. These are:
; PROJ_INFO: contains the location's projection information
; PROJ_UNITS: contains the location's map units definition
; DEFAULT_WIND: the default region (WINDow file). The format is identical to the WIND files created by g.region
; WIND: (optional?)

* see also {{src|demolocation}} in the GRASS source code

== See also ==
* [[GRASS_and_Shell#GRASS_Batch_jobs|GRASS Batch jobs]]

[[Category: FAQ]]
[[Category: Linking to other languages]]
[[Category: bash]]
[[Category:Scripting]]
[[Category: Python]]

Team

2017-04-27T09:05:31Z

⚠️Pietro: Added my name and move Nikos to respect the alphabetical order

The GRASS GIS project is an international team effort with scientists and developers participating from various fields. Below is a list of the current team.

All general queries concerning GRASS should be addressed to the respective [http://grass.osgeo.org/support/mailing-lists/ GRASS mailing lists]. If you miss yourself or somebody else on the lists below, please feel free to edit this Wiki page or send mail to the [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list].
__TOC__
== Current contributors to the development of the GRASS code ==

In alphabetical order; see for example [http://www.ohloh.net/p/grass_gis/contributors here] for contribution statistics.

{| class="wikitable sortable" border="1" style="margin: 1em auto 1em auto; text-align:left"
| width=200px | [[Image:Grasslogo vector small.png|100px|center]]
| '''Anna Kratochvílová''': GRASS 7 wxGUI development, Prague, CZ, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:benjamin.png|100px|center|center]]
| '''Benjamin Ducke''': extension manager, spatial statistics, archaeological applications, predictive modelling Location: Berlin, Germany, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Glynn Clements''': core development, UK, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ]

|-
| [[Image:hamish.jpg|100px|center]]
| '''Hamish Bowman''': Development of display, PostScript, raster, and GPS modules as well as general sanitation of the code, help, and web pages. Location: Department of Marine Science, University of Otago. Dunedin, New Zealand mail: hamish_b AT yahoo com [http://hamish.bowman.googlepages.com/grassfiles http://hamish.bowman.googlepages.com/grassfiles]

|-
| [[Image:helena.jpg|100px|center]]
| '''Helena Mitasova''': surface and volume modeling and analysis (RST modules), topographic analysis, hydrologic and erosion modelling, assistance with visualization, working with students on new module development, testing, and bug fixing Location: Raleigh, North Carolina, USA, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ][http://www4.ncsu.edu/~hmitaso/ http://www4.ncsu.edu/~hmitaso/]

|-
| [[Image:hellik.png|100px|center]]
| '''Helmut Kudrnovsky''': [http://grass.osgeo.org/grass64/binary/mswindows/native/ winGRASS packaging],german translation, Austria, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Huidae Cho''': Hydrologic modeling (TOPMODEL modules), DXF modules, FreeType support, Korean translation. Location: Atlanta, Georgia, USA mail: grass4u AT gmail com, IRC Nick: grass4u [http://idea.isnew.info http://idea.isnew.info]

|-
| [[Image:lucadelu.png|100px|center]]
| '''Luca Delucchi''': Python GRASS development (GUI and Modules), Documentation, Italian Translation, Location: Trento (Italy), mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Maris_nartiss.jpg|100px|center]]
| '''[[user:MarisN|Maris Nartiss]]''': Tcl/TK GUI development, Latvia, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Markus Metz''': GRASS 7 development, massive data processing, vector library, Italy + Germany, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:markus.jpg|100px|center]]
| '''Markus Neteler''': various contributions, coordination, main Web site and mailing lists maintenance, Location: Bonn, Germany, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list], IRC Nick: markusN [http://www.grassbook.org/neteler/ http://www.grassbook.org/neteler/]

|-
| [[Image:mlanda.png|100px|center]]
| '''Martin Landa''': various contributions, vector engine improvements, [[wxGUI]], Location: Prague, Czech Republic Mail: landa.martin AT gmail.com Homepage: [http://geo.fsv.cvut.cz/~landa http://geo.fsv.cvut.cz/~landa]

|-
| [[Image:michael.jpg|100px|center]]
| '''Michael Barton ''': GRASS native GUI development, Mac binaries, Location: Tempe, Arizona, USA mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ][http://www.public.asu.edu/~cmbarton/ http://www.public.asu.edu/~cmbarton/]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Moritz Lennert''': display tools, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Nikos Alexandris''': tester, contributed add-ons, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Pietro Zambelli''': GRASS7 Python API (mainly pygrass), Location: Europe, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list], link: ''

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Soeren Gebbert''': improvements of [http://www-pool.math.tu-berlin.de/~soeren/grass/ 3D functionality] mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Stepan Turek''': GRASS 7 wxGUI development, Prague, CZ, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Vaclav Petras''': GRASS 7 wxGUI development, Prague, CZ, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''William Kyngesburye''': [http://www.kyngchaos.com/software:grass/ Mac OS X packaging], USA, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Yann Chemin''': image processing, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''''your name''': what-you-do, Location: xyz, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list], link: ''

|}

== Former or currently inactive developers ==

(in alphabetical order)

{| class="wikitable sortable" border="1" style="margin: 1em auto 1em auto; text-align:left"
| width=200px | [[Image:Grasslogo vector small.png|100px|center]]
| '''Bob Covill''' Role: visualization, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Brad Douglas''' Role: bug fixing, code portability, imagery modules Location: Fremont, California, USA, IRC Nick: bdouglas, mail: rez AT touchofmadness com

|-
| [[Image:cedric.jpg|100px|center]]
| '''Cedric Shock''' Role: user interface enhancements, debugging Location: Eugene, Oregon, USA, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list], [http://www.shockfamily.net/cedric/ http://www.shockfamily.net/cedric/]

|-
| [[Image:DaveSampson.png|100px|center]]
| '''Dave Sampson''' Role: tutorials, data sets & public data licensing, GRASS map gallery, Ottawa Chapter of OSGeo, Location: Ottawa, Ontario, Canada, mail: samper.d at gmail dot com [http://davidsampson.ca/ http://davidsampson.ca]

|-
| [[Image:jachym.png|100px|center]]
| '''Jachym Cepicky''' Role: bug fixing, support of 3D vectors, tester and translator, UI developer, Czech Republic, mail: jachym.cepicky AT gmail.com [http://les-ejk.cz/ http://les-ejk.cz/]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Jaroslav Hofierka''' Role: development of modules for solar irradiation, flow routing, surface and volume modelling and analysis (RST modules), hydrologic and erosion modelling, assistance with visualization Location: Presov, Slovakia, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ]

|-
| [[Image:maciek.png|100px|center]]
| '''Maciej Sieczka''' Role: power user, testing Location: Wroclaw, Poland, mail: msieczka AT sieczka.org [http://www.sieczka.org/ http://www.sieczka.org]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Marco Pasetti''' Role: Microsoft Windows native binary port of GRASS Location: Brescia, Italy, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list], link: [http://grass.osgeo.org/grass64/binary/mswindows/native/ WinGRASS Project Homepage]

|-
| [[Image:Grasslogo vector small.png|100px|center]]
| '''Paul Kelly''' Role: Proj integration, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list ]

|-
| [[Image:radim.jpg|100px|center]]
| '''Radim Blazek''' Role: DBMI, vector engine core developer, Location: Trento, Italy till 2006, mail: [http://lists.osgeo.org/mailman/listinfo/grass-dev GRASS developers mailing list]

|-
| [[Image:scott.jpg|100px|center]]
| '''Scott Mitchell''' Role: tutorial and documentation development, web site maintenance, Ottawa User's Group, OSGeo Journal News and Events Editor Location: Ottawa, Ontario, Canada, mail: [http://lists.osgeo.org/mailman/listinfo/grass-web GRASS web site maintenance mailing list] [http://www.carleton.ca/~smitch http://www.carleton.ca/~smitch]

|}

== The following institutions are currently supporting the GRASS-Project ==

Please see our [http://grass.osgeo.org/donations/ GRASS sponsoring] page.

And a ''thank-you'' to:

* the many people who have contributed in the past
* the various users who have contributed bug reports and tested unstable GRASS versions;
* all the sites (and the people behind them) that provide mirrors for the GRASS web pages.

Python/pygrass

2016-03-29T09:47:08Z

⚠️Pietro: /* Interface to copying maps (g.copy) */

''PyGRASS'' is a library that extends the GRASS GIS 7 capabilities to allow users to access the low-level GRASS API.

== Documentation ==

Detailed PyGRASS documentation: http://grass.osgeo.org/grass71/manuals/libpython/

== How to test library ==

''pygrass'' has 'doctest' included in its code. You can run doctest in the [http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz North Carolina basic location], using the mapset '''user1'''.

To test a single module (file) you have to change into the source code directory of pygrass and run the following code (this is an example of functions.py):

<source lang="bash">
python -m doctest functions.py
</source>

== References ==

* Zambelli, P., Gebbert, S., Ciolli, M., 2013. ''Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)''. ISPRS International Journal of Geo-Information 2, 201–219. ([http://dx.doi.org/10.3390/ijgi2010201 DOI] | [http://www.mdpi.com/2220-9964/2/1/201/pdf PDF])

* [http://grass.osgeo.org/grass71/manuals/libpython/ pyGrass documentation] (updated weekly from SVN)

== Sample PyGRASS scripts ==

=== Training material ===

Two workshops were presented during the [http://geomorfolab.arch.unige.it/genova2013/ XIV Italian meeting of GRASS] at Genova.
The workshops use '''ipython notebook''' to show the python and pygrass API, all the material are available on github ([https://github.com/zarch/workshop-python python], [https://github.com/zarch/workshop-pygrass pygrass]). All the execute examples are reported here:

* python training (Genova)
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/03_function.ipynb Function]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/04_class.ipynb Class]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/05_other.ipynb Other]

* python training (EURAC)
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/03_version_control_system.ipynb Version Control System (hg)]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/04_objects.ipynb Objects]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/05_python_debugger.ipynb Debugger]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/06_functions.ipynb Functions]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/07_numpy.ipynb Numpy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/08_matplotlib.ipynb Matplotlib]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/09_scipy.ipynb Scipy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/10_pandas.ipynb Pandas]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/11_sympy.ipynb Sympy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/12_user_interfaces.ipynb GUI]

* pygrass training
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/00_Modules.ipynb Modules]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/01_GIS_objects.ipynb GIS]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/02_Vector.ipynb Vector]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/03_Raster.ipynb Raster]

=== Interface to listing maps (g.list/g.mlist) ===

Here we call a GRASS module that writes to stdout and do not call a Python function that returns a Python object, therefore we can save stdout and then parse it with:

<source lang="python">
from grass.pygrass.modules.shortcuts import general as g
import subprocess as sub

gl = g.list # GRASS 7
gl(type='raster', pattern='elev-*', stdout=sub.PIPE)
gl.outputs.stdout.split()
['elev-000-000', 'elev-000-001', 'elev-000-002', 'elev-001-000',
'elev-001-001', 'elev-001-002', 'elev-002-000', 'elev-002-001',
'elev-002-002']
</source>

or you can use the "glist" method of the Mapset class:

<source lang="python">
from grass.pygrass.gis import Mapset
m = Mapset()
m.glist('rast', pattern='elev-*')
['elev-002-000', 'elev-000-000', 'elev-000-002', 'elev-000-001',
'elev-001-001', 'elev-002-002', 'elev-002-001', 'elev-001-000',
'elev-001-002']
</source>

... that uses the "G_list" function through ctypes and therefore is faster.

Note: If you choose the first solution it is better if you use directly the
function in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped() etc.].

=== Interface to copying maps (g.copy) ===
<source lang="python">
from grass.pygrass.modules.shortcuts import general as g

vectinmap = 'zipcodes_wake'
vectoutmap = 'zip_elev_zonal'
g.copy(vector=(vectinmap,vectoutmap))
</source>

=== Sample script for opening, query and closing of a vector map ===

<source lang="python">
#!/usr/bin/env python

# Example for pyGRASS usage - vector API

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.vector import VectorTopo

g.message("Assessing vector topology...")

vectmap = 'zipcodes_wake'
zipcodes = VectorTopo(vectmap)

# Open the map with topology:
zipcodes.open()

# query number of topological features
areas = zipcodes.number_of("areas")
islands = zipcodes.number_of("islands")
print 'Map: <' + vectmap + '> with %d areas and %d islands' % (areas, islands)

# http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html
# (note that above documentation is slightly outdated)
dblink = zipcodes.dblinks[0]
print 'DB name:'
print dblink.database
table = dblink.table()
print 'Column names:'
print table.columns.names()
print 'Column types:'
print table.columns.types()

zipcodes.close()
</source>

=== Sample script for Landsat 7 processing ===

<source lang="python">
#!/usr/bin/env python
#Date: 7th February, 2013
#Public domain, GRASS GIS

#Run this script in the terminal as:
#python python-grass.py
#For debugging, run as:
#python -i python-grass.py
#PURPOSE
#This script processes LANDSAT 7 ETM+ images
#1 - unzip *.gz files
#2 - import files in GRASS GIS Location of your choice (r.in.gdal)
#3 - DN to Top of Atmosphere reflectance (i.landsat.toar)
#4 - TOA reflectance to Surface reflectance (i.atcorr)
#5 - NDVI (i.vi), Albedo (i.albedo), Emissivity (i.emissivity)

#USER HAS TO SET THOSE
#QUIET REPORTS
QIET=True
#OVERWRITE EXISTING FILES
OVR=False
#Define Landsat 7 sensor for i.landsat.toar
LSENSOR="tm7"
#Setup the path to the Landsat 7 Directories
rsdatapath="/home/yann/RSDATA/Myanmar/L7"
#Setup your GRASS GIS working directory
gisdb="/home/yann/GRASSDATA"
location="L7_Myanmar"
print location
mapset="PERMANENT"
#DEM input to atmospheric correction
inDEM=rsdatapath+"/dem.tif"
#set L7 Metadata wildcards
wldc_mtl="*_MTL.txt"
#wldc_met="*.met"
#Visibility distance [Km]
vis=18

#Set python path to enable finding of grass.script lib

#END OF USER CHANGES
###DO NOT CHANGE ANYTHING AFTER THIS LINE !
###
#Load necessary libraries
import os, glob, time, re
from grass import script as g
from grass.script import setup as gsetup
gisbase=os.environ['GISBASE']
gsetup.init(gisbase,gisdb,location,mapset)
from grass.pygrass.modules.shortcuts import raster as r
from grass.pygrass.modules.shortcuts import imagery as i
from grass.pygrass.modules.shortcuts import display as d
#Needed for floor()
from math import *
#env = os.environ.copy()
#env['GRASS_MESSAGE_FORMAT'] = 'gui'
#Function to get a list of L7 Directories in the rsdatapath
def fn(path):
for top, dirs, files in os.walk(path):
return [os.path.join(top, dir) for dir in dirs]

#START PROCESS
### PART 0: PRE-PROCESSING STUFF ###
#import DEM for atmospheric correction
#r.in.gdal(input=inDEM,output="dem",overwrite=OVR)
#r.mapcalc(expression="dem=25",overwrite=OVR)
#create a visibility map
r.mapcalc(expression="vis=18",overwrite=OVR)
#Find the central location of the Landsat file from metadata
metadata=[]
fileList=[]
L7Dirs=fn(rsdatapath)
for L7Dir in L7Dirs:
#Ungzip all of your Landsat7 images in all your directories
# print "Ungzip Landsat files in\t",L7Dir
# p=os.system("gzip -d -q "+L7Dir+"/*.gz")
#Using pthreads on multi-core machines
#p=os.system("pigz -d "+L7Dir+"/*.gz")
#Wait ten seconds for gzip to create the tif images
# time.sleep(10)
print "Import in GRASS GIS"
for L7f in glob.glob(os.path.join(L7Dir,"*.[tT][iI][fF]")):
f1=L7f.replace(L7Dir+"/","")
f2=f1.replace(".TIF","")
f3=f2.replace("_B10",".1")
f4=f3.replace("_B20",".2")
f5=f4.replace("_B30",".3")
f6=f5.replace("_B40",".4")
f7=f6.replace("_B50",".5")
f8=f7.replace("_B61",".61")
f9=f8.replace("_B62",".62")
f10=f9.replace("_B70",".7")
f11=f10.replace("_B80",".8")
f12=f11.replace("L72","L71")
L7r=f12.replace("_VCID_","")
print "\t> ",L7r
r.in_gdal(input=L7f,output=L7r,flags="e",overwrite=OVR)
fileList.append(L7r)

#reproject the DEM World map for the new PERMANENT location extents
r.proj(input="dem",location="Myanmar",memory=10000,resolution=90.0,overwrite=OVR)
#Get list of metadata files
for metaf in glob.glob(os.path.join(L7Dir,wldc_mtl)):
metadata.append(metaf)
print "Metadata in:\n",metadata[0]
with open(metadata[0],"r") as f:
data=f.read()

f.close()
dt=data.split("\n")
for idx in range(len(dt)):
found=dt[idx].find("CORNER_UL_LON_PRODUCT = ")
if found > 0:
ulx=float(dt[idx].replace("CORNER_UL_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_UL_LAT_PRODUCT = ")
if found > 0:
uly=float(dt[idx].replace("CORNER_UL_LAT_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LON_PRODUCT = ")
if found > 0:
lrx=float(dt[idx].replace("CORNER_LR_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LAT_PRODUCT = ")
if found > 0:
lry=float(dt[idx].replace("CORNER_LR_LAT_PRODUCT = ",""))
#Two cases, because a string starting by 0 is not converted well
found=dt[idx].find("SCENE_CENTER_TIME = ")
if found > 0:
tim=dt[idx].replace("SCENE_CENTER_TIME = ","")
print "timestamp=",str(tim)
gmth=float(tim.split(":")[0])
gmtm=float(tim.split(":")[1])
gmtdec=float(tim.split(":")[2].replace("Z",""))
print gmth,gmtm,gmtdec
found=dt[idx].find("DATE_ACQUIRED = ")
if found > 0:
dat=dt[idx].replace("DATE_ACQUIRED = ","")
date=dat.split("-")
found=dt[idx].find("SUN_ELEVATION = ")
if found > 0:
sunza=90-float(dt[idx].replace("SUN_ELEVATION = ",""))

#L7 DN->Rad->Ref
print "Convert DN to Rad to TOARef"
f1=sorted(fileList)[0]
f2=f1.replace(L7Dir+"/","")
pref=f2[:-1]
outpref=pref[:-2]+".toar."
print "Prefix IN:\t",pref
print "Prefix OUT:\t", outpref
i.landsat_toar(input_prefix=pref,output_prefix=outpref,metfile=metadata[0],sensor=LSENSOR,quiet=QIET,overwrite=OVR)
#Atmospheric Correction
print "Atmospheric Correction"
# Basic script for i.atcorr for L 7 ETM+
#Geometrical conditions (L7ETM+)
geom=7
#Sensor height (satellite is -1000)
sens_height=-1000
#Here we suppose you have altitude (DEM) and Visibility (VIS) maps ready
#---------------------------------------------
#Visibility dummy value (overwritten by VIS raster input)
vis=15
#Altitude dummy value (in Km should be negative in this param file)
#(overwritten by DEM raster input)
alt=-1.200
#datetime of satellite overpass (month, day, GMT decimal hour)
mdh=str(int(date[1]))+" "+str(int(date[2]))+" "+str("%.2f" % (gmth+gmtm/60.0+gmtdec/3600.0))
print "MM DD hh.ddd:\t",mdh
# Central Lat/Long
Long=ulx+(lrx-ulx)/2.0
Lat=lry+(uly-lry)/2.0
print "Center:\t(",Long, ",", Lat,")"
#Atmospheric mode
atm_mode=1 #Tropical
#Aerosol model
aerosol_mode=2 #Sri Lanka is a small island (maritime)
#satellite band number (L5TM [25,26,27,28,29,30], L7ETM+ [61,62,63,64,65,66,67])
satbandno=61 #Band 1 of L7ETM+ is first to undergo atmospheric correction
#make time stamp for use in time series analysis
dat1=str(date[2])+"-"+str(date[1])+"-"+str(date[0])
dat=dat1.replace(" ","")
timestamp=time.strftime("%d %b %Y",time.strptime(dat,"%d-%m-%Y"))
print "Timestamp:\t",timestamp
for idx in [1,2,3,4,5,7]:
b=pref[:-2]+".toar."+str(idx)
b_out=b.replace(".toar.",".surf.")
param=[]
param.append(str(geom)+" - geometrical conditions=Landsat 7 ETM+\n")
param.append(str(mdh)+" "+str("%.2f" % Long)+" "+str("%.2f" % Lat)+" - month day hh.ddd longitude latitude (hh.ddd is in decimal hours GMT)\n")
param.append(str(atm_mode)+" - atmospheric mode=tropical\n")
param.append(str(aerosol_mode)+" - aerosols model=maritime\n")
param.append(str(vis)+" - visibility [km] (aerosol model concentration), not used as there is raster input\n")
param.append(str(alt)+" - mean target elevation above sea level [km] (here 600m asl), not used as there is raster input\n")
param.append(str(sens_height)+" - sensor height (here, sensor on board a satellite)\n")
param.append(str(satbandno)+" - i th band of ETM+ Landsat 7 (atcorr internal no)\n")
f=open(os.path.join(L7Dir,"param_L7.txt"),"w")
f.writelines(param)
f.close()
prm=os.path.join(L7Dir,"param_L7.txt")
print "\t> ",b
print "\t> ",b_out
i.atcorr(input=b, elevation="dem", visibility="vis", parameters=prm, output=b_out, flags="ra", range=[0,1],quiet=QIET,overwrite=OVR)
r.timestamp(map=b_out,date=timestamp,finish_=False)
satbandno = satbandno + 1

#Allocate surface reflectance names
b1=pref[:-2]+".surf.1"
b2=pref[:-2]+".surf.2"
b3=pref[:-2]+".surf.3"
b4=pref[:-2]+".surf.4"
b5=pref[:-2]+".surf.5"
b61=pref[:-2]+".toar.61"
b62=pref[:-2]+".toar.62"
b7=pref[:-2]+".surf.7"
b8=pref[:-2]+".surf.8"

### PART 1: BASIC STUFF ###
b_in=pref[:-2]+".toar."
b_clouds=pref[:-2]+".toar.acca"
print "Clouds:\t\t>",b_clouds
i.landsat_acca(input_prefix=b_in,output=b_clouds,overwrite=OVR)
#png_clouds=L7Dir+"/"+pref[:-2]+".clouds.png"
#d.mon(start='png',output=png_clouds,width=800,height=800)
print "MASK:\t\tON"
#Should always be rewritten!
r.mask(raster=b_clouds,flags="i",overwrite=True)

b_ndvi=pref[:-2]+".surf.ndvi"
print "NDVI:\t",b_ndvi
i.vi(red=b3,nir=b4,output=b_ndvi,viname="ndvi",quiet=QIET,overwrite=OVR,finish_=False)

b_in=[b1,b2,b3,b4,b5,b7]
b_albedo=pref[:-2]+".surf.albedo"
print "Albedo:\t",b_albedo
i.albedo(input=b_in,output=b_albedo,flags="lc",quiet=QIET,overwrite=OVR,finish_=False)

b_emissivity=pref[:-2]+".surf.emissivity"
print "Emissivity:\t",b_emissivity
i.emissivity(input=b_ndvi, output=b_emissivity,quiet=QIET,overwrite=OVR,finish_=False)
</source>

=== Multiprocessing example: parallelized SHAPE file import ===

<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Multiprocessing example: parallelized SHAPE file import

Created on Fri, Oct 18, 2013, posted to grass-user@lists.osgeo.org

@author: Pietro Zambelli, freely inspired by: http://stackoverflow.com/a/16071616
http://lists.osgeo.org/pipermail//grass-user/2013-October/069130.html
"""

# Directory containing SHAPE files to import
DIR = '/data/shp'

###
from multiprocessing import Queue, Process, cpu_count
from os.path import split
from subprocess import Popen

from grass.pygrass.functions import findfiles

def spawn(func):
def fun(q_in, q_out):
while True:
path, cmdstr = q_in.get()
if path is None:
break
q_out.put(func(path, cmdstr))
return fun

def mltp_importer(dirpath, match, cmdstr, func, nprocs=cpu_count()):
q_in = Queue(1)
q_out = Queue()
procs = [Process(target=spawn(func), args=(q_in, q_out))
for _ in range(nprocs)]
for proc in procs:
proc.daemon = True
proc.start()

# set the parameters
sent = [q_in.put((path, cmdstr)) for path in findfiles(dirpath, match)]
# set the end of the cycle
[q_in.put((None, None)) for proc in procs]
[proc.join() for proc in procs]
return [q_out.get() for _ in range(len(sent))]

def importer(path, cmdstr):
name = split(path)[-1][:-4]
print name
popen = Popen(cmdstr.format(path=path, name=name), shell=True)
popen.wait()
return path, name, False if popen.returncode else True

CMD = 'v.in.ogr dsn={path} layer={name} output={name}'

processed = mltp_importer(DIR, '*.shp', CMD, importer)
# check for errors
errors = [p for p in processed if not p[2]]
if errors:
# do something (print list of failed SHP files at end)
pass
</source>

{{Python}}

Python/pygrass

2016-03-29T09:43:29Z

⚠️Pietro: /* Interface to copying maps (g.copy) */

''PyGRASS'' is a library that extends the GRASS GIS 7 capabilities to allow users to access the low-level GRASS API.

== Documentation ==

Detailed PyGRASS documentation: http://grass.osgeo.org/grass71/manuals/libpython/

== How to test library ==

''pygrass'' has 'doctest' included in its code. You can run doctest in the [http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz North Carolina basic location], using the mapset '''user1'''.

To test a single module (file) you have to change into the source code directory of pygrass and run the following code (this is an example of functions.py):

<source lang="bash">
python -m doctest functions.py
</source>

== References ==

* Zambelli, P., Gebbert, S., Ciolli, M., 2013. ''Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)''. ISPRS International Journal of Geo-Information 2, 201–219. ([http://dx.doi.org/10.3390/ijgi2010201 DOI] | [http://www.mdpi.com/2220-9964/2/1/201/pdf PDF])

* [http://grass.osgeo.org/grass71/manuals/libpython/ pyGrass documentation] (updated weekly from SVN)

== Sample PyGRASS scripts ==

=== Training material ===

Two workshops were presented during the [http://geomorfolab.arch.unige.it/genova2013/ XIV Italian meeting of GRASS] at Genova.
The workshops use '''ipython notebook''' to show the python and pygrass API, all the material are available on github ([https://github.com/zarch/workshop-python python], [https://github.com/zarch/workshop-pygrass pygrass]). All the execute examples are reported here:

* python training (Genova)
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/03_function.ipynb Function]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/04_class.ipynb Class]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/05_other.ipynb Other]

* python training (EURAC)
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/03_version_control_system.ipynb Version Control System (hg)]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/04_objects.ipynb Objects]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/05_python_debugger.ipynb Debugger]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/06_functions.ipynb Functions]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/07_numpy.ipynb Numpy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/08_matplotlib.ipynb Matplotlib]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/09_scipy.ipynb Scipy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/10_pandas.ipynb Pandas]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/11_sympy.ipynb Sympy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/12_user_interfaces.ipynb GUI]

* pygrass training
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/00_Modules.ipynb Modules]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/01_GIS_objects.ipynb GIS]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/02_Vector.ipynb Vector]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/03_Raster.ipynb Raster]

=== Interface to listing maps (g.list/g.mlist) ===

Here we call a GRASS module that writes to stdout and do not call a Python function that returns a Python object, therefore we can save stdout and then parse it with:

<source lang="python">
from grass.pygrass.modules.shortcuts import general as g
import subprocess as sub

gl = g.list # GRASS 7
gl(type='raster', pattern='elev-*', stdout=sub.PIPE)
gl.outputs.stdout.split()
['elev-000-000', 'elev-000-001', 'elev-000-002', 'elev-001-000',
'elev-001-001', 'elev-001-002', 'elev-002-000', 'elev-002-001',
'elev-002-002']
</source>

or you can use the "glist" method of the Mapset class:

<source lang="python">
from grass.pygrass.gis import Mapset
m = Mapset()
m.glist('rast', pattern='elev-*')
['elev-002-000', 'elev-000-000', 'elev-000-002', 'elev-000-001',
'elev-001-001', 'elev-002-002', 'elev-002-001', 'elev-001-000',
'elev-001-002']
</source>

... that uses the "G_list" function through ctypes and therefore is faster.

Note: If you choose the first solution it is better if you use directly the
function in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped() etc.].

=== Interface to copying maps (g.copy) ===
<source lang="python">
from grass.pygrass.modules.shortcuts import general as g

vectinmap = 'zipcodes_wake'
vectoutmap = 'zip_elev_zonal'
g.copy(vect=(vectinmap,vectoutmap) )
</source>

=== Sample script for opening, query and closing of a vector map ===

<source lang="python">
#!/usr/bin/env python

# Example for pyGRASS usage - vector API

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.vector import VectorTopo

g.message("Assessing vector topology...")

vectmap = 'zipcodes_wake'
zipcodes = VectorTopo(vectmap)

# Open the map with topology:
zipcodes.open()

# query number of topological features
areas = zipcodes.number_of("areas")
islands = zipcodes.number_of("islands")
print 'Map: <' + vectmap + '> with %d areas and %d islands' % (areas, islands)

# http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html
# (note that above documentation is slightly outdated)
dblink = zipcodes.dblinks[0]
print 'DB name:'
print dblink.database
table = dblink.table()
print 'Column names:'
print table.columns.names()
print 'Column types:'
print table.columns.types()

zipcodes.close()
</source>

=== Sample script for Landsat 7 processing ===

<source lang="python">
#!/usr/bin/env python
#Date: 7th February, 2013
#Public domain, GRASS GIS

#Run this script in the terminal as:
#python python-grass.py
#For debugging, run as:
#python -i python-grass.py
#PURPOSE
#This script processes LANDSAT 7 ETM+ images
#1 - unzip *.gz files
#2 - import files in GRASS GIS Location of your choice (r.in.gdal)
#3 - DN to Top of Atmosphere reflectance (i.landsat.toar)
#4 - TOA reflectance to Surface reflectance (i.atcorr)
#5 - NDVI (i.vi), Albedo (i.albedo), Emissivity (i.emissivity)

#USER HAS TO SET THOSE
#QUIET REPORTS
QIET=True
#OVERWRITE EXISTING FILES
OVR=False
#Define Landsat 7 sensor for i.landsat.toar
LSENSOR="tm7"
#Setup the path to the Landsat 7 Directories
rsdatapath="/home/yann/RSDATA/Myanmar/L7"
#Setup your GRASS GIS working directory
gisdb="/home/yann/GRASSDATA"
location="L7_Myanmar"
print location
mapset="PERMANENT"
#DEM input to atmospheric correction
inDEM=rsdatapath+"/dem.tif"
#set L7 Metadata wildcards
wldc_mtl="*_MTL.txt"
#wldc_met="*.met"
#Visibility distance [Km]
vis=18

#Set python path to enable finding of grass.script lib

#END OF USER CHANGES
###DO NOT CHANGE ANYTHING AFTER THIS LINE !
###
#Load necessary libraries
import os, glob, time, re
from grass import script as g
from grass.script import setup as gsetup
gisbase=os.environ['GISBASE']
gsetup.init(gisbase,gisdb,location,mapset)
from grass.pygrass.modules.shortcuts import raster as r
from grass.pygrass.modules.shortcuts import imagery as i
from grass.pygrass.modules.shortcuts import display as d
#Needed for floor()
from math import *
#env = os.environ.copy()
#env['GRASS_MESSAGE_FORMAT'] = 'gui'
#Function to get a list of L7 Directories in the rsdatapath
def fn(path):
for top, dirs, files in os.walk(path):
return [os.path.join(top, dir) for dir in dirs]

#START PROCESS
### PART 0: PRE-PROCESSING STUFF ###
#import DEM for atmospheric correction
#r.in.gdal(input=inDEM,output="dem",overwrite=OVR)
#r.mapcalc(expression="dem=25",overwrite=OVR)
#create a visibility map
r.mapcalc(expression="vis=18",overwrite=OVR)
#Find the central location of the Landsat file from metadata
metadata=[]
fileList=[]
L7Dirs=fn(rsdatapath)
for L7Dir in L7Dirs:
#Ungzip all of your Landsat7 images in all your directories
# print "Ungzip Landsat files in\t",L7Dir
# p=os.system("gzip -d -q "+L7Dir+"/*.gz")
#Using pthreads on multi-core machines
#p=os.system("pigz -d "+L7Dir+"/*.gz")
#Wait ten seconds for gzip to create the tif images
# time.sleep(10)
print "Import in GRASS GIS"
for L7f in glob.glob(os.path.join(L7Dir,"*.[tT][iI][fF]")):
f1=L7f.replace(L7Dir+"/","")
f2=f1.replace(".TIF","")
f3=f2.replace("_B10",".1")
f4=f3.replace("_B20",".2")
f5=f4.replace("_B30",".3")
f6=f5.replace("_B40",".4")
f7=f6.replace("_B50",".5")
f8=f7.replace("_B61",".61")
f9=f8.replace("_B62",".62")
f10=f9.replace("_B70",".7")
f11=f10.replace("_B80",".8")
f12=f11.replace("L72","L71")
L7r=f12.replace("_VCID_","")
print "\t> ",L7r
r.in_gdal(input=L7f,output=L7r,flags="e",overwrite=OVR)
fileList.append(L7r)

#reproject the DEM World map for the new PERMANENT location extents
r.proj(input="dem",location="Myanmar",memory=10000,resolution=90.0,overwrite=OVR)
#Get list of metadata files
for metaf in glob.glob(os.path.join(L7Dir,wldc_mtl)):
metadata.append(metaf)
print "Metadata in:\n",metadata[0]
with open(metadata[0],"r") as f:
data=f.read()

f.close()
dt=data.split("\n")
for idx in range(len(dt)):
found=dt[idx].find("CORNER_UL_LON_PRODUCT = ")
if found > 0:
ulx=float(dt[idx].replace("CORNER_UL_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_UL_LAT_PRODUCT = ")
if found > 0:
uly=float(dt[idx].replace("CORNER_UL_LAT_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LON_PRODUCT = ")
if found > 0:
lrx=float(dt[idx].replace("CORNER_LR_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LAT_PRODUCT = ")
if found > 0:
lry=float(dt[idx].replace("CORNER_LR_LAT_PRODUCT = ",""))
#Two cases, because a string starting by 0 is not converted well
found=dt[idx].find("SCENE_CENTER_TIME = ")
if found > 0:
tim=dt[idx].replace("SCENE_CENTER_TIME = ","")
print "timestamp=",str(tim)
gmth=float(tim.split(":")[0])
gmtm=float(tim.split(":")[1])
gmtdec=float(tim.split(":")[2].replace("Z",""))
print gmth,gmtm,gmtdec
found=dt[idx].find("DATE_ACQUIRED = ")
if found > 0:
dat=dt[idx].replace("DATE_ACQUIRED = ","")
date=dat.split("-")
found=dt[idx].find("SUN_ELEVATION = ")
if found > 0:
sunza=90-float(dt[idx].replace("SUN_ELEVATION = ",""))

#L7 DN->Rad->Ref
print "Convert DN to Rad to TOARef"
f1=sorted(fileList)[0]
f2=f1.replace(L7Dir+"/","")
pref=f2[:-1]
outpref=pref[:-2]+".toar."
print "Prefix IN:\t",pref
print "Prefix OUT:\t", outpref
i.landsat_toar(input_prefix=pref,output_prefix=outpref,metfile=metadata[0],sensor=LSENSOR,quiet=QIET,overwrite=OVR)
#Atmospheric Correction
print "Atmospheric Correction"
# Basic script for i.atcorr for L 7 ETM+
#Geometrical conditions (L7ETM+)
geom=7
#Sensor height (satellite is -1000)
sens_height=-1000
#Here we suppose you have altitude (DEM) and Visibility (VIS) maps ready
#---------------------------------------------
#Visibility dummy value (overwritten by VIS raster input)
vis=15
#Altitude dummy value (in Km should be negative in this param file)
#(overwritten by DEM raster input)
alt=-1.200
#datetime of satellite overpass (month, day, GMT decimal hour)
mdh=str(int(date[1]))+" "+str(int(date[2]))+" "+str("%.2f" % (gmth+gmtm/60.0+gmtdec/3600.0))
print "MM DD hh.ddd:\t",mdh
# Central Lat/Long
Long=ulx+(lrx-ulx)/2.0
Lat=lry+(uly-lry)/2.0
print "Center:\t(",Long, ",", Lat,")"
#Atmospheric mode
atm_mode=1 #Tropical
#Aerosol model
aerosol_mode=2 #Sri Lanka is a small island (maritime)
#satellite band number (L5TM [25,26,27,28,29,30], L7ETM+ [61,62,63,64,65,66,67])
satbandno=61 #Band 1 of L7ETM+ is first to undergo atmospheric correction
#make time stamp for use in time series analysis
dat1=str(date[2])+"-"+str(date[1])+"-"+str(date[0])
dat=dat1.replace(" ","")
timestamp=time.strftime("%d %b %Y",time.strptime(dat,"%d-%m-%Y"))
print "Timestamp:\t",timestamp
for idx in [1,2,3,4,5,7]:
b=pref[:-2]+".toar."+str(idx)
b_out=b.replace(".toar.",".surf.")
param=[]
param.append(str(geom)+" - geometrical conditions=Landsat 7 ETM+\n")
param.append(str(mdh)+" "+str("%.2f" % Long)+" "+str("%.2f" % Lat)+" - month day hh.ddd longitude latitude (hh.ddd is in decimal hours GMT)\n")
param.append(str(atm_mode)+" - atmospheric mode=tropical\n")
param.append(str(aerosol_mode)+" - aerosols model=maritime\n")
param.append(str(vis)+" - visibility [km] (aerosol model concentration), not used as there is raster input\n")
param.append(str(alt)+" - mean target elevation above sea level [km] (here 600m asl), not used as there is raster input\n")
param.append(str(sens_height)+" - sensor height (here, sensor on board a satellite)\n")
param.append(str(satbandno)+" - i th band of ETM+ Landsat 7 (atcorr internal no)\n")
f=open(os.path.join(L7Dir,"param_L7.txt"),"w")
f.writelines(param)
f.close()
prm=os.path.join(L7Dir,"param_L7.txt")
print "\t> ",b
print "\t> ",b_out
i.atcorr(input=b, elevation="dem", visibility="vis", parameters=prm, output=b_out, flags="ra", range=[0,1],quiet=QIET,overwrite=OVR)
r.timestamp(map=b_out,date=timestamp,finish_=False)
satbandno = satbandno + 1

#Allocate surface reflectance names
b1=pref[:-2]+".surf.1"
b2=pref[:-2]+".surf.2"
b3=pref[:-2]+".surf.3"
b4=pref[:-2]+".surf.4"
b5=pref[:-2]+".surf.5"
b61=pref[:-2]+".toar.61"
b62=pref[:-2]+".toar.62"
b7=pref[:-2]+".surf.7"
b8=pref[:-2]+".surf.8"

### PART 1: BASIC STUFF ###
b_in=pref[:-2]+".toar."
b_clouds=pref[:-2]+".toar.acca"
print "Clouds:\t\t>",b_clouds
i.landsat_acca(input_prefix=b_in,output=b_clouds,overwrite=OVR)
#png_clouds=L7Dir+"/"+pref[:-2]+".clouds.png"
#d.mon(start='png',output=png_clouds,width=800,height=800)
print "MASK:\t\tON"
#Should always be rewritten!
r.mask(raster=b_clouds,flags="i",overwrite=True)

b_ndvi=pref[:-2]+".surf.ndvi"
print "NDVI:\t",b_ndvi
i.vi(red=b3,nir=b4,output=b_ndvi,viname="ndvi",quiet=QIET,overwrite=OVR,finish_=False)

b_in=[b1,b2,b3,b4,b5,b7]
b_albedo=pref[:-2]+".surf.albedo"
print "Albedo:\t",b_albedo
i.albedo(input=b_in,output=b_albedo,flags="lc",quiet=QIET,overwrite=OVR,finish_=False)

b_emissivity=pref[:-2]+".surf.emissivity"
print "Emissivity:\t",b_emissivity
i.emissivity(input=b_ndvi, output=b_emissivity,quiet=QIET,overwrite=OVR,finish_=False)
</source>

=== Multiprocessing example: parallelized SHAPE file import ===

<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Multiprocessing example: parallelized SHAPE file import

Created on Fri, Oct 18, 2013, posted to grass-user@lists.osgeo.org

@author: Pietro Zambelli, freely inspired by: http://stackoverflow.com/a/16071616
http://lists.osgeo.org/pipermail//grass-user/2013-October/069130.html
"""

# Directory containing SHAPE files to import
DIR = '/data/shp'

###
from multiprocessing import Queue, Process, cpu_count
from os.path import split
from subprocess import Popen

from grass.pygrass.functions import findfiles

def spawn(func):
def fun(q_in, q_out):
while True:
path, cmdstr = q_in.get()
if path is None:
break
q_out.put(func(path, cmdstr))
return fun

def mltp_importer(dirpath, match, cmdstr, func, nprocs=cpu_count()):
q_in = Queue(1)
q_out = Queue()
procs = [Process(target=spawn(func), args=(q_in, q_out))
for _ in range(nprocs)]
for proc in procs:
proc.daemon = True
proc.start()

# set the parameters
sent = [q_in.put((path, cmdstr)) for path in findfiles(dirpath, match)]
# set the end of the cycle
[q_in.put((None, None)) for proc in procs]
[proc.join() for proc in procs]
return [q_out.get() for _ in range(len(sent))]

def importer(path, cmdstr):
name = split(path)[-1][:-4]
print name
popen = Popen(cmdstr.format(path=path, name=name), shell=True)
popen.wait()
return path, name, False if popen.returncode else True

CMD = 'v.in.ogr dsn={path} layer={name} output={name}'

processed = mltp_importer(DIR, '*.shp', CMD, importer)
# check for errors
errors = [p for p in processed if not p[2]]
if errors:
# do something (print list of failed SHP files at end)
pass
</source>

{{Python}}

Python/pygrass

2016-03-29T09:42:55Z

⚠️Pietro: /* Interface to listing maps (g.list/g.mlist) */

''PyGRASS'' is a library that extends the GRASS GIS 7 capabilities to allow users to access the low-level GRASS API.

== Documentation ==

Detailed PyGRASS documentation: http://grass.osgeo.org/grass71/manuals/libpython/

== How to test library ==

''pygrass'' has 'doctest' included in its code. You can run doctest in the [http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz North Carolina basic location], using the mapset '''user1'''.

To test a single module (file) you have to change into the source code directory of pygrass and run the following code (this is an example of functions.py):

<source lang="bash">
python -m doctest functions.py
</source>

== References ==

* Zambelli, P., Gebbert, S., Ciolli, M., 2013. ''Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)''. ISPRS International Journal of Geo-Information 2, 201–219. ([http://dx.doi.org/10.3390/ijgi2010201 DOI] | [http://www.mdpi.com/2220-9964/2/1/201/pdf PDF])

* [http://grass.osgeo.org/grass71/manuals/libpython/ pyGrass documentation] (updated weekly from SVN)

== Sample PyGRASS scripts ==

=== Training material ===

Two workshops were presented during the [http://geomorfolab.arch.unige.it/genova2013/ XIV Italian meeting of GRASS] at Genova.
The workshops use '''ipython notebook''' to show the python and pygrass API, all the material are available on github ([https://github.com/zarch/workshop-python python], [https://github.com/zarch/workshop-pygrass pygrass]). All the execute examples are reported here:

* python training (Genova)
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/03_function.ipynb Function]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/04_class.ipynb Class]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/05_other.ipynb Other]

* python training (EURAC)
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/03_version_control_system.ipynb Version Control System (hg)]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/04_objects.ipynb Objects]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/05_python_debugger.ipynb Debugger]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/06_functions.ipynb Functions]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/07_numpy.ipynb Numpy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/08_matplotlib.ipynb Matplotlib]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/09_scipy.ipynb Scipy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/10_pandas.ipynb Pandas]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/11_sympy.ipynb Sympy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/12_user_interfaces.ipynb GUI]

* pygrass training
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/00_Modules.ipynb Modules]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/01_GIS_objects.ipynb GIS]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/02_Vector.ipynb Vector]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/03_Raster.ipynb Raster]

=== Interface to listing maps (g.list/g.mlist) ===

Here we call a GRASS module that writes to stdout and do not call a Python function that returns a Python object, therefore we can save stdout and then parse it with:

<source lang="python">
from grass.pygrass.modules.shortcuts import general as g
import subprocess as sub

gl = g.list # GRASS 7
gl(type='raster', pattern='elev-*', stdout=sub.PIPE)
gl.outputs.stdout.split()
['elev-000-000', 'elev-000-001', 'elev-000-002', 'elev-001-000',
'elev-001-001', 'elev-001-002', 'elev-002-000', 'elev-002-001',
'elev-002-002']
</source>

or you can use the "glist" method of the Mapset class:

<source lang="python">
from grass.pygrass.gis import Mapset
m = Mapset()
m.glist('rast', pattern='elev-*')
['elev-002-000', 'elev-000-000', 'elev-000-002', 'elev-000-001',
'elev-001-001', 'elev-002-002', 'elev-002-001', 'elev-001-000',
'elev-001-002']
</source>

... that uses the "G_list" function through ctypes and therefore is faster.

Note: If you choose the first solution it is better if you use directly the
function in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped() etc.].

=== Interface to copying maps (g.copy) ===
<source lang="python">
from grass.pygrass.modules.shortcuts import general as g

vectinmap = 'zipcodes_wake'
vectoutmap = 'zip_elev_zonal'
g.copy(vect="%s,%s" % (vectinmap,vectoutmap) )
</source>

=== Sample script for opening, query and closing of a vector map ===

<source lang="python">
#!/usr/bin/env python

# Example for pyGRASS usage - vector API

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.vector import VectorTopo

g.message("Assessing vector topology...")

vectmap = 'zipcodes_wake'
zipcodes = VectorTopo(vectmap)

# Open the map with topology:
zipcodes.open()

# query number of topological features
areas = zipcodes.number_of("areas")
islands = zipcodes.number_of("islands")
print 'Map: <' + vectmap + '> with %d areas and %d islands' % (areas, islands)

# http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html
# (note that above documentation is slightly outdated)
dblink = zipcodes.dblinks[0]
print 'DB name:'
print dblink.database
table = dblink.table()
print 'Column names:'
print table.columns.names()
print 'Column types:'
print table.columns.types()

zipcodes.close()
</source>

=== Sample script for Landsat 7 processing ===

<source lang="python">
#!/usr/bin/env python
#Date: 7th February, 2013
#Public domain, GRASS GIS

#Run this script in the terminal as:
#python python-grass.py
#For debugging, run as:
#python -i python-grass.py
#PURPOSE
#This script processes LANDSAT 7 ETM+ images
#1 - unzip *.gz files
#2 - import files in GRASS GIS Location of your choice (r.in.gdal)
#3 - DN to Top of Atmosphere reflectance (i.landsat.toar)
#4 - TOA reflectance to Surface reflectance (i.atcorr)
#5 - NDVI (i.vi), Albedo (i.albedo), Emissivity (i.emissivity)

#USER HAS TO SET THOSE
#QUIET REPORTS
QIET=True
#OVERWRITE EXISTING FILES
OVR=False
#Define Landsat 7 sensor for i.landsat.toar
LSENSOR="tm7"
#Setup the path to the Landsat 7 Directories
rsdatapath="/home/yann/RSDATA/Myanmar/L7"
#Setup your GRASS GIS working directory
gisdb="/home/yann/GRASSDATA"
location="L7_Myanmar"
print location
mapset="PERMANENT"
#DEM input to atmospheric correction
inDEM=rsdatapath+"/dem.tif"
#set L7 Metadata wildcards
wldc_mtl="*_MTL.txt"
#wldc_met="*.met"
#Visibility distance [Km]
vis=18

#Set python path to enable finding of grass.script lib

#END OF USER CHANGES
###DO NOT CHANGE ANYTHING AFTER THIS LINE !
###
#Load necessary libraries
import os, glob, time, re
from grass import script as g
from grass.script import setup as gsetup
gisbase=os.environ['GISBASE']
gsetup.init(gisbase,gisdb,location,mapset)
from grass.pygrass.modules.shortcuts import raster as r
from grass.pygrass.modules.shortcuts import imagery as i
from grass.pygrass.modules.shortcuts import display as d
#Needed for floor()
from math import *
#env = os.environ.copy()
#env['GRASS_MESSAGE_FORMAT'] = 'gui'
#Function to get a list of L7 Directories in the rsdatapath
def fn(path):
for top, dirs, files in os.walk(path):
return [os.path.join(top, dir) for dir in dirs]

#START PROCESS
### PART 0: PRE-PROCESSING STUFF ###
#import DEM for atmospheric correction
#r.in.gdal(input=inDEM,output="dem",overwrite=OVR)
#r.mapcalc(expression="dem=25",overwrite=OVR)
#create a visibility map
r.mapcalc(expression="vis=18",overwrite=OVR)
#Find the central location of the Landsat file from metadata
metadata=[]
fileList=[]
L7Dirs=fn(rsdatapath)
for L7Dir in L7Dirs:
#Ungzip all of your Landsat7 images in all your directories
# print "Ungzip Landsat files in\t",L7Dir
# p=os.system("gzip -d -q "+L7Dir+"/*.gz")
#Using pthreads on multi-core machines
#p=os.system("pigz -d "+L7Dir+"/*.gz")
#Wait ten seconds for gzip to create the tif images
# time.sleep(10)
print "Import in GRASS GIS"
for L7f in glob.glob(os.path.join(L7Dir,"*.[tT][iI][fF]")):
f1=L7f.replace(L7Dir+"/","")
f2=f1.replace(".TIF","")
f3=f2.replace("_B10",".1")
f4=f3.replace("_B20",".2")
f5=f4.replace("_B30",".3")
f6=f5.replace("_B40",".4")
f7=f6.replace("_B50",".5")
f8=f7.replace("_B61",".61")
f9=f8.replace("_B62",".62")
f10=f9.replace("_B70",".7")
f11=f10.replace("_B80",".8")
f12=f11.replace("L72","L71")
L7r=f12.replace("_VCID_","")
print "\t> ",L7r
r.in_gdal(input=L7f,output=L7r,flags="e",overwrite=OVR)
fileList.append(L7r)

#reproject the DEM World map for the new PERMANENT location extents
r.proj(input="dem",location="Myanmar",memory=10000,resolution=90.0,overwrite=OVR)
#Get list of metadata files
for metaf in glob.glob(os.path.join(L7Dir,wldc_mtl)):
metadata.append(metaf)
print "Metadata in:\n",metadata[0]
with open(metadata[0],"r") as f:
data=f.read()

f.close()
dt=data.split("\n")
for idx in range(len(dt)):
found=dt[idx].find("CORNER_UL_LON_PRODUCT = ")
if found > 0:
ulx=float(dt[idx].replace("CORNER_UL_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_UL_LAT_PRODUCT = ")
if found > 0:
uly=float(dt[idx].replace("CORNER_UL_LAT_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LON_PRODUCT = ")
if found > 0:
lrx=float(dt[idx].replace("CORNER_LR_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LAT_PRODUCT = ")
if found > 0:
lry=float(dt[idx].replace("CORNER_LR_LAT_PRODUCT = ",""))
#Two cases, because a string starting by 0 is not converted well
found=dt[idx].find("SCENE_CENTER_TIME = ")
if found > 0:
tim=dt[idx].replace("SCENE_CENTER_TIME = ","")
print "timestamp=",str(tim)
gmth=float(tim.split(":")[0])
gmtm=float(tim.split(":")[1])
gmtdec=float(tim.split(":")[2].replace("Z",""))
print gmth,gmtm,gmtdec
found=dt[idx].find("DATE_ACQUIRED = ")
if found > 0:
dat=dt[idx].replace("DATE_ACQUIRED = ","")
date=dat.split("-")
found=dt[idx].find("SUN_ELEVATION = ")
if found > 0:
sunza=90-float(dt[idx].replace("SUN_ELEVATION = ",""))

#L7 DN->Rad->Ref
print "Convert DN to Rad to TOARef"
f1=sorted(fileList)[0]
f2=f1.replace(L7Dir+"/","")
pref=f2[:-1]
outpref=pref[:-2]+".toar."
print "Prefix IN:\t",pref
print "Prefix OUT:\t", outpref
i.landsat_toar(input_prefix=pref,output_prefix=outpref,metfile=metadata[0],sensor=LSENSOR,quiet=QIET,overwrite=OVR)
#Atmospheric Correction
print "Atmospheric Correction"
# Basic script for i.atcorr for L 7 ETM+
#Geometrical conditions (L7ETM+)
geom=7
#Sensor height (satellite is -1000)
sens_height=-1000
#Here we suppose you have altitude (DEM) and Visibility (VIS) maps ready
#---------------------------------------------
#Visibility dummy value (overwritten by VIS raster input)
vis=15
#Altitude dummy value (in Km should be negative in this param file)
#(overwritten by DEM raster input)
alt=-1.200
#datetime of satellite overpass (month, day, GMT decimal hour)
mdh=str(int(date[1]))+" "+str(int(date[2]))+" "+str("%.2f" % (gmth+gmtm/60.0+gmtdec/3600.0))
print "MM DD hh.ddd:\t",mdh
# Central Lat/Long
Long=ulx+(lrx-ulx)/2.0
Lat=lry+(uly-lry)/2.0
print "Center:\t(",Long, ",", Lat,")"
#Atmospheric mode
atm_mode=1 #Tropical
#Aerosol model
aerosol_mode=2 #Sri Lanka is a small island (maritime)
#satellite band number (L5TM [25,26,27,28,29,30], L7ETM+ [61,62,63,64,65,66,67])
satbandno=61 #Band 1 of L7ETM+ is first to undergo atmospheric correction
#make time stamp for use in time series analysis
dat1=str(date[2])+"-"+str(date[1])+"-"+str(date[0])
dat=dat1.replace(" ","")
timestamp=time.strftime("%d %b %Y",time.strptime(dat,"%d-%m-%Y"))
print "Timestamp:\t",timestamp
for idx in [1,2,3,4,5,7]:
b=pref[:-2]+".toar."+str(idx)
b_out=b.replace(".toar.",".surf.")
param=[]
param.append(str(geom)+" - geometrical conditions=Landsat 7 ETM+\n")
param.append(str(mdh)+" "+str("%.2f" % Long)+" "+str("%.2f" % Lat)+" - month day hh.ddd longitude latitude (hh.ddd is in decimal hours GMT)\n")
param.append(str(atm_mode)+" - atmospheric mode=tropical\n")
param.append(str(aerosol_mode)+" - aerosols model=maritime\n")
param.append(str(vis)+" - visibility [km] (aerosol model concentration), not used as there is raster input\n")
param.append(str(alt)+" - mean target elevation above sea level [km] (here 600m asl), not used as there is raster input\n")
param.append(str(sens_height)+" - sensor height (here, sensor on board a satellite)\n")
param.append(str(satbandno)+" - i th band of ETM+ Landsat 7 (atcorr internal no)\n")
f=open(os.path.join(L7Dir,"param_L7.txt"),"w")
f.writelines(param)
f.close()
prm=os.path.join(L7Dir,"param_L7.txt")
print "\t> ",b
print "\t> ",b_out
i.atcorr(input=b, elevation="dem", visibility="vis", parameters=prm, output=b_out, flags="ra", range=[0,1],quiet=QIET,overwrite=OVR)
r.timestamp(map=b_out,date=timestamp,finish_=False)
satbandno = satbandno + 1

#Allocate surface reflectance names
b1=pref[:-2]+".surf.1"
b2=pref[:-2]+".surf.2"
b3=pref[:-2]+".surf.3"
b4=pref[:-2]+".surf.4"
b5=pref[:-2]+".surf.5"
b61=pref[:-2]+".toar.61"
b62=pref[:-2]+".toar.62"
b7=pref[:-2]+".surf.7"
b8=pref[:-2]+".surf.8"

### PART 1: BASIC STUFF ###
b_in=pref[:-2]+".toar."
b_clouds=pref[:-2]+".toar.acca"
print "Clouds:\t\t>",b_clouds
i.landsat_acca(input_prefix=b_in,output=b_clouds,overwrite=OVR)
#png_clouds=L7Dir+"/"+pref[:-2]+".clouds.png"
#d.mon(start='png',output=png_clouds,width=800,height=800)
print "MASK:\t\tON"
#Should always be rewritten!
r.mask(raster=b_clouds,flags="i",overwrite=True)

b_ndvi=pref[:-2]+".surf.ndvi"
print "NDVI:\t",b_ndvi
i.vi(red=b3,nir=b4,output=b_ndvi,viname="ndvi",quiet=QIET,overwrite=OVR,finish_=False)

b_in=[b1,b2,b3,b4,b5,b7]
b_albedo=pref[:-2]+".surf.albedo"
print "Albedo:\t",b_albedo
i.albedo(input=b_in,output=b_albedo,flags="lc",quiet=QIET,overwrite=OVR,finish_=False)

b_emissivity=pref[:-2]+".surf.emissivity"
print "Emissivity:\t",b_emissivity
i.emissivity(input=b_ndvi, output=b_emissivity,quiet=QIET,overwrite=OVR,finish_=False)
</source>

=== Multiprocessing example: parallelized SHAPE file import ===

<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Multiprocessing example: parallelized SHAPE file import

Created on Fri, Oct 18, 2013, posted to grass-user@lists.osgeo.org

@author: Pietro Zambelli, freely inspired by: http://stackoverflow.com/a/16071616
http://lists.osgeo.org/pipermail//grass-user/2013-October/069130.html
"""

# Directory containing SHAPE files to import
DIR = '/data/shp'

###
from multiprocessing import Queue, Process, cpu_count
from os.path import split
from subprocess import Popen

from grass.pygrass.functions import findfiles

def spawn(func):
def fun(q_in, q_out):
while True:
path, cmdstr = q_in.get()
if path is None:
break
q_out.put(func(path, cmdstr))
return fun

def mltp_importer(dirpath, match, cmdstr, func, nprocs=cpu_count()):
q_in = Queue(1)
q_out = Queue()
procs = [Process(target=spawn(func), args=(q_in, q_out))
for _ in range(nprocs)]
for proc in procs:
proc.daemon = True
proc.start()

# set the parameters
sent = [q_in.put((path, cmdstr)) for path in findfiles(dirpath, match)]
# set the end of the cycle
[q_in.put((None, None)) for proc in procs]
[proc.join() for proc in procs]
return [q_out.get() for _ in range(len(sent))]

def importer(path, cmdstr):
name = split(path)[-1][:-4]
print name
popen = Popen(cmdstr.format(path=path, name=name), shell=True)
popen.wait()
return path, name, False if popen.returncode else True

CMD = 'v.in.ogr dsn={path} layer={name} output={name}'

processed = mltp_importer(DIR, '*.shp', CMD, importer)
# check for errors
errors = [p for p in processed if not p[2]]
if errors:
# do something (print list of failed SHP files at end)
pass
</source>

{{Python}}

FOSS4G Europe 2015: GRASS related workshops and presentations

2015-08-18T08:33:43Z

⚠️Pietro: add presentation from EURAC and UNITN

== Introduction ==

FOSS4G Europe 2015, Como, Italy in July 14th-17th 2015, http://europe.foss4g.org/2015/

== Workshops ==

* Zambelli, P., Neteler, M., Delucchi, L., Petras, V., Petrasova, A., 2015: [https://github.com/wenzeslaus/python-grass-addon How to write a Python GRASS GIS 7 addon]. Workshop at [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy ([http://europe.foss4g.org/2015/Workshops in program])

== Presentations ==

* Garegnani G., Zambelli P., Grilli G. Vettorato D. (2015): ''Evaluation of wind, solar and hydro energy potential using GRASS''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy.

* Garegnani G., Geri F., Zambelli P., Grilli G., Sacchelli S., Paletto A., Curetti G. Ciolli M., Vettorato D. (2015): ''A new open source DSS for assessment and planning of renewable energy: r.green''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy.

* Mezzini, E., Antisari, L. V., Ventura, F., Magnan, F. (2015): ''[https://drive.google.com/open?id=0B46kztqdEkOHUnlyZWZzUllPM2s RUSLE model application with GRASS GIS: Rio Centonara catchment]''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy.

* Mitasova, H., Jeziorska, J., Petrasova, A., Petras V., Zajkowski, T. (2015): ''[http://ncsu-osgeorel.github.io/uav-talk Flow analysis using sUAS and lidar data]''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy.

* Pareeth, S., Delucchi, L., Metz, M., Salmaso, N., Neteler, M. (2015): An open source framework for processing daily satellite images (AVHRR) over last 28 years. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy. ([http://geomatica.como.polimi.it/workbooks/n12/FOSS4G-eu15_submission_137.pdf Abstract])

* Petras V., Petrasova, A., Cepero-Perez, K., Neteler, M., Delucchi, L., Landa, M., Mitasova, H. (2015): ''[https://drive.google.com/open?id=0B46kztqdEkOHX3g4QUlyME4tYXc Using Free and Open Source Solutions in Geospatial Science Education]''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy. ([http://wenzeslaus.github.io/foss-in-geospatial-science-education/ alternative location], [https://github.com/wenzeslaus/foss-in-geospatial-science-education source code for slides])

* Petrasova, A., Petras V., Shoemaker, D. A., Dorning, M. A., Meentemeyer, R. K. (2015): ''[https://drive.google.com/open?id=0B46kztqdEkOHSXhBRG8wOXllZVE The integration of land change modeling framework FUTURES in GRASS GIS 7]''. [http://europe.foss4g.org/2015/ FOSS4G Europe 2015], 14-17 Jul 2015, Como, Italy.

== Code sprint ==

* 18 July: FOSS4G EU 2015 Code Sprint
* 19-22 July: GRASS Community Sprint

See details at [[GRASS Community Sprint Como 2015]] and [[Talk:GRASS Community Sprint Como 2015]].

[[Category: Workshops]]

User:Pietro

2014-09-27T15:45:39Z

⚠️Pietro: add extra ideas on grass and sphinx docs

Pietro Zambelli is ph.D. student of University of Trento, in April 2012 proposed a GSoC on [[GRASS_SoC_Ideas_2012/High_level_map_interaction | High level map interaction ]].

== TO DO ==

* Write email about GRASS8 and HDF5
* Try to move GRASS from SVN to GIT using [http://subgit.com/ SubGit]
* Rewrite pygrass.vector, split primary from topological features
* start porting GRASS to python3
* waiting ipython 4.0 to implement ipython interfaces and facilities for GRASS, see the ipython [https://github.com/ipython/ipython/wiki/Roadmap:-IPython roadmap].
* Remove RasterNumpy class
* Go on to implement the raster interface with [http://cython.org/ Cython] and do a benchmark
* try to substitute the make system with [https://jpakkane.github.io/meson/ Meson]
* i.segment add auto find threshold if given some draw segments
* add the sphinx numpydoc extension to remove/hide docstring characters and output from the doc, to make easier to copy and paste.
could be great have also a live terminal such as in sympy with a http://live.sympy.org/.
* split the sphinx doc in sub-documents.

User:Pietro

2014-09-20T13:36:23Z

⚠️Pietro: /* TO DO */

User:Pietro

2014-09-18T14:06:52Z

⚠️Pietro: to not forget ideas

R statistics

2014-07-07T13:27:15Z

⚠️Pietro: /* GRASS 6: calling GRASS from R: add a less trivial example */

'''Q:''' How do I enjoy high quality statistic analysis in GRASS?

'''A:''' Well, GRASS has got an interface to the most powerful statistics analysis package around: '''''R''''' (http://www.r-project.org)
: The [http://cran.r-project.org/web/packages/spgrass6/ '''spgrass6'''] ''R'' addon package provides the R ←→ GRASS interface.

Using R in GRASS GIS directly has two meanings:

* The '''first''' is that R is run "on top of" GRASS, transferring GRASS data to R to run statistical functions on the imported data as R objects in memory, and possibly transfer the results back to GRASS.
* The '''second''' is to leave the data mostly in GRASS, and to use R as a scripting language "on top of" GRASS with execGRASS() - in this case, little data is moved to R, so memory constraints are not important, but R functionality is available.

=== Quick start ===

For the impatient just start it:

> R

#and install packages directly from the net
pkgs <- c('akima', 'spgrass6', 'RODBC', 'VR', 'gstat')

install.packages(pkgs, dependencies=TRUE, type='source')

or to get all packages for spatial analysis in one:

> R

#To automatically install the spatial task view, the ctv package needs to be installed, e.g., via
install.packages("ctv")
library("ctv")

install.views("Spatial")
#or
update.views("Spatial")

Once you have '''''R''''' and '''''spgrass6''''' on your system, have a look at this tutorial:
: http://grassold.osgeo.org/statsgrass/grass_geostats.html (from 2001)

=== Installation ===

First of all you need to install '''''R''''' onto your system.

R and many of its addon packages are pre-built and distributed through the CRAN network of mirrors. In addition many Linux distributions prepackage R and a number of the most popular addon toolboxes.

All the necessary functions for the GRASS 6 interface are now in packages on CRAN, so that on Linux/Unix (or Mac OSX) installing '''rgdal''' from source with PROJ4 and GDAL installed, or Windows installing from binary, the required packages are: '''sp'''; '''maptools''' (now includes spmaptools); '''rgdal''' (now includes spGDAL, spproj); '''spgrass6''' - now all on CRAN.

==== Source packages ====

From the R console first pick a local mirror:
chooseCRANmirror()

you can then see what it picked with
options("repos")

To permanently save the mirror site add it to <tt>~/.Rprofile</tt>. For example:
options(repos=c(CRAN="<nowiki>http://cran.stat.auckland.ac.nz</nowiki>"))

and then run <tt>install.packages()</tt> as in the Quick Start section above.

For more information see http://cran.r-project.org/doc/manuals/R-admin.html

==== Linux ====

===== Debian and Ubuntu =====

''R'' and a number of pre-build cran packages are already present in the main repositories. Start with:

# apt-get install r-base r-cran-vr r-cran-rodbc r-cran-xml

Once those are installed start "<tt>R</tt>" at the command prompt and install the libraries not packaged by the OS:
: ''n.b. <tt>r-cran-sp</tt> is now shipped as an official Debian/Ubuntu package and can be installed with <tt>apt</tt> as above''

install.packages("sp")
install.packages("gstat")

Debian/Lenny ships with ''R'' 2.7.1 which is too old for the modern ''rgdal'' package. So we have to fetch an old one from the archive and build it from the Linux command line:
$ wget http://cran.r-project.org/src/contrib/Archive/rgdal/rgdal_0.6-24.tar.gz
$ R CMD INSTALL -l /usr/local/lib/R/site-library rgdal_0.6-24.tar.gz

If you are using a newer version of R than that you can install the ''rgdal'' CRAN package directly:
install.packages("rgdal")

And finally, back inside the ''R'' session:
install.packages("spgrass6")

* [http://cran.r-project.org/bin/linux/debian/README Debian] and [http://cran.r-project.org/bin/linux/ubuntu/README Ubuntu] specific help is also available from the R-project website.

You can also use the CRAN Debian package repository: (pick one; adjust distribution as needed [here "Debian/testing"])
deb http://debian.cran.r-project.org/cran2deb/debian-i386 testing/
deb http://debian.cran.r-project.org/cran2deb/debian-amd64 testing/

===== RPM based =====

* '''RedHat, Fedora, openSuse, Mandriva''' and similar distros: take the latest '''''R''''' RPM and install it

''R'' and a number of pre-build cran packages are already present in the main repositories. Start with:

# su
# yum install R-core R-core-devel R-XML
# exit

Once those are installed, start as normal user "<tt>R</tt>" at the command prompt and install the libraries not packaged by the distro provider:

<source lang="bash">
R
install.packages("spgrass6", dependencies = TRUE)
</source>

'''Usage:''' You have the best user experience if you launch R within a running GRASS GIS session (then R automatically recognises the current settings of the [[Computational region]] and "sees" the GRASS maps).

==== Mac OSX ====

Start a R session, then

* for install.packages() you might have to rely on building packages from source code. try:
<source lang="bash">
R
install.packages("spgrass6", type="source", dependencies = TRUE)
</source>

'''Startup of GRASS from within R:'''

First you need to find the path to the GRASS binaries: Control-click on the GRASS.app and you'll get a popup menu; select "Show Package Contents" - this opens you to the directory structure. Go to Contents->MacOS which would be "GISBASE"; So, in my case, the "gisBase" parameter is "/HD/Applications/Grass-6.4/Contents/MacOS". If you Command-click at the top of the window on the folder icon beside "MacOS" (from the line above this one), you can see the full path.

Now we can run GRASS from within a R session:

<source lang="bash">
initGRASS(gisBase ='/Applications/GRASS/GRASS-6.4.app/Contents/MacOS',
location = 'geostat2012_ll', mapset = 'user1',
gisDbase = '/Users/Lars/Documents/Biologi/grassdata', override = TRUE)
</source>

===== Troubleshooting =====
If you get an error message when trying to call GRASS from R containing this line: dyld: Library not loaded: /usr/local/lib/libintl.8.dylib you need to establish a link from /Applications/Grass/GRASS-7.0.app/Contents/MacOS/lib/libintl.8.dylib to /usr/local/lib. This can be done through Terminal with the command:

<source lang="bash">
sudo ln -s /Applications/Grass/GRASS-7.0.app/Contents/MacOS/lib/libintl.8.dylib /usr/local/lib/
</source>

Note: The path to the GRASS-x.x.app must reflect your own configuration.

==== MS Windows ====

===== Installation =====
Run:
install.packages("spgrass6", dependencies = TRUE)

or install Task View 'Spatial' - Analysis of Spatial Data
install.packages("ctv")
library("ctv")
install.views("Spatial")

===== GRASS 6: Calling R from GRASS =====
On Windows, the easiest way is calling R in a running GRASS 6 session by specifying the full path to the R startup executable. Note that all "\" must be changed to "/", furthermore quote white spaces in the path:

GRASS 6.4> C:/Users/"Catherine user"/Documents/R/R-2.15.1/bin/i386/R.exe
R version 2.15.1 (2012-06-22) -- "Roasted Marshmallows"
...
library(spgrass6)

In some cases, you can use this path:
- For 32 bits: <source lang="bash">C:/"Program Files"/R/R-2.15.1/bin/i386/R.exe --save</source>
- For 64 bits: <source lang="bash">C:/"Program Files"/R/R-2.15.1/bin/x64/R.exe --save</source>

The best solution is then to add this path to the %PATH% entry in the grass64.bat-starting script.

===== GRASS 6: calling GRASS from R =====
On Windows, the second easiest way is calling GRASS from R with ''initGRASS()'' from the R package spgrass6(). After GRASS has been initialized for R, you have access to GRASS commands from within R (you may need to adjust the path):

spgrass6()
loc <- initGRASS("C:\\Program Files\\GRASS 6.4", home=tempdir())

or using an already existing mapset:

spgrass6()
loc <- initGRASS(gisBase="C:\\Program Files\\GRASS 6.4",
gisDbase = "'C:\\Users\\netler\\Documents\\grassdata'",
location = "spearfish60", mapset = "user1", SG="elevation.dem",
override = TRUE)

For an example, see http://geomorphometry.org/content/geomorphometry-r-saga-ilwis-grass

===== GRASS 6 Usage III (taken from the grass-stats-ML) =====

http://lists.osgeo.org/pipermail/grass-stats/2010-September/001274.html

at the moment there is following for a Grass-R-connection implemented in WinGRASS 64

(1) the WinGrass64-installer searches during installation for a installed R and writes -
if found - the R-installation-path to %PATH% in the grass64.bat-starting script
(see http://trac.osgeo.org/grass/browser/grass/branches/develbranch_6/mswindows/GRASS-Installer.nsi#L660)

--> this means that you FIRST have to install R and then winGRASS!

(2) you can start "GRASS-command-line" - it's a windows-command-line, not a msys-rxvt-terminal
(you can find this starting option under Programs -> GRASS64 -> Grass command line; but not as a desktop icon)

with this starting option you start a Grass-session in the good old text mode.
if you type R in the command line, then you start R inside a GRASS-session like in Linux.

===== GRASS 7 Usage =====

In WinGRASS 7 ([http://grass.osgeo.org/download/software.php#g70x standalone installer]) the [http://code.google.com/p/batchfiles/ Windows batchfiles for use with R] are now integrated for a smooth WinGRASS-R-integration. The R-installation-path is dynamically loaded into PATH.

Following R starting options are availabe:

* R cd - cd to R_ROOT, typically to C:\Program Files\R (0)
* R cmd - Run Rcmd.exe
* R dir - List contents of R_ROOT in chronological order showing R versions (0)
* R gui - Run Rgui.exe
* R help - Help info (0)
* R path - Add R_TOOLS, R_MIKTEX & R_PATH to path for this cmd line session (0)
* R Run R.exe (0)
* R script - Run Rscript.exe
* R show - Show R_ variable values used. R_PATH, etc. (0)
* R SetReg - Run RSetReg; see 2.17 in R FAQ for Windows (A)
* R tools - Add R_TOOLS and R_MIKTEX to path for this cmd line session (0)
* R touch - Change date on R_HOME to now (0) (A)

Start WinGRASS 7, bring the WinGRASS-windows console in front and type ''R'' for opening a R-session (command line mode) inside a GRASS-session.

[[Image:wingrass7_R_integration.png|600px|center]]

Start WinGRASS 7, bring the WinGRASS-windows console in front and type ''R gui'' for opening a R-session (GUI mode) inside a GRASS-session.

[[Image:wingrass7_RGui_integration.png|600px|center]]

===== Open tickets =====

* Ticket {{trac|1103}} (new enhancement) WinGrass64 - windows-commandline not released: a Grass-session with wxGui, command-line and R inside a Grass-session would be possible (as already does in WinGrass7)
* Ticket {{trac|1149}} (new enhancement) WinGrass - load R-installation-path dynamically into PATH: Wingrass would recognize also an upgraded R-installation (which does not at the moment)

=== Command help ===

Start the ''R'' help browser:
help.start()

* Select '''Packages''' and then '''spgrass6'''.

=== Running ===
: ''by Roger Bivand''

The ''R'' interface for GRASS 5.4 was provided by a CRAN package called ''grass''. Changes going forward to the current GRASS 6 release meant that the interface had to be rewritten, and this provided the opportunity to adapt it to the ''sp'' CRAN package classes. Because GRASS provides the same kinds of data as ''sp'' classes handle, and relies on much of the same open source infrastructure (PROJ.4, GDAL, OGR), this step seemed sensible. Wherever possible ''spgrass6'' tries to respect the [[current region]] in GRASS to avoid handling raster data with different resolutions or extents. ''R'' is assumed to be running within GRASS:

==== Startup ====
* Start GRASS. At the GRASS command line start ''R''.
: ''In this example we will use the sample Spearfish dataset.''

Reset the region settings to the defaults
GRASS> g.region -d

Launch R from the GRASS prompt
GRASS> R

Load the ''spgrass6'' library:
> library(spgrass6)

Get the GRASS environment (mapset, region, map projection, etc.); you can display the metadata for your location by printing G:
> G <- gmeta6()

==== Listing of existing maps ====

List available vector maps:
execGRASS("g.mlist", parameters = list(type = "vect"))

List selected vector maps (wildcard):
execGRASS("g.mlist", parameters = list(type = "vect", pattern = "precip*"))

Save selected vector maps into R vector:
my_vmaps <- execGRASS("g.mlist", parameters = list(type = "vect", pattern = "precip*"))
attributes(my_vmaps)
attributes(my_vmaps)$resOut

List available raster maps:
execGRASS("g.mlist", parameters = list(type = "rast"))

List selected raster maps (wildcard):
execGRASS("g.mlist", parameters = list(type = "rast", pattern = "lsat7_2000*"))

==== Reading in data ====
Read in two raster maps:
> spear <- readRAST6(c("geology", "elevation.dem"),
+ cat=c(TRUE, FALSE), ignore.stderr=TRUE,
+ plugin=NULL)

The metadata are accessed and available, but are not (yet) used to structure the ''sp'' class objects, here a SpatialGridDataFrame object filled with data from two Spearfish layers. Here is a plot of the elevation data:
> image(spear, attr = 2, col = terrain.colors(20))

Add a title to the plot:
> title("Spearfish elevation")

[[Image:R_stats_elev.png|center]]

In addition, we can show what is going on inside the objects read into R:
> '''str(G)'''
<pre>
List of 26
$ GISDBASE : chr "/home/rsb/topics/grassdata"
$ LOCATION_NAME: chr "spearfish57"
$ MAPSET : chr "rsb"
$ DEBUG : chr "0"
$ GRASS_GUI : chr "text"
$ projection : chr "1 (UTM)"
$ zone : chr "13"
$ datum : chr "nad27"
$ ellipsoid : chr "clark66"
$ north : num 4928010
$ south : num 4913700
$ west : num 589980
$ east : num 609000
$ top : num 1
$ bottom : num 0
$ nsres : num 30
$ nsres3 : num 30
$ ewres : num 30
$ ewres3 : num 30
$ tbres : num 1
$ rows : int 477
$ rows3 : int 477
$ cols : int 634
$ cols3 : int 634
$ depths : int 1
$ proj4 : chr "+proj=utm +zone=13 +a=6378206.4 +rf=294.9786982 +no_defs +nadgrids=/home/rsb/topics/grass61/grass-6.1.cvs/etc/nad/conus"
</pre>

> '''summary(spear)'''
<pre>
Object of class SpatialGridDataFrame
Coordinates:
min max
coords.x1 589980 609000
coords.x2 4913700 4928010
Is projected: TRUE
proj4string : [+proj=utm +zone=13 +a=6378206.4 +rf=294.9786982 +no_defs +nadgrids=/home/rsb/topics/grass61/grass-6.1.cvs/etc/nad/conus]
Number of points: 2
Grid attributes:
cellcentre.offset cellsize cells.dim
1 589995 30 634
2 4913715 30 477
Data attributes:
geology elevation.dem
sandstone:74959 Min. : 1066
limestone:61355 1st Qu.: 1200
shale :46423 Median : 1316
sand :36561 Mean : 1354
igneous :36534 3rd Qu.: 1488
(Other) :37636 Max. : 1840
NA's : 8950 NA's :10101
</pre>

==== Summarizing data ====
We can create a table of cell counts:
> '''table(spear$geology)'''
{| class="wikitable" border="1"
!metamorphic
!transition
!igneous
!sandstone
!limestone
!shale
!sandy shale
!claysand
!sand
|-
|11693
|142
|36534
|74959
|61355
|46423
|11266
|14535
|36561
|}

And compare with the equivalent GRASS module:
> '''execGRASS("r.stats", flags=c("c", "l"), parameters=list(input="geology"), ignore.stderr=TRUE)'''
<pre>
1 metamorphic 11693
2 transition 142
3 igneous 36534
4 sandstone 74959
5 limestone 61355
6 shale 46423
7 sandy shale 11266
8 claysand 14535
9 sand 36561
* no data 8950
</pre>

Create a box plot of geologic types at different elevations:
> '''boxplot(spear$elevation.dem ~ spear$geology, medlwd = 1)'''

[[Image:R_stats_boxplot_geo.png|center]]

==== Exporting data back to GRASS ====
Finally, a SpatialGridDataFrame object is written back to a GRASS raster map:

First prepare some data: (square root of elevation)
> spear$sqdem <- sqrt(spear$elevation.dem)

Export data from ''R'' back into a GRASS raster map:
> writeRAST6(spear, "sqdemSP", zcol="sqdem", ignore.stderr=TRUE)

Check that it imported into GRASS ok:
> '''execGRASS("r.info", parameters=list(map="sqdemSP"))'''

<pre>
+----------------------------------------------------------------------------+
| Layer: sqdemSP Date: Sun May 14 21:59:26 2006 |
| Mapset: rsb Login of Creator: rsb |
| Location: spearfish57 |
| DataBase: /home/rsb/topics/grassdata |
| Title: ( sqdemSP ) |
|----------------------------------------------------------------------------|
| |
| Type of Map: raster Number of Categories: 255 |
| Data Type: FCELL |
| Rows: 477 |
| Columns: 634 |
| Total Cells: 302418 |
| Projection: UTM (zone 13) |
| N: 4928010 S: 4913700 Res: 30 |
| E: 609000 W: 589980 Res: 30 |
| Range of data: min = 32.649654 max = 42.895222 |
| |
| Data Source: |
| |
| |
| |
| Data Description: |
| generated by r.in.gdal |
| |
| |
+----------------------------------------------------------------------------+
</pre>

=== Calling GRASS functionality in R batch job ===

To call GRASS functionality within a R batch job, use the initGRASS() function to define the GRASS settings:

library(spgrass6)

# initialisation and the use of spearfish60 data
initGRASS(gisBase = "/usr/local/grass-6.4.1", home = tempdir(),
gisDbase = "/home/neteler/grassdata/",
location = "spearfish60", mapset = "user1", SG="elevation.dem",
override = TRUE)

system("g.region -d")
# verify
gmeta6()

spear <- readRAST6(c("geology", "elevation.dem"),
cat=c(TRUE, FALSE), ignore.stderr=TRUE,
plugin=NULL)

summary(spear$geology)

Run this script with

R CMD BATCH batch.R

The result is (shorted here):

cat batch.Rout

R version 2.10.0 (2009-10-26)
Copyright (C) 2009 The R Foundation for Statistical Computing
ISBN 3-900051-07-0
...
> library(spgrass6)
Loading required package: sp
Loading required package: rgdal
Geospatial Data Abstraction Library extensions to R successfully loaded
Loaded GDAL runtime: GDAL 1.7.2, released 2010/04/23
Path to GDAL shared files: /usr/local/share/gdal
Loaded PROJ.4 runtime: Rel. 4.7.1, 23 September 2009
Path to PROJ.4 shared files: (autodetected)
Loading required package: XML
GRASS GIS interface loaded with GRASS version: (GRASS not running)
>
> # initialisation and the use of spearfish60 data
> initGRASS(gisBase = "/usr/local/grass-6.4.1", home = tempdir(), gisDbase = "/home/neteler/grassdata/",
+ location = "spearfish60", mapset = "user1", SG="elevation.dem", override = TRUE)
gisdbase /home/neteler/grassdata/
location spearfish60
mapset user1
rows 477
columns 634
north 4928010
south 4913700
west 589980
east 609000
nsres 30
ewres 30
projection +proj=utm +zone=13 +a=6378206.4 +rf=294.9786982 +no_defs
+nadgrids=/usr/local/grass-6.4.1/etc/nad/conus +to_meter=1.0
Warning messages:
1: In dir.create(gisDbase) : '/home/neteler/grassdata' already exists
2: In dir.create(loc_path) :
'/home/neteler/grassdata//spearfish60' already exists
>
> system("g.region -d")
> # verify
> gmeta6()
gisdbase /home/neteler/grassdata/
location spearfish60
mapset user1
rows 477
columns 634
north 4928010
...
>
> spear <- readRAST6(c("geology", "elevation.dem"),
+ cat=c(TRUE, FALSE), ignore.stderr=TRUE,
+ plugin=NULL)
>
> summary(spear$geology)
metamorphic transition igneous sandstone limestone shale
11693 142 36534 74959 61355 46423
sandy shale claysand sand NA's
11266 14535 36561 8950
>
>
> proc.time()
user system elapsed
2.891 0.492 3.412

=== GRASS Modules ===

==== v.krige ====

{{cmd|v.krige|version=70}} is a GRASS python script which performs kriging operations in the GRASS environment, using R functions for the back-end interpolation. It is present in GRASS 6.5svn, and further developed in GRASS 7svn. It requires a number of dependencies: '''python-rpy2''' (''needs to be "Rpy2", "Rpy" will not do'' unless it is rpy 2.x), then the following R-CRAN packages:
* gstat, spgrass6 (as above)
install.packages(c("gstat","spgrass6"))
* maptools
install.packages("maptools")
* automap (optional), with gpclib (or rgeos)
install.packages("automap")
install.packages("rgeos")

(''merge further info from man page here'')

=== Getting Support ===

* Primary support for ''R'' + GRASS and the ''spgrass6'' package is through the [http://lists.osgeo.org/mailman/listinfo/grass-stats grass-stats] mailing list.

=== See also ===

* R. Bivand, 2007: [http://spatial.nhh.no/R/etc/FBK07 Interfacing R and OSGeo projects: status and perspectives] (Presentation with slides and scripts)

* http://grass.ibiblio.org/statsgrass/index.php#grassR

* Using GRASS and R: http://grassold.osgeo.org/statsgrass/grass6_r_interface.html

* Connecting R to RDBMS: http://grassold.osgeo.org/statsgrass/r_and_dbms.html

* [http://www.r-project.org R-Statistics homepage]

* [http://r-spatial.sourceforge.net/ R-spatial main web page]

* [http://geodacenter.asu.edu/r-spatial-projects R Spatial Projects at ASU]

* Neural Networks with GRASS and R (posted by Markus Neteler on the grass-user mailing list) http://www.uam.es/proyectosinv/Mclim/pdf/MBenito_EcoMod.pdf

* A detailed example on the use of GRASS and R, with spearfish data: http://casoilresource.lawr.ucdavis.edu/drupal/node/438

* Using R and GRASS with cygwin: It is possible to use Rterm inside the GRASS shell in cygwin, just as in Unix/Linux or OSX. You should not, however, start Rterm from a cygwin xterm, because Rterm is not expecting to be run in an xterm under Windows, and loses its input. If you use the regular cygwin bash shell, but need to start display windows, start X from within GRASS with startx &, and then start Rterm in the same cygwin shell, not in the xterm.

* [http://r-spatial.sourceforge.net/ Spatial data in R] (<code>sp</code>) is a '''''R''''' library that provides classes and methods for spatial data (points, lines, polygons, grids), and to new or existing spatial statistics '''''R''''' packages that use sp, depend on sp, or will become dependent on <code>sp</code>, such as <code>maptools</code>, <code>rgdal</code>, <code>splancs</code>, '''<code>spgrass6</code>''', <code>gstat</code>, <code>spgwr</code> and many others.

* [http://rpy.sourceforge.net/ RPy] - Python interface to the R Programming Language

=== Workshop material ===

* M. Neteler and M. Metz, 2011: ''Introduction to GRASS GIS''. GEOSTAT 2011 Landau. [http://geostat-course.org/Topic_NetelerMetz_2011 Download workshop material] '''(includes a R session)'''

=== Articles ===

* [http://grass.osgeo.org/newsletter/grassnews3.html GRASS News vol.3], June 2005 (R. Bivand. Interfacing GRASS 6 and R. ''GRASS Newsletter'', 3:11-16, June 2005. ISSN 1614-8746).
* [http://www.osgeo.org/journal OSGeo Journal] vol. 1 May 2007 (R. Bivand. Using the R— GRASS interface. ''OSGeo Journal'', 1:31-33, May 2007. ISSN 1614-8746).
* [http://www.grassbook.org GRASS Book, last chapter]

[[Category:Installation]]
[[Category:FAQ]]
[[Category:Linking to other languages]]
[[Category:R]]
[[Category:Statistics]]

Python/pygrass

2014-05-15T09:07:31Z

⚠️Pietro: Add trainign materials on Python

''PyGRASS'' is a library that extends the GRASS GIS 7 capabilities to allow users to access the low-level GRASS API.

== Architecture ==

=== Training material ===

Two workshops were presented during the [http://geomorfolab.arch.unige.it/genova2013/ XIV Italian meeting of GRASS] at Genova.
The workshops use '''ipython notebook''' to show the python and pygrass API, all the material are available on github ([https://github.com/zarch/workshop-python python], [https://github.com/zarch/workshop-pygrass pygrass]). All the execute examples are reported here:

* python (Genova)
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/03_function.ipynb Function]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/04_class.ipynb Class]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/05_other.ipynb Other]

* python (EURAC)
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/03_version_control_system.ipynb Version Control System (hg)]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/04_objects.ipynb Objects]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/05_python_debugger.ipynb Debugger]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/06_functions.ipynb Functions]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/07_numpy.ipynb Numpy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/08_matplotlib.ipynb Matplotlib]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/09_scipy.ipynb Scipy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/10_pandas.ipynb Pandas]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/11_sympy.ipynb Sympy]
** [http://nbviewer.ipython.org/urls/bitbucket.org/zarch/python-course/raw/teacher/12_user_interfaces.ipynb GUI]

* pygrass
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/00_Modules.ipynb Modules]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/01_GIS_objects.ipynb GIS]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/02_Vector.ipynb Vector]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/03_Raster.ipynb Raster]

== How to test library ==

''pygrass'' has doctest inside its code. You can run doctest inside the [http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz North Carolina basic location], using the mapset '''user1'''.

To test the single module (file) you have to move to the source code of pygrass and run the following code (this is an example of functions.py):

<source lang="bash">
python -m doctest functions.py
</source>

=== Already tested modules ===

==== Working ====

The files are found in GRASS GIS 7, lib/python/pygrass/
* functions.py
* gis/region.py
* gis/__init__.py
* modules/__init.py
* vector/abstract.py
* vector/__init__.py
* vector/basic.py
* vector/table.py
* vector/geometry.py
* raster/abstract.py
* ...

See https://svn.osgeo.org/grass/grass/trunk/lib/python/

==== Not working ====

* ...

== References ==

* Zambelli, P., Gebbert, S., Ciolli, M., 2013. ''Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)''. ISPRS International Journal of Geo-Information 2, 201–219. ([http://dx.doi.org/10.3390/ijgi2010201 DOI] | [http://www.mdpi.com/2220-9964/2/1/201/pdf PDF])

* <strike>[http://www.ing.unitn.it/~zambelli/projects/pygrass/ (old) pyGrass documentation]</strike>
* [http://grass.osgeo.org/programming7/pygrass/ pyGrass documentation] (updated weekly from SVN)

== Sample PyGRASS scripts ==

=== Interface to listing maps (g.list/g.mlist) ===
In this case we are calling a GRASS module that write to the stdout and not a Python function that return a Python object, therefore you can save the stdout and then parse it with:

<source lang="python">
from grass.pygrass.modules.shortcuts import general as g
import subprocess as sub
gl = g.mlist
gl(type='rast', pattern='elev-*', stdout=sub.PIPE)
gl.outputs.stdout.split()
['elev-000-000', 'elev-000-001', 'elev-000-002', 'elev-001-000',
'elev-001-001', 'elev-001-002', 'elev-002-000', 'elev-002-001',
'elev-002-002']
</source>

or you can use the "glist" method of the Mapset class:

<source lang="python">
from grass.pygrass.gis import Mapset
m = Mapset()
m.glist('rast', pattern='elev-*')
['elev-002-000', 'elev-000-000', 'elev-000-002', 'elev-000-001',
'elev-001-001', 'elev-002-002', 'elev-002-001', 'elev-001-000',
'elev-001-002']
</source>

that uses the "G_list" function through ctypes and therefore is faster.

If you choose the first solution is better if you use directly the
function in [http://grass.osgeo.org/programming7/namespacepython_1_1script_1_1core.html python.script.core.mlist_grouped() etc.].

=== Sample script for opening, query and closing of a vector map ===

<source lang="python">
#!/usr/bin/env python

# Example for pyGRASS usage - vector API

from grass.pygrass.modules.shortcuts import general as g
from grass.pygrass.vector import VectorTopo

g.message("Assessing vector topology...")

vectmap = 'zipcodes_wake'
zipcodes = VectorTopo(vectmap)

# Open the map with topology:
zipcodes.open()

# query number of topological features
areas = zipcodes.number_of("areas")
islands = zipcodes.number_of("islands")
print 'Map: <' + vectmap + '> with %d areas and %d islands' % (areas, islands)

# http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html
# (note that above documentation is slightly outdated)
dblink = zipcodes.dblinks[0]
print 'DB name:'
print dblink.database
table = dblink.table()
print 'Column names:'
print table.columns.names()
print 'Column types:'
print table.columns.types()

zipcodes.close()
</source>

=== Sample script for Landsat 7 processing ===

<source lang="python">
#!/usr/bin/env python
#Date: 7th February, 2013
#Public domain, GRASS GIS

#Run this script in the terminal as:
#python python-grass.py
#For debugging, run as:
#python -i python-grass.py
#PURPOSE
#This script processes LANDSAT 7 ETM+ images
#1 - unzip *.gz files
#2 - import files in GRASS GIS Location of your choice (r.in.gdal)
#3 - DN to Top of Atmosphere reflectance (i.landsat.toar)
#4 - TOA reflectance to Surface reflectance (i.atcorr)
#5 - NDVI (i.vi), Albedo (i.albedo), Emissivity (i.emissivity)

#USER HAS TO SET THOSE
#QUIET REPORTS
QIET=True
#OVERWRITE EXISTING FILES
OVR=False
#Define Landsat 7 sensor for i.landsat.toar
LSENSOR="tm7"
#Setup the path to the Landsat 7 Directories
rsdatapath="/home/yann/RSDATA/Myanmar/L7"
#Setup your GRASS GIS working directory
gisdb="/home/yann/GRASSDATA"
location="L7_Myanmar"
print location
mapset="PERMANENT"
#DEM input to atmospheric correction
inDEM=rsdatapath+"/dem.tif"
#set L7 Metadata wildcards
wldc_mtl="*_MTL.txt"
#wldc_met="*.met"
#Visibility distance [Km]
vis=18

#Set python path to enable finding of grass.script lib

#END OF USER CHANGES
###DO NOT CHANGE ANYTHING AFTER THIS LINE !
###
#Load necessary libraries
import os, glob, time, re
from grass import script as g
from grass.script import setup as gsetup
gisbase=os.environ['GISBASE']
gsetup.init(gisbase,gisdb,location,mapset)
from grass.pygrass.modules.shortcuts import raster as r
from grass.pygrass.modules.shortcuts import imagery as i
from grass.pygrass.modules.shortcuts import display as d
#Needed for floor()
from math import *
#env = os.environ.copy()
#env['GRASS_MESSAGE_FORMAT'] = 'gui'
#Function to get a list of L7 Directories in the rsdatapath
def fn(path):
for top, dirs, files in os.walk(path):
return [os.path.join(top, dir) for dir in dirs]

#START PROCESS
### PART 0: PRE-PROCESSING STUFF ###
#import DEM for atmospheric correction
#r.in.gdal(input=inDEM,output="dem",overwrite=OVR)
#r.mapcalc(expression="dem=25",overwrite=OVR)
#create a visibility map
r.mapcalc(expression="vis=18",overwrite=OVR)
#Find the central location of the Landsat file from metadata
metadata=[]
fileList=[]
L7Dirs=fn(rsdatapath)
for L7Dir in L7Dirs:
#Ungzip all of your Landsat7 images in all your directories
# print "Ungzip Landsat files in\t",L7Dir
# p=os.system("gzip -d -q "+L7Dir+"/*.gz")
#Using pthreads on multi-core machines
#p=os.system("pigz -d "+L7Dir+"/*.gz")
#Wait ten seconds for gzip to create the tif images
# time.sleep(10)
print "Import in GRASS GIS"
for L7f in glob.glob(os.path.join(L7Dir,"*.[tT][iI][fF]")):
f1=L7f.replace(L7Dir+"/","")
f2=f1.replace(".TIF","")
f3=f2.replace("_B10",".1")
f4=f3.replace("_B20",".2")
f5=f4.replace("_B30",".3")
f6=f5.replace("_B40",".4")
f7=f6.replace("_B50",".5")
f8=f7.replace("_B61",".61")
f9=f8.replace("_B62",".62")
f10=f9.replace("_B70",".7")
f11=f10.replace("_B80",".8")
f12=f11.replace("L72","L71")
L7r=f12.replace("_VCID_","")
print "\t> ",L7r
r.in_gdal(input=L7f,output=L7r,flags="e",overwrite=OVR)
fileList.append(L7r)

#reproject the DEM World map for the new PERMANENT location extents
r.proj(input="dem",location="Myanmar",memory=10000,resolution=90.0,overwrite=OVR)
#Get list of metadata files
for metaf in glob.glob(os.path.join(L7Dir,wldc_mtl)):
metadata.append(metaf)
print "Metadata in:\n",metadata[0]
with open(metadata[0],"r") as f:
data=f.read()

f.close()
dt=data.split("\n")
for idx in range(len(dt)):
found=dt[idx].find("CORNER_UL_LON_PRODUCT = ")
if found > 0:
ulx=float(dt[idx].replace("CORNER_UL_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_UL_LAT_PRODUCT = ")
if found > 0:
uly=float(dt[idx].replace("CORNER_UL_LAT_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LON_PRODUCT = ")
if found > 0:
lrx=float(dt[idx].replace("CORNER_LR_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LAT_PRODUCT = ")
if found > 0:
lry=float(dt[idx].replace("CORNER_LR_LAT_PRODUCT = ",""))
#Two cases, because a string starting by 0 is not converted well
found=dt[idx].find("SCENE_CENTER_TIME = ")
if found > 0:
tim=dt[idx].replace("SCENE_CENTER_TIME = ","")
print "timestamp=",str(tim)
gmth=float(tim.split(":")[0])
gmtm=float(tim.split(":")[1])
gmtdec=float(tim.split(":")[2].replace("Z",""))
print gmth,gmtm,gmtdec
found=dt[idx].find("DATE_ACQUIRED = ")
if found > 0:
dat=dt[idx].replace("DATE_ACQUIRED = ","")
date=dat.split("-")
found=dt[idx].find("SUN_ELEVATION = ")
if found > 0:
sunza=90-float(dt[idx].replace("SUN_ELEVATION = ",""))

#L7 DN->Rad->Ref
print "Convert DN to Rad to TOARef"
f1=sorted(fileList)[0]
f2=f1.replace(L7Dir+"/","")
pref=f2[:-1]
outpref=pref[:-2]+".toar."
print "Prefix IN:\t",pref
print "Prefix OUT:\t", outpref
i.landsat_toar(input_prefix=pref,output_prefix=outpref,metfile=metadata[0],sensor=LSENSOR,quiet=QIET,overwrite=OVR)
#Atmospheric Correction
print "Atmospheric Correction"
# Basic script for i.atcorr for L 7 ETM+
#Geometrical conditions (L7ETM+)
geom=7
#Sensor height (satellite is -1000)
sens_height=-1000
#Here we suppose you have altitude (DEM) and Visibility (VIS) maps ready
#---------------------------------------------
#Visibility dummy value (overwritten by VIS raster input)
vis=15
#Altitude dummy value (in Km should be negative in this param file)
#(overwritten by DEM raster input)
alt=-1.200
#datetime of satellite overpass (month, day, GMT decimal hour)
mdh=str(int(date[1]))+" "+str(int(date[2]))+" "+str("%.2f" % (gmth+gmtm/60.0+gmtdec/3600.0))
print "MM DD hh.ddd:\t",mdh
# Central Lat/Long
Long=ulx+(lrx-ulx)/2.0
Lat=lry+(uly-lry)/2.0
print "Center:\t(",Long, ",", Lat,")"
#Atmospheric mode
atm_mode=1 #Tropical
#Aerosol model
aerosol_mode=2 #Sri Lanka is a small island (maritime)
#satellite band number (L5TM [25,26,27,28,29,30], L7ETM+ [61,62,63,64,65,66,67])
satbandno=61 #Band 1 of L7ETM+ is first to undergo atmospheric correction
#make time stamp for use in time series analysis
dat1=str(date[2])+"-"+str(date[1])+"-"+str(date[0])
dat=dat1.replace(" ","")
timestamp=time.strftime("%d %b %Y",time.strptime(dat,"%d-%m-%Y"))
print "Timestamp:\t",timestamp
for idx in [1,2,3,4,5,7]:
b=pref[:-2]+".toar."+str(idx)
b_out=b.replace(".toar.",".surf.")
param=[]
param.append(str(geom)+" - geometrical conditions=Landsat 7 ETM+\n")
param.append(str(mdh)+" "+str("%.2f" % Long)+" "+str("%.2f" % Lat)+" - month day hh.ddd longitude latitude (hh.ddd is in decimal hours GMT)\n")
param.append(str(atm_mode)+" - atmospheric mode=tropical\n")
param.append(str(aerosol_mode)+" - aerosols model=maritime\n")
param.append(str(vis)+" - visibility [km] (aerosol model concentration), not used as there is raster input\n")
param.append(str(alt)+" - mean target elevation above sea level [km] (here 600m asl), not used as there is raster input\n")
param.append(str(sens_height)+" - sensor height (here, sensor on board a satellite)\n")
param.append(str(satbandno)+" - i th band of ETM+ Landsat 7 (atcorr internal no)\n")
f=open(os.path.join(L7Dir,"param_L7.txt"),"w")
f.writelines(param)
f.close()
prm=os.path.join(L7Dir,"param_L7.txt")
print "\t> ",b
print "\t> ",b_out
i.atcorr(input=b, elevation="dem", visibility="vis", parameters=prm, output=b_out, flags="ra", range=[0,1],quiet=QIET,overwrite=OVR)
r.timestamp(map=b_out,date=timestamp,finish_=False)
satbandno = satbandno + 1

#Allocate surface reflectance names
b1=pref[:-2]+".surf.1"
b2=pref[:-2]+".surf.2"
b3=pref[:-2]+".surf.3"
b4=pref[:-2]+".surf.4"
b5=pref[:-2]+".surf.5"
b61=pref[:-2]+".toar.61"
b62=pref[:-2]+".toar.62"
b7=pref[:-2]+".surf.7"
b8=pref[:-2]+".surf.8"

### PART 1: BASIC STUFF ###
b_in=pref[:-2]+".toar."
b_clouds=pref[:-2]+".toar.acca"
print "Clouds:\t\t>",b_clouds
i.landsat_acca(input_prefix=b_in,output=b_clouds,overwrite=OVR)
#png_clouds=L7Dir+"/"+pref[:-2]+".clouds.png"
#d.mon(start='png',output=png_clouds,width=800,height=800)
print "MASK:\t\tON"
#Should always be rewritten!
r.mask(raster=b_clouds,flags="i",overwrite=True)

b_ndvi=pref[:-2]+".surf.ndvi"
print "NDVI:\t",b_ndvi
i.vi(red=b3,nir=b4,output=b_ndvi,viname="ndvi",quiet=QIET,overwrite=OVR,finish_=False)

b_in=[b1,b2,b3,b4,b5,b7]
b_albedo=pref[:-2]+".surf.albedo"
print "Albedo:\t",b_albedo
i.albedo(input=b_in,output=b_albedo,flags="lc",quiet=QIET,overwrite=OVR,finish_=False)

b_emissivity=pref[:-2]+".surf.emissivity"
print "Emissivity:\t",b_emissivity
i.emissivity(input=b_ndvi, output=b_emissivity,quiet=QIET,overwrite=OVR,finish_=False)
</source>

=== Multiprocessing example: parallelized SHAPE file import ===

<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Multiprocessing example: parallelized SHAPE file import

Created on Fri, Oct 18, 2013, posted to grass-user@lists.osgeo.org

@author: Pietro Zambelli, freely inspired by: http://stackoverflow.com/a/16071616
http://lists.osgeo.org/pipermail//grass-user/2013-October/069130.html
"""

# Directory containing SHAPE files to import
DIR = '/data/shp'

###
from multiprocessing import Queue, Process, cpu_count
from os.path import split
from subprocess import Popen

from grass.pygrass.functions import findfiles

def spawn(func):
def fun(q_in, q_out):
while True:
path, cmdstr = q_in.get()
if path is None:
break
q_out.put(func(path, cmdstr))
return fun

def mltp_importer(dirpath, match, cmdstr, func, nprocs=cpu_count()):
q_in = Queue(1)
q_out = Queue()
procs = [Process(target=spawn(func), args=(q_in, q_out))
for _ in range(nprocs)]
for proc in procs:
proc.daemon = True
proc.start()

# set the parameters
sent = [q_in.put((path, cmdstr)) for path in findfiles(dirpath, match)]
# set the end of the cycle
[q_in.put((None, None)) for proc in procs]
[proc.join() for proc in procs]
return [q_out.get() for _ in range(len(sent))]

def importer(path, cmdstr):
name = split(path)[-1][:-4]
print name
popen = Popen(cmdstr.format(path=path, name=name), shell=True)
popen.wait()
return path, name, False if popen.returncode else True

CMD = 'v.in.ogr dsn={path} layer={name} output={name}'

processed = mltp_importer(DIR, '*.shp', CMD, importer)
# check for errors
errors = [p for p in processed if not p[2]]
if errors:
# do something (print list of failed SHP files at end)
pass
</source>

{{Python}}

Test Suite

2013-10-29T09:53:09Z

⚠️Pietro: add my name to the list of interested people

__TOC__

= GRASS GIS 7 Test Suite =

We aim at creating a comprehensive test suite for GRASS GIS 7 modules and libraries.

== Background ==

See what has been done so far by Sören Gebbert and others here: [[Development#QA]] and the good [http://www.vtk.org/Wiki/images/b/bc/Testing.cover.txt VKT test suite]

Keep an eye on [[GRASS_7_ideas_collection#Complete_GRASS_Test_Suite:_see_activity_on_Test_Suite_development_page | GRASS 7 ideas collection]]

== Main picture ==

We plan to run unit tests and integration tests for both libraries and modules. The test suite will be run after compilation, with a command like:

$ make tests [ proj ]

Options:
* proj: run the tests with a [list of] CRS, so that reprojection and map unit handling are tested.
* ...

Tests are executed recursively. If the "make tests" command is executed in the root source folder all libraries and modules are tested. To test only the libraries you need to switch in the '''lib''' directory and execute "make tests". If you want to test only raster modules switch into the '''raster''' directory and run "make tests", same for other modules directories. To test a single module switch into the module directory and run "make tests".

Testing should work in parallel, so that make -j6 tests will execute as maximum 6 tests in parallel. The framework should take care that parallel testing test runs can be performed.

== Tests ==

=== Modules ===
Tests are targeted to cover all modules as well as library test modules.

The modules tests should as independent as possible from other GRASS modules.

Tests are written as simple shell script with annotations. Test script should start with '''test.''' followed by the module name i.e. '''r.mapcalc.''' and further ending with '''.sh'''. Example '''test.r.mapcalc.1.sh'''. All test should be well documented using shell comments.

The framework will execute all test scripts starting with '''test.''' and ending with '''.sh''' located in module or library directories.

Annotations are integrated in the test documentation (simple shell comments) and specify pre-processing steps, the tests and the type of the data to validate. The following annotations should be supported:

* The '''@preprocess''' annotation
** All commands below this annotation are handled as preprocessing steps for the tests.
** If any of the preprocess commands fail, the framework should stop testing an create a detailed error report.
** Preprocessing steps may be data generation, region settings and so on.
** The preprocess annotation is valid till a '''@test''' annotation specifies the begin of a test
** Preprocess annotations can be specified at between tests
* The '''@test''' annotation
** All command below a this annotation are handled as tests by the framework
** The test annotation must be integrated in the comment block which describes the test
** Data validation is performed by the framework for tests if reference data is present
** The test annotation is valid till a '''@preprocess''' annotation specifies the begin of a preprocess block for further test runs
** The data type annotations
*** Data type annotations should be specified in the same comment block as the '''@test''' annotation
*** Data type annotations specify the grass data types which should be validated with reference data
*** The following data type annotations should be specified
**** '''@file''' the framework should compare the reference data with files
**** '''@raster''' the framework should compare the reference data with raster maps using r.out.ascii for export
**** '''@vector''' the framework should compare the reference data with vector maps using v.out.ascii for export
**** '''@raster3d''' the framework should compare the reference data with raster3d maps using r3.out.ascii for export
**** '''@color''' the framework should compare the reference data with color rules using r.color.out for export
**** '''@color3d''' the framework should compare the reference data with 3d color rules using r3.color.out for export
**** '''@table''' the framework should compare the reference data with SQL tables using db.select for export
**** ... please add more
** The '''@precision=[positive integer]''' annotation
*** Should be located in a test comment block
*** Specifies the precision to use to export grass data for validation with reference files
*** In case the precision is not provided the default behavior of the export module is used

Reference data for validation must be located in the module/library reference directory. The reference data names must be identical with the generated data (files, maps, ...) except that reference data always has a '''.ref''' suffix.

Tests are in each module's and in each library's folder. To test library functions special modules must be implemented. Library test modules test the library functions directly and should be written in C. Have a look at the test directories in the g3d, gpde and gmath libraries of grass7.

Framework should be able to generate and compare grass data types: raster, vector, raster3d, general, db, icon, imagery, d.*?

wxGUI testing should be tested separately.

Automated tests on server generates HTML report. Test several platforms.

Here some examples already available in grass7:

=== test.v.random.sh ===

<source lang="bash">
# This is a simple test for v.random
# We create several identical pseudo random points maps :)
# using the seed option for rand and drand48

# In the @preprocess step we set up a suitable region
g.region n=80 s=0 w=0 e=120 res=10 -p

# First @test the rand function. Create a 3d vector map with attribute table
# The validation is based on @vector map with a @precision=3
v.random --o -z output=test_random_vect_1 n=20 zmin=0 zmax=100 seed=501
# Now the attribute @table should be validated. Booth maps are identical
v.random --o -z output=test_random_vect_2 n=20 zmin=0 zmax=100 column=height seed=501

# Second @test the drand48 function. Create a 3d vector map with attribute table
# The validation is based on @vector map with a @precision=3
v.random --o -zd output=test_random_vect_3 n=20 zmin=0 zmax=100 seed=501
# Now the attribute @table should be validated. Booth maps are identical
v.random --o -zd output=test_random_vect_4 n=20 zmin=0 zmax=100 column=height seed=501

# Export the generated data as references
# v.out.ascii --o format=point dp=3 input=test_random_vect_1 output=test_random_vect_1.ref
# db.select "select * from test_random_vect_2" > test_random_vect_2.ref
# v.out.ascii --o format=point dp=3 input=test_random_vect_3 output=test_random_vect_3.ref
# db.select "select * from test_random_vect_4" > test_random_vect_4.ref
</source>

The following reference files are located in the v.random directory:
<pre>
-rw-r--r-- 1 soeren users 460 18. Jun 01:20 test_random_vect_1.ref
-rw-r--r-- 1 soeren users 257 18. Jun 01:20 test_random_vect_2.ref
-rw-r--r-- 1 soeren users 455 18. Jun 01:20 test_random_vect_3.ref
-rw-r--r-- 1 soeren users 256 18. Jun 01:20 test_random_vect_4.ref
</pre>

=== test.r3.out.vtk.sh ===

<source lang="bash">
# This script tests the export of voxel data
# into the VTK format. Almost all options of
# r3.out.vtk are tested. Validation data for each test
# is located in the module source directory

# We need to set a specific region in the
# @preprocess step of this test. We generate
# raster and voxel data with r.mapcalc and r3.mapcalc
# The region setting should work for UTM and LL test locations
g.region s=0 n=80 w=0 e=120 b=0 t=50 res=10 res3=10 -p3
# Now generate two elevation maps, we have 8 rows and use
# them for elevation computation. The rows are counted from north
# to south. So in the south the elevation must have a maximum.
r.mapcalc --o expr="elev_bottom = row()"
r.mapcalc --o expr="elev_top = row() + 50"
# Now create a voxel map with value = col + row + depth.
r3.mapcalc --o expr="volume = col() + row() + depth()"
# Add null value information
r3.mapcalc --o expr="volume_null = if(row() == 2 || row() == 7, null(), volume)"
# Create the rgb maps
r3.mapcalc --o expr="volume_rgb = volume_null * 5"

# The first @test just exports the volume map as cell and point data
# using a low precision and replaces the default null value with 0
# the created @files should be compared with the reference data
r3.out.vtk --o input=volume_null output=test_volume_null_1_cells.vtk dp=3 null=0
r3.out.vtk -p --o input=volume_null output=test_volume_null_1_points.vtk dp=3 null=0

# The second @test adds rgb and vector maps. We re-use the created volume map
# for vector creation. The rgb value must range fom 0 - 255. The generated @files
# should be compared with the reference data.
r3.out.vtk --o rgbmaps=volume_rgb,volume_rgb,volume_rgb vectormaps=volume_null,volume_null,volume_null input=volume_null output=test_volume_null_1_cells_rgb_vect.vtk dp=3 null=-1.0
r3.out.vtk -p --o rgbmaps=volume_rgb,volume_rgb,volume_rgb vectormaps=volume_null,volume_null,volume_null input=volume_null output=test_volume_null_1_points_rgb_vect.vtk dp=3 null=-1.0

# The third @test uses raster maps to create volume data with an elevation surface
# The maximum elevation should be in the south. Reference @files are present for validation.
r3.out.vtk -s --o top=elev_top bottom=elev_bottom input=volume_null output=test_volume_null_1_cells_elevation.vtk dp=3 null=0
r3.out.vtk -sp --o top=elev_top bottom=elev_bottom input=volume_null output=test_volume_null_1_points_elevation.vtk dp=3 null=0
</source>

The following reference files are located in the r3.out.vtk directory:
<pre>
-rw-r--r-- 1 soeren users 104556 16. Jun 18:14 test_volume_null_1_cells_elevation.ref
-rw-r--r-- 1 soeren users 3434 16. Jun 18:14 test_volume_null_1_cells.ref
-rw-r--r-- 1 soeren users 22749 16. Jun 18:14 test_volume_null_1_cells_rgb_vect.ref
-rw-r--r-- 1 soeren users 13360 16. Jun 18:14 test_volume_null_1_points_elevation.ref
-rw-r--r-- 1 soeren users 3435 16. Jun 18:14 test_volume_null_1_points.ref
-rw-r--r-- 1 soeren users 22750 16. Jun 18:14 test_volume_null_1_points_rgb_vect.ref
</pre>

=== test.r3.cross.rast.sh ===

<source lang="bash">
# This script tests the r3.cross.rast module to compute
# cross section raster maps based on a raster3d and elevation map

# We need to set a specific region in the
# @preprocess step of this test. We generate
# raster and voxel data with r.mapcalc and r3.mapcalc
# The region setting should work for UTM and LL test locations
g.region s=0 n=80 w=0 e=100 b=0 t=50 res=10 res3=10 -p3
# We create several elevation maps to create slices of the voxel map
# We start from bottom and raise to the top. Value equal or greater 50
# should generate grass NULL values
r.mapcalc --o expr="elev_0 = 0"
r.mapcalc --o expr="elev_1 = 5"
r.mapcalc --o expr="elev_2 = 15"
r.mapcalc --o expr="elev_3 = 25"
r.mapcalc --o expr="elev_4 = 35"
r.mapcalc --o expr="elev_5 = 45"
r.mapcalc --o expr="elev_NAN = 50"
r.mapcalc --o expr="elev_cross = float(col()* 5)"
# Now create a voxel map with value = col + row + depth.
r3.mapcalc --o expr="volume = col() + row() + depth()"
# Add null value information
r3.mapcalc --o expr="volume_null = if(row() == 1 || row() == 5, null(), volume)"

# We @test the creation of slices and a cross section of the voxel map. Reference data
# for @raster map validation is located in the r3.cross.rast source directory.
# Slice 0 and 1 should be identical. The last slice should consist only of grass NULL values
r3.cross.rast --o input=volume_null elevation=elev_0 output=test_cross_section_slice_0
r3.cross.rast --o input=volume_null elevation=elev_1 output=test_cross_section_slice_1
r3.cross.rast --o input=volume_null elevation=elev_2 output=test_cross_section_slice_2
r3.cross.rast --o input=volume_null elevation=elev_3 output=test_cross_section_slice_3
r3.cross.rast --o input=volume_null elevation=elev_4 output=test_cross_section_slice_4
r3.cross.rast --o input=volume_null elevation=elev_5 output=test_cross_section_slice_5
r3.cross.rast --o input=volume_null elevation=elev_NAN output=test_cross_section_slice_NAN
r3.cross.rast --o input=volume_null elevation=elev_cross output=test_cross_section_result
</source>

The following reference files are located in the r3.cross.rast directory:

<pre>
-rw-r--r-- 1 soeren users 264 16. Jun 18:14 test_cross_section_result.ref
-rw-r--r-- 1 soeren users 264 16. Jun 18:14 test_cross_section_slice_0.ref
-rw-r--r-- 1 soeren users 264 16. Jun 18:14 test_cross_section_slice_1.ref
-rw-r--r-- 1 soeren users 269 16. Jun 18:14 test_cross_section_slice_2.ref
-rw-r--r-- 1 soeren users 273 16. Jun 18:14 test_cross_section_slice_3.ref
-rw-r--r-- 1 soeren users 276 16. Jun 18:14 test_cross_section_slice_4.ref
-rw-r--r-- 1 soeren users 279 16. Jun 18:14 test_cross_section_slice_5.ref
-rw-r--r-- 1 soeren users 222 16. Jun 18:14 test_cross_section_slice_NAN.ref
</pre>

=== test.r3.out.ascii.sh ===

<source lang="bash">
# Tests for r3.out.ascii and r3.in.ascii
# This script tests the export of voxel data using r3.out.ascii
# as well as the import of the generated data with r3.in.ascii
# using different row and depth ordering options.

# We set up a specific region in the
# @preprocess step of this test. We generate
# voxel data with r3.mapcalc. The region setting
# should work for UTM and LL test locations
g.region s=0 n=80 w=0 e=120 b=0 t=50 res=10 res3=10 -p3
# Now create several (float, double, null value) voxel map
# with value = col + row + depth.
r3.mapcalc --o expr="volume_float = float(col() + row() + depth())"
r3.mapcalc --o expr="volume_double = double(col() + row() + depth())"
# Add null value information
r3.mapcalc --o expr="volume_float_null = if(row() == 1 || row() == 5, null(), volume_float)"
r3.mapcalc --o expr="volume_double_null = if(row() == 1 || row() == 5, null(), volume_double)"

# We export float data in the first @test using different order and precision
# as text @files for valdiation of correct ordering and null data handling
r3.out.ascii --o input=volume_float_null output=test_float_nsbt_null.txt dp=0 null=*
r3.out.ascii --o -r input=volume_float_null output=test_float_snbt_null.txt dp=0 null=*
r3.out.ascii --o -d input=volume_float_null output=test_float_nstb_null.txt dp=0 null=*
r3.out.ascii --o -rd input=volume_float_null output=test_float_sntb_null.txt dp=0 null=*
# Different precision and null values than default
r3.out.ascii --o input=volume_float_null output=test_float_nsbt_null_prec5.txt dp=5 null=-1000
r3.out.ascii --o -rd input=volume_float_null output=test_float_sntb_null_prec8.txt dp=8 null=-2000
# Test the no header and grass6 compatibility flags
r3.out.ascii --o -h input=volume_float_null output=test_float_nsbt_null_no_header.txt dp=3 null=*
r3.out.ascii --o -c input=volume_float_null output=test_float_nsbt_null_grass6_comp_1.txt dp=3 null=*
# Any row or depth order should be ignored in case grass6 compatibility is enabled
# The rsult of comp_1, _2 and _3 must be identical
r3.out.ascii --o -cr input=volume_float_null output=test_float_nsbt_null_grass6_comp_2.txt dp=3 null=*
r3.out.ascii --o -crd input=volume_float_null output=test_float_nsbt_null_grass6_comp_3.txt dp=3 null=*

# We export double data in the second @test using different order and precision
# as text @files for valdiation of correct ordering and null data handling. Its hte same
# procedure as with float data
r3.out.ascii --o input=volume_double_null output=test_double_nsbt_null.txt dp=0 null=*
r3.out.ascii --o -r input=volume_double_null output=test_double_snbt_null.txt dp=0 null=*
r3.out.ascii --o -d input=volume_double_null output=test_double_nstb_null.txt dp=0 null=*
r3.out.ascii --o -rd input=volume_double_null output=test_double_sntb_null.txt dp=0 null=*
# Different precision and null values than default
r3.out.ascii --o input=volume_double_null output=test_double_nsbt_null_prec5.txt dp=5 null=-1000
r3.out.ascii --o -rd input=volume_double_null output=test_double_sntb_null_prec8.txt dp=8 null=-2000
# Test the no header and grass6 compatibility flags
r3.out.ascii --o -h input=volume_double_null output=test_double_nsbt_null_no_header.txt dp=3 null=*
r3.out.ascii --o -c input=volume_double_null output=test_double_nsbt_null_grass6_comp_1.txt dp=3 null=*
# Any row or depth order should be ignored in case grass6 compatibility is enabled
# The result of comp_1, _2 and _3 must be identical
r3.out.ascii --o -cr input=volume_double_null output=test_double_nsbt_null_grass6_comp_2.txt dp=3 null=*
r3.out.ascii --o -crd input=volume_double_null output=test_double_nsbt_null_grass6_comp_3.txt dp=3 null=*

# In the third @test we import all the generated data using r3.in.ascii
# The created @raster maps should be identical to the map "volume_double_null"
# The export of the created g3d map should use as @precision=0 for data validation
# The same raster name is used for all the imported data and so for the validation reference file
r3.in.ascii --o output=test_double_nsbt_null input=test_double_nsbt_null.txt nv=*
r3.in.ascii --o output=test_double_nsbt_null input=test_double_snbt_null.txt nv=*
r3.in.ascii --o output=test_double_nsbt_null input=test_double_nstb_null.txt nv=*
r3.in.ascii --o output=test_double_nsbt_null input=test_double_sntb_null.txt nv=*
# Different precision and null values than default
r3.in.ascii --o output=test_double_nsbt_null input=test_double_nsbt_null_prec5.txt nv=-1000
r3.in.ascii --o output=test_double_nsbt_null input=test_double_sntb_null_prec8.txt nv=-2000
# Any row or depth order should be ignored in case grass6 compatibility is enabled
r3.in.ascii --o output=test_double_nsbt_null input=test_double_nsbt_null_grass6_comp_1.txt

# In this @preprocess step for the last test we create a large region and
# generate large input data to test the handling of large files
g.region s=0 n=800 w=0 e=1200 b=0 t=50 res=10 res3=1.5 -p3
r3.mapcalc --o expr="volume_double_large = double(col() + row() + depth())"
# Add null value information
r3.mapcalc --o expr="volume_double_null_large = if(row() == 1 || row() == 5, null(), volume_double_large)"

# Now @test the export and import of large data without validation
r3.out.ascii --o input=volume_double_null_large output=test_double_nsbt_null_large.txt dp=0 null=*
r3.in.ascii --o output=test_double_nsbt_null_large input=test_double_nsbt_null_large.txt nv=*
# Just for the logs
r3.info test_double_nsbt_null_large
</source>

The following reference files are located in the r3.out.ascii directory:

<pre>
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_double_nsbt_null_grass6_comp_1.ref
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_double_nsbt_null_grass6_comp_2.ref
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_double_nsbt_null_grass6_comp_3.ref
-rw-r--r-- 1 soeren users 2751 17. Jun 21:36 test_double_nsbt_null_no_header.ref
-rw-r--r-- 1 soeren users 4103 17. Jun 21:36 test_double_nsbt_null_prec5.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_double_nsbt_null.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_double_nstb_null.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_double_snbt_null.ref
-rw-r--r-- 1 soeren users 5183 17. Jun 21:36 test_double_sntb_null_prec8.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_double_sntb_null.ref
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_float_nsbt_null_grass6_comp_1.ref
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_float_nsbt_null_grass6_comp_2.ref
-rw-r--r-- 1 soeren users 2875 17. Jun 21:36 test_float_nsbt_null_grass6_comp_3.ref
-rw-r--r-- 1 soeren users 2751 17. Jun 21:36 test_float_nsbt_null_no_header.ref
-rw-r--r-- 1 soeren users 4103 17. Jun 21:36 test_float_nsbt_null_prec5.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_float_nsbt_null.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_float_nstb_null.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_float_snbt_null.ref
-rw-r--r-- 1 soeren users 5183 17. Jun 21:36 test_float_sntb_null_prec8.ref
-rw-r--r-- 1 soeren users 1463 17. Jun 21:36 test_float_sntb_null.ref
</pre>

== Test framework: ==

What the test framework should do:

* Creation of a test mapset for each test case in a specific test location located in the grass sources
* Setting the environment variables to the test location and grass installation (grass environment to run modules)
* For each test case a separate temporary directory should be created in which the test is executed. After testing the temporary directory get removed. The temporary directory should be located in the temporary mapset which will be automatically removed after testing.
* Parsing and interpretation and execution of test scripts
* Support of several test scripts in a single module directory
* Run of location specific test scripts (only LL or UTM test scripts)
* Handles module test results codes and stderr messages
* Validation of module output based on reference data and data type annotations in the test description
* Creates a HTML report for single modules and the whole test run
* Deletion of the generated test mapset to clean up the test location

== Implementation ==

* All test cases must be implemented as text files in shell style including annotations in comment blocks
* The test framework should be implemented in Python, parsing and analyzing and executing the test cases line by line
* The Make-System must be modified to start the tests by typing "make tests"

=== Test framework Python approach ===

I suggest the following Python classes:
* TestBase class - implements the test logic
** LatLongTest class - for LatLong test location initialization and test run, derived from TestBase class
** UTMTest class - for UTM test location initialization and test run, derived from TestBase class
* A CommandBase class - implements command line specific methods and attributes and executes a command, logging return value and stderr using the subprocess module
** PreProcess class - derived from CommandBase class for preprocess execution
** TestCase class - derived from CommandBase class for test execution
* ...

The TestBase class implementing the following methods:

<source lang="python">

class TestBase:
def StartGrassSession(self):
"""Abstract method, should be overwritten in a subclass"""
pass
def Run(self):
"""Create the environment variables for the grass session, create a mapset and execute all tests"""
self.StartGrassSession()
self.CreateTestMapset()
self.CheckForReferenceFiles()
self.ExecuteAll()

def CreateTestMapset(self):
"""Creates a temporary mapset for the test using g.mapset"""
pass

def CreateExecutionOrder(self):
"""
* Reads the entire test case into memory and parses the file line by line
* Creates the execution order list as internal structure to store specific execution settings
* For each command in the test case a specific CommandBase object is created and stored in the execution order list
* TestCase objects store the validation type (@file, ...) and the validation precision (@precision=1) ... and maybe more
"""
pass

def ExecuteAll(self):
"""
* Create a temporary test directory in the temporary mapset
* Calls ExecuteTest or ExecutePreProcess for each entry in the execution order list
* Summarize the HTML and text summary content for each entry in the list
* Clean up the temporary directories generate for each command
"""
pass

def ExecuteTest(self):
"""
* Execute a single test command using the TestCase object
* Logs stderr and return value from TestCase object
* Analyses return value and stderr in case of an error
* Checks for new generated maps/files of the command
* Checks if reference files are present
* Export data with data specific commands (r/r3/v.out.ascii, r/r3.colors.out, ...)
* Compares reference files with exported files
* Creates HTML and text logfile entry
"""
pass

def CheckForReferenceFiles(self):
"""Lists all available reference files of a directory in an internal dict,
base name, path and full name are stored"""
pass

def ExecutePreprocess(self):
"""
* Execute a single preprocess command using the PreProcess object
* Logs stderr and return value from PreProcess object
* Analyses return value and stderr in case of an error
* Creates HTML and text logfile entry
"""
pass

def CompareVectorMap(self):
"""
* Exports vector map with v.out.ascii using the default or specific TestCase precision
* Compares exported file with reference file
"""
pass

def CompareRasterMap(self):
"""
* Exports raster map with r.out.ascii using the default or specific TestCase precision
* Compares exported file with reference file
"""
pass

def CompareRaster3dMap(self):
"""
* Exports raster3d map with r3.out.ascii using the default or specific TestCase precision
* Compares exported file with reference file
"""
pass

def CompareColor(self):
"""
* Export raster color with r.colors.out
* Compares exported file with reference file
"""
pass

def CompareColor3d(self):
"""
* Export raster3d color with r3.colors.out
* Compares exported file with reference file
"""
pass

def CreateHTMLTestSummary(self):
pass

def CreateTextTestSummary(self):
pass

def CleanUp(self):
""" Remove the temporary test mapset and all generated test files """
pass

# ... many more
</source>

The LatLongTest implements the following method:

<source lang="python">
class LatLongTest(BaseTest):
def StartGrassSession(self):
"""starts the grass7 session in a LatLong test location"""
pass
</source>

The UTMTest implements the following method:

<source lang="python">
class UTMTest(BaseTest):
def StartGrassSession(self):
"""starts the grass7 session in a UTM test location"""
pass
</source>

The CommandBase class:

* Uses the subprocess module to execute a command
* Is able to identify some shell specific commands in the command line ("&&, |, <, >")
* Acts as a very simple shell interpreter
** In case if "|" connects multiple commands in a command line with subprocess.PIPE
** In case of ">" or "<" uses stdout or stdin io
** No support for complex shell functionality (for, test, ...)

=== Make system ===

New rules should be added to the make system so that:
<source lang="bash">
make test ll
</source>
Will start recursively library and/or module tests from the current directory in the LatLong test location.
The Make system should execute the Python test framework main Python file in each Module or Library directory.
I guess test specific entries must be added to the modules and library Makefiles?

== Timeline and status ==

{|class="wikitable sortable"
|'''Task''' || '''Status''' || '''Developer(s)'''
|-
| Implementation of modules' tests || Progress || Sören
|-
| Implementation of r3.* tests || Progress || Sören
|-
| Implementation of test framework || Starting || Anne
|-
| Make integration || To be done || -
|-
|}

== Interested people ==

* [[User:huhabla | Sören Gebbert]]
* [[User:AnneGhisla| Anne Ghisla]]
* [[User:Landa|Martin Landa]]
* [[User:Wenzeslaus|Vaclav Petras]]
* [[User:Pietro|Pietro Zambelli]]
* Add your name here

[[Category: Development]]
[[Category: Testing]]

Python/pygrass

2013-10-10T14:08:14Z

⚠️Pietro: /* Update link to examples */

''pygrass'' is a library that extends the GRASS capabilities to allow users to access the low-level GRASS API.

== Workshops ==

=== XIV Italian meeting of GRASS and GFOSS users ===

Two workshops were presented during the [http://geomorfolab.arch.unige.it/genova2013/ XIV Italian meeting of GRASS] at Genova.
The workshops use '''ipython notebook''' to show the python and pygrass API, all the material are available on github ([https://github.com/zarch/workshop-python python], [https://github.com/zarch/workshop-pygrass pygrass]). All the execute examples are reported here:

* python
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/00_intro.ipynb Introduction]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/01_data_types.ipynb Data Types]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/02_syntax.ipynb Syntax]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/03_function.ipynb Function]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/04_class.ipynb Class]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-python/master/05_other.ipynb Other]

* pygrass
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/00_Modules.ipynb Modules]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/01_GIS_objects.ipynb GIS]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/02_Vector.ipynb Vector]
** [http://nbviewer.ipython.org/urls/raw.github.com/zarch/workshop-pygrass/master/03_Raster.ipynb Raster]

== How to test library ==

''pygrass'' has doctest inside its code. You can run doctest inside the [http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz North Carolina basic location], using the mapset '''user1'''.

To test the single module (file) you have to move to the source code of pygrass and run the following code (this is an example of functions.py):

<source lang="bash">

python -m doctest functions.py

</source>

=== Already tested modules ===

==== Working ====

* functions.py
* gis/region.py
* gis/__init__.py
* modules/__init.py
* vector/abstract.py
* vector/__init__.py
* vector/basic.py
* vector/table.py
* vector/geometry.py
* raster/abstract.py

==== Not working ====

* ...

== References ==

* Zambelli, P., Gebbert, S., Ciolli, M., 2013. ''Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)''. ISPRS International Journal of Geo-Information 2, 201–219. ([http://dx.doi.org/10.3390/ijgi2010201 DOI] | [http://www.mdpi.com/2220-9964/2/1/201/pdf PDF])

* [http://www.ing.unitn.it/~zambelli/projects/pygrass/ pyGrass documentation]

== Some script for Landsat 7 ==

<source lang="python">

#!/usr/bin/python
#Date: 7th February, 2013
#Public domain, GRASS GIS

#Run this script in the terminal as:
#python python-grass.py
#For debugging, run as:
#python -i python-grass.py
#PURPOSE
#This script processes LANDSAT 7 ETM+ images
#1 - unzip *.gz files
#2 - import files in GRASS GIS Location of your choice (r.in.gdal)
#3 - DN to Top of Atmosphere reflectance (i.landsat.toar)
#4 - TOA reflectance to Surface reflectance (i.atcorr)
#5 - NDVI (i.vi), Albedo (i.albedo), Emissivity (i.emissivity)

#USER HAS TO SET THOSE
#QUIET REPORTS
QIET=True
#OVERWRITE EXISTING FILES
OVR=False
#Define Landsat 7 sensor for i.landsat.toar
LSENSOR="tm7"
#Setup the path to the Landsat 7 Directories
rsdatapath="/home/yann/RSDATA/Myanmar/L7"
#Setup your GRASS GIS working directory
gisdb="/home/yann/GRASSDATA"
location="L7_Myanmar"
print location
mapset="PERMANENT"
#DEM input to atmospheric correction
inDEM=rsdatapath+"/dem.tif"
#set L7 Metadata wildcards
wldc_mtl="*_MTL.txt"
#wldc_met="*.met"
#Visibility distance [Km]
vis=18

#Set python path to enable finding of grass.script lib

#END OF USER CHANGES
###DO NOT CHANGE ANYTHING AFTER THIS LINE !
###
#Load necessary libraries
import os, glob, time, re
from grass import script as g
from grass.script import setup as gsetup
gisbase=os.environ['GISBASE']
gsetup.init(gisbase,gisdb,location,mapset)
from grass.pygrass.modules.shortcuts import raster as r
from grass.pygrass.modules.shortcuts import imagery as i
from grass.pygrass.modules.shortcuts import display as d
#Needed for floor()
from math import *
#env = os.environ.copy()
#env['GRASS_MESSAGE_FORMAT'] = 'gui'
#Function to get a list of L7 Directories in the rsdatapath
def fn(path):
for top, dirs, files in os.walk(path):
return [os.path.join(top, dir) for dir in dirs]

#START PROCESS
### PART 0: PRE-PROCESSING STUFF ###
#import DEM for atmospheric correction
#r.in.gdal(input=inDEM,output="dem",overwrite=OVR)
#r.mapcalc(expression="dem=25",overwrite=OVR)
#create a visibility map
r.mapcalc(expression="vis=18",overwrite=OVR)
#Find the central location of the Landsat file from metadata
metadata=[]
fileList=[]
L7Dirs=fn(rsdatapath)
for L7Dir in L7Dirs:
#Ungzip all of your Landsat7 images in all your directories
# print "Ungzip Landsat files in\t",L7Dir
# p=os.system("gzip -d -q "+L7Dir+"/*.gz")
#Using pthreads on multi-core machines
#p=os.system("pigz -d "+L7Dir+"/*.gz")
#Wait ten seconds for gzip to create the tif images
# time.sleep(10)
print "Import in GRASS GIS"
for L7f in glob.glob(os.path.join(L7Dir,"*.[tT][iI][fF]")):
f1=L7f.replace(L7Dir+"/","")
f2=f1.replace(".TIF","")
f3=f2.replace("_B10",".1")
f4=f3.replace("_B20",".2")
f5=f4.replace("_B30",".3")
f6=f5.replace("_B40",".4")
f7=f6.replace("_B50",".5")
f8=f7.replace("_B61",".61")
f9=f8.replace("_B62",".62")
f10=f9.replace("_B70",".7")
f11=f10.replace("_B80",".8")
f12=f11.replace("L72","L71")
L7r=f12.replace("_VCID_","")
print "\t> ",L7r
r.in_gdal(input=L7f,output=L7r,flags="e",overwrite=OVR)
fileList.append(L7r)

#reproject the DEM World map for the new PERMANENT location extents
r.proj(input="dem",location="Myanmar",memory=10000,resolution=90.0,overwrite=OVR)
#Get list of metadata files
for metaf in glob.glob(os.path.join(L7Dir,wldc_mtl)):
metadata.append(metaf)
print "Metadata in:\n",metadata[0]
with open(metadata[0],"r") as f:
data=f.read()

f.close()
dt=data.split("\n")
for idx in range(len(dt)):
found=dt[idx].find("CORNER_UL_LON_PRODUCT = ")
if found > 0:
ulx=float(dt[idx].replace("CORNER_UL_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_UL_LAT_PRODUCT = ")
if found > 0:
uly=float(dt[idx].replace("CORNER_UL_LAT_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LON_PRODUCT = ")
if found > 0:
lrx=float(dt[idx].replace("CORNER_LR_LON_PRODUCT = ",""))
found=dt[idx].find("CORNER_LR_LAT_PRODUCT = ")
if found > 0:
lry=float(dt[idx].replace("CORNER_LR_LAT_PRODUCT = ",""))
#Two cases, because a string starting by 0 is not converted well
found=dt[idx].find("SCENE_CENTER_TIME = ")
if found > 0:
tim=dt[idx].replace("SCENE_CENTER_TIME = ","")
print "timestamp=",str(tim)
gmth=float(tim.split(":")[0])
gmtm=float(tim.split(":")[1])
gmtdec=float(tim.split(":")[2].replace("Z",""))
print gmth,gmtm,gmtdec
found=dt[idx].find("DATE_ACQUIRED = ")
if found > 0:
dat=dt[idx].replace("DATE_ACQUIRED = ","")
date=dat.split("-")
found=dt[idx].find("SUN_ELEVATION = ")
if found > 0:
sunza=90-float(dt[idx].replace("SUN_ELEVATION = ",""))

#L7 DN->Rad->Ref
print "Convert DN to Rad to TOARef"
f1=sorted(fileList)[0]
f2=f1.replace(L7Dir+"/","")
pref=f2[:-1]
outpref=pref[:-2]+".toar."
print "Prefix IN:\t",pref
print "Prefix OUT:\t", outpref
i.landsat_toar(input_prefix=pref,output_prefix=outpref,metfile=metadata[0],sensor=LSENSOR,quiet=QIET,overwrite=OVR)
#Atmospheric Correction
print "Atmospheric Correction"
# Basic script for i.atcorr for L 7 ETM+
#Geometrical conditions (L7ETM+)
geom=7
#Sensor height (satellite is -1000)
sens_height=-1000
#Here we suppose you have altitude (DEM) and Visibility (VIS) maps ready
#---------------------------------------------
#Visibility dummy value (overwritten by VIS raster input)
vis=15
#Altitude dummy value (in Km should be negative in this param file)
#(overwritten by DEM raster input)
alt=-1.200
#datetime of satellite overpass (month, day, GMT decimal hour)
mdh=str(int(date[1]))+" "+str(int(date[2]))+" "+str("%.2f" % (gmth+gmtm/60.0+gmtdec/3600.0))
print "MM DD hh.ddd:\t",mdh
# Central Lat/Long
Long=ulx+(lrx-ulx)/2.0
Lat=lry+(uly-lry)/2.0
print "Center:\t(",Long, ",", Lat,")"
#Atmospheric mode
atm_mode=1 #Tropical
#Aerosol model
aerosol_mode=2 #Sri Lanka is a small island (maritime)
#satellite band number (L5TM [25,26,27,28,29,30], L7ETM+ [61,62,63,64,65,66,67])
satbandno=61 #Band 1 of L7ETM+ is first to undergo atmospheric correction
#make time stamp for use in time series analysis
dat1=str(date[2])+"-"+str(date[1])+"-"+str(date[0])
dat=dat1.replace(" ","")
timestamp=time.strftime("%d %b %Y",time.strptime(dat,"%d-%m-%Y"))
print "Timestamp:\t",timestamp
for idx in [1,2,3,4,5,7]:
b=pref[:-2]+".toar."+str(idx)
b_out=b.replace(".toar.",".surf.")
param=[]
param.append(str(geom)+" - geometrical conditions=Landsat 7 ETM+\n")
param.append(str(mdh)+" "+str("%.2f" % Long)+" "+str("%.2f" % Lat)+" - month day hh.ddd longitude latitude (hh.ddd is in decimal hours GMT)\n")
param.append(str(atm_mode)+" - atmospheric mode=tropical\n")
param.append(str(aerosol_mode)+" - aerosols model=maritime\n")
param.append(str(vis)+" - visibility [km] (aerosol model concentration), not used as there is raster input\n")
param.append(str(alt)+" - mean target elevation above sea level [km] (here 600m asl), not used as there is raster input\n")
param.append(str(sens_height)+" - sensor height (here, sensor on board a satellite)\n")
param.append(str(satbandno)+" - i th band of ETM+ Landsat 7 (atcorr internal no)\n")
f=open(os.path.join(L7Dir,"param_L7.txt"),"w")
f.writelines(param)
f.close()
prm=os.path.join(L7Dir,"param_L7.txt")
print "\t> ",b
print "\t> ",b_out
i.atcorr(input=b, elevation="dem", visibility="vis", parameters=prm, output=b_out, flags="ra", range=[0,1],quiet=QIET,overwrite=OVR)
r.timestamp(map=b_out,date=timestamp,finish_=False)
satbandno = satbandno + 1

#Allocate surface reflectance names
b1=pref[:-2]+".surf.1"
b2=pref[:-2]+".surf.2"
b3=pref[:-2]+".surf.3"
b4=pref[:-2]+".surf.4"
b5=pref[:-2]+".surf.5"
b61=pref[:-2]+".toar.61"
b62=pref[:-2]+".toar.62"
b7=pref[:-2]+".surf.7"
b8=pref[:-2]+".surf.8"

### PART 1: BASIC STUFF ###
b_in=pref[:-2]+".toar."
b_clouds=pref[:-2]+".toar.acca"
print "Clouds:\t\t>",b_clouds
i.landsat_acca(input_prefix=b_in,output=b_clouds,overwrite=OVR)
#png_clouds=L7Dir+"/"+pref[:-2]+".clouds.png"
#d.mon(start='png',output=png_clouds,width=800,height=800)
print "MASK:\t\tON"
#Should always be rewritten!
r.mask(raster=b_clouds,flags="i",overwrite=True)

b_ndvi=pref[:-2]+".surf.ndvi"
print "NDVI:\t",b_ndvi
i.vi(red=b3,nir=b4,output=b_ndvi,viname="ndvi",quiet=QIET,overwrite=OVR,finish_=False)

b_in=[b1,b2,b3,b4,b5,b7]
b_albedo=pref[:-2]+".surf.albedo"
print "Albedo:\t",b_albedo
i.albedo(input=b_in,output=b_albedo,flags="lc",quiet=QIET,overwrite=OVR,finish_=False)

b_emissivity=pref[:-2]+".surf.emissivity"
print "Emissivity:\t",b_emissivity
i.emissivity(input=b_ndvi, output=b_emissivity,quiet=QIET,overwrite=OVR,finish_=False)

</source>

=== Already tested modules ===

{{Python}}

Python/Closures

2013-09-09T19:32:52Z

⚠️Pietro: Add a new page

=Why are useful=
A closure is a way to define a variable statically into a function. They are good to:
* Replace hard coded constants;
* Eliminate globals.

=Some examples=

Define a function that return another function:

<source lang="python">
def print_something(msg):
def _print(var):
print msg % var
return _print
</source>

Now we can use to instantiate the function and define the string formatting statically and then call the returned function.

<source lang="python">
>>> p = print_something('Hi %s!')
>>> p('Pietro')
Hi Pietro!
</source>

Now a more interesting example for the grass users:

<source lang="python">
from grass.pygrass.modules import Module

def get_module(cmd):
mod = Module(cmd)

def do(**kwargs):
mod(**kwargs)
return do
</source>

If we test the speed of a GRASS module, using ipython I got:

<source lang="python">
>>> %timeit Module('g.region', flags='p')
10 loops, best of 3: 30.8 ms per loop
</source>

Instead, using the python closure, I got:

<source lang="python">
>>> greg = get_module('g.region')
>>> %timeit greg(flags='p')
100 loops, best of 3: 12.8 ms per loop
</source>

Note: This example doesn't work with multiprocessing.

=References=
* [http://ynniv.com/blog/2007/08/closures-in-python.html Closures in Python]
* [http://www.shutupandship.com/2012/01/python-closures-explained.html Python closures explained]
* [http://effbot.org/zone/closure.htm Closure]

Python/pygrass

2013-02-15T10:47:43Z

⚠️Pietro: Add workshops material

GRASS and Python

2013-02-03T17:11:45Z

⚠️Pietro: /* Python Scripting Library */

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system. The library for "scripting" is "grass.script", typically used as:

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

The related files are at $GISBASE/etc/python/grass/script/*.py. See below for more details.

''Note: For code which needs access to the power of C, you can access the GRASS C library functions via [[GRASS and Python#Python Ctypes Interface|the Python "ctypes" interface]].''

=== Python script editor ===

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

[[Image:wxgui-pyshell.png|center|350px|Embedded interactive Python Shell in wxGUI Layer Manager]]

=== Using the GRASS Python Scripting Library ===

You can run Python scripts easily in a GRASS session.

To write these scripts,
* check the code in lib/python/ which provides grass.script in order to support GRASS scripts written in Python.<br>
See the [[GRASS Python Scripting Library]] for notes and examples.
* The scripts/ directory of GRASS contains a series of examples actually provided to the end users.

For the desired Python code style, have a look at {{src|SUBMITTING_PYTHON}}.

=== Creating Python scripts that call GRASS functionality from outside ===

Note: This is a more advanced use case of using GRASS' functionality from outside via Python. Commonly, a user will run GRASS Python script from inside a GRASS session, i.e. either from the command line or from the Python shell embedded in the wxGUI ([[:File:Wxgui-pyshell.png|screenshot]]).

For calling GRASS functionality from outside, see also [[Working with GRASS without starting it explicitly]].

==== MS-Windows ====

In order to use GRASS functionality via Python from outside, some environment variables have to be set:

GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-64\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-64\msys\bin\sh.exe

Some hints:

# The ".grassrc6" file listed above must exist. Run GRASS one time interactively to create it or see below for how to writing it
# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %GISBASE%\etc\python

Points 2-4 should be taken care of by the Python installer. 5 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

Alternatively to run GRASS interactively, you can also create the ".grassrc6" file yourself, e.g. (update to existing directory for "grassdata"):

GISDBASE: C:\Documents and Settings\user\grassdata
LOCATION_NAME: nc_spm_08
MAPSET: user1
GRASS_DB_ENCODING: ascii

It doesn't matter what the file is called, so long as %GISRC% points to it and it contains the necessary settings.

The normal location for GRASS 6.x on Windows is:

%APPDATA%\GRASS6\grassrc6

On Windows 7, a typical setting for %APPDATA% is

C:\Users\<username>\AppData\Roaming

==== Linux ====

In order to use GRASS functionality via Python from outside, some environment variables have to be set:

export GISBASE="/usr/local/grass-6.4.svn/"
export PATH="$PATH:$GISBASE/bin:$GISBASE/scripts"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$GISBASE/lib"
# for parallel session management, we use process ID (PID) as lock file number:
export GIS_LOCK=$$
# path to GRASS settings file
export GISRC="$HOME/.grassrc6"

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Testing and installing Python extensions ===

==== Debugging ====

Make sure the script is executable:

chmod +x /path/to/my.extension.py

During development, a Python script can be debugged using the Python Debugger (pdb):

python -m pdb /path/to/my.extension.py input=my_input_layer output=my_output_layer option=value -f

==== Installation ====

Once you're happy with your script, you can put it in the scripts/ folder of your GRASS install. To do so, first create a directory named after your extension, then create a Makefile for it, and a HTML man page:

cd /path/to/grass_src/
cd scripts
ls # It is useful to check out the existing scripts and their structure
mkdir my.extension
cd my.extension
cp path/to/my.extension.py .
touch my.extension.html
touch Makefile

Next step is to edit the Makefile. It is a very simple text file, the only thing to check is to put the right extension name (WITHOUT the .py file extension) after PGM:

MODULE_TOPDIR = ../..

PGM = my.extension

include $(MODULE_TOPDIR)/include/Make/Script.make

default: script

The HTML file would be generated automatically. If you want to add more precisions in it, you can do it (just make sure you start at DESCRIPTION. See existing scripts.)

You can then run "make" within the my.extension folder. Running "make" in the extension directory places the resulting files in the staging directory (path/to/grass_src/dist.<YOUR_ARCH>/). If you're running GRASS from the staging directory (/path/to/grass_src/bin.<YOUR_ARCH>/grass7), subsequent commands will used the updated files.

# in your extension directory (/path/to/grass_src/scripts/my.extension/)
make
# Starting GRASS from the staging directory
/path/to/grass_src/bin.<YOUR_ARCH>/grass7
my.extension help

You can also run "make install" from the top level directory of your GRASS install (say /usr/local/src/grass_trunk/). Running "make install" from the top level just copies the whole of the dist.<YOUR_ARCH>/ directory to the installation directory (e.g. /usr/local/grass70) and the bin.<YOUR_ARCH>/grass70 bin file to the bin directory (e.g. /usr/local/bin), and fixes any embedded paths in scripts and configuration files.

cd /path/to/grass_src
make install
# Starting GRASS as usual would work and show your extension available
grass7
my.extension help

==Python extensions in GRASS GIS==

=== Python Scripting Library ===

* See [[GRASS Python Scripting Library]]

=== pygrass Library ===

* See [[Python/pygrass|pygrass]]

=== Python Ctypes Interface ===

This interface allows calling GRASS library functions from Python scripts. See [[Python Ctypes Examples]] for details.

Examples:

* GRASS 7: [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/raster_example_ctypes.py raster], [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/vector_example_ctypes.py vector] example

* Latest and greatest: GRASS 7 Python {{src|scripts}}

* <strike>[[PythonSwigExamples|More complicated examples]]</strike> <<-- TODO: update to Ctypes

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

## TODO: update example to Ctypes

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

Sample script for vector access (use within GRASS, Spearfish session):

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

# define open level (level 2: topology)
grassvect.Vect_set_open_level (2)

# open existing map
grassvect.Vect_open_old(map, input, mapset)

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

=== wxPython GUI development ===

* See the [[wxGUI]] wiki page

=== Python-GRASS add-ons ===

Stand-alone addons:

* Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using GRASS gui.tcl in Python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

<source lang="python">
import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")
</source>

== FAQ ==

* '''Q:''' Error message "execl() failed: Permission denied" - what to do?
: '''A:''' Be sure that the execute bit of the script is set.

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
*: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]
* [http://wiki.python.org/moin/PythonEditors Python Editors]

=== Programming ===

* Python and GRASS:
** Library interfaces: [GRASS Python Scripting Library http://grass.osgeo.org/programming7/pythonlib.html]
** Graphical user interface (GIU): [GRASS wxPython-based GUI http://grass.osgeo.org/programming7/wxpythonlib.html]
** PyWPS, GRASS-Web Processing Service: [[WPS]]

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006 (see also [[WPS]])

{{Python}}

Python/pygrass

2013-02-03T17:09:20Z

⚠️Pietro: Created page with "''pygrass'' it is a library that extent the GRASS capability allow users to access to the lower GRASS API."

''pygrass'' it is a library that extent the GRASS capability allow users to access to the lower GRASS API.

GRASS Community Sprint Genova 2013

2013-01-07T22:17:55Z

⚠️Pietro: /* Participation */

The GRASS GIS team will organize a '''GRASS Developer and Power User Meeting, aka 'GRASS Community Sprint'''' from '''2-7 Feb, 2013'''. The sprint is at the same time of the [http://geomorfolab.arch.unige.it/genova2013/index.php?lang=en XIV Meeting degli Utenti Italiani Grass e Gfoss], 6-9 Feb 2013, University of Genova, Dipartimento di Scienze per l'Architettura della Scuola Politecnica, [http://en.wikipedia.org/wiki/Genoa Genova], [http://en.wikipedia.org/wiki/Italy Italy].

== Purpose ==

This next edition of the GRASS GIS community sprint 2013 is a great occasion for folks to support the development by actively contributing to the source code, manuals or likewise. The '''community''' sprint is a get-together for GRASS project members and supporters and related [http://www.osgeo.org/ OSGeo] projects to make decisions and tackle larger problems. For this meeting, we welcome people committed to improving the GRASS GIS project and the interfaces to [[QGIS GRASS Cookbook|QGIS]], [[GDAL]], [[PostGIS]], [[R statistics]], [[GRASS and Sextante|Sextante, gvSIG]], OGC Services (esp. [[WPS]]) and more. This includes developers, documenters, bug reporters, translators and others.

For this meeting, we welcome people committed to improving the GRASS GIS and related projects. This includes developers, document writers, wish and bug reporters, translators etc.

== 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 travelling and accommodation expenses for GRASS developers with far arrival. If you are interested to sponsor the GRASS Community Sprint, please read about

:::'''sponsoring the GRASS project at [http://grass.osgeo.org/donations/ http://grass.osgeo.org/donations/]'''

For questions, please contact [[User:Lucadelu|Luca Delucchi]] <tt><lucadeluge at gmail.com></tt>. Any surplus at the end of the event will be turned over to the GRASS GIS project.

The third GRASS Community Sprint is a great occasion for you to support the development of GRASS. With your contribution you'll enable more developers to meet. The community sprint is an important opportunity for the GRASS developers to discuss and collaboratively resolve bugs, plan the direction for the project and work on new features. Please see below for the more 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 sprint will be directly contributed back into the GRASS project to the benefit of everyone who uses it.

== Timing ==

'''When''': 2-7 Feb, 2013

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

'''Duration''': 6 days

== Venue ==

For the 2nd and 3rd of February we are hosted by the [http://www.alid.it ALID association] at Circolo Zenzero in [http://osm.org/go/xX0m6qo~B-- Via Torti 35, Genova] (in Italy universities are closed during weekends).

From 4th to 7th at University of Genova, Dipartimento di Scienze per l'Architettura della Scuola Politecnica, Genova, Italy.

'''[http://geomorfolab.arch.unige.it/ Geomorfolab]''',
Dipartimento di Scienze per l'Architettura,
Scuola Politecnica - Università degli Studi di Genova,
[http://osm.org/go/xX0ml6cj7-- Stradone S. Agostino 37, 16128 Genova]

Rooms: TBD

== Accommodation and Costs ==

* Bed and breakfast (few rooms) - close to venue (please contact [[User:Lucadelu|Luca Delucchi]] <tt><lucadeluge at gmail.com></tt>)
* New youth hostel, http://www.manenahostel.it/ - close to venue (please contact [[User:Lucadelu|Luca Delucchi]] <tt><lucadeluge at gmail.com></tt>)
* List of [http://geomorfolab.arch.unige.it/genova2013/index.php?option=com_content&view=article&id=42&Itemid=18 Site of XIV Meeting degli utenti italiani GRASS e GFOSS]

== Weather and Common Item Prices ==

== Agenda ==

=== Timeline ===

==== Saturday, 2 Feb ====
* Kick-off in the [http://www.alid.it ALID association] at Circolo Zenzero in [http://osm.org/go/xX0m6qo~B-- Via Torti 35, Genova]
* Participants presentation
* Dinner: at Circolo Zenzero

==== Sunday, 3 Feb ====
* 9:00-evening
* Meeting again in the at Circolo Zenzero

List of topics:
* TBD
* Dinner: at Circolo Zenzero

==== Monday, 4 Feb ====
* 9:00-evening
* Meeting at University of Genova, Dipartimento di Scienze per l'Architettura della Scuola Politecnica, Genova, Italy at the '''[http://geomorfolab.arch.unige.it/ Geomorfolab]''', [http://osm.org/go/xX0ml6cj7-- Stradone S. Agostino 37, 16128 Genova]

List of topics:
* TBD

==== Tuesday, 5 Feb ====
* 9:00-evening
* Meeting again at University of Genova, Geomorfolab

List of topics:
* TBD

==== Wednesday, 6 Feb ====
* 9:00-evening
* Meeting again at University of Genova, Geomorfolab

List of topics:
* TBD
* Group photo!!
* Prepare press release

==== Thursday, 7 Feb ====
* 9:00-evening
* Meeting again at University of Genova, Geomorfolab

List of topics:
* TBD
* Prepare short presentations for Friday at the Italian GFOSS meeting
* Finish and publish press release

Closing of community sprint

==== Friday, 8 Feb ====
* Two hours of time for '''presenting Community Sprint results''' at Italian GFOSS meeting ([http://geomorfolab.arch.unige.it/genova2013/index.php?option=com_content&view=article&id=29&Itemid=21&lang=en venue])

== Participation ==

=== 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'''
!'''Topic'''
!width=75px|'''T-Shirt'''
!'''Notes'''
|-
|1
|[[User:Lucadelu|Luca Delucchi]]
|Italy
| Feb 2
| Feb 10
|
| L
|
|-
|2
|[[User:Neteler|Markus Neteler]]
|Italy
|
|
|
| M + S
|
|-
|3
|[[User:Madi|Margherita Di Leo]]
|Italy
|
|
|
| L
|
|-
|4
|[[User:pcav|Paolo Cavallini]]
|Italy
|
|
|
| L
|
|-
|5
|[[User:lcasagrande|Luca Casagrande]]
|Italy
|
|
| GRASS Tutorial with Open Data from Italy
| L
|
|-
|6
|[[User:Annakrat|Anna Kratochvilova]]
|Czech Republic
|
|
|
| M
|
|-
|7
|Vaclav Petras
|Czech Republic
|
|
|
| M
|
|-
|8
|[[User:pietro|Pietro Zambelli]]
|Italy
| Feb 2
| Feb 9
| Python and Pygrass workshops
| M
|
|-
|9
|[[User:Landa|Martin Landa]]
|Czech Republic
| Feb 2
| Feb 10
| [[wxGUI]], vector architecture, GRASS 7 development
| L
| Probably unable to come :-(
|-
|10
|[[User:Maxi|Massimiliano Cannata]]
|Italy
|
|
|
| XL
|
|-
|11
|[[User:NikosA|Nikos Alexandris]]
|Greece
|
|
| GRASS-wiki, (re-)working on the idea for a practical & visual guide to GRASS-GIS, testing all landsat related (core + addons) modules
| M
| Will be there with Nikos V!
|-
|12
|[[User:AnneGhisla|Anne Ghisla]]
|Italy
|
|
| fix v.krige, examine i.atcorr problems with RapidEye
| M
| Almost sure of participation
|-
|13
|[[User:vesnikos|Ves Nikos]]
|Greece
|
|
|
| L
| Will try and come with Nikos Alexandris
|-
|}

=== Via IRC chat ===

: [irc://freenode/grass #grass] on Freenode

For details, see [[IRC]]

=== Collaborative document scratching ===

== Individual Preparation ==

* Bring your own computer
* Bring [http://en.wikipedia.org/wiki/Mains_electricity_by_country your power connector adapter] if needed ([http://en.wikipedia.org/wiki/File:L_plug.jpg Italy])
* Install subversion and the compiler tools, and come with a working GRASS development environment if possible.

== Photos ==

Also during the event :)

== FAQ ==

* How was it last time?
** Very cool, see [[GRASS Community Sprint Prague 2012]]!
* ''Is the GRASS Community Sprint 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 Sprint for developers only?''
** Not at all: anybody can help, with testing, checking out bugs and fixes, documentation and more.
* ''Where can I get help and more information about the community sprint?''
** Contact [[User:Lucadelu|Luca Delucchi]] <tt><lucadeluge at gmail dot com></tt> or [[User:Neteler|Markus Neteler]]

[[Category: Workshops]]

GRASS Community Sprint Genova 2013

2012-10-06T14:14:57Z

⚠️Pietro: /* In person */

GRASS GSoC 2012 High level map interaction

2012-08-17T21:28:34Z

⚠️Pietro: /* Report11 - 2012-08-17 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || {{done}}
|-
|August 17 || Add support to the Vector head structure || {{done}}
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== Report11 - 2012-08-10 ==

=== What did I do this week? ===

This week I did a lot of works:

* move the documentation from ReadTheDocs to: http://www.ing.unitn.it/~zambelli/projects/pygrass in this way I'm able to use the sphinx automodule to document the API.
* Add more examples and documentation on vector geometry features: http://www.ing.unitn.it/~zambelli/projects/pygrass/vector.html
* Add a basic support for the vector attributes: http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html

To run the above examples you need to use the North Carolina mapset, copy and build the topology, and copy the table attributes from dbf to sqlite and/or postgresql.

=== What will I be working on next week? ===

I will add the write mode to the Vector objects.

=== Did I meet with any stumbling blocks? ===

None

== Report12 - 2012-08-17 ==

=== What did I do this week? ===

* Re-organize the code structure;
* Add more documentation for each class, and when possible add docstring http://www.ing.unitn.it/~zambelli/projects/pygrass/;
* Add README, AUTHOR, NEWS files to the project root;
* Add the setup.py file to the project;
* Split the Vector class into Vector (without topology) and in VectTopo (with the topology support);
* Add vector head information.

=== What will I be working on next week? ===

Going on cleaning and fixing the code.

=== Did I meet with any stumbling blocks? ===

None

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-17T21:26:52Z

⚠️Pietro: /* Project plan */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || {{done}}
|-
|August 17 || Add support to the Vector head structure || {{done}}
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== Report11 - 2012-08-10 ==

=== What did I do this week? ===

This week I did a lot of works:

* move the documentation from ReadTheDocs to: http://www.ing.unitn.it/~zambelli/projects/pygrass in this way I'm able to use the sphinx automodule to document the API.
* Add more examples and documentation on vector geometry features: http://www.ing.unitn.it/~zambelli/projects/pygrass/vector.html
* Add a basic support for the vector attributes: http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html

To run the above examples you need to use the North Carolina mapset, copy and build the topology, and copy the table attributes from dbf to sqlite and/or postgresql.

=== What will I be working on next week? ===

I will add the write mode to the Vector objects.

=== Did I meet with any stumbling blocks? ===

None

== Report11 - 2012-08-17 ==

=== What did I do this week? ===

* Re-organize the code structure;
* Add more documentation for each class, and when possible add docstring http://www.ing.unitn.it/~zambelli/projects/pygrass/;
* Add README, AUTHOR, NEWS files to the project root;
* Add the setup.py file to the project;
* Split the Vector class into Vector (without topology) and in VectTopo (with the topology support);
* Add vector head information.

=== What will I be working on next week? ===

Going on cleaning and fixing the code.

=== Did I meet with any stumbling blocks? ===

None

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-17T21:24:58Z

⚠️Pietro: /* Report12 - 2012-08-17 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== Report11 - 2012-08-10 ==

=== What did I do this week? ===

This week I did a lot of works:

* move the documentation from ReadTheDocs to: http://www.ing.unitn.it/~zambelli/projects/pygrass in this way I'm able to use the sphinx automodule to document the API.
* Add more examples and documentation on vector geometry features: http://www.ing.unitn.it/~zambelli/projects/pygrass/vector.html
* Add a basic support for the vector attributes: http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html

To run the above examples you need to use the North Carolina mapset, copy and build the topology, and copy the table attributes from dbf to sqlite and/or postgresql.

=== What will I be working on next week? ===

I will add the write mode to the Vector objects.

=== Did I meet with any stumbling blocks? ===

None

== Report11 - 2012-08-17 ==

=== What did I do this week? ===

* Re-organize the code structure;
* Add more documentation for each class, and when possible add docstring http://www.ing.unitn.it/~zambelli/projects/pygrass/;
* Add README, AUTHOR, NEWS files to the project root;
* Add the setup.py file to the project;
* Split the Vector class into Vector (without topology) and in VectTopo (with the topology support);
* Add vector head information.

=== What will I be working on next week? ===

Going on cleaning and fixing the code.

=== Did I meet with any stumbling blocks? ===

None

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-10T22:20:23Z

⚠️Pietro: /* What did I do this week? */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== Report11 - 2012-08-10 ==

=== What did I do this week? ===

This week I did a lot of works:

* move the documentation from ReadTheDocs to: http://www.ing.unitn.it/~zambelli/projects/pygrass in this way I'm able to use the sphinx automodule to document the API.
* Add more examples and documentation on vector geometry features: http://www.ing.unitn.it/~zambelli/projects/pygrass/vector.html
* Add a basic support for the vector attributes: http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html

To run the above examples you need to use the North Carolina mapset, copy and build the topology, and copy the table attributes from dbf to sqlite and/or postgresql.

=== What will I be working on next week? ===

I will add the write mode to the Vector objects.

=== Did I meet with any stumbling blocks? ===

None

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-10T22:19:20Z

⚠️Pietro: /* Report11 - 2012-08-10 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== Report11 - 2012-08-10 ==

=== What did I do this week? ===

This week I did a lot of works:

* move the documentation from ReadTheDocs to: http://www.ing.unitn.it/~zambelli/projects/pygrass in this way I'm able to use the sphinx automodule to document the API.
* Add more examples and documentation on vector geometry features: http://www.ing.unitn.it/~zambelli/projects/pygrass/vector.html
* Add a basic support for the vector attributes:
http://www.ing.unitn.it/~zambelli/projects/pygrass/attributes.html

To run the above examples you need to use the North Carolina mapset, copy and build the topology, and copy the table attributes from dbf to sqlite and/or postgresql.

=== What will I be working on next week? ===

I will add the write mode to the Vector objects.

=== Did I meet with any stumbling blocks? ===

None

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-10T22:10:50Z

⚠️Pietro: /* Project plan */ update

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Add basic vector features || {{done}}
|-
|August 3 || Add complex vector features || {{done}}
|-
|August 10 || Add support for vector attributes || {{done}}
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-08-03T20:42:08Z

⚠️Pietro: /* Report10 - 2012-08-03 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Implement Vector class || missing
|-
|August 3 || Implement Vector class || missing
|-
|August 10 || Implement Vector class || missing
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== Report10 - 2012-08-03 ==

=== What did I do this week? ===

Go on with the vector API, add more geometry feature like border, isle, and area, clean the code and study vector documentation and functions.
This week I did an university exam, the last one for this summer.

=== What will I be working on next week? ===

Start to test the new vector classes add test and documentation

=== Did I meet with any stumbling blocks? ===

As the last week I'm studying more and more the vector API of GRASS, I would like to have more time... :-)

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-07-27T21:19:47Z

⚠️Pietro: /* Report9 - 2012-07-27 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Implement Vector class || missing
|-
|August 3 || Implement Vector class || missing
|-
|August 10 || Implement Vector class || missing
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== Report9 - 2012-07-27 ==

=== What did I do this week? ===

I've worked on vector API, in particular on geometry feature.

====Point====

* class Point(x, y, z=None, is2D=True)
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.x
0.0
>>> pnt.y
0.0
>>> pnt.z
>>> pnt.is2D
True
>>> pnt.coords()
(0.0, 0.0)
>>> pnt.z = 0
>>> pnt.is2D
False
>>> pnt
Point(0.000000, 0.000000, 0.000000)
>>> print pnt
POINT(0.000000, 0.000000, 0.000000)
</source>

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return an Area object using the Vect_point_buffer2 C function. Creates buffer around the point (px, py).

* coords()
Return a tuple with the point coordinates.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.coords()
(0.0, 0.0)
</source>
If the point is 2D return a x, y tuple.

* distance(pnt)
Calculate distance of 2 points, using the Vect_points_distance C function, If one of the point have z == None, return the 2D distance.
<source lang="python">
>>> pnt0 = Point(0, 0, 0)
>>> pnt1 = Point(1, 0)
>>> pnt0.distance(pnt1)
1.0
>>> pnt1.z = 1
>>> pnt1
Point(1.000000, 0.000000, 1.000000)
>>> pnt0.distance(pnt1)
1.4142135623730951
</source>
The distance method require a :class:Point or a tuple with the coordinates.

* get_wkb()
Return a “well know binary” (WKB) geometry buffer

* get_wkt()
Return a “well know text” (WKT) geometry string.
<source lang="python">
>>> pnt = Point(0, 0)
>>> pnt.get_wkt()
'POINT(0.000000, 0.000000)'
</source>
Only POINT (2/3D) are supported, POINTM and POINT with: XYZM are not supported yet.

====Line====

class Line(points=None, mapinfo=None, lineid=None, field=None, is2D=True)
Instantiate a new Line with a list of tuple, or with a list of Point.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 0.000000),
Point(1.000000, -1.000000)])
</source>

* append(pnt)
Appends one point to the end of a line, using the Vect_append_point C function.
<source lang="python">
>>> line = Line()
>>> line.append((10, 100))
>>> line
Line([Point(10.000000, 100.000000)])
>>> line.append((20, 200))
>>> line
Line([Point(10.000000, 100.000000), Point(20.000000, 200.000000)])
</source>
Like python list.

* bbox()
Return the bounding box of the line, using Vect_line_box C function.
<source lang="python">
>>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
>>> bbox = line.bbox()
>>> bbox.north
1.0
>>> bbox.south
0.0
>>> bbox.east
2.0
>>> bbox.west
0.0
>>> bbox.top
0.0
>>> bbox.bottom
0.0
</source>
It is possible to access to the C struct of the object with: bbox.c_bbox

* buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)
Return the buffer area around the line, using the Vect_line_buffer2 C function.
Not implemented yet.

* delete(indx)
Remove the point in the index position.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.delete(-1)
>>> line
Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
</source>

* distance(pnt)
Return a tuple with:
- the closest point on the line,
- the distance between these two points,
- distance of point from segment beginning
- distance of point from line
The distance is compute using the Vect_line_distance C function.

* extend(line, forward=True)
Appends points to the end of a line.

It is possible to extend a line, give a list of points, or directly with a line_pnts struct.

If forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.extend( Line([(2, 2), (3, 3)]) )
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000),
Point(3.000000, 3.000000)])
</source>
Like python list, it is possible to extend a line, with another line or with a list of points.

* from_wkt(wkt)
Read a WKT string.
<source lang="python">
>>> line = Line()
>>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(1.000000, 2.000000)])
</source>

* get_first_cat()
Fetches FIRST category number for given vector line and field, using the Vect_get_line_cat C function.

* get_pnt(distance, angle=0, slope=0)
Return a Point object on line in the specified distance, using the Vect_point_on_line C function. Raise a ValueError If the distance exceed the Line length.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.get_pnt(5)
Traceback (most recent call last):
...
ValueError: The distance exceed the lenght of the line, that is: 1.414214
>>> line.get_pnt(1)
Point(0.707107, 0.707107)
</source>

* get_wkt()
Return a Well Known Text string of the line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 2)])
>>> line.get_wkt()
'LINESTRING(0.000000 0.000000, 1.000000 1.000000, 1.000000 2.000000)'

* insert(indx, pnt)
Insert new point at index position and move all old points at that position and above up, using Vect_line_insert_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1)])
>>> line.insert(0, Point(1.000000, -1.000000) )
>>> line
Line([Point(1.000000, -1.000000),
Point(0.000000, 0.000000),
Point(1.000000, 1.000000)])
</source>

* length()
Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length()
2.414213562373095
</source>

* length_geodesic()
Calculate line length, usig Vect_line_geodesic_length C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (0, 1)])
>>> line.length_geodesic()
2.414213562373095
</source>

* pop(indx)
Return the point in the index position and remove from the Line.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> midle_pnt = line.pop(1)
>>> midle_pnt
Point(1.000000, 1.000000)
>>> line
Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
</source>

* prune()
Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (1, 1), (2, 2)])
>>> line.prune()
>>> line
Line([Point(0.000000, 0.000000),
Point(1.000000, 1.000000),
Point(2.000000, 2.000000)])
</source>

* prune_thresh(threshold)
Remove points in threshold, using the Vect_line_prune_thresh C funtion.

* remove(pnt)
Delete point at given index and move all points above down, using Vect_line_delete_point C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.remove((2, 2))
>>> line[-1]
Point(1.000000, 1.000000)

* reset()
Reset line, using Vect_reset_line C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> len(line)
4
>>> line.reset()
>>> len(line)
0
>>> line
Line([])
</source>

* reverse()
Reverse the order of vertices, using Vect_line_reverse C function.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 2)])
>>> line.reverse()
>>> line
Line([Point(2.000000, 2.000000),
Point(1.000000, 1.000000),
Point(0.000000, 0.000000)])
</source>

* segment(start, end)
Create line segment. using the Vect_line_segment C function.
</source>

* toarray()
Return an array of coordinates.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.toarray()
array([[ 0., 0.],
[ 1., 1.],
[ 2., 0.],
[ 1., -1.]])
</source>

* tolist()
Return a list of tuple.
<source lang="python">
>>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
>>> line.tolist()
[(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]
</source>

=== What will I be working on next week? ===

Implement the other vector features.

=== Did I meet with any stumbling blocks? ===

Not really, but I need more time to assimilate the ideas of the GRASS vector API.

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-07-20T13:12:13Z

⚠️Pietro: /* Report8 - 2012-07-20 */

''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || [[User:Pietro|Pietro Zambelli]], University of Trento, Italy
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Sören Gebbert, Backup mentors: Luca Delucchi, Martin Landa
|-
| Title: || '''Proposal for a high level maps interaction'''
|-
|}

= Proposal for a high level maps interaction =

The idea is: extend the python GRASS API to make it more pythonic :-)

As you can see in the subsequent tests, a lot of functionality are redundant, similarly with `numpy` library<ref>http://numpy.scipy.org/</ref> I think that could be a good idea binding all the grass functions and add some of them as methods of the class.

For example you can use both:
<source lang="python">
# import the raster function
>>> import grass.obj.function.raster as r

# import the raster object library
>>> import grass.obj.raster as raster

# initialize a RasterObject present in the mapset with
>>> dtm = raster.Raster('dtm10')

# then you can print the info using the class method
>>> print(dtm.info())

# or using grass function
>>> print(r.info(dtm))
</source>

== GRASS as Python library ==

I would like to have the ability to call GRASS as a normal Python library outside GRASS environment::
<source lang="python">
# import the library
>>> import grass

# specify the mapset
>>> grass.obj.config(mapset='/path/to/gisdata/location/mapset')
</source>

== Region as an object ==

=== Region Attributes, read and write ===

<source lang="python">
# import the new virtual extension of the GRASS API
>>> import grass.obj.region as region

# save as default region option: `-s`
>>> region.default = True

# see region parameters as attribute of the class
>>> region.nsres
10

# change the region parameters in a more pythonic way
>>> region.nsres = 20

# view the region extension
>>> region.bbox
[(4928030,589980),(4913690, 609000)]

# change the region extension directly
>>> region.bbox = [(4928030,589980),(4913690, 609000)]

# view the convergence angle (degrees CCW)
>>> region.conv_angle
0.0

>>> region.name = 'Trento'
</source>

=== Region Methods ===

<source lang="python">
# print the current region `-p`
>>> print(region) # using the `__str__` method

# set as default region `-s`
>>> region.set_as_default() # It's equal to set `region.default = True`

# set from default region `-d`
>>> region.set_from(regionname='default')

# set region from a map
>>> region.set_from_map(MapObject)

# align region to resolution (default = align to bounds, works only for 2D resolution)
>>> region.align()

# adjust region cells to cleanly align with this raster map
>>> region.align(RastObj)

# shrink region until it meets non-NULL data from this raster map
>>> region.zoom(RastObj)

# save current region settings in named region file
>>> region.save('/your/path') # will produce a file: '/your/path/%s.region' % region.name
</source>

== Maps as objects ==

=== MapObject class ===

==== Map Attributes ====

Similarly with the region the MapObject is characterize by some attributes, but only some of these attributes are modifiable.

===== Read and Write =====

Suppose that we initialize a MapObject called `dtm`

<source lang="python">
# import the raster object library
>>> import grass.obj.Raster as Raster

# load an existing raster map, read mode
>>> dtm = Raster(name = "dtm", mapset = "", mode = 'r', method = 'row')
# create a new map, write mode
>>> dtm2 = Raster(name = "dtm2", mapset = "", mode = 'w', method = 'row')
# open the maps
>>> dtm.open(); dtm2.open()

# access row by row
>>> for i in range(dtm.rows):
... dtm2[i] = 2 * dtm[i] # dtm[i] return a numpy array

# access cell by cell
>>> for row in dtm:
... for cell in row:
... # do something

# close
>>> dtm.close(); dtm2.close()

# open in read & write mode
>>> dtm.open(mode = 'rw', method = 'segmentation')
>>> for row in dtm:
... row *= 2
>>> dtm.close()

# to rename the map you have just to reassign the Map attribute
>>> dtm.name = 'dtm__10x10m'

>>> dtm.title
"Digital Terrain Model compute from LIDAR2008"

# to change the title, as before, you can just reassign the Map attribute
>>> dtm.title = "Digital Terrain Model compute from LIDAR2008; Licence: Creative Common 0"

# to see in witch mapset the map is
>>> dtm.mapset
'/your/gisbase/location0/mapset'

# if you want to copy the map in another mapset changing the projection
>>> dtm.mapset = '/your/gisbase/location1/mapset
</source>

===== Read only attributes =====

This attributes are only readable, and are relative to the attributes of the map and not to the region.

<source lang="python">

>>> dtm.north
4928030
>>> dtm.south
4913690
>>> dtm.east
609000
>>> dtm.west
589980

# what append if the user try to change the resolution of the map
>>> dtm.north = 4928000
SyntaxError: invalid syntax.
you can not modify the map attributes,
please consider to change region parameters.

>>> dtm.bbox
[(4928030,589980),(4913690, 609000)]
>>> dtm.type
'raster'
>>> dtm.creator
'pietro'
>>> dtm.creationtime
datetime.datetime(2012, 3, 9, 17, 25, 6, 406987)
</source>

==== Map Methods ====

<source lang="python">
# return the args and the kargs that generated the map
>>> dtm.generated_by()
(["r.in.ogr", "bla", "bla"], {'overwrite' : True})

# return the bash command string that generate the map
>>> dtm.bash()
"r.in.ogr bla bla -overwrite=True"

# to rename the map in the mapset
>>> dtm.rename('newname0')

# to copy the mapname
>>> dtm.copy('newmap1')

# to copy the mapname in an other mapset
>>> dtm.copy('newmap2', mapset='path/to/your/mapset')
</source>

=== Raster Map ===

==== Raster attributes ====

Raster class is a child class of the MapObject and inherits all the attributes and methods, and add some more specific attributes and methods

===== Read only attributes =====

<source lang="python">
>>> dtm.min
0.000000
>>> dtm.max
52.520164
>>> dtm.nsres
30
>>> dtm.ewres
30
>>> dtm.datatype
FCELL
>>> dtm.rows
477
>>> dtm.cols
634
>>> dtm.cells
302418
</source>

===== Raster Methods =====

One thing that some time could be useful is the access to the low level of C library from python,
This is a stupid example, and for this kind of things is better to use the Map algebra, but I think that sometimes have an access to a low level function is useful.

<source lang="python">
# import the raster object library
>>> import grass.obj.raster as raster

# initialize an empty raster map, copy from another
>>> newmap = raster.Raster('newmap')
>>> for row in dtm:
... for pixel_coords in row.not_null():
... # pixel_coords is a couple of values, with the row and col
... # do something...
</source>

==== Multilayer raster (i.group) ====

<source lang="python">
# initialize a multi raster map
>>> multi = raster.MultiRaster('multi')

# add layers
>>> multi['elev'] = dtm
>>> multi['slope'] = slope_aspect(dtm, slope = 'slope')

# query to one point
>>> multi[10,10]
{'elev': 100, 'slope': 30}
>>> multi['elev'][10,10]
100
>>> multi.layers() or multi.keys()
('elev', 'slope')
>>> multi[10,10].items()
(val0, val1)
</source>

==== Time raster ====

I know that there are a lot of new staff regarding the time maps, but I don't know exactly how they works therefore any hint are welcome.

=== Vector MapObject ===

For the vector we can add some particular attributes and methods.
<source lang="python">
# import the vector object library
>>> import grass.obj.vector as vector

# import a vector map from file into the location and load
>>> roads = vector.import(fname = 'roads.shp', name = 'roads')

# or if the map already exist in the mapset
>>> roads = vector.Vector('roads')

# add a category column
>>> roads.add_column('length')
>>> for road in roads:
... road.cols.length = road.length()

>>> for road in roads:
... for point in road:
... # do something with point
</source>

See [[GRASS SoC Ideas 2012/High level map interaction/Vector]] for more info.

== Execute function==

<source lang="python">
>>> import grass.obj.function.vector as v
>>> import grass.obj.function.raster as r
>>> from math import pi

>>> road_buff_50 = v.buffer(roads, dist = 50.)

>>> slope_deg, aspect = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10')
>>> slope_rad = pi / 180 * slope_deg

# we can set that default values name are slope = 'slope' and aspect = 'aspect'
# PROBLEM: some function like r.slope.aspect, may return a different number of maps
# the function generate these map only if the name is given, could be?
# we need to generate a python function that read all the C header and generate
# the code, when the user build the package, using the GCC-XML?
# idea? hint?
>>> slope, aspect, dxx = r.slope_aspect(dtm, slope = 'slope10_deg',
... aspect = 'aspect10',
... dxx = 'dxx')

# of course we need to handle wrong input map
>>> slope, aspect = r.slope_aspect(road)
TypeMapError: The function: "slope_aspect" require a raster map.
</source>

== Algebra and logic function ==

Use mathematic functions and map algebra.
<source lang="python">
>>> import numpy as np
>>> drop = dtm.nsres * np.sin(slope_rad)
>>> dist = dtm.nsres * np.cos(slope_rad)
>>> length = np.sqrt(drop**2 + dist**2)

# use logic ::
>>> slope30 = slope if slope<=30 else None

# and similarly mixing raster and vector maps ::
>>> dtmroad = dtm if road else None
>>> dtmroad100 = dtm if road.cols.length <= 100 else None

# or you can make a mask, with boolean values:
>>> slope30 = slope <= 30

# or query a vector map with:
>>> track = road.cols.highway == 'track'
</source>

== Save and Export ==

<source lang="python">
# save all the maps created during the session ::
>>> grass.obj.session.save()

# or save or export, just one map: ::
>>> slope30.save()

# or save specify another location and mapset, with: ::
>>> slope30.save(location='locationname', mapset='mapsetname')

# export:
>>> slope30.export('filename', format='asciigrid')

# allow to convert a raster map to vector, like
>>> slope30.export('filename', format='shp')
You are converting a raster map to vector.
Choose your Feature type [POINT/line/area]: point

# or given directly the geometry type
>>> slope30.export('filename', format='shp', feature_type = 'point')
</source>

= Project plan =

{| {{table}}
|-
!Period !! Task !! Status / Notes
|-
|May 25 || Region class || using g.region {{done}}
|-
|June 1 || Implement Raster class || {{done}}
|-
|June 8 || Split Raster class, for each method || {{done}}
|-
|June 15 || Implement Buffer and RasterSegment classes || {{done}}
|-
|June 22 || Add documentation, doctest, and benchmark, RasterRowIO || {{done}}
|-
|June 29 || Add RasterNumpy class || {{done}}
|-
|July 6 || Add categories to Rasters classes || {{done}}
|-
|July 13 || Implement module wrapper class or function generator || {{done}}
|-
|'''July 13''' || Mid-term evaluations deadline || {{done}}
|-
|July 20 || Continue the module wrapper part || {{done}}
|-
|July 27 || Implement Vector class || missing
|-
|August 3 || Implement Vector class || missing
|-
|August 10 || Implement Vector class || missing
|-
|'''August 13''' || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc. || missing
|-
|August 17 || Implement Vector class || missing
|-
|'''August 20''' || Final evaluation
|}

= Weekly reports =

== Report0 - 2012-05-25 ==

=== What did I do this week? ===

* studying the C-API of grass and ctypes;
* at the moment I'm in Prague at the [[GRASS_Community_Sprint_Prague_2012|Code Sprint]] with a lot of main developers and power users of the amazing GRASS community! and I have the opportunity to exchange ideas with them.
* start to develop a first implementation of the Raster and Region class.
* open a new website on [http://code.google.com/p/pygrass/ | google code]
* make a new repository, have a look: git clone https://code.google.com/p/pygrass/ or [http://code.google.com/p/pygrass/downloads/list | download] it.

=== What will I be working on next week? ===

Go on with the develop to open the Raster class using the read and write mode with the `row` method. Clean the Region class to use only ctypes and avoid the use grass.run_command.
Continue to study the segment library of the C API.

=== Did I meet with any stumbling blocks? ===

I had some problem trying to use the segment library, but I hope to solve during the next week.

== Report1 - 2012-06-01 ==

=== What did I do this week? ===

* add more functionality to the raster object (rename, remove, del()):
<source lang="python">
# open an existing map
>>> elev = obj.Raster('elevation')
>>> elev.open()
# get the name of the map
>>> elev.name
'elevation'
# rename the map
>>> elev.name = 'elev'
>>> elev.name
'elev'
# or rename using the method
>>> elev.rename('elevation')
>>> elev.name
'elevation'
# we can check if the map exist with
>>> elev.exist()
True
# we can remove the map with
>>> elev.remove()
>>> elev.exist()
False
# or we can remove the map and de-instantiate the map object with
>>> del(elev)
</source>

* re-factoring some part of the code, the write row method has been changed from:
<source lang="python">
# open a new map
>>> new = obj.Raster('new', mode = 'w')
>>> new.open()

>>> c = 0
>>> for row in elev:
... new[c] = row
</source>
when we are writing with 'row' method, we can not choose which row write, the above syntax could make the users confused, we just add one more row to the file, so I have changed the behavior adding a new method 'writerow', that is more explicit, so now we write:

<source lang="python">
>>> for row in elev:
... new.writerow(row)
</source>

* Try to add a new Row object, to extend the capabilities, at the moment the Raster object return a LP_c_float, that support slice, but not support iteration and basic algebra:

<source lang="python">
>>> type(elev[0])
<class 'grass.lib.ctypes_preamble.LP_c_float'>

# making a Row object
>>> row = Row(elev[0], elev._cols)
# add the support for a sum
>>> row2 = row + 2
# we can convert the row into an array
>>> row.to_array()
array([ 1.03014536e+015, 1.06602391e+015, 1.12519191e+015, ...,
0.00000000e+000, 0.00000000e+000, 4.94065646e-324])
</source>

* Continuing to study the segmentation library, add some new function and C struct, that should call by the Raster class using ctypes.
* Start to think how the map algebra should be implemented, may be I could use jinja to make a template to generate a C code that will be compile when user make GRASS, then the Raster class just call this function with ctypes.

=== What will I be working on next week? ===

Implement the read and write mode using the segmentation library.

=== Did I meet with any stumbling blocks? ===

I do not understand how should I extend the class object "LP_c_float", without write a new class (Row).

== Report2 - 2012-06-08 ==

=== What did I do this week? ===

* As suggested by the mentor I split the Raster class into:

- RasterAbstractBase;
- RasterRow;
- RasterRowIO;
- RasterSegment;
- RasterNumpy;

* Discussed with my mentor the next steps;
* Studied the ctypes interface;
* Finished the module use to improve my C knowledge and to look the C API of grass [https://github.com/zarch/distdrop | r.distdrop];
* Took a course at the university;

=== What will I be working on next week? ===

Develop the RasterSegment class.

=== Did I meet with any stumbling blocks? ===

Still problem with "LP_c_float"

<source lang="python">
# import and open a map
>>> import obj
>>> elev = obj.RasterRow('elevation')
>>> elev.open()

# instantiate a Row object
>>> row0 = elev[0]

# now if I look at the object return by Rast_get_row function
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]

# rather than the row is
>>> row0[:3]
Row([ 1.03014536e+15, 1.06602391e+15, 1.12519191e+15])
</source>

as you see there is not correspondence, so I'm not convert correctly the
LP_c_float into a buffer.

I create the row with:

<source lang="python">
def __getitem__(self, row):
libraster.Rast_get_row(self._fd, self._pbuf, row, self._type)
buf = np.core.multiarray.int_asbuffer( c.addressof(self._pbuf.contents),
8*self._cols)
self.row = Row( (self._cols, ), buffer = buf)
return self.row
</source>

The good thing is that the elev._pbuf and row0 are looking at the same memory,
if I change the first row value:

<source lang="python">
>>>> row0[0]
1030145362214880.4

>>> row0[0] = 10
>>> elev._pbuf[:3]
[0.0, 2.5625, 141.37904357910156]

>>> row0[0] = 1030145362214880.4
>>> elev._pbuf[:3]
[141.9961395263672, 141.2784881591797, 141.37904357910156]
</source>

if I change the second value:

<source lang="python">
>>> row0[1]
1066023908387873.1

>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375]

>>> row0[1] = 10
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 0.0, 2.5625]

>>> row0[1] = 1066023908387873.1
>>> elev._pbuf[:4]
[141.9961395263672, 141.2784881591797, 141.37904357910156, 142.2982177734375
</source>

I don't understand this behavior. Any hint?

== Report3 - 2012-06-15 ==

=== What did I do this week? ===

Complete the Row class, the Row is an object that inherit from a [http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html | numpy.ndarray]. It is possible to read and write using the RastrRow

<source lang="python">
>>> import obj
>>> elev = obj.RasterRow("elevation");
>>> elev.open()
>>> el_le_100 = obj.RasterRow('elev_le_100', 'w', mtype = 'CELL', overwrite = True)
>>> el_le_100.open()
>>> for row in elev:
... el_le_100.put_row( row <= 100 )
...

>>> el_le_100.close()
</source>

Finish the RasterSegment class:

<source lang="python">
>>> import obj
>>> elev = obj.RasterSegment('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> new = obj.RasterSegment('new')
>>> new.open()
>>> for irow in xrange(elev.rows): new[irow] = elev[irow] < 144
>>> for row in new[:5]: print(row[:3])
[1 1 1]
[1 1 1]
[1 1 1]
[0 0 0]
[0 0 0]
>>> elev[0, 0] == elev[0][0]
True
>>> new[0, 0] = 10
>>> new[0, 0]
10
>>> new.close()
>>> new.exist()
True
>>> new.remove()
>>> elev.close()
</source>

=== What will I be working on next week? ===

Next week I will start to work to integrate RowIO and Numpy.
Start to add more documentation and tests and benchmarks.

=== Did I meet with any stumbling blocks? ===

No.

== Report4 - 2012-06-22 ==

=== What did I do this week? ===

Change names, and add new directories (obj => pygrass, docs, tests).
Start the documentation of the [http://pygrass.readthedocs.org/en/latest/raster.html | pygrass ]. Complete the RowIO class, and start to develop the RasterNumpy class. Start to develop tests using unittest. Benchmark the library, and compare the result with r.mapcalc.
Met the co-mentors (Luca de Lucchi and Martin Landa) to illustrate the work done and discuss with them the next steps.

What can you do with the RowIO library:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterRowIO('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> elev.close()
</source>

Start the RasterNumpy class:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[ True, True, True],
[ True, True, True],
[ True, True, True],
[False, False, False],
[False, False, False]], dtype=bool)
>>> el.name = 'new'
>>> el.close()

# but I have problem to read the new map
>>> new = pygrass.RasterNumpy('new', mtype = 'CELL')
>>> new.open()
>>> new[:5,:3]
RasterNumpy([[1124990723, 1124943691, 1124950281],
[1125050261, 1125016830, 1125035941],
[1125110156, 1125092365, 1125111544],
[1125159092, 1125160382, 1125178722],
[1125187249, 1125202588, 1125225033]], dtype=int32)
</source>

=== What will I be working on next week? ===

Finish the RasterNumpy class, start to work on raster categories and may be history.

=== Did I meet with any stumbling blocks? ===

No, Thank you to my mentor that give me the right hints!

== Report5 - 2012-06-29 ==

=== What did I do this week? ===

Finish the RasterNumpy class, it's working now:

<source lang="python">
>>> import pygrass
>>> elev = pygrass.RasterNumpy('elevation', 'PERMANENT')
>>> elev.open()
>>> for row in elev[:5]: print(row[:3])
[ 141.99613953 141.27848816 141.37904358]
[ 142.90461731 142.39450073 142.68611145]
[ 143.81854248 143.54707336 143.83972168]
[ 144.56524658 144.58493042 144.86477661]
[ 144.99488831 145.22894287 145.57142639]
>>> # in this case RasterNumpy is an extention of the numpy class
>>> # therefore you may use all the fancy things of numpy.
>>> elev[:5, :3]
RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
[ 142.90461731, 142.39450073, 142.68611145],
[ 143.81854248, 143.54707336, 143.83972168],
[ 144.56524658, 144.58493042, 144.86477661],
[ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
>>> el = elev < 144
>>> el[:5, :3]
RasterNumpy([[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]], dtype=int32)
>>> el.name == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.close()
>>> el.remove()
</source>

Add the RasterNumpy class to the benchmarks.
Start to study the C API to implement the categories.

=== What will I be working on next week? ===

Go on to develop categories support for the raster classes,

=== Did I meet with any stumbling blocks? ===

No

== Report6 - 2012-07-06 ==

=== What did I do this week? ===

Add categories to the Raster classes:

All the raster classes support raster categories and share commons methods to modify the raster category. It is possible to check if the map has or not the categories with the has_cats method.
<source lang="python">
>>> elev.has_cats()
False
</source>

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset. The has_cats method return True.
<source lang="python">
>>> land = pygrass.RasterRow('landcover_1m')
>>> land.has_cats()
True
</source>

Get and set the categories title, with:
<source lang="python">
>>> land.cats_title
'Rural area: Landcover'
>>> land.cats_title = 'Rural area: Landcover2'
>>> land.cats_title
'Rural area: Landcover2'
>>> land.cats_title = 'Rural area: Landcover'
</source>

Get the number of categories of the map with:
<source lang="python">
>>> land.num_cats()
11
</source>

See all the categories with:
<source lang="python">
>>> land.cats
[('pond', 1, None),
('forest', 2, None),
('developed', 3, None),
('bare', 4, None),
('paved road', 5, None),
('dirt road', 6, None),
('vineyard', 7, None),
('agriculture', 8, None),
('wetland', 9, None),
('bare ground path', 10, None),
('grass', 11, None)]
</source>

Access to single category, using Rast_get_ith_cat(), with:
<source lang="python">
>>> land.cats[0]
('pond', 1, None)
>>> land.cats['pond']
('pond', 1, None)
>>> land.get_cat(0)
('pond', 1, None)
>>> land.get_cat('pond')
('pond', 1, None)
</source>

Add new or change existing categories:
<source lang="python">
>>> land.set_cat('label', 1)
>>> land.get_cat('label')
('label', 1, None)
>>> land.set_cat('pond', 1, 1)
Sort categories, with:
</source>

>>> land.sort_cats()
Copy categories from another raster map with:
<source lang="python">
>>> land.copy_cats(elev)
</source>

Read and Write:
<source lang="python">
>>> land.read_cats()
>>> #land.write_cats()
</source>

Get a Category object or set from a Category object:
<source lang="python">
>>> cats = land.get_cats()
>>> land.set_cats(cats)
</source>

Export and import from a file:
<source lang="python">
>>> land.write_cats_rules('land_rules.csv', ';')
>>> land.read_cats_rules('land_rules.csv', ';')
</source>

Add a new History class:

Instantiate a new object, with:
<source lang="python">
>>> hist = pygrass.History()
</source>

read the history of a map:
<source lang="python">
>>> hist.read('aspect')
</source>

Then it is possible to read and change the history attributes:
<source lang="python">
>>> hist.creator
'helena'
>>> hist.creator = 'pietro'
>>> hist.src1
'raster elevation file elev_ned10m'
>>> hist.src2
''
>>> hist.keyword
'generated by r.slope.aspect'
>>> hist.date
datetime.datetime(2006, 11, 7, 1, 11, 23)
>>> hist.mapset
'PERMANENT'
>>> hist.maptype
'raster'
>>> hist.title
'asp_ned10m'
</source>

=== What will I be working on next week? ===

Next week I will work on a function factory to wrap all the Grass modules and see and interact with module as python functions.

I would like something like:

<source lang="python">
>>> import pygrass.modules.raster as r
>>> elev, slope, aspect, dxx = r.slope_aspect(elevation='elevation',
... slope='slope',
... aspect='aspect',
... dxx='dxx', overwrite = True)
</source>

or like:

<source lang="python">
>>> import pygrass
>>> import pygrass.modules.raster as r
>>> elev = pygrass.RasterRow('elevation')
>>> slope = pygrass.RasterRowIO('slope')
>>> aspect = pygrass.RasterSegment('aspect')
>>> dxx = pygrass.RasterNumpy('dxx')
>>> r.slope_aspect(elevation=elev, slope=slope aspect=aspect, dxx=dxx, overwrite = True)
</source>

The behavior and the implementation need to be discuss with my mentor. This is just an idea.

=== Did I meet with any stumbling blocks? ===

No

== Report7 - 2012-07-13 ==

=== What did I do this week? ===

Start to work on the pygrass modules class.

=== What will I be working on next week? ===

Continue with the the pygrass modules class.

=== Did I meet with any stumbling blocks? ===

No, I wrote a first implementation of the pygrass modules, but after discussion with my mentor I have started to rewrite the class.

== Report8 - 2012-07-20 ==

=== What did I do this week? ===

Finish the pygrass modules class and start to study the GRASS vector API.
Yesterday and today I had some troubles with my OS installation and hard disk.

The Module class read the xml module description and instantiate a Module class, that is a callable object, user can change parameters, and the object check if the parameter are or not valid.

<source lang="python">
>>> from pygrass.modules import Module
>>> slope_aspect = Module("r.slope.aspect")
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

or it is possible to run all in one line, similar to run_command, with:
<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True)
</source>

The Module class allow user to run the command later, with:

<source lang="python">
>>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
... slope='slp', aspect='asp',
... format='percent', overwrite=True, run_=False)
>>> slope_aspect()
</source>

The class allow to manage the process, and read stdout and stderr, with:
<source lang="python">
>>> slope_aspect = Module('r.slope.aspect')
>>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
>>> slope_aspect.popen.wait() # *.kill(), *.terminate()
0
>>> out, err = slope_aspect.popen.communicate()
</source>

for more info on the Module class look at: http://pygrass.readthedocs.org/en/latest/modules.html

=== What will I be working on next week? ===

Work on the Vector interface.

=== Did I meet with any stumbling blocks? ===

Not really, I need to better understand of the GRASS vector API.

== References ==

<references />
{{Python}}
{{GSoC}}

GRASS GSoC 2012 High level map interaction

2012-07-20T12:58:23Z

⚠️Pietro: /* Project plan */

GRASS SoC Ideas 2012/High level map interaction/Vector

2012-07-16T18:55:34Z

⚠️Pietro: vector brain storming

=Vector Maps=

==Vector Geometries==

I would like to implement different Geometry classes:

* point
* (segment)
* line
* boundary
* centroid
* area

<source lang="python">
>>> pnt0 = Point(x0, y0)
>>> pnt1 = Point(x1, y1)
>>> pnt2 = Point(x2, y2)
>>> line0 = Line([pnt0, pnt1, pnt2])
>>> bound0 = Boundary([pnt0, pnt1, pnt2])
>>> area = Area(bount0, Centroid(x3, y3))
</source>

===Line attributes and methods===

Line should have attributes, like:
<source lang="python">
>>> line0.length # return the length
960.5
>>> line0.bbox # return the bbox>>> for segment in line.nseg
2
(pnt0, pnt1)
>>> line0.number # return the number line
>>> for segment in line.nseg # return the number of segments
2
</source>

Line is iterable and return a point object.
<source lang="python">
>>> for point in line0:
... # do somenthing
</source>

Line should have a method to return a Segments.
<source lang="python">
>>> for segment in line.segs():
... # return a list of tuple [(pnt0, pnt1), (pnt1, pnt2),]
... # do somethig

>>> pnt0 in line0 # check if line contain point
True
>>> lineX in line0
</source>

===Boundary===

<source lang="python">
>>> bound0.perimeter()
1023.8
>>> bound.nseg # return the number of segments

>>> for point in bound0:
... # do something

>>> for seg in bound0.segs():
... # do something
</source>

===Area===

<source lang="python">
>>> area0.boundary # return a boundary object
>>> area0.centroid #return a point object
>>> area0.area()
2034
</source>
All the geometries object should have methods like the python sets (may be not all):

Operation Equivalent Result
len(s) return the number of points
x in s test x for membership in s
x not in s test x for non-membership in s
s.issubset(t) s <= t test whether every element in s is in t
s.issuperset(t) s >= t test whether every element in t is in s
s.union(t) s | t new set with elements from both s and t
s.intersection(t) s & t new set with elements common to s and t
s.difference(t) s - t new set with elements in s but not in t
s.symmetric_difference(t) s ^ t new set with elements in either s or t but not both
s.copy() new set with a shallow copy of s

more details on python sets here:

http://docs.python.org/library/sets.html#set-objects

and/or use some methods like shapely:

http://toblerity.github.com/shapely/manual.html#binary-predicates

and

http://toblerity.github.com/shapely/manual.html#spatial-analysis-methods

another possibility could be to include shapely to add a native support to grass and topology.

And point, line, boundary and Area should have a:
* buffer method, that return an Area object.
* distance method, that return the minimal distance between objcts
* wkt, return a well know text
* wkb, return well know binary

==Vector obj==

Vect obj should have attributes like:
<source lang="python">
>>> roads = Vect('roads')
>>> roads.name
'roads'
</source>

As for raster object should have an history object:
<source lang="python">
>>> road.hist.creator
'pietro'
</source>

<source lang="python">
>>> roads.exist()
True
>>> roads.isopen()
False
>>> for row in roads:
... # do something
...
</source>
>>> roads.open(topology = True)

===Layer===

===Topology===

===Categories===

===Attributes table===

The attributes table should be inherit from Structured Array class

http://docs.scipy.org/doc/numpy/user/basics.rec.html#structured-arrays

Vector should have a connection attribute:

<source lang="python">
>>> roads.connect
Connection (db='postgresql', user='pietro', etc.)
>>> roads.exist()
False
>>> roads.attributes # return a OrderedDict
OrderedDict([('cat', int),('name', str),('geo', geometry)])
</source>

we can add a new column with

<source lang="python">
>>> roads.attributes['length'] = float
>>> for road in roads:
... road['length'] = road.length

#as for numpy array:
>>> (roads['length'] <= 1000).nonzero() # return the index of all the roads that respect this conditions
</source>

allow SQL query:
<source lang="python">
>>> roads.sql("SELECT * FROM roads WHERE length <= 1000 ORDER BY length LIMIT 100")
</source>

GRASS GSoC 2012 High level map interaction

2012-07-13T20:58:03Z

⚠️Pietro: /* Report7 - 2012-07-13 */

Pylint rc file for GRASS

2012-07-11T09:31:06Z

⚠️Pietro: /* Pylint rc file */

Pylint is static code analyser for Python. You can use it for detecting errors in your source codes or to help follow coding standards. However, default Pylint configuration is not compatible with GRASS Python coding style. The rc file is on this page (use copy and paste). You can specify it rc file by <tt>--rcfile</tt> Pylint's command line option:
pylint --rcfile=grass_pylintrc module_or_package
If you are using Python editor which allows Pylint analysis but not allows specify Pylint's command line parameters (e.g. Spyder) you can create or replace <tt>.pylintrc</tt> file in your home directory.
# for GNU/Linux
cd ~
cp .pylintrc .pylintrc_old
cp grass_pylintrc .pylintrc

Note that you can also use Pylint for error checking only:
pylint --errors-only module_or_package

== Pylint rc file ==

''This version is not (yet) suitable for wxGUI but can be used for Python scripts.''

Get a copy of the file with:
<source lang="bash">
git clone git://gist.github.com/3089272.git gist-3089272
</source>

The content is: https://gist.github.com/3089272
<source lang="ini">
[MASTER]

# Specify a configuration file.
#rcfile=

# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
#init-hook=

# Profiled execution.
profile=no

# Add files or directories to the blacklist. They should be base names, not
# paths.
ignore=CVS

# Pickle collected data for later comparisons.
persistent=yes

# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
load-plugins=

[MESSAGES CONTROL]

# Enable the message, report, category or checker with the given id(s). You can
# either give multiple identifier separated by comma (,) or put this option
# multiple time.
#enable=

# Disable the message, report, category or checker with the given id(s). You
# can either give multiple identifier separated by comma (,) or put this option
# multiple time (only on the command line, not in the configuration file where
# it should appear only once).
#disable=

[REPORTS]

# Set the output format. Available formats are text, parseable, colorized, msvs
# (visual studio) and html
output-format=text

# Include message's id in output
include-ids=no

# Put messages in a separate file for each module / package specified on the
# command line instead of printing them on stdout. Reports (if any) will be
# written in a file name "pylint_global.[txt|html]".
files-output=no

# Tells whether to display a full report or only the messages
reports=yes

# Python expression which should return a note less than 10 (10 is the highest
# note). You have access to the variables errors warning, statement which
# respectively contain the number of errors / warnings messages and the total
# number of statements analyzed. This is used by the global evaluation report
# (RP0004).
evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)

# Add a comment according to your evaluation note. This is used by the global
# evaluation report (RP0004).
comment=no

[VARIABLES]

# Tells whether we should check for unused import in __init__ files.
init-import=yes

# A regular expression matching the beginning of the name of dummy variables
# (i.e. not used).
dummy-variables-rgx=_|dummy

# List of additional names supposed to be defined in builtins. Remember that
# you should avoid to define new builtins when possible.
additional-builtins=

[BASIC]

# Required attributes for module, separated by a comma
required-attributes=

# List of builtins function names that should not be used, separated by a comma
bad-functions=map,filter,apply,input

# Regular expression which should only match correct module names
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$

# Regular expression which should only match correct module level names
const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$

# Regular expression which should only match correct class names
class-rgx=[A-Z_][a-zA-Z0-9]+$

# Regular expression which should only match correct function names
function-rgx=[a-z_][a-zA-Z0-9_]{2,30}$

# Regular expression which should only match correct method names
method-rgx=[a-z_][a-zA-Z0-9_]{2,30}$

# Regular expression which should only match correct instance attribute names
attr-rgx=[a-z_][a-zA-Z0-9_]{2,30}$

# Regular expression which should only match correct argument names
argument-rgx=[a-z_][a-zA-Z0-9_]{2,30}$

# Regular expression which should only match correct variable names
variable-rgx=[a-z_][a-zA-Z0-9_]{2,30}$|[a-z]

# Regular expression which should only match correct list comprehension /
# generator expression variable names
inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$

# Good variable names which should always be accepted, separated by a comma
good-names=i,j,_,x,y,z,N,E,S,W

# Bad variable names which should always be refused, separated by a comma
bad-names=foo,bar,baz,toto,tutu,tata

# Regular expression which should only match functions or classes name which do
# not require a docstring
no-docstring-rgx=__.*__

[MISCELLANEOUS]

# List of note tags to take in consideration, separated by a comma.
notes=FIXME,TODO

# general regexp for convention, warning etc. would be great

[TYPECHECK]

# Tells whether missing members accessed in mixin class should be ignored. A
# mixin class is detected if its name ends with "mixin" (case insensitive).
ignore-mixin-members=yes

# List of classes names for which member attributes should not be checked
# (useful for classes with attributes dynamically set).
ignored-classes=SQLObject

# When zope mode is activated, add a predefined set of Zope acquired attributes
# to generated-members.
zope=no

# List of members which are set dynamically and missed by pylint inference
# system, and so shouldn't trigger E0201 when accessed. Python regular
# expressions are accepted.
generated-members=REQUEST,acl_users,aq_parent

[FORMAT]

# Maximum number of characters on a single line.
max-line-length=80

# Maximum number of lines in a module
max-module-lines=1000

# String used as indentation unit. This is usually " " (4 spaces) or "\t" (1
# tab).
indent-string=' '

[SIMILARITIES]

# Minimum lines number of a similarity.
min-similarity-lines=4

# Ignore comments when computing similarities.
ignore-comments=yes

# Ignore docstrings when computing similarities.
ignore-docstrings=yes

[DESIGN]

# Maximum number of arguments for function / method
max-args=5

# Argument names that match this expression will be ignored. Default to name
# with leading underscore
ignored-argument-names=_.*

# Maximum number of locals for function / method body
max-locals=15

# Maximum number of return / yield for function / method body
max-returns=6

# Maximum number of branch for function / method body
max-branchs=12

# Maximum number of statements in function / method body
max-statements=50

# Maximum number of parents for a class (see R0901).
max-parents=7

# Maximum number of attributes for a class (see R0902).
max-attributes=7

# Minimum number of public methods for a class (see R0903).
min-public-methods=2

# Maximum number of public methods for a class (see R0904).
max-public-methods=20

[IMPORTS]

# Deprecated modules which should not be used, separated by a comma
deprecated-modules=regsub,string,TERMIOS,Bastion,rexec

# Create a graph of every (i.e. internal and external) dependencies in the
# given file (report RP0402 must not be disabled)
import-graph=

# Create a graph of external dependencies in the given file (report RP0402 must
# not be disabled)
ext-import-graph=

# Create a graph of internal dependencies in the given file (report RP0402 must
# not be disabled)
int-import-graph=

[CLASSES]

# List of interface methods to ignore, separated by a comma. This is used for
# instance to not check methods defines in Zope's Interface base class.
ignore-iface-methods=isImplementedBy,deferred,extends,names,namesAndDescriptions,queryDescriptionFor,getBases,getDescriptionFor,getDoc,getName,getTaggedValue,getTaggedValueTags,isEqualOrExtendedBy,setTaggedValue,isImplementedByInstancesOf,adaptWith,is_implemented_by

# List of method names used to declare (i.e. assign) instance attributes.
defining-attr-methods=__init__,__new__,setUp

# List of valid names for the first argument in a class method.
valid-classmethod-first-arg=cls

[EXCEPTIONS]

# Exceptions that will emit a warning when being caught. Defaults to
# "Exception"
overgeneral-exceptions=Exception
</source>

{{Python}}

GRASS GSoC 2012 High level map interaction

2012-07-06T15:56:45Z

⚠️Pietro: /* Report6 - 2012-07-06 */

GRASS GSoC 2012 High level map interaction

2012-07-06T15:25:38Z

⚠️Pietro: /* Project plan */

GRASS GSoC 2012 High level map interaction

2012-06-29T20:01:47Z

⚠️Pietro: /* Report 5 */

GRASS GSoC 2012 High level map interaction

2012-06-22T17:55:11Z

⚠️Pietro: /* Report4 - 2012-06-22 */

GRASS GSoC 2012 High level map interaction

2012-06-19T13:34:04Z

⚠️Pietro: /* Project plan */

GRASS GSoC 2012 High level map interaction

2012-06-19T13:32:41Z

⚠️Pietro: /* Save and Export */

GRASS GSoC 2012 High level map interaction

2012-06-15T16:53:49Z

⚠️Pietro: /* Did I meet with any stumbling blocks? */

GRASS GSoC 2012 High level map interaction

2012-06-15T16:51:13Z

⚠️Pietro: /* What will I be working on next week? */

GRASS GSoC 2012 High level map interaction

2012-06-15T16:50:05Z

⚠️Pietro: /* What will I be working on next week? */

GRASS GSoC 2012 High level map interaction

2012-06-15T16:48:45Z

⚠️Pietro: /* What did I do this week? */

GRASS GSoC 2012 High level map interaction

2012-06-11T14:22:28Z

⚠️Pietro: /* Report3 - 2012-06-08 */

GRASS GSoC 2012 High level map interaction

2012-06-08T15:47:55Z

⚠️Pietro: /* Did I meet with any stumbling blocks? */

GRASS GSoC 2012 High level map interaction

2012-06-08T15:45:49Z

⚠️Pietro: /* Report2 - 2012-06-08 */

GRASS GSoC 2012 High level map interaction

2012-06-01T09:32:09Z

⚠️Pietro: /* Report1 - 2012-06-01 */

GRASS GSoC 2012 High level map interaction

2012-06-01T09:31:24Z

⚠️Pietro: /* correct identation */