# pygrass.vector package

## Submodules

## pygrass.vector.abstract module

Created on Fri Aug 17 17:24:03 2012

@author: pietro

class `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

  `comment`

    Set or obtain the Vector comment

  `date`

    Set or obtain the Vector date

  `exist`()

    Return if the Vector exists or not

  `full_name`

    Return the full name of Vector

  `is_3D`()

    Return if the Vector is 3D

  `is_open`()

    Return if the Vector is open

  `map_date`

    Set or obtain the Vector map date

  `mapset`

    Set or obtain the Vector mapset

  `maptype`

    Return the map type of Vector

  `mode`
  `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 connecttion 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

  `organization`

    Set or obtain the Vector organization

  `person`

    Set or obtain the Vector author

  `proj`

    Set or obtain the Vector projection code

  `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

  `scale`

    Set or obtain the Vector scale

  `thresh`

    Set or obtain the Vector threshold

  `title`

    Set or obtain the Vector title

  `write_header`()

    Save the change in the C struct permanently to disk.

  `zone`

    Set or obtain the Vector projection zone

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

  Return if the Vector is open

## pygrass.vector.basic module

Created on Tue Jul 31 13:06:20 2012

@author: pietro

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

  `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

  `east`

    Set and obtain east value

  `items`()
  `keys`()
  `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

  `south`

    Set and obtain south value

  `top`

    Set and obtain top value

  `west`

    Set and obtain west value

class `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`()
  `ids`
  `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 `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
      []

  `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

  `layer`
  `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 `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

  `layer`

    Return the layer number

  `max`

    Return the maximum value

  `min`

    Return the minimum value

  `n_ranges`

    Return the ranges number

class `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

## pygrass.vector.find module

Created on Tue Mar 19 11:09:30 2013

@author: pietro

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

  Bases: `object`

  Find geometry feature around a point.

  `is_open`()

    Check if the vector map is open or not

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

  Bases: `pygrass.vector.find.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                   #doctest: +NORMALIZE_WHITESPACE
        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] #doctest: +NORMALIZE_WHITESPACE
        [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                   #doctest: +NORMALIZE_WHITESPACE
        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] #doctest: +NORMALIZE_WHITESPACE
        [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                   #doctest: +NORMALIZE_WHITESPACE
        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 `pygrass.vector.find.``PointFinder`(c_mapinfo, table=None, writeable=False)

  Bases: `pygrass.vector.find.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 `pygrass.vector.find.``PolygonFinder`(c_mapinfo, table=None, writeable=False)

  Bases: `pygrass.vector.find.AbstractFinder`

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

## pygrass.vector.geometry module

Created on Wed Jul 18 10:46:25 2012

@author: pietro

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

  Bases: `pygrass.vector.geometry.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

  `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

  `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 `pygrass.vector.geometry.``Attrs`(cat, table, writeable=False)

  Bases: `object`

  `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 `pygrass.vector.geometry.``Boundary`(**kargs)

  Bases: `pygrass.vector.geometry.Line`

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

  `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 `pygrass.vector.geometry.``Centroid`(area_id=None, **kargs)

  Bases: `pygrass.vector.geometry.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()

  `gtype` = 8

class `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

  `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 `pygrass.vector.geometry.``Isle`(**kargs)

  Bases: `pygrass.vector.geometry.Geo`

  An Isle is an area contained by another area.

  `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 `pygrass.vector.geometry.``Isles`(c_mapinfo, area_id=None)

  Bases: `object`

  `isles`()

    Return isles

  `isles_ids`()

    Return the id of isles

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

  Bases: `pygrass.vector.geometry.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)])

  `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                              #doctest: +ELLIPSIS
        Line([Point(-10.000000, 0.000000),...Point(-10.000000, 0.000000)])
        >>> centroid                     #doctest: +NORMALIZE_WHITESPACE
        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                     #doctest: +NORMALIZE_WHITESPACE
        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)           #doctest: +NORMALIZE_WHITESPACE
        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 ot 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, usig 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)         #doctest: +NORMALIZE_WHITESPACE
          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 `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 `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 `pygrass.vector.geometry.``Point`(x=0, y=0, z=None, **kargs)

  Bases: `pygrass.vector.geometry.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

  `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                              #doctest: +ELLIPSIS
        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.

  `x`

    Set and obtain x coordinate

  `y`

    Set and obtain y coordinate

  `z`

    Set and obtain z coordinate

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

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

`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))                          #doctest: +ELLIPSIS
      Traceback (most recent call last):
          ...
      ValueError: The the format of the point is not supported: (1, 1, 2, 2)

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

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

  Read the binary buffer and return a geometry object

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

`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.

`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.

## 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;'

## pygrass.vector.table module

Created on Wed Aug 8 15:29:21 2012

@author: pietro

class `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                              #doctest: +SKIP
      >>> cols_pg = Columns(test_vector_name,
      ...                   pg.connect('host=localhost dbname=grassdb')) #doctest: +SKIP
      >>> cols_pg.tname #doctest: +SKIP
      'table_doctest_map'                                   #doctest: +SKIP

  `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                         # doctest: +SKIP
        >>> cols_pg = Columns('boundary_municp_pg',
        ...                   pg.connect('host=localhost dbname=grassdb'))  #doctest: +SKIP
        >>> cols_pg.add('n_pizza', 'INT')                 # doctest: +SKIP
        >>> 'n_pizza' in cols_pg                          # doctest: +SKIP
        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')  # doctest: +ELLIPSIS
        Traceback (most recent call last):
          ...
        grass.exceptions.DBError: SQLite does not support to cast columns.
        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.cast('n_pizzas', 'float8')            # doctest: +SKIP
        >>> cols_pg['n_pizzas']                           # doctest: +SKIP
        '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')                 # doctest: +ELLIPSIS
        >>> 'name' in cols_sqlite
        False

        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.drop('name') # doctest: +SKIP
        >>> 'name' in cols_pg # doctest: +SKIP
        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 #doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) #doctest: +SKIP
        >>> cols_pg.is_pg() #doctest: +SKIP
        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()                       # doctest: +ELLIPSIS
        [('cat', 'INTEGER'), ('name', 'varchar(50)'), ('value', 'double precision')]
        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.items()                     # doctest: +ELLIPSIS +SKIP
        [('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()                      # doctest: +ELLIPSIS
        ['cat', 'name', 'value']
        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,       # doctest: +SKIP
        ...                   pg.connect('host=localhost dbname=grassdb'))
        >>> cols_pg.names()                     # doctest: +ELLIPSIS +SKIP
        ['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')  # doctest: +ELLIPSIS
        >>> 'n_pizza' in cols_sqlite
        False
        >>> 'n_pizzas' in cols_sqlite
        True

        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.rename('n_pizza', 'n_pizzas')         # doctest: +SKIP
        >>> 'n_pizza' in cols_pg                          # doctest: +SKIP
        False
        >>> 'n_pizzas' in cols_pg                         # doctest: +SKIP
        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()                   # doctest: +ELLIPSIS
        'cat INTEGER, name varchar(50), value double precision'
        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.sql_descr()                 # doctest: +ELLIPSIS +SKIP
        '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()                       # doctest: +ELLIPSIS
        ['INTEGER', 'varchar(50)', 'double precision']
        >>> import psycopg2 as pg                         # doctest: +SKIP
        >>> cols_pg = Columns(test_vector_name,
        ...                   pg.connect('host=localhost dbname=grassdb')) # doctest: +SKIP
        >>> cols_pg.types()                     # doctest: +ELLIPSIS +SKIP
        ['INTEGER', 'varchar(50)', 'double precision']

  `update_odict`()

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

class `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')                     # doctest: +SKIP
        >>> dblinks  # need to open vector map in write mode
        DBlinks([Link(1, table_doctest_map, sqlite)])

class `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 `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'                                # doctest: +SKIP
      >>> link.driver                                       # doctest: +SKIP
      'pg'
      >>> link.driver = 'postgres'                # doctest: +ELLIPSIS +SKIP
      Traceback (most recent call last):
        ...
      TypeError: Driver not supported, use: sqlite, pg.
      >>> link.driver                                       # doctest: +SKIP
      'pg'
      >>> link.number = 0                         # doctest: +ELLIPSIS +SKIP
      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)              # doctest: +ELLIPSIS
        <sqlite3.Cursor object at ...>
        >>> cur.fetchone()     #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
        (1, 'point', 1.0)
        >>> cur.close()
        >>> conn.close()

  `database`

    Set and obtain database value

  `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

  `key`

    Set and obtain cat value

  `layer`

    Set and obtain layer number

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

  `table_name`

    Set and obtain table name value

class `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                                   # doctest: +SKIP
      >>> tab_pg = Table(test_vector_name,
      ...                psycopg2.connect('host=localhost dbname=grassdb',
      ...                                 'pg'))            # doctest: +SKIP
      >>> tab_pg.columns                          # doctest: +ELLIPSIS +SKIP
      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()     #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
         (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

  `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

`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

## pygrass.vector.vector_type module

Created on Wed Jul 18 10:49:26 2012

@author: pietro

## Module contents

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

  Bases: `grass.pygrass.vector.abstract.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 = [(u'cat',       'INTEGER PRIMARY KEY'),
        ...         (u'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 `pygrass.vector.``VectorTopo`(name, mapset='', *args, **kwargs)

  Bases: `pygrass.vector.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)                     #doctest: +ELLIPSIS
        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)                             #doctest: +ELLIPSIS
        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 = [(u'cat',       'INTEGER PRIMARY KEY'),
        ...         (u'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()

Help Index | Topics Index | Keywords Index | Full Index

© 2003-2022 GRASS Development Team, GRASS GIS 8.3.dev Reference Manual