grass.pygrass.vector package — GRASS Python Library documentation

# grass.pygrass.vector package

class grass.pygrass.vector.Vector(name, mapset='', *args, **kwargs)

  Bases: `Info`

  Vector class is the grass vector format without topology

      >>> from grass.pygrass.vector import Vector
      >>> test_vect = Vector(test_vector_name)
      >>> test_vect.is_open()
      False
      >>> test_vect.mapset
      ''
      >>> test_vect.exist()
      True
      >>> test_vect.overwrite
      False

  has_color_table()

    Return if vector has color table associated in file system; Color table stored in the vector’s attribute table well be not checked

        >>> test_vect = Vector(test_vector_name)
        >>> test_vect.open(mode="r")
        >>> test_vect.has_color_table()
        False

        >>> test_vect.close()
        >>> from grass.pygrass.utils import copy, remove
        >>> copy(test_vector_name, "mytest_vect", "vect")
        >>> from grass.pygrass.modules.shortcuts import vector as v
        >>> v.colors(map="mytest_vect", color="population", column="value")
        Module('v.colors')
        >>> mytest_vect = Vector("mytest_vect")
        >>> mytest_vect.open(mode="r")
        >>> mytest_vect.has_color_table()
        True
        >>> mytest_vect.close()
        >>> remove("mytest_vect", "vect")

  next()
  rewind()

    Rewind vector map to cause reads to start at beginning.

  write(geo_obj, cat=None, attrs=None)

    Write geometry features and attributes.

    Parameters:

      - geo_obj (geometry GRASS object) – a geometry grass object define in grass.pygrass.vector.geometry

      - attrs (list) – a list with the values that will be insert in the attribute table.

      - cat (integer) – The category of the geometry feature, otherwise the c_cats attribute of the geometry object will be used.

    Open a new vector map

        >>> new = VectorTopo("newvect")
        >>> new.exist()
        False

    define the new columns of the attribute table

        >>> cols = [("cat", "INTEGER PRIMARY KEY"), ("name", "TEXT")]

    open the vector map in write mode

        >>> new.open("w", tab_name="newvect", tab_cols=cols)

    import a geometry feature

        >>> from grass.pygrass.vector.geometry import Point

    create two points

        >>> point0 = Point(0, 0)
        >>> point1 = Point(1, 1)

    then write the two points on the map, with

        >>> new.write(point0, cat=1, attrs=("pub",))
        >>> new.write(point1, cat=2, attrs=("resturant",))

    commit the db changes

        >>> new.table.conn.commit()
        >>> new.table.execute().fetchall()
        [(1, 'pub'), (2, 'resturant')]

    close the vector map

        >>> new.close()
        >>> new.exist()
        True

    then play with the map

        >>> new.open(mode="r")
        >>> new.read(1)
        Point(0.000000, 0.000000)
        >>> new.read(2)
        Point(1.000000, 1.000000)
        >>> new.read(1).attrs["name"]
        'pub'
        >>> new.read(2).attrs["name"]
        'resturant'
        >>> new.close()
        >>> new.remove()

class grass.pygrass.vector.VectorTopo(name, mapset='', *args, **kwargs)

  Bases: `Vector`

  Vector class with the support of the GRASS topology.

  Open a vector map using the with statement:

      >>> with VectorTopo(test_vector_name, mode="r") as test_vect:
      ...     for feature in test_vect[:7]:
      ...         print(feature.attrs["name"])
      ...
      point
      point
      point
      line
      line
      line
      >>> test_vect.is_open()
      False

  areas_to_wkb_list(bbox=None, field=1)

    Return all features of type point, line, boundary or centroid as a list of Well Known Binary representations (WKB) (id, cat, wkb) triplets located in a specific bounding box.

    Parameters:

      - bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search for features, if bbox=None the boundingbox of the whole vector map layer is used

      - field (integer) – The centroid category field

    Returns:

      A list of triplets, or None if nothing was found

    The well known binary are stored in byte arrays.

    > Examples:

    >     >>> from grass.pygrass.vector import VectorTopo
    >     >>> from grass.pygrass.vector.basic import Bbox
    >     >>> test_vect = VectorTopo(test_vector_name)
    >     >>> test_vect.open("r")

    >     >>> bbox = Bbox(north=20, south=-1, east=20, west=-1)
    >     >>> result = test_vect.areas_to_wkb_list(bbox=bbox)
    >     >>> len(result)
    >     4
    >     >>> for entry in result:
    >     ...     a_id, cat, wkb = entry
    >     ...     print((a_id, cat, len(wkb)))
    >     ...
    >     (1, 3, 225)
    >     (2, 3, 141)
    >     (3, 3, 93)
    >     (4, 3, 141)

    >     >>> result = test_vect.areas_to_wkb_list()
    >     >>> len(result)
    >     4
    >     >>> for entry in result:
    >     ...     a_id, cat, wkb = entry
    >     ...     print((a_id, cat, len(wkb)))
    >     ...
    >     (1, 3, 225)
    >     (2, 3, 141)
    >     (3, 3, 93)
    >     (4, 3, 141)

    >     >>> test_vect.close()

  bbox()

    Return the BBox of the vecor map

  cat(cat_id, vtype, layer=None, generator=False, geo=None)

    Return the geometry features with category == cat_id.

    Parameters:

      - cat_id (int) – the category number

      - vtype (str) – the type of geometry feature that we are looking for

      - layer (int) – the layer number that will be used

      - generator (bool) – if True return a generator otherwise it return a list of features

  close(build=True, release=True)

    Close the VectorTopo map, if release is True, the memory occupied by spatial index is released

  delete(feature_id)

    Remove a feature by its id

    Parameters:

      feature_id (int) – the id of the feature

  features_to_wkb_list(bbox=None, feature_type='point', field=1)

    Return all features of type point, line, boundary or centroid as a list of Well Known Binary representations (WKB) (id, cat, wkb) triplets located in a specific bounding box.

    Parameters:

      - bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search for features, if bbox=None the boundingbox of the whole vector map layer is used

      - feature_type –

        The type of feature that should be converted to

          the Well Known Binary (WKB) format. Supported are:

        ’point’ -> libvect.GV_POINT 1 ‘line’ -> libvect.GV_LINE 2 ‘boundary’ -> libvect.GV_BOUNDARY 3 ‘centroid’ -> libvect.GV_CENTROID 4

      - field (integer) – The category field

    Returns:

      A list of triplets, or None if nothing was found

    The well known binary are stored in byte arrays.

    > Examples:

    >     >>> from grass.pygrass.vector import VectorTopo
    >     >>> from grass.pygrass.vector.basic import Bbox
    >     >>> test_vect = VectorTopo(test_vector_name)
    >     >>> test_vect.open("r")

    >     >>> bbox = Bbox(north=20, south=-1, east=20, west=-1)
    >     >>> result = test_vect.features_to_wkb_list(bbox=bbox, feature_type="point")
    >     >>> len(result)
    >     3
    >     >>> for entry in result:
    >     ...     f_id, cat, wkb = entry
    >     ...     print((f_id, cat, len(wkb)))
    >     ...
    >     (1, 1, 21)
    >     (2, 1, 21)
    >     (3, 1, 21)

    >     >>> result = test_vect.features_to_wkb_list(bbox=None, feature_type="line")
    >     >>> len(result)
    >     3
    >     >>> for entry in result:
    >     ...     f_id, cat, wkb = entry
    >     ...     print((f_id, cat, len(wkb)))
    >     ...
    >     (4, 2, 57)
    >     (5, 2, 57)
    >     (6, 2, 57)

    >     >>> result = test_vect.features_to_wkb_list(bbox=bbox, feature_type="boundary")
    >     >>> len(result)
    >     11

    >     >>> result = test_vect.features_to_wkb_list(bbox=None, feature_type="centroid")
    >     >>> len(result)
    >     4

    >     >>> for entry in result:
    >     ...     f_id, cat, wkb = entry
    >     ...     print((f_id, cat, len(wkb)))
    >     ...
    >     (19, 3, 21)
    >     (18, 3, 21)
    >     (20, 3, 21)
    >     (21, 3, 21)

    >     >>> result = test_vect.features_to_wkb_list(bbox=bbox, feature_type="blub")
    >     Traceback (most recent call last):
    >     ...
    >     grass.exceptions.GrassError: Unsupported feature type <blub>, supported are <point,line,boundary,centroid>

    >     >>> test_vect.close()

  is_empty()

    Return if a vector map is empty or not

  num_primitive_of(primitive)

    Return the number of primitive

    Parameters:

      primitive (str) –

      the name of primitive to query; the supported values are:

      - boundary,

      - centroid,

      - face,

      - kernel,

      - line,

      - point

      - area

      - volume

        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open(mode="r")
        >>> test_vect.num_primitive_of("point")
        3
        >>> test_vect.num_primitive_of("line")
        3
        >>> test_vect.num_primitive_of("centroid")
        4
        >>> test_vect.num_primitive_of("boundary")
        11
        >>> test_vect.close()

  num_primitives()

    Return dictionary with the number of all primitives

  number_of(vtype)

    Return the number of the chosen element type

    Parameters:

      vtype – the name of type to query; the supported values are: areas, dblinks, faces, holes, islands, kernels, points, lines, centroids, boundaries, nodes, line_points, update_lines, update_nodes, volumes

  read(feature_id)

    Return a geometry object given the feature id.

    Parameters:

      feature_id (int) – the id of feature to obtain

        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open(mode="r")
        >>> feature1 = test_vect.read(0)
        Traceback (most recent call last):
            ...
        ValueError: The index must be >0, 0 given.
        >>> feature1 = test_vect.read(5)
        >>> feature1
        Line([Point(12.000000, 4.000000), Point(12.000000, 2.000000), Point(12.000000, 0.000000)])
        >>> feature1.length()
        4.0
        >>> test_vect.read(-1)
        Centroid(7.500000, 3.500000)
        >>> len(test_vect)
        21
        >>> test_vect.read(21)
        Centroid(7.500000, 3.500000)
        >>> test_vect.read(22)
        Traceback (most recent call last):
          ...
        IndexError: Index out of range
        >>> test_vect.close()

  restore(geo_obj)
  rewind()

    Rewind vector map to cause reads to start at beginning.

        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open(mode="r")
        >>> test_vect.next()
        Point(10.000000, 6.000000)
        >>> test_vect.next()
        Point(12.000000, 6.000000)
        >>> test_vect.next()
        Point(14.000000, 6.000000)
        >>> test_vect.rewind()
        >>> test_vect.next()
        Point(10.000000, 6.000000)
        >>> test_vect.close()

  rewrite(geo_obj, cat, attrs=None, **kargs)

    Rewrite a geometry features

        >>> cols = [("cat", "INTEGER PRIMARY KEY"), ("name", "TEXT")]

    Generate a new vector map

        >>> test_vect = VectorTopo("newvect_2")
        >>> test_vect.open("w", tab_name="newvect_2", tab_cols=cols, overwrite=True)

    import a geometry feature

        >>> from grass.pygrass.vector.geometry import Point

    create two points

        >>> point0 = Point(0, 0)
        >>> point1 = Point(1, 1)
        >>> point2 = Point(2, 2)

    then write the two points on the map, with

        >>> test_vect.write(point0, cat=1, attrs=("pub",))
        >>> test_vect.write(point1, cat=2, attrs=("resturant",))
        >>> test_vect.table.conn.commit()  # save changes in the DB
        >>> test_vect.table_to_dict()
        {1: [1, 'pub'], 2: [2, 'resturant']}
        >>> test_vect.close()

    Now rewrite one point of the vector map:

        >>> test_vect.open("rw")
        >>> test_vect.rewrite(point2, cat=1, attrs=("Irish Pub",))
        >>> test_vect.table.conn.commit()  # save changes in the DB
        >>> test_vect.close()

    Check the output:

        >>> test_vect.open("r")
        >>> test_vect[1] == point2
        True
        >>> test_vect[1].attrs["name"] == "Irish Pub"
        True
        >>> test_vect.close()
        >>> test_vect.remove()

  table_to_dict(where=None)

    Return the attribute table as a dictionary with the category as keys

    The columns have the order of the self.table.columns.names() list.

    Examples

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.basic import Bbox
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open("r")

        >>> test_vect.table_to_dict()
        {1: [1, 'point', 1.0], 2: [2, 'line', 2.0], 3: [3, 'centroid', 3.0]}

        >>> test_vect.table_to_dict(where="value > 2")
        {3: [3, 'centroid', 3.0]}

        >>> test_vect.table_to_dict(where="value > 0")
        {1: [1, 'point', 1.0], 2: [2, 'line', 2.0], 3: [3, 'centroid', 3.0]}

        >>> test_vect.table.filters.get_sql()
        'SELECT cat,name,value FROM vector_doctest_map WHERE value > 0 ORDER BY cat;'

  viter(vtype, idonly=False)

    Return an iterator of vector features

    Parameters:

      - vtype (str) – the name of type to query; the supported values are: areas, dblinks, faces, holes, islands, kernels, line_points, lines, nodes, points, update_lines, update_nodes, volumes

      - idonly – variable to return only the id of features instead of full features

    to sort the result in a efficient way, use:

        >>> from operator import methodcaller as method
        >>> areas.sort(key=method("area"), reverse=True)  # sort the list
        >>> for area in areas[:3]:
        ...     print(area, area.area())
        Area(1) 12.0
        Area(2) 8.0
        Area(4) 8.0

        >>> areas = [area for area in test_vect.viter("areas")]
        >>> for area in areas:
        ...     print(area.centroid().cat)
        ...
        3
        3
        3
        3

        >>> test_vect.close()

## Submodules

## grass.pygrass.vector.abstract module

Created on Fri Aug 17 17:24:03 2012

@author: pietro

class grass.pygrass.vector.abstract.Info(name, mapset='', *aopen, **kwopen)

  Bases: `object`

  Basic vector info. To get access to the vector info the map must be opened.

      >>> test_vect = Info(test_vector_name)
      >>> test_vect.open(mode='r')

  Then it is possible to read and write the following map attributes:

      >>> test_vect.organization
      'Thuenen Institut'
      >>> test_vect.person
      'Soeren Gebbert'
      >>> test_vect.title
      'Test dataset'
      >>> test_vect.scale
      1
      >>> test_vect.comment
      'This is a comment'
      >>> test_vect.comment = "One useful comment!"
      >>> test_vect.comment
      'One useful comment!'

  There are some read only attributes:

      >>> test_vect.maptype
      'native'

  And some basic methods:

      >>> test_vect.is_3D()
      False
      >>> test_vect.exist()
      True
      >>> test_vect.is_open()
      True
      >>> test_vect.close()

  build()

    Close the vector map and build vector Topology

  close(build=False)

    Method to close the Vector

    Parameters:

      build (bool) – True if the vector map should be build before close it

  property comment

    Set or obtain the Vector comment

  property date

    Set or obtain the Vector date

  exist()

    Return if the Vector exists or not

  property full_name

    Return the full name of Vector

  is_3D()

    Return if the Vector is 3D

  is_open()

    Return if the Vector is open

  property map_date

    Set or obtain the Vector map date

  property mapset

    Set or obtain the Vector mapset

  property maptype

    Return the map type of Vector

  property mode
  property name

    Set or obtain the Vector name

  open(mode=None, layer=1, overwrite=None, with_z=None, tab_name='', tab_cols=None, link_name=None, link_key='cat', link_db='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db', link_driver='sqlite')

    Open a Vector map.

    Parameters:

      - mode (str) – open a vector map in `r` in reading, `w` in writing and in `rw` read and write mode

      - layer (int) – specify the layer that you want to use

      - overwrite (bool) – valid only for `w` mode

      - with_z (bool) – specify if vector map must be open with third dimension enabled or not. Valid only for `w` mode, default: False

      - tab_name (str) – define the name of the table that will be generate

      - tab_cols (list of pairs) – define the name and type of the columns of the attribute table of the vecto map

      - link_name (str) – define the name of the link connection with the database

      - link_key (str) – define the nema of the column that will be use as vector category

      - link_db (str) – define the database connection parameters

      - link_driver – define witch database driver will be used

      - link_driver – str

    Some of the parameters are valid only with mode `w` or `rw`

    See more examples in the documentation of the `read` and `write` methods

  property organization

    Set or obtain the Vector organization

  property person

    Set or obtain the Vector author

  property proj

    Set or obtain the Vector projection code

  property proj_name

    Return the project name of Vector

  remove()

    Remove vector map

  rename(newname)

    Method to rename the Vector map

    Parameters:

      newname (str) – the new name for the Vector map

  property scale

    Set or obtain the Vector scale

  property thresh

    Set or obtain the Vector threshold

  property title

    Set or obtain the Vector title

  write_header()

    Save the change in the C struct permanently to disk.

  property zone

    Set or obtain the Vector projection zone

grass.pygrass.vector.abstract.is_open(c_mapinfo)

  Return if the Vector is open

## grass.pygrass.vector.basic module

Created on Tue Jul 31 13:06:20 2012

@author: pietro

class grass.pygrass.vector.basic.Bbox(north=0, south=0, east=0, west=0, top=0, bottom=0)

  Bases: `object`

  Instantiate a Bounding Box class that contains a ctypes pointer to the C struct bound_box, that could be used by C GRASS functions.

      >>> bbox = Bbox()
      >>> bbox
      Bbox(0.0, 0.0, 0.0, 0.0)

  The default parameters are 0. It is possible to set or change the parameters later, with:

      >>> bbox.north = 10
      >>> bbox.south = -10
      >>> bbox.east = -20
      >>> bbox.west = 20
      >>> bbox
      Bbox(10.0, -10.0, -20.0, 20.0)

  Or directly istantiate the class with the values, with:

      >>> bbox = Bbox(north=100, south=0, east=0, west=100)
      >>> bbox
      Bbox(100.0, 0.0, 0.0, 100.0)

  property bottom

    Set and obtain bottom value

  contains(point)

    Return True if the object is contained by the BoundingBox

    Parameters:

      point (a Point object or a tuple with the coordinates) – the point to analyze

        >>> from grass.pygrass.vector.geometry import Point
        >>> poi = Point(5,5)
        >>> bbox = Bbox(north=10, south=0, west=0, east=10)
        >>> bbox.contains(poi)
        True

  property east

    Set and obtain east value

  items()
  keys()
  property north

    Set and obtain north value

  nsewtb(tb=True)

    Return a list of values from bounding box

    Parameters:

      tb (bool) – if tb parameter is False return only: north, south, east, west and not top and bottom

  property south

    Set and obtain south value

  property top

    Set and obtain top value

  property west

    Set and obtain west value

class grass.pygrass.vector.basic.BoxList(boxlist=None)

  Bases: `object`

  Instantiate a BoxList class to create a list of Bounding Box

  append(box)

    Append a Bbox object to a Boxlist object, using the `Vect_boxlist_append` C function.

    Parameters:

      - bbox – the bounding box to add to the list

      - bbox – a Bbox object

        >>> box0 = Bbox()
        >>> box1 = Bbox(1,2,3,4)
        >>> box2 = Bbox(5,6,7,8)
        >>> boxlist = BoxList([box0, box1])
        >>> boxlist
        Boxlist([Bbox(0.0, 0.0, 0.0, 0.0), Bbox(1.0, 2.0, 3.0, 4.0)])
        >>> len(boxlist)
        2
        >>> boxlist.append(box2)
        >>> len(boxlist)
        3

  have_boxes()
  property ids
  property n_values
  remove(indx)

    Remove Bbox from the boxlist, given an integer or a list of integer or a boxlist, using `Vect_boxlist_delete` C function or the `Vect_boxlist_delete_boxlist`.

    Parameters:

      - indx – the index value of the Bbox to remove

      - indx – int

        >>> boxlist = BoxList([Bbox(),
        ...                    Bbox(1, 0, 0, 1),
        ...                    Bbox(1, -1, -1, 1)])
        >>> boxlist.remove(0)
        >>> boxlist
        Boxlist([Bbox(1.0, 0.0, 0.0, 1.0), Bbox(1.0, -1.0, -1.0, 1.0)])

  reset()

    Reset the c_boxlist C struct, using the `Vect_reset_boxlist` C function.

        >>> boxlist = BoxList([Bbox(),
        ...                    Bbox(1, 0, 0, 1),
        ...                    Bbox(1, -1, -1, 1)])
        >>> len(boxlist)
        3
        >>> boxlist.reset()
        >>> len(boxlist)
        0

class grass.pygrass.vector.basic.Cats(c_cats=None)

  Bases: `object`

  Instantiate a Category class that contains a ctypes pointer to the C line_cats struct.

      >>> cats = Cats()
      >>> for cat in range(100, 110): cats.set(cat, layer=cat-50)
      >>> cats.n_cats
      10
      >>> cats.cat
      [100, 101, 102, 103, 104, 105, 106, 107, 108, 109]
      >>> cats.layer
      [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]
      >>> cats.get()  # default layer is 1
      (-1, 0)
      >>> cats.get(50)
      (100, 1)
      >>> cats.get(51)
      (101, 1)
      >>> cats.set(1001, 52)
      >>> cats.cat
      [100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 1001]
      >>> cats.layer
      [50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 52]
      >>> cats.get(52)
      (102, 2)
      >>> cats.reset()
      >>> cats.layer
      []
      >>> cats.cat
      []

  property cat
  check_cats_constraints(cats_list, layer=1)

    Check if categories match with category constraints

    Parameters:

      - cats_list (list) – a list of categories

      - layer (int) – the number of layer

  delete(cat=None, layer=1)

    If cat is given delete cat from line_cats structure (using Vect_field_cat_del) else delete all categories of given layer (using Vect_cat_del).

    Parameters:

      - cat (int) – the cat to add

      - layer (int) – the number of layer

  get(layer=1)

    Return the first found category of given layer and the number of category found.

    Parameters:

      layer (int) – the number of layer

  get_list(layer=1)

    Get list of categories of given field.

    Parameters:

      layer (int) – the number of layer

  property layer
  property n_cats

    Return the number of categories

  reset()

    Reset the C cats struct from previous values.

  set(cat, layer=1)

    Add new field/cat to category structure if doesn’t exist yet.

    Parameters:

      - cat (int) – the cat to add

      - layer (int) – the number of layer

class grass.pygrass.vector.basic.CatsList(c_cat_list=None)

  Bases: `object`

      >>> cats_list = CatsList()
      >>> cats_list.min
      []
      >>> cats_list.max
      []
      >>> cats_list.n_ranges
      0
      >>> cats_list.layer
      0
      >>> string = "2,3,5-9,20"
      >>> cats_list.from_string(string)
      >>> cats_list.min
      [2, 3, 5, 20]
      >>> cats_list.max
      [2, 3, 9, 20]
      >>> cats_list.n_ranges
      4

  from_array(array)

    Convert ordered array of integers to cat_list structure.

    Parameters:

      array (array) – the input array containing the cats

  from_string(string)

    Converts string of categories and cat ranges separated by commas to cat_list.

    Parameters:

      string (str) – a string containing the cats separated by commas

  property layer

    Return the layer number

  property max

    Return the maximum value

  property min

    Return the minimum value

  property n_ranges

    Return the ranges number

class grass.pygrass.vector.basic.Ilist(integer_list=None)

  Bases: `object`

  Instantiate a list of integer using the C GRASS struct `ilist`, the class contains this struct as `c_ilist` attribute.

  append(value)

    Append an integer to the list

  contains(value)

    Check if value is in the list

  extend(ilist)

    Extend the list with another Ilist object or with a list of integers

    Parameters:

      ilist (a Ilist object) – the ilist to append

  remove(value)

    Remove a value from a list

  reset()

    Reset the list

## grass.pygrass.vector.find module

Created on Tue Mar 19 11:09:30 2013

@author: pietro

class grass.pygrass.vector.find.AbstractFinder(c_mapinfo, table=None, writeable=False)

  Bases: `object`

  ### Abstract finder

  Find geometry feature around a point.

  is_open()

    Check if the vector map is open or not

class grass.pygrass.vector.find.BboxFinder(c_mapinfo, table=None, writeable=False)

  Bases: `AbstractFinder`

  Bounding Box finder

  This class provides an interface to search geometry features of a vector map that are inside or intersect a boundingbox. The BboxFinder class is part of a topological vector map object.

  Find geometry feature(s)that are insider or intersect with a boundingbox.

  > param c_mapinfo:

  >   Pointer to the vector layer mapinfo structure

  > type c_mapinfo:

  >   ctypes pointer to mapinfo structure

  > param table:

  >   Attribute table of the vector layer

  > type table:

  >   Class Table from grass.pygrass.table

  > param writable:

  >   True or False

  > type writeable:

  >   boolean

  areas(bbox, boxlist=None, bboxlist_only=False)

    Find areas inside a boundingbox.

    Parameters:

      - bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search in

      - boxlist – An existing BoxList to be filled with

      - bboxlist_only (boolean) – If true the BoxList will be returned, no features are generated

    Type_boxlist:

      grass.pygrass.vector.basic.BoxList

    Returns:

      A list of areas or None if nothing was found

    This methods uses libvect.Vect_select_areas_by_box()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.basic import Bbox
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find areas in box >>> bbox = Bbox(north=5, south=-1, east=9, west=-1) >>> result = test_vect.find_by_bbox.areas(bbox=bbox) >>> [area for area in result] [Area(1), Area(2), Area(3), Area(4)]

        >>> bbox = Bbox(north=5, south=-1, east=9, west=-1)
        >>> result = test_vect.find_by_bbox.areas(bbox=bbox,
        ...                                       bboxlist_only=True)
        >>> result
        Boxlist([Bbox(4.0, 0.0, 4.0, 0.0),
                 Bbox(4.0, 0.0, 6.0, 4.0),
                 Bbox(3.0, 1.0, 3.0, 1.0),
                 Bbox(4.0, 0.0, 8.0, 6.0)])

        >>> bbox = Bbox(north=20, south=18, east=20, west=18)
        >>> test_vect.find_by_bbox.areas(bbox=bbox)

        >>> test_vect.find_by_bbox.areas(bbox=bbox,
        ...                              bboxlist_only=True)

        >>> test_vect.close()

  geos(bbox, type='all', bboxlist_only=False)

    Find vector features inside a boundingbox.

    Parameters:

      - bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search in

      - type (string) – The type of feature to search for Valid type are all the keys in find.vtype dictionary

      - bboxlist_only (boolean) – If true the BoxList will be returned, no features are generated

    Returns:

      A list of grass.pygrass.vector.geometry (Line, Point, Boundary, Centroid) if found, or None if nothing was found. If bboxlist_only is True a BoxList object will be returned, or None if nothing was found.

    This methods uses libvect.Vect_select_lines_by_box()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.basic import Bbox
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

        >>> bbox = Bbox(north=5, south=-1, east=3, west=-1)
        >>> result = test_vect.find_by_bbox.geos(bbox=bbox)
        >>> [bbox for bbox in result]
        [Boundary([Point(4.000000, 0.000000), Point(0.000000, 0.000000)]),
         Boundary([Point(0.000000, 0.000000), Point(0.000000, 4.000000)]),
         Boundary([Point(0.000000, 4.000000), Point(4.000000, 4.000000)]),
         Boundary([Point(1.000000, 1.000000), Point(1.000000, 3.000000),
                   Point(3.000000, 3.000000), Point(3.000000, 1.000000),
                   Point(1.000000, 1.000000)]),
         Centroid(2.500000, 2.500000)]

        >>> bbox = Bbox(north=5, south=-1, east=3, west=-1)
        >>> result = test_vect.find_by_bbox.geos(bbox=bbox,
        ...                                      bboxlist_only=True)
        >>> result
        Boxlist([Bbox(0.0, 0.0, 4.0, 0.0),
                 Bbox(4.0, 0.0, 0.0, 0.0),
                 Bbox(4.0, 4.0, 4.0, 0.0),
                 Bbox(3.0, 1.0, 3.0, 1.0),
                 Bbox(2.5, 2.5, 2.5, 2.5)])

        >>> bbox = Bbox(north=7, south=-1, east=15, west=9)
        >>> result = test_vect.find_by_bbox.geos(bbox=bbox)
        >>> [bbox for bbox in result]
        [Line([Point(10.000000, 4.000000), Point(10.000000, 2.000000),
               Point(10.000000, 0.000000)]),
         Point(10.000000, 6.000000),
         Line([Point(12.000000, 4.000000), Point(12.000000, 2.000000),
               Point(12.000000, 0.000000)]),
         Point(12.000000, 6.000000),
         Line([Point(14.000000, 4.000000), Point(14.000000, 2.000000),
               Point(14.000000, 0.000000)]),
         Point(14.000000, 6.000000)]

        >>> bbox = Bbox(north=20, south=18, east=20, west=18)
        >>> test_vect.find_by_bbox.geos(bbox=bbox)

        >>> bbox = Bbox(north=20, south=18, east=20, west=18)
        >>> test_vect.find_by_bbox.geos(bbox=bbox, bboxlist_only=True)

        >>> test_vect.close()

  islands(bbox, bboxlist_only=False)

    Find isles inside a boundingbox.

    Parameters:

      - bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search in

      - bboxlist_only (boolean) – If true the BoxList will be returned, no features are generated

    Returns:

      A list of isles or None if nothing was found

    This methods uses libvect.Vect_select_isles_by_box()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.basic import Bbox
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find isles in box >>> bbox = Bbox(north=5, south=-1, east=9, west=-1) >>> result = test_vect.find_by_bbox.islands(bbox=bbox) >>> [isle for isle in result] [Isle(1), Isle(2)]

        >>> bbox = Bbox(north=5, south=-1, east=9, west=-1)
        >>> result = test_vect.find_by_bbox.islands(bbox=bbox,
        ...                                       bboxlist_only=True)
        >>> result
        Boxlist([Bbox(4.0, 0.0, 8.0, 0.0),
                 Bbox(3.0, 1.0, 3.0, 1.0)])

        >>> bbox = Bbox(north=20, south=18, east=20, west=18)
        >>> test_vect.find_by_bbox.islands(bbox=bbox)

        >>> test_vect.find_by_bbox.islands(bbox=bbox,
        ...                              bboxlist_only=True)

        >>> test_vect.close()

  nodes(bbox)

    Find nodes inside a boundingbox.

    Parameters:

      bbox (grass.pygrass.vector.basic.Bbox) – The boundingbox to search in

    Returns:

      A list of nodes or None if nothing was found

    This methods uses libvect.Vect_select_nodes_by_box()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.basic import Bbox
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find nodes in box >>> bbox = Bbox(north=5, south=-1, east=15, west=9) >>> result = test_vect.find_by_bbox.nodes(bbox=bbox) >>> [node for node in result] [Node(2), Node(1), Node(4), Node(3), Node(5), Node(6)]

        >>> bbox = Bbox(north=20, south=18, east=20, west=18)
        >>> test_vect.find_by_bbox.nodes(bbox=bbox)

        >>> test_vect.close()

class grass.pygrass.vector.find.PointFinder(c_mapinfo, table=None, writeable=False)

  Bases: `AbstractFinder`

  Point finder

  This class provides an interface to search geometry features of a vector map that are close to a point. The PointFinder class is part of a topological vector map object.

  Find geometry feature(s) around a point.

  Parameters:

    - c_mapinfo (ctypes pointer to mapinfo structure) – Pointer to the vector layer mapinfo structure

    - table (Class Table from grass.pygrass.table) – Attribute table of the vector layer

    - writable – True or False

  area(point)

    Find the nearest area around a specific point.

    Parameters:

      point (grass.pygrass.vector.geometry.Point) – The point to search

    Returns:

      A grass.pygrass.vector.geometry.Area if found or None

    This methods uses libvect.Vect_find_area()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.geometry import Point
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find AREAS >>> points = (Point(0.5,0.5), Point(5,1), Point(7,1)) >>> result = [] >>> for point in points: … area = test_vect.find_by_point.area(point) … result.append(area) >>> result [Area(1), Area(2), Area(4)] >>> for area in result: … print(area.to_wkt()) #doctest: +NORMALIZE_WHITESPACE POLYGON ((0.0000000000000000 0.0000000000000000,

    > > 0.0000000000000000 4.0000000000000000, 0.0000000000000000 4.0000000000000000, 4.0000000000000000 4.0000000000000000, 4.0000000000000000 4.0000000000000000, 4.0000000000000000 0.0000000000000000, 4.0000000000000000 0.0000000000000000, 0.0000000000000000 0.0000000000000000),

    > (1.0000000000000000 1.0000000000000000,

    >   3.0000000000000000 1.0000000000000000, 3.0000000000000000 3.0000000000000000, 1.0000000000000000 3.0000000000000000, 1.0000000000000000 1.0000000000000000))

    POLYGON ((4.0000000000000000 0.0000000000000000,

      4.0000000000000000 4.0000000000000000, 4.0000000000000000 4.0000000000000000, 6.0000000000000000 4.0000000000000000, 6.0000000000000000 4.0000000000000000, 6.0000000000000000 0.0000000000000000, 6.0000000000000000 0.0000000000000000, 4.0000000000000000 0.0000000000000000))

    POLYGON ((6.0000000000000000 0.0000000000000000,

      6.0000000000000000 4.0000000000000000, 6.0000000000000000 4.0000000000000000, 8.0000000000000000 4.0000000000000000, 8.0000000000000000 4.0000000000000000, 8.0000000000000000 0.0000000000000000, 8.0000000000000000 0.0000000000000000, 6.0000000000000000 0.0000000000000000))

        >>> test_vect.find_by_point.area(Point(20,20))

        >>> test_vect.close()

  geo(point, maxdist, type='all', exclude=0)

    Find the nearest vector feature around a specific point.

    Parameters:

      - point (grass.pygrass.vector.geometry.Point) – The point to search

      - maxdist (float) – The maximum search distance around the point

      - type (string) – The type of feature to search for Valid type are all the keys in find.vtype dictionary

      - exclude – if > 0 number of lines which should be excluded from selection

    Returns:

      A grass.pygrass.vector.geometry.Node if found or None

    This methods uses libvect.Vect_find_line()()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.geometry import Point
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find single features >>> points = (Point(10,0), Point(10,6), Point(14,2)) >>> result = [] >>> for point in points: … f = test_vect.find_by_point.geo(point=point, maxdist=1) … if f: … result.append(f) >>> for f in result: … print(f.to_wkt_p()) #doctest: +NORMALIZE_WHITESPACE LINESTRING(10.000000 4.000000,

    > 10.000000 2.000000, 10.000000 0.000000)

    POINT(10.000000 6.000000) LINESTRING(14.000000 4.000000,

    > 14.000000 2.000000, 14.000000 0.000000)

        >>> test_vect.find_by_point.geo(point=Point(20,20), maxdist=0)

        >>> test_vect.close()

  geos(point, maxdist, type='all', exclude=None)

    Find the nearest vector features around a specific point.

    Parameters:

      - point (grass.pygrass.vector.geometry.Point) – The point to search

      - maxdist (float) – The maximum search distance around the point

      - type (string) – The type of feature to search for Valid type are all the keys in find.vtype dictionary

      - exclude – if > 0 number of lines which should be excluded from selection

    Returns:

      A list of grass.pygrass.vector.geometry (Line, Point, Boundary, Centroid) if found or None

    This methods uses libvect.Vect_find_line_list()()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.geometry import Point
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find multiple features >>> points = (Point(10,0), Point(10,5), Point(14,2)) >>> result = [] >>> for point in points: … f = test_vect.find_by_point.geos(point=point, … maxdist=1.5) … if f: … result.append(f) >>> for f in result: … print(f) #doctest: +NORMALIZE_WHITESPACE [Line([Point(10.000000, 4.000000),

    > Point(10.000000, 2.000000), Point(10.000000, 0.000000)])]

    [Line([Point(10.000000, 4.000000),

      > Point(10.000000, 2.000000), Point(10.000000, 0.000000)]),

      Point(10.000000, 6.000000)]

    [Line([Point(14.000000, 4.000000),

      Point(14.000000, 2.000000), Point(14.000000, 0.000000)])]

    # Find multiple boundaries >>> point = Point(3,3) >>> result = test_vect.find_by_point.geos(point=Point(3,3), … type=”boundary”, … maxdist=1.5) >>> result #doctest: +NORMALIZE_WHITESPACE [Boundary([Point(0.000000, 4.000000), Point(4.000000, 4.000000)]),

    > Boundary([Point(4.000000, 4.000000), Point(4.000000, 0.000000)]), Boundary([Point(1.000000, 1.000000), Point(1.000000, 3.000000),

    > > Point(3.000000, 3.000000), Point(3.000000, 1.000000), Point(1.000000, 1.000000)]),

    > Boundary([Point(4.000000, 4.000000), Point(6.000000, 4.000000)])]

    # Find multiple centroids >>> point = Point(3,3) >>> result = test_vect.find_by_point.geos(point=Point(3,3), … type=”centroid”, … maxdist=1.5) >>> result #doctest: +NORMALIZE_WHITESPACE [Centroid(2.500000, 2.500000),

    > Centroid(3.500000, 3.500000)]

        >>> test_vect.find_by_point.geos(point=Point(20,20), maxdist=0)

        >>> test_vect.close()

  island(point)

    Find the nearest island around a specific point.

    Parameters:

      point (grass.pygrass.vector.geometry.Point) – The point to search

    Returns:

      A grass.pygrass.vector.geometry.Isle if found or None

    This methods uses Vect_find_island.Vect_find_area()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.geometry import Point
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find ISLANDS >>> points = (Point(2,2), Point(5,1)) >>> result = [] >>> for point in points: … area = test_vect.find_by_point.island(point) … result.append(area) >>> result [Isle(2), Isle(1)] >>> for isle in result: … print(isle.to_wkt()) #doctest: +NORMALIZE_WHITESPACE Polygon((1.000000 1.000000, 3.000000 1.000000,

    > 3.000000 3.000000, 1.000000 3.000000, 1.000000 1.000000))

    Polygon((0.000000 4.000000, 0.000000 0.000000, 4.000000 0.000000,

      6.000000 0.000000, 8.000000 0.000000, 8.000000 4.000000, 6.000000 4.000000, 4.000000 4.000000, 0.000000 4.000000))

        >>> test_vect.find_by_point.island(Point(20,20))

        >>> test_vect.close()

  node(point, maxdist)

    Find the nearest node around a specific point.

    Parameters:

      - point (grass.pygrass.vector.geometry.Point) – The point to search

      - maxdist (float) – The maximum search distance around the point

    Returns:

      A grass.pygrass.vector.geometry.Node if found or None

    This methods uses libvect.Vect_find_node()()

    Examples:

        >>> from grass.pygrass.vector import VectorTopo
        >>> from grass.pygrass.vector.geometry import Point
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')

    # Find nearest node >>> points = (Point(10,0), Point(10,4), Point(14,0)) >>> result = [] >>> for point in points: … f = test_vect.find_by_point.node(point=point, maxdist=1) … if f: … result.append(f) >>> result [Node(2), Node(1), Node(6)]

        >>> test_vect.find_by_point.node(point=Point(20,20), maxdist=0)

        >>> test_vect.close()

class grass.pygrass.vector.find.PolygonFinder(c_mapinfo, table=None, writeable=False)

  Bases: `AbstractFinder`

  ### Abstract finder

  Find geometry feature around a point.

  areas(polygon, isles=None)
  lines(polygon, isles=None)

## grass.pygrass.vector.geometry module

Created on Wed Jul 18 10:46:25 2012

@author: pietro

class grass.pygrass.vector.geometry.Area(**kargs)

  Bases: `Geo`

  Vect_build_line_area, Vect_find_area, Vect_get_area_box, Vect_get_area_points_geos, Vect_centroid_area,

  Vect_get_isle_area, Vect_get_line_areas, Vect_get_num_areas, Vect_get_point_in_area, Vect_isle_find_area, Vect_point_in_area, Vect_point_in_area_outer_ring,

  Vect_read_area_geos, Vect_remove_small_areas, Vect_select_areas_by_box, Vect_select_areas_by_polygon

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  alive()

    Check if area is alive or dead (topology required)

  area()

    Returns area of area without areas of isles. double Vect_get_area_area (const struct Map_info *Map, int area)

  bbox(bbox=None)

    Return the Bbox of area

    Parameters:

      bbox (a Bbox object) – a Bbox object to fill with info from bounding box of area

  boundaries(ilist=False)

    Creates list of boundaries for given area.

    int Vect_get_area_boundaries(const struct Map_info *Map,

      int area, struct ilist *List)

  buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, caps=True, tol=0.1)

    Return the buffer area around the area, using the `Vect_area_buffer2` C function.

    Parameters:

      - dist (num) – the distance around the area

      - dist_x (num) – the distance along x

      - dist_y (num) – the distance along y

      - angle (num) – the angle between 0x and major axis

      - round (bool) – to make corners round

      - tol (float) – fix the maximum distance between theoretical arc and output segments

    Returns:

      the buffer as line, centroid, isles object tuple

  property cat
  cats(cats=None)

    Get area categories.

    Parameters:

      cats (a Cats object) – a Cats object to fill with info with area categories

  centroid()

    Return the centroid

    Parameters:

      centroid (a Centroid object) – a Centroid object to fill with info from centroid of area

  contains_point(point, bbox=None)

    Check if point is in area.

    Parameters:

      - point (a Point object or a tuple with the coordinates) – the point to analyze

      - bbox (a Bbox object) – the bounding box where run the analysis

  get_first_cat()

    Find FIRST category of given field and area.

    int Vect_get_area_cat(const struct Map_info *Map, int area, int field)

    ..warning: Not implemented

  gtype = 64
  isles(isles=None)

    Return a list of islands located in this area

  num_isles()
  perimeter()

    Calculate area perimeter.

    Returns:

      double Vect_area_perimeter (const struct line_pnts *Points)

  points(line=None)

    Return a Line object with the outer ring

    Parameters:

      line (a Line object) – a Line object to fill with info from points of area

  read()

    Read and set the coordinates of the centroid from the vector map, using the centroid_id and calling the Vect_read_line C function

  to_wkb()

    Return a “well know binary” (WKB) area byte array, this method uses the GEOS implementation in the vector library.

  to_wkt()

    Return a “well know text” (WKT) area string, this method uses the GEOS implementation in the vector library.

class grass.pygrass.vector.geometry.Attrs(cat, table, writeable=False)

  Bases: `object`

  property cat

    Set and obtain cat value

  commit()

    Save the changes

  keys()

    Return the column name of the attribute table.

        >>> from grass.pygrass.vector import VectorTopo
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')
        >>> v1 = test_vect[1]
        >>> v1.attrs.keys()
        ['cat', 'name', 'value']
         >>> test_vect.close()

  values()

    Return the values of the attribute table row.

        >>> from grass.pygrass.vector import VectorTopo
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open('r')
        >>> v1 = test_vect[1]
        >>> v1.attrs.values()
        (1, 'point', 1.0)
         >>> test_vect.close()

class grass.pygrass.vector.geometry.Boundary(**kargs)

  Bases: `Line`

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  area()

    Return the area of the polygon.

        >>> bound = Boundary(points=[(0, 0), (0, 2), (2, 2), (2, 0),
        ...                          (0, 0)])
        >>> bound.area()
        4.0

  gtype = 4
  property left_area_id

    Left side area id, only available after read_area_ids() was called

  left_centroid(idonly=False)

    Return left centroid

    Parameters:

      idonly (bool) – True to return only the cat of feature

  read_area_ids()

    Read and return left and right area ids of the boundary

  property right_area_id

    Right side area id, only available after read_area_ids() was called

  right_centroid(idonly=False)

    Return right centroid

    Parameters:

      idonly (bool) – True to return only the cat of feature

class grass.pygrass.vector.geometry.Centroid(area_id=None, **kargs)

  Bases: `Point`

  The Centroid class inherit from the Point class. Centroid contains an attribute with the C Map_info struct, and attributes with the id of the Area.

      >>> centroid = Centroid(x=0, y=10)
      >>> centroid
      Centroid(0.000000, 10.000000)
      >>> from grass.pygrass.vector import VectorTopo
      >>> test_vect = VectorTopo(test_vector_name)
      >>> test_vect.open(mode='r')
      >>> centroid = Centroid(v_id=18, c_mapinfo=test_vect.c_mapinfo)
      >>> centroid
      Centroid(3.500000, 3.500000)
      >>> test_vect.close()

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  gtype = 8

class grass.pygrass.vector.geometry.Geo(v_id=0, c_mapinfo=None, c_points=None, c_cats=None, table=None, writeable=False, is2D=True, free_points=False, free_cats=False)

  Bases: `object`

  Base object for different feature types

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  property cat
  gtype = None
  has_topology()
  read()

    Read and set the coordinates of the centroid from the vector map, using the centroid_id and calling the Vect_read_line C function

  to_wkb()

    Return a “well know binary” (WKB) geometry byte array, this method uses the GEOS implementation in the vector library.

        >>> pnt = Point(10, 100)
        >>> wkb = pnt.to_wkb()
        >>> len(wkb)
        21

  to_wkt()

    Return a “well know text” (WKT) geometry string, this method uses the GEOS implementation in the vector library.

        >>> pnt = Point(10, 100)
        >>> pnt.to_wkt()
        'POINT (10.0000000000000000 100.0000000000000000)'

class grass.pygrass.vector.geometry.Isle(**kargs)

  Bases: `Geo`

  An Isle is an area contained by another area.

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  alive()

    Check if isle is alive or dead (topology required)

  area()

    Return the area value of an Isle

  area_id()

    Returns area id for isle.

  bbox(bbox=None)

    Return bounding box of Isle

  boundaries()

    Return a list of boundaries

  contain_pnt(pnt)

    Check if point is in area.

    Parameters:

      pnt (a Point object or a tuple with the coordinates) – the point to remove

  perimeter()

    Return the perimeter value of an Isle.

  points()

    Return a Line object with the outer ring points

  points_geos()

    Return a Line object with the outer ring points

  to_wkb()

    Return a “well know text” (WKB) geometry array.

  to_wkt()

    Return a Well Known Text string of the isle.

    For now the outer ring is returned

    TODO: Implement inner rings detected from isles

class grass.pygrass.vector.geometry.Isles(c_mapinfo, area_id=None)

  Bases: `object`

  isles()

    Return isles

  isles_ids()

    Return the id of isles

class grass.pygrass.vector.geometry.Line(points=None, **kargs)

  Bases: `Geo`

  Instantiate a new Line with a list of tuple, or with a list of Point.

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

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  alive()

    Return True if this line is alive or False if this line is dead or its index is out of range.

  append(pnt)

    Appends one point to the end of a line, using the `Vect_append_point` C function.

    Parameters:

      pnt – the point to add to line

    Like python list.

  bbox(bbox=None)

    Return the bounding box of the line, using `Vect_line_box` C function.

        >>> line = Line([(0, 0), (0, 1), (2, 1), (2, 0)])
        >>> bbox = line.bbox()
        >>> bbox
        Bbox(1.0, 0.0, 2.0, 0.0)

  buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, caps=True, tol=0.1)

    Return the buffer area around the line, using the `Vect_line_buffer2` C function.

    Parameters:

      - dist (num) – the distance around the line

      - dist_x (num) – the distance along x

      - dist_y (num) – the distance along y

      - angle (num) – the angle between 0x and major axis

      - round (bool) – to make corners round

      - tol (float) – fix the maximum distance between theoretical arc and output segments

    Returns:

      the buffer as Area object

        >>> line = Line([(0, 0), (0, 2)])
        >>> boundary, centroid, isles = line.buffer(10)
        >>> boundary
        Line([Point(-10.000000, 0.000000),...Point(-10.000000, 0.000000)])
        >>> centroid
        Point(0.000000, 0.000000)
        >>> isles
        []

  delete(indx)

    Remove the point in the index position. :param indx: the index where add new point :type indx: int

        >>> line = Line([(0, 0), (1, 1), (2, 2)])
        >>> line.delete(-1)
        >>> line
        Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])

  distance(pnt)

    Calculate the distance between line and a point.

    Parameters:

      pnt (a Point object or a tuple with the coordinates) – the point to calculate distance

    Return a namedtuple with:

    > - point: the closest point on the line,

    > - dist: the distance between these two points,

    > - spdist: distance to point on line from segment beginning

    > - sldist: distance to point on line form line beginning along line

    The distance is compute using the `Vect_line_distance` C function.

        >>> point = Point(2.3, 0.5)
        >>> line = Line([(0, 0), (2, 0), (3, 0)])
        >>> line.distance(point)
        LineDist(point=Point(2.300000, 0.000000),
                 dist=0.5, spdist=0.2999999999999998, sldist=2.3)

  extend(line, forward=True)

    Appends points to the end of a line.

    Parameters:

      - line (Line object of list of points) – it is possible to extend a line, give a list of points, or directly with a line_pnts struct.

      - forward – if forward is True the line is extend forward otherwise is extend backward. The method use the Vect_append_points C function.

  first_cat()

    Fetches FIRST category number for given vector line and field, using the `Vect_get_line_cat` C function.

    Warning

    Not implemented yet.

  from_wkt(wkt)

    Create a line reading a WKT string.

    Parameters:

      wkt – the WKT string containing the LINESTRING

  gtype = 2
  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.

    Parameters:

      - indx (int) – the index where add new point

      - pnt – the point to add

  length()

    Calculate line length, 3D-length in case of 3D vector line, using Vect_line_length C function.

        >>> line = Line([(0, 0), (1, 1), (0, 1)])
        >>> line.length()
        2.414213562373095

  length_geodesic()

    Calculate line length, using Vect_line_geodesic_length C function.

        >>> line = Line([(0, 0), (1, 1), (0, 1)])
        >>> line.length_geodesic()
        2.414213562373095

  nodes()

    Return the start and end nodes of the line

    This method requires topology build.

    return: A tuple of Node objects that represent the

      start and end point of this line.

  point_on_line(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.

        >>> line = Line([(0, 0), (1, 1)])
        >>> line.point_on_line(5)
        Traceback (most recent call last):
            ...
        ValueError: The distance exceed the length of the line,
        that is: 1.414214
        >>> line.point_on_line(1)
        Point(0.707107, 0.707107)

  pop(indx)

    Return the point in the index position and remove from the Line.

    Parameters:

      indx – the index where add new point

  prune()

    Remove duplicate points, i.e. zero length segments, using Vect_line_prune C function.

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

  prune_thresh(threshold)

    Remove points in threshold, using the `Vect_line_prune_thresh` C function.

    Parameters:

      threshold – the threshold value where prune points

    Warning

    prune_thresh is not working yet.

  remove(pnt)

    Delete point at given index and move all points above down, using Vect_line_delete_point C function.

    Parameters:

      pnt – the point to remove

  reset()

    Reset line, using Vect_reset_line C function.

        >>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
        >>> len(line)
        4
        >>> line.reset()
        >>> len(line)
        0
        >>> line
        Line([])

  reverse()

    Reverse the order of vertices, using Vect_line_reverse C function.

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

  segment(start, end)

    Create line segment. using the `Vect_line_segment` C function.

    Parameters:

      - start (float) – distance from the beginning of the line where the segment start

      - end (float) – distance from the beginning of the line where the segment end

    ::

      # x (1, 1) # | # |- # | # x——–x (1, 0) # (0, 0) ^

          >>> line = Line([(0, 0), (1, 0), (1, 1)])
          >>> line.segment(0.5, 1.5)
          Line([Point(0.500000, 0.000000),
                Point(1.000000, 0.000000),
                Point(1.000000, 0.500000)])

  to_array()

    Return an array of coordinates.

        >>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
        >>> line.to_array()
        array([[ 0.,  0.],
               [ 1.,  1.],
               [ 2.,  0.],
               [ 1., -1.]])

  to_list()

    Return a list of tuple.

        >>> line = Line([(0, 0), (1, 1), (2, 0), (1, -1)])
        >>> line.to_list()
        [(0.0, 0.0), (1.0, 1.0), (2.0, 0.0), (1.0, -1.0)]

  to_wkt_p()

    Return a Well Known Text string of the line.

        >>> line = Line([(0, 0), (1, 1), (1, 2)])
        >>> line.to_wkt_p()
        'LINESTRING(0.000000 0.000000, ..., 1.000000 2.000000)'

class grass.pygrass.vector.geometry.LineDist(point, dist, spdist, sldist)

  Bases: `tuple`

  Create new instance of LineDist(point, dist, spdist, sldist)

  dist

    Alias for field number 1

  point

    Alias for field number 0

  sldist

    Alias for field number 3

  spdist

    Alias for field number 2

class grass.pygrass.vector.geometry.Node(v_id, c_mapinfo, **kwords)

  Bases: `object`

  Node class for topological analysis of line neighbors.

  Objects of this class will be returned by the node() function of a Line object.

  All methods in this class require a proper setup of the Node objects. Hence, the correct id and a valid pointer to a mapinfo object must be provided in the constructions. Otherwise a segfault may happen.

  Construct a Node object

  param v_id: The unique node id param c_mapinfo: A valid pointer to the mapinfo object param **kwords: Ignored

  alive()

    Return True if this node is alive or False if this node is dead or its index is out of range.

  angles()

    Return a generator with all lines angles in a node.

  coords()

    Return a tuple with the node coordinates.

  ilines(only_in=False, only_out=False)

    Return a generator with all lines id connected to a node. The line id is negative if line is ending on the node and positive if starting from the node.

    Parameters:

      - only_in (bool) – Return only the lines that are ending in the node

      - only_out (bool) – Return only the lines that are starting in the node

  lines(only_in=False, only_out=False)

    Return a generator with all lines connected to a node.

    Parameters:

      - only_in (bool) – Return only the lines that are ending in the node

      - only_out (bool) – Return only the lines that are starting in the node

  to_wkb()

    Return a “well know binary” (WKB) geometry array.

    TODO: Must be implemented

  to_wkt()

    Return a “well know text” (WKT) geometry string.

class grass.pygrass.vector.geometry.Point(x=0, y=0, z=None, **kargs)

  Bases: `Geo`

  Instantiate a Point object that could be 2 or 3D, default parameters are 0.

      >>> pnt = Point()
      >>> pnt.x
      0.0
      >>> pnt.y
      0.0
      >>> pnt.z
      >>> pnt.is2D
      True
      >>> pnt
      Point(0.000000, 0.000000)
      >>> pnt.z = 0
      >>> pnt.is2D
      False
      >>> pnt
      Point(0.000000, 0.000000, 0.000000)
      >>> print(pnt)
      POINT Z (0.0000000000000000 0.0000000000000000 0.0000000000000000)

      >>> c_points = ctypes.pointer(libvect.line_pnts())
      >>> c_cats = ctypes.pointer(libvect.line_cats())
      >>> p = Point(c_points = c_points, c_cats=c_cats)
      >>> del p

      >>> c_points = ctypes.pointer(libvect.line_pnts())
      >>> c_cats = ctypes.pointer(libvect.line_cats())
      >>> p = Point(c_points=c_points, c_cats=c_cats, free_points=True,
      ...           free_cats=True)
      >>> del p

  Constructor of a geometry object

  Parameters:

    - v_id – The vector feature id

    - c_mapinfo – A pointer to the vector mapinfo structure

    - c_points – A pointer to a libvect.line_pnts structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - c_cats – A pointer to a libvect.line_cats structure, this is optional, if not set an internal structure will be allocated and free’d at object destruction

    - table – The attribute table to select attributes for this feature

    - writeable – Not sure what this is for?

    - is2D – If True this feature has two dimensions, False if this feature has three dimensions

    - free_points – Set this True if the provided c_points structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

    - free_cats – Set this True if the provided c_cats structure should be free’d at object destruction, be aware that no other object should free them, otherwise you can expect a double free corruption segfault

  buffer(dist=None, dist_x=None, dist_y=None, angle=0, round_=True, tol=0.1)

    Return the buffer area around the point, using the `Vect_point_buffer2` C function.

    Parameters:

      - dist (num) – the distance around the point

      - dist_x (num) – the distance along x

      - dist_y (num) – the distance along y

      - angle (num) – the angle between 0x and major axis

      - round (bool) – to make corners round

      - tol (float) – fix the maximum distance between theoretical arc and output segments

    Returns:

      the buffer as Area object

        >>> pnt = Point(0, 0)
        >>> boundary, centroid = pnt.buffer(10)
        >>> boundary
        Line([Point(10.000000, 0.000000),...Point(10.000000, 0.000000)])
        >>> centroid
        Point(0.000000, 0.000000)

  coords()

    Return a tuple with the point coordinates.

        >>> pnt = Point(10, 100)
        >>> pnt.coords()
        (10.0, 100.0)

    If the point is 2D return a x, y tuple. But if we change the `z` the Point object become a 3D point, therefore the method return a x, y, z tuple.

        >>> pnt.z = 1000.
        >>> pnt.coords()
        (10.0, 100.0, 1000.0)

  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.

    Parameters:

      pnt – the point for calculate the distance

  gtype = 1
  to_wkt_p()

    Return a “well know text” (WKT) geometry string Python implementation.

        >>> pnt = Point(10, 100)
        >>> pnt.to_wkt_p()
        'POINT(10.000000 100.000000)'

    Warning

    Only `POINT` (2/3D) are supported, `POINTM` and `POINT` with: `XYZM` are not supported yet.

  property x

    Set and obtain x coordinate

  property y

    Set and obtain y coordinate

  property z

    Set and obtain z coordinate

grass.pygrass.vector.geometry.c_read_line(feature_id, c_mapinfo, c_points, c_cats)

grass.pygrass.vector.geometry.c_read_next_line(c_mapinfo, c_points, c_cats)

grass.pygrass.vector.geometry.get_xyz(pnt)

  Return a tuple with: x, y, z.

      >>> pnt = Point(0, 0)
      >>> get_xyz(pnt)
      (0.0, 0.0, 0.0)
      >>> get_xyz((1, 1))
      (1, 1, 0.0)
      >>> get_xyz((1, 1, 2))
      (1, 1, 2)
      >>> get_xyz((1, 1, 2, 2))
      Traceback (most recent call last):
          ...
      ValueError: The the format of the point is not supported: (1, 1, 2, 2)

grass.pygrass.vector.geometry.intersects(lineA, lineB, with_z=False)

  Return a list of points

      >>> lineA = Line([(0, 0), (4, 0)])
      >>> lineB = Line([(2, 2), (2, -2)])
      >>> intersects(lineA, lineB)
      Line([Point(2.000000, 0.000000)])

grass.pygrass.vector.geometry.read_WKB(buff)

  Read the binary buffer and return a geometry object

grass.pygrass.vector.geometry.read_WKT(string)

  Read the string and return a geometry object

  WKT:

      POINT(0 0)
      LINESTRING(0 0,1 1,1 2)
      POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))
      MULTIPOINT(0 0,1 2)
      MULTILINESTRING((0 0,1 1,1 2),(2 3,3 2,5 4))
      MULTIPOLYGON(((0 0,4 0,4 4,0 4,0 0),(1 1,2 1,2 2,1 2,1 1)),
                   ((-1 -1,-1 -2,-2 -2,-2 -1,-1 -1)))
      GEOMETRYCOLLECTION(POINT(2 3),LINESTRING(2 3,3 4))

  EWKT:

      POINT(0 0 0) -- XYZ
      SRID=32632;POINT(0 0) -- XY with SRID
      POINTM(0 0 0) -- XYM
      POINT(0 0 0 0) -- XYZM
      SRID=4326;MULTIPOINTM(0 0 0,1 2 1) -- XYM with SRID
      MULTILINESTRING((0 0 0,1 1 0,1 2 1),(2 3 1,3 2 1,5 4 1))
      POLYGON((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2 0,1 2 0,1 1 0))
      MULTIPOLYGON(((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),
                    (1 1 0,2 1 0,2 2 0,1 2 0,1 1 0)),
                   ((-1 -1 0,-1 -2 0,-2 -2 0,-2 -1 0,-1 -1 0)))
      GEOMETRYCOLLECTIONM( POINTM(2 3 9), LINESTRINGM(2 3 4, 3 4 5) )
      MULTICURVE( (0 0, 5 5), CIRCULARSTRING(4 0, 4 4, 8 4) )
      POLYHEDRALSURFACE( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
                         ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)),
                         ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
                         ((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
                         ((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)),
                         ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )
      TRIANGLE ((0 0, 0 9, 9 0, 0 0))
      TIN( ((0 0 0, 0 0 1, 0 1 0, 0 0 0)), ((0 0 0, 0 1 0, 1 1 0, 0 0 0)) )

grass.pygrass.vector.geometry.read_line(feature_id, c_mapinfo, table=None, writeable=False, c_points=None, c_cats=None, is2D=True)

  Return a geometry object given the feature id and the c_mapinfo.

grass.pygrass.vector.geometry.read_next_line(c_mapinfo, table=None, writeable=False, c_points=None, c_cats=None, is2D=True)

  Return the next geometry feature of a vector map.

## grass.pygrass.vector.sql module

It is a collection of strings to avoid to repeat the code.

    >>> SELECT.format(cols=', '.join(['cat', 'area']), tname='table')
    'SELECT cat, area FROM table;'
    >>> SELECT_WHERE.format(cols=', '.join(['cat', 'area']),
    ...                     tname='table', condition='area>10000')
    'SELECT cat, area FROM table WHERE area>10000;'

## grass.pygrass.vector.table module

Created on Wed Aug 8 15:29:21 2012

@author: pietro

class grass.pygrass.vector.table.Columns(tname, connection, key='cat')

  Bases: `object`

  Object to work with columns table.

  It is possible to instantiate a Columns object given the table name and the database connection.

  For a sqlite table:

      >>> import sqlite3
      >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
      >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
      >>> cols_sqlite.tname
      'table_doctest_map'

  For a postgreSQL table:

      >>> import psycopg2 as pg
      >>> cols_pg = Columns(
      ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
      ... )
      >>> cols_pg.tname
      'table_doctest_map'

  add(col_name, col_type)

    Add a new column to the table.

    Parameters:

      - col_name (str) – the name of column to add

      - col_type (str) – the tipe of column to add

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> from grass.pygrass.utils import copy, remove
        >>> copy(test_vector_name, "mycensus", "vect")
        >>> cols_sqlite = Columns("mycensus", sqlite3.connect(get_path(path)))
        >>> cols_sqlite.add(["n_pizza"], ["INT"])
        >>> "n_pizza" in cols_sqlite
        True
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     "boundary_municp_pg", pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.add("n_pizza", "INT")
        >>> "n_pizza" in cols_pg
        True
        >>> remove("mycensus", "vect")

  cast(col_name, new_type)

    Change the column type.

    Parameters:

      - col_name (str) – the name of column

      - new_type (str) – the new type of column

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> from grass.pygrass.utils import copy, remove
        >>> copy(test_vector_name, "mycensus", "vect")
        >>> cols_sqlite = Columns("mycensus", sqlite3.connect(get_path(path)))
        >>> cols_sqlite.add(["n_pizzas"], ["INT"])
        >>> cols_sqlite.cast("n_pizzas", "float8")
        Traceback (most recent call last):
          ...
        grass.exceptions.DBError: SQLite does not support to cast columns.
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.cast("n_pizzas", "float8")
        >>> cols_pg["n_pizzas"]
        'float8'
        >>> remove("mycensus", "vect")

    Warning

    It is not possible to cast a column with sqlite

  drop(col_name)

    Drop a column from the table.

    Parameters:

      col_name (str) – the name of column to remove

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> from grass.pygrass.utils import copy, remove
        >>> copy(test_vector_name, "mycensus", "vect")
        >>> cols_sqlite = Columns("mycensus", sqlite3.connect(get_path(path)))
        >>> cols_sqlite.drop("name")
        >>> "name" in cols_sqlite
        False

        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.drop("name")
        >>> "name" in cols_pg
        False
        >>> remove("mycensus", "vect")

  is_pg()

    Return True if is a psycopg connection.

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
        >>> cols_sqlite.is_pg()
        False
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.is_pg()
        True

  items()

    Return a list of tuple with column name and column type.

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
        >>> cols_sqlite.items()
        [('cat', 'INTEGER'), ('name', 'varchar(50)'), ('value', 'double precision')]
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.items()
        [('cat', 'INTEGER'), ('name', 'varchar(50)'), ('value', 'double precision')]

  names(remove=None, unicod=True)

    Return a list with the column names. Remove it is used to remove a columns.

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
        >>> cols_sqlite.names()
        ['cat', 'name', 'value']
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name,
        ...     pg.connect("host=localhost dbname=grassdb"),
        ... )
        >>> cols_pg.names()
        ['cat', 'name', 'value']

  rename(old_name, new_name)

    Rename a column of the table.

    Parameters:

      - old_name (str) – the name of existing column

      - new_name (str) – the name of new column

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> from grass.pygrass.utils import copy, remove
        >>> copy(test_vector_name, "mycensus", "vect")
        >>> cols_sqlite = Columns("mycensus", sqlite3.connect(get_path(path)))
        >>> cols_sqlite.add(["n_pizza"], ["INT"])
        >>> "n_pizza" in cols_sqlite
        True
        >>> cols_sqlite.rename("n_pizza", "n_pizzas")
        >>> "n_pizza" in cols_sqlite
        False
        >>> "n_pizzas" in cols_sqlite
        True

        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.rename("n_pizza", "n_pizzas")
        >>> "n_pizza" in cols_pg
        False
        >>> "n_pizzas" in cols_pg
        True
        >>> remove("mycensus", "vect")

  sql_descr(remove=None)

    Return a string with description of columns. Remove it is used to remove a columns.

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
        >>> cols_sqlite.sql_descr()
        'cat INTEGER, name varchar(50), value double precision'
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.sql_descr()
        'cat INTEGER, name varchar(50), value double precision'

  types()

    Return a list with the column types.

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> cols_sqlite = Columns(test_vector_name, sqlite3.connect(get_path(path)))
        >>> cols_sqlite.types()
        ['INTEGER', 'varchar(50)', 'double precision']
        >>> import psycopg2 as pg
        >>> cols_pg = Columns(
        ...     test_vector_name, pg.connect("host=localhost dbname=grassdb")
        ... )
        >>> cols_pg.types()
        ['INTEGER', 'varchar(50)', 'double precision']

  update_odict()

    Read columns name and types from table and update the odict attribute.

class grass.pygrass.vector.table.DBlinks(c_mapinfo)

  Bases: `object`

  Interface containing link to the table DB.

      >>> from grass.pygrass.vector import VectorTopo
      >>> cens = VectorTopo(test_vector_name)
      >>> cens.open(mode="r")
      >>> dblinks = DBlinks(cens.c_mapinfo)
      >>> dblinks
      DBlinks([Link(1, table_doctest_map, sqlite)])
      >>> dblinks[0]
      Link(1, table_doctest_map, sqlite)
      >>> dblinks[test_vector_name]
      Link(1, table_doctest_map, sqlite)
      >>> cens.close()

  add(link)

    Add a new link. Need to open vector map in write mode

    Parameters:

      link – the Link to add to the DBlinks

  by_index(indx)

    Return a Link object by index

    Parameters:

      indx (int) – the index where add new point

  by_layer(layer)

    Return the chosen Link using the layer

    Parameters:

      layer (int) – the number of layer

  by_name(name)

    Return the chosen Link using the name

    Parameters:

      name (str) – the name of Link

  from_name_to_num(name)

    Vect_get_field_number

  num_dblinks()

    Return the number of DBlinks

  remove(key, force=False)

    Remove a link. If force set to true remove also the table

    Parameters:

      - key (str) – the key of Link

      - force (boole) – if True remove also the table from database otherwise only the link between table and vector

        >>> from grass.pygrass.vector import VectorTopo
        >>> test_vect = VectorTopo(test_vector_name)
        >>> test_vect.open(mode="r")
        >>> dblinks = DBlinks(test_vect.c_mapinfo)
        >>> dblinks
        DBlinks([Link(1, table_doctest_map, sqlite)])
        >>> dblinks.remove("pg_link")
        >>> dblinks  # need to open vector map in write mode
        DBlinks([Link(1, table_doctest_map, sqlite)])

class grass.pygrass.vector.table.Filters(tname)

  Bases: `object`

  Help user to build a simple sql query.

      >>> filter = Filters("table")
      >>> filter.get_sql()
      'SELECT * FROM table;'
      >>> filter.where("area<10000").get_sql()
      'SELECT * FROM table WHERE area<10000;'
      >>> filter.select("cat", "area").get_sql()
      'SELECT cat, area FROM table WHERE area<10000;'
      >>> filter.order_by("area").limit(10).get_sql()
      'SELECT cat, area FROM table WHERE area<10000 ORDER BY area LIMIT 10;'

  get_sql()

    Return the SQL query

  group_by(*groupby)

    Create the group by condition

    Parameters:

      groupby (str, list) – the name of column/s to group the result

  limit(number)

    Create the limit condition

    Parameters:

      number (int) – the number to limit the result

  order_by(*orderby)

    Create the order by condition

    Parameters:

      orderby (str) – the name of column/s to order the result

  reset()

    Clean internal variables

  select(*args)

    Create the select query

  where(condition)

    Create the where condition

    Parameters:

      condition (str) – the condition of where statement, for example cat = 1

class grass.pygrass.vector.table.Link(layer=1, name=None, table=None, key='cat', database='$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db', driver='sqlite', c_fieldinfo=None)

  Bases: `object`

  Define a Link between vector map and the attributes table.

  It is possible to define a Link object or given all the information (layer, name, table name, key, database, driver):

      >>> link = Link(
      ...     1,
      ...     "link0",
      ...     test_vector_name,
      ...     "cat",
      ...     "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db",
      ...     "sqlite",
      ... )
      >>> link.layer
      1
      >>> link.name
      'link0'
      >>> link.table_name
      'table_doctest_map'
      >>> link.key
      'cat'
      >>> link.database
      '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
      >>> link.driver
      'sqlite'
      >>> link
      Link(1, link0, sqlite)

  It is possible to change parameters with:

      >>> link.driver = "pg"
      >>> link.driver
      'pg'
      >>> link.driver = "postgres"
      Traceback (most recent call last):
        ...
      TypeError: Driver not supported, use: sqlite, pg.
      >>> link.driver
      'pg'
      >>> link.number = 0
      Traceback (most recent call last):
        ...
      TypeError: Number must be positive and greater than 0.

  Or given a c_fieldinfo object that is a ctypes pointer to the field_info C struct.

      >>> link = Link(c_fieldinfo=ctypes.pointer(libvect.field_info()))

  connection()

    Return a connection object.

        >>> link = Link(
        ...     1,
        ...     "link0",
        ...     test_vector_name,
        ...     "cat",
        ...     "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db",
        ...     "sqlite",
        ... )
        >>> conn = link.connection()
        >>> cur = conn.cursor()
        >>> link.table_name
        'table_doctest_map'
        >>> cur.execute(
        ...     "SELECT cat, name, value from %s" % link.table_name
        ... )
        <sqlite3.Cursor object at ...>
        >>> cur.fetchone()
        (1, 'point', 1.0)
        >>> cur.close()
        >>> conn.close()

  property database

    Set and obtain database value

  property driver

    Set and obtain driver value. The drivers supported by PyGRASS are: SQLite and PostgreSQL

  info()

    Print information of the link.

        >>> link = Link(
        ...     1,
        ...     "link0",
        ...     test_vector_name,
        ...     "cat",
        ...     "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db",
        ...     "sqlite",
        ... )
        >>> link.info()
        layer:     1
        name:      link0
        table:     table_doctest_map
        key:       cat
        database:  $GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db
        driver:    sqlite

  property key

    Set and obtain cat value

  property layer

    Set and obtain layer number

  property name

    Set and obtain name vale

  table()

    Return a Table object.

        >>> link = Link(
        ...     1,
        ...     "link0",
        ...     test_vector_name,
        ...     "cat",
        ...     "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db",
        ...     "sqlite",
        ... )
        >>> table = link.table()
        >>> table.filters.select("cat", "name", "value")
        Filters('SELECT cat, name, value FROM table_doctest_map;')
        >>> cur = table.execute()
        >>> cur.fetchone()
        (1, 'point', 1.0)
        >>> cur.close()

  property table_name

    Set and obtain table name value

class grass.pygrass.vector.table.Table(name, connection, key='cat')

  Bases: `object`

      >>> import sqlite3
      >>> path = "$GISDBASE/$LOCATION_NAME/PERMANENT/sqlite/sqlite.db"
      >>> tab_sqlite = Table(
      ...     name=test_vector_name, connection=sqlite3.connect(get_path(path))
      ... )
      >>> tab_sqlite.name
      'table_doctest_map'
      >>> import psycopg2
      >>> tab_pg = Table(
      ...     test_vector_name, psycopg2.connect("host=localhost dbname=grassdb", "pg")
      ... )
      >>> tab_pg.columns
      Columns([('cat', 'int4'), ...])

  create(cols, name=None, overwrite=False, cursor=None)

    Create a new table

    Parameters:

      - cols

      - name (str) – the name of table to create, None for the name of Table object

      - overwrite (bool) – overwrite existing table

      - cursor (Cursor object) – the cursor to connect, if None it use the cursor of connection table object

  drop(cursor=None, force=False)

    Method to drop table from database

    Parameters:

      - cursor (Cursor object) – the cursor to connect, if None it use the cursor of connection table object

      - force (bool) – True to remove the table, by default False to print advice

  execute(sql_code=None, cursor=None, many=False, values=None)

    Execute SQL code from a given string or build with filters and return a cursor object.

    Parameters:

      - sql_code (str) – the SQL code to execute, if not pass it use filters variable

      - cursor (Cursor object) – the cursor to connect, if None it use the cursor of connection table object

      - many (bool) – True to run executemany function

      - values (list of tuple) – The values to substitute into sql_code string

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> tab_sqlite = Table(
        ...     name=test_vector_name, connection=sqlite3.connect(get_path(path))
        ... )
        >>> tab_sqlite.filters.select("cat", "name").order_by("value")
        Filters('SELECT cat, name FROM table_doctest_map ORDER BY value;')
        >>> cur = tab_sqlite.execute()
        >>> cur.fetchone()
         (1, 'point')

  exist(cursor=None)

    Return True if the table already exist in the DB, False otherwise

    Parameters:

      cursor – the cursor to connect, if None it use the cursor of connection table object

  insert(values, cursor=None, many=False)

    Insert a new row

    Parameters:

      - values (tuple) – a tuple of values to insert, it is possible to insert more rows using a list of tuple and parameter many

      - cursor (Cursor object) – the cursor to connect, if None it use the cursor of connection table object

      - many (bool) – True to run executemany function

  n_rows()

    Return the number of rows

        >>> import sqlite3
        >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
        >>> tab_sqlite = Table(
        ...     name=test_vector_name, connection=sqlite3.connect(get_path(path))
        ... )
        >>> tab_sqlite.n_rows()
        3

  property name

    Set and obtain table name

  update(key, values, cursor=None)

    Update a table row

    Parameters:

      - key (int) – the rowid

      - values (list) – the values to insert without row id. For example if we have a table with four columns: cat, c0, c1, c2 the values list should containing only c0, c1, c2 values.

      - cursor (Cursor object) – the cursor to connect, if None it use the cursor of connection table object

grass.pygrass.vector.table.get_path(path, vect_name=None)

  Return the full path to the database; replacing environment variable with real values

  Parameters:

    - path – The path with substitutional parameter

    - vect_name – The name of the vector map

      >>> from grass.script.core import gisenv
      >>> import os
      >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db"
      >>> new_path = get_path(path)
      >>> new_path2 = os.path.join(
      ...     gisenv()["GISDBASE"],
      ...     gisenv()["LOCATION_NAME"],
      ...     gisenv()["MAPSET"],
      ...     "sqlite",
      ...     "sqlite.db",
      ... )
      >>> new_path.replace("//", "/") == new_path2.replace("//", "/")
      True
      >>> path = "$GISDBASE/$LOCATION_NAME/$MAPSET/vector/$MAP/sqlite.db"
      >>> new_path = get_path(path, "test")
      >>> new_path2 = os.path.join(
      ...     gisenv()["GISDBASE"],
      ...     gisenv()["LOCATION_NAME"],
      ...     gisenv()["MAPSET"],
      ...     "vector",
      ...     "test",
      ...     "sqlite.db",
      ... )
      >>> new_path.replace("//", "/") == new_path2.replace("//", "/")
      True

## grass.pygrass.vector.vector_type module

Created on Wed Jul 18 10:49:26 2012

@author: pietro

Help Index | Topics Index | Keywords Index | Full Index

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