pygrass.raster package — GRASS Python Library documentation

# pygrass.raster package

## Submodules

## pygrass.raster.abstract module

Created on Fri Aug 17 16:05:25 2012

@author: pietro

class pygrass.raster.abstract.Info(name, mapset='')

  Bases: `object`

  Read the information for a raster map.

      >>> info = Info(test_raster_name)
      >>> info.read()
      >>> info

  abstract_test_map@ rows: 4 cols: 4 north: 40.0 south: 0.0 nsres:10.0 east: 40.0 west: 0.0 ewres:10.0 range: 11, 44 … <BLANKLINE>

  property bottom
  property cols
  property east
  property ewres
  items()
  keys()
  property max
  property min
  property mtype
  property north
  property nsres
  property proj
  property range
  read()
  property rows
  property semantic_label

    Get semantic label identifier.

    Return str:

      semantic label (eg. S2_1) or None

  property south
  property tbres
  property top
  property units
  property vdatum
  property west
  property zone

class pygrass.raster.abstract.RasterAbstractBase(name, mapset='', *aopen, **kwopen)

  Bases: `object`

  Raster_abstract_base: The base class from which all sub-classes inherit. It does not implement any row or map access methods:

  - Implements raster metadata information access (Type, …)

  - Implements an open method that will be overwritten by the sub-classes

  - Implements the close method that might be overwritten by sub-classes (should work for simple row access)

  - Implements get and set region methods

  - Implements color, history and category handling

  - Renaming, deletion, …

  The constructor need at least the name of the map optional field is the mapset.

      >>> ele = RasterAbstractBase(test_raster_name)
      >>> ele.name
      'abstract_test_map'
      >>> ele.exist()
      True

  property cats_title
  close()

    Close the map

  copy_cats(raster)

    Copy categories from another raster map object

  exist()

    Return True if the map already exist, and set the mapset if were not set.

    call the C function G_find_raster.

        >>> ele = RasterAbstractBase(test_raster_name)
        >>> ele.exist()
        True

  fullname()

    Return the full name of a raster map: name@mapset

  get_cat(label)

    Return a category given an index or a label

  get_cats()

    Return a category object

  get_value(point, region=None)

    This method returns the pixel value of a given pair of coordinates:

    Parameters:

      point – pair of coordinates in tuple object or class object with coords() method

  has_cats()

    Return True if the raster map has categories

  is_open()

    Return True if the map is open False otherwise.

        >>> ele = RasterAbstractBase(test_raster_name)
        >>> ele.is_open()
        False

  property mode
  property mtype

    Private method to get the Raster type

  property name

    Private method to return the Raster name

  name_mapset(name=None, mapset=None)

    Return the full name of the Raster.

        >>> ele = RasterAbstractBase(test_raster_name)
        >>> name = ele.name_mapset().split("@")
        >>> name
        ['abstract_test_map']

  num_cats()

    Return the number of categories

  property overwrite
  read_cats()

    Read category from the raster map file

  read_cats_rules(filename, sep=':')

    Read category from the raster map file

  remove()

    Remove the map

  rename(newname)

    Rename the map

  set_cat(label, min_cat, max_cat=None, index=None)

    Set or update a category

  set_cats(category)

    The internal categories are copied from this object.

  set_region(region)

    Set the computational region that can be different from the current region settings. This region will be used by all raster map layers that are opened in the same process.

    The GRASS region settings will not be modified.

  set_region_from_rast(rastname='', mapset='')

    Set the computational region from a map, if rastername and mapset is not specify, use itself. This region will be used by all raster map layers that are opened in the same process.

    The GRASS region settings will not be modified.

    call C function Rast_get_cellhd, Rast_set_window

  sort_cats()

    Sort categories order by range

  write_cats()

    Write category to the raster map file

  write_cats_rules(filename, sep=':')

    Write category to the raster map file

## pygrass.raster.buffer module

class pygrass.raster.buffer.Buffer(shape, mtype='FCELL', buffer=None, offset=0, strides=None, order=None)

  Bases: `ndarray`

  shape, mtype=’FCELL’, buffer=None, offset=0, strides=None, order=None

  property mtype

## pygrass.raster.category module

Created on Thu Jun 28 17:44:14 2012

@author: pietro

class pygrass.raster.category.Category(name, mapset='', mtype='CELL', *args, **kargs)

  Bases: `list`

  I would like to add the following functions:

  Getting the umber of cats: Rast_number_of_cats() <- Important for ith access

  Getting and setting the title: Rast_get_cats_title() Rast_set_cats_title()

  Do not use these functions for category access: Rast_get_cat() and the specialized types for CELL, FCELL and DCELL. Since these functions are working on hidden static buffer.

  Use the ith-get methods: Rast_get_ith_c_cat() Rast_get_ith_f_cat() Rast_get_ith_d_cat()

  This can be implemented using an iterator too. So that the category object provides the [] access operator to the categories, returning a tuple (label, min, max). Using this, the category object must be aware of its raster map type.

  Set categories using: Rast_set_c_cat() Rast_set_f_cat() Rast_set_d_cat()

  Misc: Rast_sort_cats() Rast_copy_cats() <- This should be wrapped so that categories from an existing Python category class are copied.

  copy(category)

    Copy from another Category class

    Parameters:

      category (Category object) – Category class to be copied

  get_cat(index)
  labels()
  property mtype

    Set or obtain raster data type

  ncats()
  read()

    Read categories from a raster map

    The category file for raster map name in mapset is read into the cats structure. If there is an error reading the category file, a diagnostic message is printed.

    int Rast_read_cats(const char * name,

      const char * mapset, struct Categories * pcats )

  read_rules(filename, sep=':')

    Copy categories from a rules file, default separator is ‘:’, the columns must be: min and/or max and label.

        1:forest
        2:road
        3:urban

        0.:0.5:forest
        0.5:1.0:road
        1.0:1.5:urban

    Parameters:

      - filename (str) – the name of file with categories rules

      - sep (str) – the separator used to divide values and category

  reset()
  set_cat(index, value)
  set_cats_fmt(fmt, m1, a1, m2, a2)

    Not implemented yet. void Rast_set_cats_fmt()

  sort()

    Sort the list in ascending order and return None.

    The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

    If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

    The reverse flag can be set to sort in descending order.

  property title

    Set or obtain raster title

  write()
    Writes the category file for the raster map name in the current

      mapset from the cats structure.

    void Rast_write_cats(const char * name,

      struct Categories * cats )

  write_rules(filename, sep=':')

    Copy categories from a rules file, default separator is ‘:’, the columns must be: min and/or max and label.

        1:forest
        2:road
        3:urban

        0.:0.5:forest
        0.5:1.0:road
        1.0:1.5:urban

    Parameters:

      - filename (str) – the name of file with categories rules

      - sep (str) – the separator used to divide values and category

## pygrass.raster.history module

Created on Thu Jun 28 17:44:45 2012

@author: pietro

class pygrass.raster.history.History(name, mapset='', mtype='', creator='', src1='', src2='', keyword='', date='', title='')

  Bases: `object`

  History class help to manage all the metadata of a raster map

  append(obj)

    Rast_append_history

  append_fmt(fmt, *args)

    Rast_append_format_history

  clear()

    Clear the history

  command()

    Rast_command_history

  property creator

    Set or obtain the creator of map

  property date

    Set or obtain the date of map

  format(field, fmt, *args)

    Rast_format_history

  property keyword

    Set or obtain the keywords of map

  length()

    Rast_history_length

  line(line)

    Rast_history_line

  property mapset

    Set or obtain the mapset of map

  property maptype

    Set or obtain the type of map

  read()

    Read the history of map, users need to use this function to obtain all the information of map.

        >>> import grass.lib.gis as libgis
        >>> import ctypes
        >>> import grass.lib.raster as libraster
        >>> hist = libraster.History()

  short()

    Rast_short_history

  property src1

    Set or obtain the first source of map

  property src2

    Set or obtain the second source of map

  property title

    Set or obtain the title of map

  write()

    Rast_write_history

## pygrass.raster.raster_type module

Created on Wed Jun 13 19:42:22 2012

@author: pietro

## pygrass.raster.rowio module

Created on Mon Jun 18 13:22:38 2012

@author: pietro

class pygrass.raster.rowio.RowIO

  Bases: `object`

  get(row_index, buf)
  open(fd, rows, cols, mtype)
  release()

pygrass.raster.rowio.getmaprow_CELL(fd, buf, row, l)

pygrass.raster.rowio.getmaprow_DCELL(fd, buf, row, l)

pygrass.raster.rowio.getmaprow_FCELL(fd, buf, row, l)

## pygrass.raster.segment module

Created on Mon Jun 11 18:02:27 2012

@author: pietro

class pygrass.raster.segment.Segment(srows=64, scols=64, maxmem=100)

  Bases: `object`

  close()

    Free memory allocated to segment and delete temp file.

  cols()
  flush()

    Flush pending updates to disk. Forces all pending updates generated by Segment_put() to be written to the segment file seg. Must be called after the final Segment_put() to force all pending updates to disk. Must also be called before the first call to Segment_get_row.

  format(mapobj, file_name='', fill=True)

    The segmentation routines require a disk file to be used for paging segments in and out of memory. This routine formats the file open for write on file descriptor fd for use as a segment file.

  get(row_index, col_index)

    Return the value of the map

  get_row(row_index, buf)

    Return the row using, the segment method

  get_seg_number(row_index, col_index)

    Return the segment number

  init(mapobj, file_name='')
  nseg()
  open(mapobj)

    Open a segment it is necessary to pass a RasterSegment object.

  put(row_index, col_index)

    Write the value to the map

  put_row(row_index, buf)

    Write the row using the segment method

  release()

    Free memory allocated to segment. Releases the allocated memory associated with the segment file seg. Note: Does not close the file. Does not flush the data which may be pending from previous Segment_put() calls.

  rows()
  segments_in_mem()

## Module contents

class pygrass.raster.RasterRow(name, mapset='', *args, **kargs)

  Bases: `RasterAbstractBase`

  Raster_row_access”: Inherits: “Raster_abstract_base” and implements the default row access of the Rast library.

  > - Implements row access using row id

  > - The get_row() method must accept a Row object as argument that will be used for value storage, so no new buffer will be allocated

  > - Implements sequential writing of rows

  > - Implements indexed value read only access using the [row][col] operator

  > - Implements the [row] read method that returns a new Row object

  > - Writing is limited using the put_row() method which accepts a Row as argument

  > - No mathematical operation like __add__ and stuff for the Raster object (only for rows), since r.mapcalc is more sophisticated and faster

  > - Raises IndexError if [row] is out of range

  > Examples:

  >     >>> elev = RasterRow(test_raster_name)
  >     >>> elev.exist()
  >     True
  >     >>> elev.is_open()
  >     False
  >     >>> elev.open()
  >     >>> elev.is_open()
  >     True
  >     >>> elev.has_cats()
  >     True
  >     >>> elev.mode
  >     'r'
  >     >>> elev.mtype
  >     'CELL'
  >     >>> elev.num_cats()
  >     16
  >     >>> elev.info.range
  >     (11, 44)
  >     >>> elev.info.cols
  >     4
  >     >>> elev.info.rows
  >     4

  > Editing the history

  >     >>> elev.hist.read()
  >     >>> elev.hist.title = "A test map"
  >     >>> elev.hist.write()
  >     >>> elev.hist.title
  >     'A test map'
  >     >>> elev.hist.keyword
  >     'This is a test map'

  >     >>> attrs = list(elev.hist)
  >     >>> attrs[0]
  >     ('name', 'Raster_test_map')
  >     >>> attrs[2]
  >     ('mtype', '')

  > Each Raster map have an attribute call `cats` that allow user to interact with the raster categories.

  >     >>> elev.cats
  >     [('A', 11, None),
  >      ('B', 12, None),
  >     ...
  >      ('P', 44, None)]

  >     >>> elev.cats.labels()
  >     ['A', 'B', 'C', 'D', 'E',
  >      'F', 'G', 'H', 'I', 'J',
  >      'K', 'L', 'M', 'n', 'O', 'P']
  >     >>> elev.cats[0]
  >     ('A', 11, None)
  >     >>> elev.cats[2]
  >     ('C', 13, None)
  >     >>> elev.cats[0] = ('AA', 11)
  >     >>> elev.cats[1] = ('BB', 12)
  >     >>> elev.cats.write()
  >     >>> elev.cats.read()
  >     >>> elev.cats[0]
  >     ('AA', 11, None)
  >     >>> elev.cats[1]
  >     ('BB', 12, None)

  > Open a raster map using the with statement:

  >     >>> with RasterRow(test_raster_name) as elev:
  >     ...     for row in elev:
  >     ...         row
  >     Buffer([11, 21, 31, 41], dtype=int32)
  >     Buffer([12, 22, 32, 42], dtype=int32)
  >     Buffer([13, 23, 33, 43], dtype=int32)
  >     Buffer([14, 24, 34, 44], dtype=int32)

  >     >>> elev.is_open()
  >     False

  The constructor need at least the name of the map optional field is the mapset.

      >>> ele = RasterAbstractBase(test_raster_name)
      >>> ele.name
      'abstract_test_map'
      >>> ele.exist()
      True

  get_row(row, row_buffer=None)

    Private method that return the row using the read mode call the Rast_get_row C function.

    Parameters:

      - row (int) – the number of row to obtain

      - row_buffer (Buffer) – Buffer object instance with the right dim and type

        >>> elev = RasterRow(test_raster_name)
        >>> elev.open()
        >>> elev[0]
        Buffer([11, 21, 31, 41], dtype=int32)
        >>> elev.get_row(0)
        Buffer([11, 21, 31, 41], dtype=int32)

  open(mode=None, mtype=None, overwrite=None)

    Open the raster if exist or created a new one.

    Parameters:

      - mode (str) – Specify if the map will be open with read or write mode (‘r’, ‘w’)

      - type (str) – If a new map is open, specify the type of the map(CELL, FCELL, DCELL)

      - overwrite (bool) – Use this flag to set the overwrite mode of existing raster maps

    if the map already exist, automatically check the type and set:

    > - self.mtype

    Set all the privite, attributes:

    > - self._fd;

    > - self._gtype

    > - self._rows and self._cols

  put_row(row)

    Private method to write the row sequentially.

    Parameters:

      row (Buffer object) – a Row object to insert into raster

class pygrass.raster.RasterRowIO(name, *args, **kargs)

  Bases: `RasterRow`

  Raster_row_cache_access”: The same as “Raster_row_access” but uses the ROWIO library for cached row access

  The constructor need at least the name of the map optional field is the mapset.

      >>> ele = RasterAbstractBase(test_raster_name)
      >>> ele.name
      'abstract_test_map'
      >>> ele.exist()
      True

  close()

    Function to close the raster

  get_row(row, row_buffer=None)

    This method returns the row using:

    > - the read mode and

    > - rowcache method

    Parameters:

      - row (int) – the number of row to obtain

      - row_buffer – Specify the Buffer object that will be instantiate

  open(mode=None, mtype=None, overwrite=False)

    Open the raster if exist or created a new one.

    Parameters:

      - mode (str) – specify if the map will be open with read or write mode (‘r’, ‘w’)

      - type (str) – if a new map is open, specify the type of the map(CELL, FCELL, DCELL)

      - overwrite (bool) – use this flag to set the overwrite mode of existing raster maps

class pygrass.raster.RasterSegment(name, srows=64, scols=64, maxmem=100, *args, **kargs)

  Bases: `RasterAbstractBase`

  Raster_segment_access”: Inherits “Raster_abstract_base” and uses the segment library for cached randomly reading and writing access.

  > - Implements the [row][col] operator for read and write access using Segment_get() and Segment_put() functions internally

  > - Implements row read and write access with the [row] operator using Segment_get_row() Segment_put_row() internally

  > - Implements the get_row() and put_row() method using Segment_get_row() Segment_put_row() internally

  > - Implements the flush_segment() method

  > - Implements the copying of raster maps to segments and vice verse

  > - Overwrites the open and close methods

  > - No mathematical operation like __add__ and stuff for the Raster object (only for rows), since r.mapcalc is more sophisticated and faster

  The constructor need at least the name of the map optional field is the mapset.

      >>> ele = RasterAbstractBase(test_raster_name)
      >>> ele.name
      'abstract_test_map'
      >>> ele.exist()
      True

  close(rm_temp_files=True)

    Close the map, copy the segment files to the map.

    Parameters:

      rm_temp_files (bool) – if True all the segments file will be removed

  get(row, col)

    Return the map value using the segment.get method

    Parameters:

      - row (int) – Specify the row number

      - col – Specify the column number

  get_row(row, row_buffer=None)

    Return the row using the segment.get_row method

    Parameters:

      - row (int) – specify the row number

      - row_buffer – specify the Buffer object that will be instantiate

  map2segment()

    Transform an existing map to segment file.

  property mode

    Set or obtain the opening mode of raster

  open(mode=None, mtype=None, overwrite=None)

    Open the map, if the map already exist: determine the map type and copy the map to the segment files; else, open a new segment map.

    Parameters:

      - mode (str) – specify if the map will be open with read, write or read/write mode (‘r’, ‘w’, ‘rw’)

      - mtype (str) – specify the map type, valid only for new maps: CELL, FCELL, DCELL

      - overwrite (bool) – use this flag to set the overwrite mode of existing raster maps

  put(row, col, val)

    Write the value to the map using the segment.put method

    Parameters:

      - row (int) – Specify the row number

      - col (int) – Specify the column number

      - val – Specify the value that will be write to the map cell

  put_row(row, row_buffer)

    Write the row using the segment.put_row method

    Parameters:

      row (Buffer object) – a Row object to insert into raster

    Input and output must have the same type in case of row copy

        >>> map_a = RasterSegment(test_raster_name)
        >>> map_b = RasterSegment(test_raster_name + "_segment")
        >>> map_a.open('r')
        >>> map_b.open('w', mtype="CELL", overwrite=True)
        >>> for row in range(map_a.info.rows):
        ...     map_b[row] = map_a[row] + 1000
        >>> map_a.close()
        >>> map_b.close()

        >>> map_b = RasterSegment(test_raster_name + "_segment")
        >>> map_b.open("r")
        >>> for row in map_b:
        ...         row
        Buffer([1011, 1021, 1031, 1041], dtype=int32)
        Buffer([1012, 1022, 1032, 1042], dtype=int32)
        Buffer([1013, 1023, 1033, 1043], dtype=int32)
        Buffer([1014, 1024, 1034, 1044], dtype=int32)
        >>> map_b.close()

  segment2map()

    Transform the segment file to a map.

pygrass.raster.numpy2raster(array, mtype, rastname, overwrite=False)

  Save a numpy array to a raster map

  Parameters:

    - array (obj) – a numpy array

    - mtype (obj) – the datatype of array

    - rastername (str) – the name of output map

    - overwrite (bool) – True to overwrite existing map

pygrass.raster.random_map(mapname, mtype, overwrite=True, factor=100)

pygrass.raster.random_map_only_columns(mapname, mtype, overwrite=True, factor=100)

pygrass.raster.raster2numpy(rastname, mapset='')

  Return a numpy array from a raster map

  Parameters:

    rastname (str) – the name of raster map

  Parar str mapset:

    the name of mapset containing raster map

pygrass.raster.raster2numpy_img(rastname, region, color='ARGB', array=None)

  Convert a raster map layer into a string with 32Bit ARGB, 24Bit RGB or 8Bit Gray little endian encoding.

  > Return a numpy array from a raster map of type uint8 that contains the colored map data as 32 bit ARGB, 32Bit RGB or 8 bit image

  Parameters:

    - rastname (string) – The name of raster map

    - region (grass.pygrass.gis.region.Region) – The region to be used for raster map reading

    - color (String) – “ARGB”, “RGB”, “GRAY1”, “GRAY2” ARGB -> 32Bit RGB with alpha channel (0xAARRGGBB) RGB -> 32Bit RGB (0xffRRGGBB) GRAY1 -> grey scale formular: .33R+ .5G+ .17B GRAY2 -> grey scale formular: .30R+ .59G+ .11B

    - array (numpy.ndarray) –

      A numpy array (optional) to store the image, the array needs to setup as follows:

      array = np.ndarray((region.rows*region.cols*scale), np.uint8)

      scale = 4 in case of ARGB and RGB or scale = 1 in case of Gray scale

  Returns:

    A numpy array of size rows*cols*4 in case of ARGB, RGB and rows*cols*1 in case of gray scale

  Attention: This function will change the computational raster region of the current process while running.

Help Index | Topics Index | Keywords Index | Full Index

© 2003-2026 GRASS Development Team, GRASS GIS 8.4.3dev Reference Manual