PyGrass use 4 different Raster classes, that respect the 4 different approaches of C grass API. The read access is row wise for RastRow and RasterRowIO and additionally cached in the RowIO class. Booth classes write sequentially. RowIO is row cached, RastSegment and RasterNumpy are tile cached for reading and writing therefore a randomly access is possible. Hence RasterRow and RasterRowIO should be used in case for fast (cached) row read 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 | Write |
|---|---|---|---|
| RastRow | Raster library | randomly | sequentially |
| RasterRowIO | RowIO library | cached | no |
| RastSegment | Segmentation library | cached | randomly |
| RasterNumpy | 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
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.
>>> 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:
>>> 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', ';')
PyGrass allow user to open the maps, in read and write mode, row by row using the Raster library, there is not support to read and write to the same map at the same time, for this functionality, please see the RastSegment and RasterNumpy classes. The RasterRow class allow to read in a randomly order the row from a map, but it is only possible to write the map using only a sequence order, therefore every time you are writing a new map, the row is add 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.cols
1500
>>> # 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')
>>> 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
The RasterRowIO class use the grass RowIO library, and implement a row cache. The RasterRowIO class support only reading the raster, because the raster rows can only be written in sequential order, writing by row id is not supported by design. Hence, we should use the rowio lib only for caching rows for reading and use the default row 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()
The RasterSegment class use the grass Segmentation library, it work dividing the raster map into small different files, that grass read load into the memory and write to the hardisk. The segment library allow to open a map in a read-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:
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()
The RasterNumpy class, is based on the numpy.memmap class If you open an existing map, the map will be copied on 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 == None
True
>>> # give a name to the new map
>>> el.name = 'new'
>>> el.exist()
False
>>> el.close()
>>> el.exist()
True
>>> el.remove()
The buffer class is used to interact with a memory buffer of a map like a raster row. The buffer class is based on the numpy.ndarray class. Therefore all the nice feature of the ndarray are allowed.