pygrass.gis package — GRASS Python Library documentation

# pygrass.gis package

## Submodules

## pygrass.gis.region module

Created on Fri May 25 12:57:10 2012

@author: Pietro Zambelli

class pygrass.gis.region.Region(default=False)

  Bases: `object`

  This class is design to easily access and modify GRASS computational region.

      >>> r = Region()
      >>> r.north
      40.0
      >>> r.south
      0.0
      >>> r.east
      40.0
      >>> r.west
      0.0
      >>> r.cols
      20
      >>> r.rows
      20
      >>> r.nsres
      2.0
      >>> r.ewres
      2.0

      >>> r.north = 100
      >>> r.east = 100
      >>> r.adjust(rows=True, cols=True)
      >>> r.nsres
      5.0
      >>> r.ewres
      5.0
      >>> r.cols
      20
      >>> r.rows
      20

      >>> r.read()
      >>> r.north = 100
      >>> r.east = 100
      >>> r.adjust(rows=False, cols=True)
      >>> r.nsres
      2.0
      >>> r.ewres
      5.0
      >>> r.cols
      20
      >>> r.rows
      50

      >>> r.read()
      >>> r.north = 100
      >>> r.east = 100
      >>> r.adjust(rows=True, cols=False)
      >>> r.nsres
      5.0
      >>> r.ewres
      2.0
      >>> r.cols
      50
      >>> r.rows
      20

      >>> r.read()
      >>> r.north = 100
      >>> r.east = 100
      >>> r.adjust(rows=False, cols=False)
      >>> r.nsres
      2.0
      >>> r.ewres
      2.0
      >>> r.cols
      50
      >>> r.rows
      50

      >>> r.read()
      >>> r.cols = 1000
      >>> r.ewres
      0.04
      >>> r.rows = 1000
      >>> r.nsres
      0.04

  adjust(rows=False, cols=False)

    Adjust rows and cols number according with the nsres and ewres resolutions. If rows or cols parameters are True, the adjust method update nsres and ewres according with the rows and cols numbers.

  align(raster_name)

    Adjust region cells to cleanly align with this raster map

    Warning: This will change the user GRASS region settings

    Parameters:

      raster_name (str) – the name of raster

  property bottom

    Set and obtain bottom value

  byref()

    Return the internal region representation as pointer

  property cells

    Return the number of cells

  property cols

    Set and obtain number of columns

  property depths

    Set and obtain number of depths

  property east

    Set and obtain east coordinate

  property ewres

    Set and obtain east-west resolution value

  from_rast(raster_name)

    Set the region from the computational region of a raster map layer.

    Parameters:

      - raster_name (str) – the name of raster

      - mapset (str) – the mapset of raster

    call C function Rast_get_cellhd

    Example

        >>> reg = Region()
        >>> reg.from_rast(test_raster_name)
        >>> reg.get_bbox()

    Bbox(50.0, 0.0, 60.0, 0.0) >>> reg.read() >>> reg.get_bbox() Bbox(40.0, 0.0, 40.0, 0.0)

  from_vect(vector_name)

    Adjust bounding box of region using a vector

    Parameters:

      vector_name (str) – the name of vector

    Example

        >>> reg = Region()
        >>> reg.from_vect(test_vector_name)
        >>> reg.get_bbox()

    Bbox(6.0, 0.0, 14.0, 0.0) >>> reg.read() >>> reg.get_bbox() Bbox(40.0, 0.0, 40.0, 0.0)

  get_bbox()

    Return a Bbox object with the extension of the region.

        >>> reg = Region()
        >>> reg.get_bbox()
        Bbox(40.0, 0.0, 40.0, 0.0)

  get_current()

    Get the current working region of this process and store it into this Region object

    Previous calls to set_current() affects values returned by this function. Previous calls to read() affects values returned by this function only if the current working region is not initialized.

    > Example:

    >     >>> r = Region()
    >     >>> r.north
    >     40.0

    >     >>> r.north = 30
    >     >>> r.north
    >     30.0
    >     >>> r.get_current()
    >     >>> r.north
    >     40.0

  items()

    Return a list of tuple with key and value.

  keys()

    Return a list of valid keys.

        >>> reg = Region()
        >>> reg.keys()
        ['proj', 'zone', ..., 'cols', 'cells']

  property north

    Set and obtain north coordinate

  property nsres

    Set and obtain north-south resolution value

  property proj

    Return a code for projection

  read(force_read=True)

    Read the region into this region object

    Reads the region as stored in the WIND file in the user’s current mapset into region.

    3D values are set to defaults if not available in WIND file. An error message is printed and exit() is called if there is a problem reading the region.

    <b>Note:</b> GRASS applications that read or write raster maps should not use this routine since its use implies that the active module region will not be used. Programs that read or write raster map data (or vector data) can query the active module region using Rast_window_rows() and Rast_window_cols().

    Parameters:

      force_read (boolean) – If True the WIND file of the current mapset is re-readed, otherwise the initial region set at process start will be loaded from the internal static variables.

  read_default()

    Get the default region

    Reads the default region for the location in this Region object. 3D values are set to defaults if not available in WIND file.

    An error message is printed and exit() is called if there is a problem reading the default region.

  property rows

    Set and obtain number of rows

  set_bbox(bbox)

    Set region extent from Bbox

    Parameters:

      bbox (Bbox object) – a Bbox object to set the extent

        >>> from grass.pygrass.vector.basic import Bbox
        >>> b = Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
        >>> reg = Region()
        >>> reg.set_bbox(b)
        >>> reg.get_bbox()
        Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
        >>> reg.get_current()

  set_current()

    Set the current working region from this region object

    This function adjusts the values before setting the region so you don’t have to call G_adjust_Cell_head().

    Attention: Only the current process is affected.

      > The GRASS computational region is not affected.

      Example:

          >>> r = Region()
          >>> r.north

      40.0 >>> r.south 0.0

          >>> r.north = 30
          >>> r.south = 20
          >>> r.set_current()
          >>> r.north
          30.0
          >>> r.south
          20.0
          >>> r.get_current()
          >>> r.north
          30.0
          >>> r.south
          20.0

          >>> r.read(force_read=False)
          >>> r.north
          40.0
          >>> r.south
          0.0

          >>> r.read(force_read=True)
          >>> r.north
          40.0
          >>> r.south
          0.0

  set_raster_region()

    Set the computational region (window) for all raster maps in the current process.

    Attention: All raster objects must be closed or the

      process will be terminated.

    The Raster library C function Rast_set_window() is called.

  property south

    Set and obtain south coordinate

  property tbres

    Set and obtain top-bottom 3D value

  property top

    Set and obtain top value

  property west

    Set and obtain west coordinate

  write()

    Writes the region from this region object

    This function writes this region to the Region file (WIND) in the users current mapset. This function should be carefully used, since the user will ot notice if his region was changed and would expect that only g.region will do this.

    > Example

    >     >>> from copy import deepcopy
    >     >>> r = Region()
    >     >>> rn = deepcopy(r)
    >     >>> r.north = 20
    >     >>> r.south = 10

    >     >>> r.write()
    >     >>> r.read()
    >     >>> r.north
    >     20.0
    >     >>> r.south
    >     10.0

    >     >>> rn.write()
    >     >>> r.read()
    >     >>> r.north
    >     40.0
    >     >>> r.south
    >     0.0

    >     >>> r.read_default()
    >     >>> r.write()

  property zone

    Return the zone of projection

  zoom(raster_name)

    Shrink region until it meets non-NULL data from this raster map

    Warning: This will change the user GRASS region settings

    Parameters:

      raster_name (str) – the name of raster

## Module contents

class pygrass.gis.Gisdbase(gisdbase='')

  Bases: `object`

  Return Gisdbase object.

      >>> from grass.script.core import gisenv
      >>> gisdbase = Gisdbase()
      >>> gisdbase.name == gisenv()['GISDBASE']
      True

  locations()

    Return a list of locations that are available in the gisdbase:

        >>> gisdbase = Gisdbase()
        >>> gisdbase.locations()
        [...]

  property name

    Set or obtain the name of GISDBASE

  new_location()

class pygrass.gis.Location(location='', gisdbase='')

  Bases: `object`

  Location object

      >>> from grass.script.core import gisenv
      >>> location = Location()
      >>> location
      Location(...)
      >>> location.gisdbase == gisenv()['GISDBASE']
      True
      >>> location.name == gisenv()['LOCATION_NAME']
      True

  property gisdbase

    Set or obtain the name of GISDBASE

  mapsets(pattern=None, permissions=True)

    Return a list of the available mapsets.

    Parameters:

      - pattern (str) – the pattern to filter the result

      - permissions (bool) – check the permission of mapset

    Returns:

      a list of mapset’s names

    Return type:

      list of strings

        >>> location = Location()
        >>> sorted(location.mapsets())
        [...]

  property name

    Set or obtain the name of LOCATION

  path()

    Return the complete path of the location

class pygrass.gis.Mapset(mapset='', location='', gisdbase='')

  Bases: `object`

  Mapset

      >>> from grass.script.core import gisenv
      >>> genv = gisenv()
      >>> mapset = Mapset()
      >>> mapset
      Mapset(...)
      >>> mapset.gisdbase == genv['GISDBASE']
      True
      >>> mapset.location == genv['LOCATION_NAME']
      True
      >>> mapset.name == genv['MAPSET']
      True

  current()

    Set the mapset as current

  delete()

    Delete the mapset

  property gisdbase

    Set or obtain the name of GISDBASE

  glist(type, pattern=None)

    Return a list of grass types like:

    > - ‘group’,

    > - ‘label’,

    > - ‘raster’,

    > - ‘raster_3d’,

    > - ‘region’,

    > - ‘vector’,

    Parameters:

      - type (str) – the type of element to query

      - pattern (str) – the pattern to filter the result

        >>> mapset = Mapset()
        >>> mapset.current()
        >>> rast = mapset.glist('raster')
        >>> test_raster_name in rast
        True
        >>> vect = mapset.glist('vector')
        >>> test_vector_name in vect
        True

  is_current()

    Check if the MAPSET is the working MAPSET

  property location

    Set or obtain the name of LOCATION

  property name

    Set or obtain the name of MAPSET

  path()

    Return the complete path of the mapset

class pygrass.gis.VisibleMapset(mapset, location='', gisdbase='')

  Bases: `object`

  VisibleMapset object

  add(mapset)

    Add a mapset to the search path

    Parameters:

      mapset (str) – a mapset’s name

  extend(mapsets)

    Add more mapsets to the search path

    Parameters:

      mapsets (list) – a list of mapset’s names

  read()

    Return the mapsets in the search path

  remove(mapset)

    Remove mapset to the search path

    Parameters:

      mapset (str) – a mapset’s name

  reset()

    Reset to the original search path

pygrass.gis.is_valid(value, path, type)

  Private function to check the correctness of a value.

  Parameters:

    - value (str) – Name of the directory

    - path (path) – Path where the directory is located

    - type (str) – it is a string defining the type that will e checked, valid types are: GISBASE, GISDBASE, LOCATION_NAME, MAPSET

  Returns:

    True if valid else False

  Return type:

    str

pygrass.gis.make_mapset(mapset, location=None, gisdbase=None)

  Create a new mapset

  Parameters:

    - mapset – Name of the mapset

    - location (str) – Name of the location

    - gisdbase (str) – Name of the gisdbase

pygrass.gis.set_current_mapset(mapset, location=None, gisdbase=None)

  Set the current mapset as working area

  Parameters:

    - mapset – Name of the mapset

    - location (str) – Name of the location

    - gisdbase (str) – Name of the gisdbase

Help Index | Topics Index | Keywords Index | Full Index

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