PyGrass DocumentationRelease alpha

Pietro Zambelli

September 16, 2013

Contents

i

ii

PyGrass Documentation, Release alpha

Since in the 2006 GRASS developers start to adopt python for the new GUI, python becoming more and moreimportant and developers plan to convert all the bash scripts in to python for the next major release GRASS 7.

pygrass want to improve integration between GRASS and python, make the use of python under GRASS moreconsistent with the language itself and make the GRASS scripting and programming activity easier and morenatural to the final users.

This project has been funded with support from the google Summer of Code 2012.

Contents:

Contents 1

PyGrass Documentation, Release alpha

2 Contents

CHAPTER 1

Introduction

To work with pygrass you need a up-to-date version of GRASS 7. You can obtain a recent version followingthe information on the main web site of GRASS, and you can read more about compilation on the GRASS wiki

Now you can download the pygrass source using git

git clone https://lucadeluge@code.google.com/p/pygrass/

If you have not git you can install it from the git website or download the source code of pygrass fromhttp://code.google.com/p/pygrass/downloads/list

At this point you have to install pygrass, so enter in the right folder and launch with administration permission

python setup.py install

The last action before start to work with pygrass is to run GRASS 7 and from the console launch python oripython (the second one is the the suggested)

Read more about how to work with Raster, Vector, Modules.

3

PyGrass Documentation, Release alpha

4 Chapter 1. Introduction

CHAPTER 2

Raster

PyGrass use 4 different Raster classes, that respect the 4 different approaches of C grass API. The read access isrow wise for RastRow and RasterRowIO and additionally cached in the RowIO class. Booth classes write sequen-tially. RowIO is row cached, RastSegment and RasterNumpy are tile cached for reading and writing therefore arandomly access is possible. Hence RasterRow and RasterRowIO should be used in case for fast (cached) rowread access and RasterRow for fast sequential writing. Segment and Numpy should be used for random access,but numpy only for files not larger than 2GB.

Class Name C library Read WriteRastRow Raster library randomly sequentiallyRasterRowIO RowIO library cached noRastSegment Segmentation library cached randomlyRasterNumpy numpy.memmap cached randomly

All these classes share common methods and attributes, necessary to address common tasks as rename, remove,open, close, exist, is_open. In the next examples we instantiate a RasterRow object.

>>> from pygrass import raster>>> elev = raster.RasterRow(’elevation’)>>> elev.name’elevation’>>> print(elev)elevation@PERMANENT>>> elev.exist()True>>> elev.is_open()False>>> new = raster.RasterRow(’new’)>>> new.exist()False>>> new.is_open()False

We can rename the map:

>>> # setting the attribute>>> new.name = ’new_map’>>> print(new)new_map>>> # or using the rename methods>>> new.rename(’new’)>>> print(new)new

5

PyGrass Documentation, Release alpha

2.1 Categories

All the raster classes support raster categories and share commons methods to modify the raster category. It ispossible to check if the map has or not the categories with the has_cats method.

>>> elev.has_cats()False

Opening a map that has category, for example the “landcove_1m” raster map from the North Carolina mapset.The has_cats method return True.

>>> land = raster.RasterRow(’landcover_1m’)>>> land.has_cats()True

Get and set the categories title, with:

>>> land.cats_title’Rural area: Landcover’>>> land.cats_title = ’Rural area: Landcover2’>>> land.cats_title’Rural area: Landcover2’>>> land.cats_title = ’Rural area: Landcover’

Get the number of categories of the map with:

>>> land.num_cats()11

See all the categories with:

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

Access to single category, using Rast_get_ith_cat(), with:

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

Add new or change existing categories:

>>> land.set_cat(’label’, 1)>>> land.get_cat(’label’)(’label’, 1, None)>>> land.set_cat(’pond’, 1, 1)

Sort categories, with:

6 Chapter 2. Raster

PyGrass Documentation, Release alpha

>>> land.sort_cats()

Copy categories from another raster map with:

>>> land.copy_cats(elev)

Read and Write:

>>> land.read_cats()>>> #land.write_cats()

Get a Category object or set from a Category object:

>>> cats = land.get_cats()>>> land.set_cats(cats)

Export and import from a file:

>>> land.write_cats_rules(’land_rules.csv’, ’;’)>>> land.read_cats_rules(’land_rules.csv’, ’;’)

2.2 RastRow

PyGrass allow user to open the maps, in read and write mode, row by row using the Raster library, there is notsupport to read and write to the same map at the same time, for this functionality, please see the RastSegment andRasterNumpy classes. The RasterRow class allow to read in a randomly order the row from a map, but it is onlypossible to write the map using only a sequence order, therefore every time you are writing a new map, the row isadd to the file as the last row.

>>> raster = reload(raster)>>> elev = raster.RasterRow(’elevation’)>>> # the cols attribute is set from the current region only when the map is open>>> elev.cols>>> elev.open()>>> elev.is_open()True>>> elev.cols1500>>> # we can read the elevation map, row by row>>> 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]>>> # we can open a new map in write mode>>> new = raster.RasterRow(’new’)>>> new.open(’w’, ’CELL’)>>> # for each elev row we can perform computation, and write the result into>>> # the new map>>> for row in elev:... new.put_row(row < 144)...>>> # close the maps>>> new.close()>>> elev.close()>>> # check if the map exist>>> new.exist()True>>> # we can open the map in read mode>>> new.open(’r’)

2.2. RastRow 7

PyGrass Documentation, Release alpha

>>> for row in new[:5]: print(row[:3])[1 1 1][1 1 1][1 1 1][0 0 0][0 0 0]>>> new.close()>>> new.remove()>>> new.exist()False

2.3 RasterRowIO

The RasterRowIO class use the grass RowIO library, and implement a row cache. The RasterRowIO class supportonly reading the raster, because the raster rows can only be written in sequential order, writing by row id is notsupported by design. Hence, we should use the rowio lib only for caching rows for reading and use the defaultrow write access as in the RasterRow class.

>>> raster = reload(raster)>>> elev = raster.RasterRowIO(’elevation’)>>> elev.open(’r’)>>> 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()

2.4 RastSegment

The RasterSegment class use the grass Segmentation library, it work dividing the raster map into small differentfiles, that grass read load into the memory and write to the hardisk. The segment library allow to open a map in aread-write mode.

>>> raster = reload(raster)>>> elev = raster.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 = raster.RasterSegment(’new’)>>> new.open(’w’, ’CELL’)>>> 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]

The RasterSegment class define two methods to read and write the map:

8 Chapter 2. Raster

PyGrass Documentation, Release alpha

• get_row that return the buffer object with the row that call the C function segment_get_row.

>>> # call explicity the method>>> elev_row0 = elev.get_row(0)>>> # call implicity the method>>> elev_row0 = elev[0]

• get that return the value of the call map that call the C function segment_get.

>>> # call explicity the method>>> elev_val_0_0 = elev.get(0, 0)>>> # call implicity the method>>> elev_val_0_0 = elev[0, 0]

Similarly to write the map, with put_row, to write a row and with put to write a single value to the map.

>>> # compare the cell value get using the ‘‘get‘‘ method, and take the first>>> # value of the row with the ‘‘get_row‘‘ method>>> elev[0, 0] == elev[0][0]True>>> # write a new value to a cell,>>> new[0, 0] = 10>>> new[0, 0]10>>> new.close()>>> new.exist()True>>> new.remove()>>> elev.close()>>> elev.remove()

2.5 RasterNumpy

The RasterNumpy class, is based on the numpy.memmap class If you open an existing map, the map will be copiedon a binary format, and read to avoid to load all the map in memory.

>>> raster = reload(raster)>>> elev = raster.RasterNumpy(’elevation’, ’PERMANENT’)>>> elev.open(’r’)>>> # 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 == NoneTrue>>> # give a name to the new map>>> el.name = ’new’>>> el.exist()False>>> el.close()>>> el.exist()

2.5. RasterNumpy 9

PyGrass Documentation, Release alpha

True>>> el.remove()

2.6 Buffer

The buffer class is used to interact with a memory buffer of a map like a raster row. The buffer class is based onthe numpy.ndarray class. Therefore all the nice feature of the ndarray are allowed.

2.7 RowIO

2.8 Segment

2.9 History

2.10 Category

10 Chapter 2. Raster

CHAPTER 3

Vector

Instantiation and basic interaction.

>>> from pygrass.vector import VectTopo>>> municip = VectTopo(’boundary_municp_sqlite’)>>> municip.is_open()False>>> municip.mapset’’>>> municip.exist() # check if exist, and if True set mapsetTrue>>> municip.mapset’user1’

Open the map with topology:

>>> municip.open()

get the number of primitive:>>> municip.num_primitive_of(’line’)0>>> municip.num_primitive_of(’centroid’)3579>>> municip.num_primitive_of(’boundary’)5128

ask for other feature in the vector map:

>>> municip.number_of("areas")3579>>> municip.number_of("islands")2629>>> municip.number_of("holes")0>>> municip.number_of("lines")8707>>> municip.number_of("nodes")4178>>> municip.number_of("pizza")Traceback (most recent call last):

...ValueError: vtype not supported, use one of: ’areas’, ..., ’volumes’

Suppose that we want to select all and only the areas that have an area bigger than 10000m2:

11

PyGrass Documentation, Release alpha

>>> big = [area for area in municip.viter(’areas’)... if area.alive() and area.area >= 10000]

it’s pretty easy, isn’t it?!? :-)

the method “viter” return an iterator object of the vector features, in this way no memory is wasted... User canchoose on which vector features want to iterate...

then you can go on with python stuff like, sort by area dimension:

>>> from operator import methodcaller as method>>> big.sort(key = method(’area’), reverse = True) # sort the list>>> for area in big[:3]:... print area, area.area()Area(3102) 697521857.848Area(2682) 320224369.66Area(2552) 298356117.948

or sort for the number of isles that are contained inside:

>>> big.sort(key = lambda x: x.isles.__len__(), reverse = True)>>> for area in big[:3]:... print area, area.isles.__len__()...Area(2682) 68Area(2753) 45Area(872) 42

or you may have only the list of the areas that contain isles inside, with:

>>> area_with_isles = [area for area in big if area.isles]>>> area_with_isles[Area(...), ..., Area(...)]

Of course is still possible work only with a specific area, with:

>>> from pygrass.vector.geometry import Area>>> area = Area(v_id=1859, c_mapinfo=municip.c_mapinfo)>>> area.area()39486.05401495844>>> area.bbox() # north, south, east, westBbox(175711.718494, 175393.514494, 460344.093986, 460115.281986)>>> area.islesIsles([])

Now, find an area with an island inside...

>>> area = Area(v_id=2972, c_mapinfo=municip.c_mapinfo)>>> area.islesIsles([Isle(1538), Isle(1542), Isle(1543), ..., Isle(2571)])>>> isle = area.isles[0]>>> isle.bbox()Bbox(199947.296494, 199280.969494, 754920.623987, 754351.812986)

3.1 VectorTopo

3.2 Vector

12 Chapter 3. Vector

CHAPTER 4

Vector Features

4.1 Point

4.2 Line

4.3 Boundary

4.4 Isle

4.5 Isles

4.6 Area

13

PyGrass Documentation, Release alpha

14 Chapter 4. Vector Features

CHAPTER 5

Utils

5.1 Bbox

5.2 BoxList

5.3 Ilist

5.4 Cats

15

PyGrass Documentation, Release alpha

16 Chapter 5. Utils

CHAPTER 6

Attributes

It is possible to access to the vector attributes with:

>>> from pygrass.vector import Vector>>> municip = Vector(’boundary_municp_sqlite’)>>> municip.open()>>> municip.dblinksDBlinks([[Link(1, boundary_municp, sqlite)]])

The vector map have a table attributes that contain a Table object, that have some useful attributes like: layer,name, driver, etc.

>>> link = municip.dblinks[1]>>> link.number1>>> link.name’boundary_municp’>>> link.table_name’boundary_municp_sqlite’>>> link.driver’sqlite’>>> link.database’.../sqlite.db’>>> link.key’cat’

It is possible to change values, like:

>>> link.name = ’boundary’>>> link.driver = ’pg’>>> link.database = ’host=localhost,dbname=grassdb’>>> link.key = ’gid’

Now change again to old values:

>>> link.name = ’boundary_municp_sqlite’>>> link.driver = ’sqlite’>>> link.database = ’$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite.db’>>> link.key = ’cat’

Link object have methods that return a Connection object, and to return a Table object:

>>> conn = link.connection()>>> cur = conn.cursor()>>> import sql>>> cur.execute(sql.SELECT.format(cols=’, ’.join([’cat’, ’AREA’]),

17

PyGrass Documentation, Release alpha

... tname=link.name))<sqlite3.Cursor object at ...>>>> cur.fetchone()(1, 0.0)>>> cur.close()>>> conn.close()

From the Link object we can instantiate a Table object that allow user to make simple query with the Filters object:

>>> table = link.table()>>> table.filters.select(’cat’, ’COUNTY’,... ’AREA’,’PERIMETER’).order_by(’AREA’).limit(3)Filters(’SELECT cat, COUNTY, AREA, PERIMETER FROM boundary_municp_sqlite ORDER BY AREA LIMIT 3;’)>>> cur = table.execute()>>> for row in cur.fetchall():... print repr(row)...(1, u’SURRY’, 0.0, 1415.331)(2, u’SURRY’, 0.0, 48286.011)(3, u’CASWELL’, 0.0, 5750.087)

Then we can get table information about table columns, from the columns attribute that is an instantiation of aColumns class.

>>> table.columnsColumns([(u’cat’, u’integer’), ..., (u’ACRES’, u’double precision’)])>>> table.columns.names()[u’cat’, u’OBJECTID’, u’AREA’, u’PERIMETER’, ..., u’ACRES’]>>> table.columns.types()[u’integer’, u’integer’, u’double precision’, ..., u’double precision’]

Note: If the map use postgresql it is possible to: add/rename/cast/remove columns the sqlite does not supportthese operations.

For people that are used to the standardized Python SQL 2.0 interface:

• http://docs.python.org/library/sqlite3.html

• http://www.python.org/dev/peps/pep-0249/

Therefore advanced user can just use, the connect attribute to build a new cursor object and interact with thedatabase.

>>> cur = table.conn.cursor()>>> cur.execute("SELECT * FROM %s" % table.name)<sqlite3.Cursor object at ...>>>> cur.fetchone()[:5](1, 1, 0.0, 1415.331, 2.0)>>> # Close communication with the database>>> cur.close()>>> conn.close()

18 Chapter 6. Attributes

PyGrass Documentation, Release alpha

6.1 Link

6.2 DBlinks

6.3 Filters

6.4 Columns

6.5 Table

6.1. Link 19

PyGrass Documentation, Release alpha

20 Chapter 6. Attributes

CHAPTER 7

Modules

Grass modules are represented as objects. These objects are generated based on the XML module description thatis used for GUI generation already.

>>> from pygrass.modules import Module>>> slope_aspect = Module("r.slope.aspect", elevation=’elevation’,... slope=’slp’, aspect=’asp’,... format=’percent’, overwrite=True)

It is possible to create a run-able module object and run later:

>>> slope_aspect = Module("r.slope.aspect", elevation=’elevation’,... slope=’slp’, aspect=’asp’,... format=’percent’, overwrite=True, run_=False)

Then we can run the module with:

>>> slope_aspect()

or using the run method:

>>> slope_aspect.run()

It is possible to initialize a module, and give the parameters later:

>>> slope_aspect = Module("r.slope.aspect")>>> slope_aspect(elevation=’elevation’, slope=’slp’, aspect=’asp’,... format=’percent’, overwrite=True)

Create the module object input step by step and run later:

>>> slope_aspect = Module("r.slope.aspect")>>> slope_aspect.inputs[’elevation’]Parameter <elevation> (required:yes, type:raster, multiple:no)>>> slope_aspect.inputs["elevation"].value = "elevation">>> slope_aspect.inputs["format"]Parameter <format> (required:no, type:string, multiple:no)>>> print slope_aspect.inputs["format"].__doc__format: ’degrees’, optional, string

Format for reporting the slopeValues: ’degrees’, ’percent’

>>> slope_aspect.inputs["format"].value = ’percents’Traceback (most recent call last):

...ValueError: The Parameter <format>, must be one of: [’degrees’, ’percent’]>>> slope_aspect.inputs["format"].value = ’percent’>>> slope_aspect.flags = "g"

21

PyGrass Documentation, Release alpha

Traceback (most recent call last):...

ValueError: Flag not valid, valid flag are: [’a’]>>> slope_aspect.flags = "a">>> slope_aspect.flags_dict[’overwrite’]Flag <overwrite> (Allow output files to overwrite existing files)>>> slope_aspect.flags_dict[’overwrite’].value = True>>> slope_aspect()

It is possible to access to the module info, with:

>>> slope_aspect.name’r.slope.aspect’>>> slope_aspect.description’Aspect is calculated counterclockwise from east.’>>> slope_aspect.keywords’raster, terrain’>>> slope_aspect.label’Generates raster maps of slope, aspect, curvatures and partial derivatives from a elevation raster map.’

and get the module documentation with:

>>> print slope_aspect.__doc__r.slope.aspect(elevation=elevation, slope=None, aspect=None

format=percent, prec=None, pcurv=Nonetcurv=None, dx=None, dy=Nonedxx=None, dyy=None, dxy=Nonezfactor=None, min_slp_allowed=None)

Parameters----------

elevation: required, stringName of input elevation raster map

slope: optional, stringName for output slope raster map

aspect: optional, stringName for output aspect raster map

format: ’degrees’, optional, stringFormat for reporting the slopeValues: ’degrees’, ’percent’

prec: ’float’, optional, stringType of output aspect and slope mapsValues: ’default’, ’double’, ’float’, ’int’

pcurv: optional, stringName for output profile curvature raster map

tcurv: optional, stringName for output tangential curvature raster map

dx: optional, stringName for output first order partial derivative dx (E-W slope) raster map

dy: optional, stringName for output first order partial derivative dy (N-S slope) raster map

dxx: optional, stringName for output second order partial derivative dxx raster map

dyy: optional, stringName for output second order partial derivative dyy raster map

dxy: optional, stringName for output second order partial derivative dxy raster map

zfactor: 1.0, optional, floatMultiplicative factor to convert elevation units to meters

min_slp_allowed: optional, floatMinimum slope val. (in percent) for which aspect is computed

22 Chapter 7. Modules

PyGrass Documentation, Release alpha

Flags------

a: NoneDo not align the current region to the elevation layer

overwrite: NoneAllow output files to overwrite existing files

verbose: NoneVerbose module output

quiet: NoneQuiet module output

For each inputs and outputs parameters it is possible to get info, to see all the module inputs, just type:

>>> slope_aspect.inputsTypeDict([(’elevation’, Parameter <elevation> (required:yes, type:raster, multiple:no)), (’format’, Parameter <format> (required:no, type:string, multiple:no)), (’prec’, Parameter <prec> (required:no, type:string, multiple:no)), (’zfactor’, Parameter <zfactor> (required:no, type:float, multiple:no)), (’min_slp_allowed’, Parameter <min_slp_allowed> (required:no, type:float, multiple:no))])

To get info for each parameter:

>>> slope_aspect.inputs["elevation"].description’Name of input elevation raster map’>>> slope_aspect.inputs["elevation"].type’raster’>>> slope_aspect.inputs["elevation"].typedesc’string’>>> slope_aspect.inputs["elevation"].multipleFalse>>> slope_aspect.inputs["elevation"].requiredTrue

Or get a small documentation for each parameter with:

>>> print slope_aspect.inputs["elevation"].__doc__elevation: required, string

Name of input elevation raster map

User or developer can check which parameter are set, with:

if slope_aspect.outputs[’aspect’].value == None:print "Aspect is not computed"

After we set the parameter and run the module, the execution of the module instantiate a popen attribute to theclass. The Popen class allow user to kill/wait/ the process.

>>> 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()>>> print err100%

Aspect raster map <asp> completeSlope raster map <slp> complete

On the above example we use a new parameter finish_, if is set to True, the run method, automatically store thestdout and stderr to stdout and stderr attributes of the class:

>>> slope_aspect = Module(’r.slope.aspect’)>>> slope_aspect(elevation=’elevation’, slope=’slp’, aspect=’asp’, overwrite=True, finish_=True)>>> print slope_aspect.stderr100%

Aspect raster map <asp> completeSlope raster map <slp> complete

23

PyGrass Documentation, Release alpha

Another example of use:

>>> info = Module("r.info", map="elevation", flags="r", finish_=True)>>> from pygrass.modules import stdout2dict>>> stdout2dict(info.stdout){’max’: ’156.3299’, ’min’: ’55.57879’}>>> info = Module("r.info", map="elevation", flags="r", finish_=False)>>> category = Module("r.category", map="elevation",... stdin_=info.popen.stdout, finish_=True)

24 Chapter 7. Modules

CHAPTER 8

Indices and tables

• genindex

• modindex

• search

25