pygrass doc: extended (contribution Jarrett Keifer)

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@61941 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/docs/src/pygrass_raster.rst

@@ -6,16 +6,15 @@ Introduction to Raster classes
 Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Raster Library <http://grass.osgeo.org/programming7/rasterlib.html>`_
 
 PyGRASS uses 4 different Raster classes, that respect the 4 different approaches
-of GRASS-C API.
-The read access is row wise for :ref:`RasterRow-label` and
-:ref:`RasterRowIO-label` and additionally
+of GRASS-C API. The classes use a standardized interface to keep methods
+consistent between them. The read access is row wise for :ref:`RasterRow-label`
+and :ref:`RasterRowIO-label` and additionally
 cached in the RowIO class. Both classes write sequentially.
 RowIO is row cached, :ref:`RasterSegment-label` and :ref:`RasterNumpy-label`
-are tile cached for reading and writing therefore a randomly access is possible.
-Hence RasterRow and RasterRowIO should be used in case for fast (cached)
+are tile cached for reading and writing; therefore, random access is possible.
+Hence RasterRow and RasterRowIO should be used for fast (cached)
 row read access and RasterRow for fast sequential writing.
-Segment and Numpy should be used for random access, but Numpy only for files
-not larger than 2GB.
+RasterSegment and RasterNumpy should be used for random access.
 
 
 ==========================  =======================  ========  ============
@@ -28,11 +27,11 @@ Class Name                  C library                Read      Write
 ==========================  =======================  ========  ============
 
 
-All these classes share common methods and attributes, necessary to address
+These classes share common methods and attributes to address
 common tasks as rename, remove, open, close, exist, is_open.
-In the next examples we instantiate a RasterRow object. ::
+In the following example we instantiate a RasterRow object. ::
 
-    >>> from pygrass import raster
+    >>> from grass.pygrass import raster
     >>> elev = raster.RasterRow('elevation')
     >>> elev.name
     'elevation'
@@ -62,16 +61,16 @@ We can rename the map: ::
 
 .. _RasterRow-label:
 
-RastRow
--------
+RasterRow
+---------
 
-PyGrass allow user to open the maps, in read and write mode,
-row by row using the `Raster library`_, there is not support to read and write
-to the same map at the same time, for this functionality, please see the
-:ref:`RasterSegment-label` and :ref:`RasterNumpy-label` classes.
-The RasterRow class allow to read in a randomly order the row from a map, but
-it is only possible to write the map using only a sequence order, therefore every
-time you are writing a new map, the row is add to the file as the last row. ::
+The PyGrass :class:`~pygrass.raster.RasterRow` class allow user to open maps row
+by row in either read or write mode using the `Raster library`_. Reading and writing
+to the same map at the same time is not supported. For this functionality,
+please see the :ref:`RasterSegment-label` and :ref:`RasterNumpy-label` classes.
+The RasterRow class allows map rows to be read in any order, but map rows can
+only be written in sequential order. Therefore, each now row written to a map is
+added to the file as the last row. ::
 
     >>> raster = reload(raster)
     >>> elev = raster.RasterRow('elevation')
@@ -122,11 +121,11 @@ time you are writing a new map, the row is add to the file as the last row. ::
 RasterRowIO
 -----------
 
-The RasterRowIO class use the grass `RowIO library`_, and implement a row
-cache. The RasterRowIO class support only reading the raster, because the
-raster rows can only be written in sequential order, writing by row id is not
-supported by design. Hence, we should use the rowio lib only for caching rows
-for reading and use the default row write access as in the RasterRow class. ::
+The :class:`~pygrass.raster.RasterRowIO` class uses the GRASS `RowIO library`_, and implements a row
+cache. The RasterRowIO class only supports reading rasters; because raster rows
+can only be written in sequential order, writing by row id is not
+supported by design. Hence, the rowio lib can only be used to cache rows
+for reading, and any write access should use the :ref:`RasterRow-label` class. ::
 
     >>> raster = reload(raster)
     >>> elev = raster.RasterRowIO('elevation')
@@ -142,13 +141,14 @@ for reading and use the default row write access as in the RasterRow class. ::
 
 .. _RasterSegment-label:
 
-RastSegment
------------
+RasterSegment
+-------------
 
-The RasterSegment class use the grass `Segmentation library`_, it work dividing
-the raster map into small different files, that grass read load into the memory
-and write to the hardisk.
-The segment library allow to open a map in a read-write mode. ::
+The :class:`~pygrass.raster.RasterSegment` class uses the GRASS `Segmentation library`_. The class divides
+a raster map into small tiles stored on disk. Initialization of this class is
+therefore intensive. However, this class has lower memory requirements, as GRASS
+loads only currently-accessed tiles into memory. The segment library allow
+opening maps in a read-write mode. ::
 
     >>> raster = reload(raster)
     >>> elev = raster.RasterSegment('elevation')
@@ -171,33 +171,35 @@ The segment library allow to open a map in a read-write mode. ::
     [0 0 0]
     [0 0 0]
 
-The RasterSegment class define two methods to read and write the map:
+Due to the unique behavior of this class, the RasterSegment class defines two
+methods to read a map:
 
-    * ``get_row`` that return the buffer object with the row that call the
-      C function ``segment_get_row``. ::
+    * ``get_row`` calls the C function ``segment_get_row`` and returns a buffer
+      object with the row. ::
 
         >>> # call explicity the method
         >>> elev_row0 = elev.get_row(0)
         >>> # call implicity the method
         >>> elev_row0 = elev[0]
 
-    * ``get`` that return the value of the call map that call the
-      C function ``segment_get``. ::
+    * ``get`` calls the C function ``segment_get`` and returns the value of the
+      map cell. ::
 
         >>> # call explicity the method
         >>> elev_val_0_0 = elev.get(0, 0)
         >>> # call implicity the method
         >>> elev_val_0_0 = elev[0, 0]
 
-Similarly to write the map, with ``put_row``, to write a row and with ``put``
-to write a single value to the map. ::
+Similarly, writing to a map uses two methods: ``put_row`` to write a row and
+``put`` to write a single value to the map. ::
 
     >>> # compare the cell value get using the ``get`` method, and take the first
     >>> # value of the row with the ``get_row`` method
+    >>> # the methods are used internally by the index operators
     >>> elev[0, 0] == elev[0][0]
     True
     >>> # write a new value to a cell,
-    >>> new[0, 0] = 10
+    >>> new[0, 0] = 10  # ``put`` is used internally by the index operators
     >>> new[0, 0]
     10
     >>> new.close()
@@ -213,9 +215,12 @@ to write a single value to the map. ::
 RasterNumpy
 -----------
 
-The RasterNumpy class, is based on the `numpy.memmap`_ class If you open an
-existing map, the map will be copied on a binary format, and read to avoid
-to load all the map in memory. ::
+The :class:`~pygrass.raster.RasterNumpy` class, is based on the `numpy.memmap`_ class
+(refer to the linked documentation for details). If an existing map is opened,
+small sections will be loaded into memory as accessed, but GRASS does not need to
+load the whole file into memory. Memmap is a subclass of the `numpy.ndarray`
+class, so RasterNumpy will behave like a numpy array and can be used with numpy
+array operations. ::
 
     >>> raster = reload(raster)
     >>> elev = raster.RasterNumpy('elevation', 'PERMANENT')
@@ -251,4 +256,3 @@ to load all the map in memory. ::
 .. _RowIO library: http://grass.osgeo.org/programming7/rowiolib.html
 .. _Segmentation library: http://grass.osgeo.org/programming7/segmentlib.html
 .. _numpy.memmap: http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html
-

lib/python/docs/src/pygrass_vector.rst

@@ -3,13 +3,50 @@
 Introduction to Vector classes
 ==============================
 
-Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
+Details about the GRASS vector architecture can be found in the
+`GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
 
+PyGrass has two classes for vector maps: :ref:`Vector-label` and :ref:`VectorTopo-label`.
+As the names suggest, the Vector class is for vector maps, while VectorTopo
+opens vector maps with GRASS topologies. VectorTopo is an extension
+of the Vector class, so supports all the Vector class methods, with additions.
 
-Instantiation and basic interaction. ::
+.. _Vector-label:
 
-    >>> from pygrass.vector import VectTopo
-    >>> municip = VectTopo('boundary_municp_sqlite')
+Vector
+------
+
+The :class:`~pygrass.vector.Vector` class is part of the :mod:`~pygrass.vector`
+module. It is based on the :class:`~pygrass.vector.abstract.Info` class, which
+provides methods for accessing basic information about the vector map: ::
+
+    >>> from grass.pygrass.vector import Vector
+    >>> cens = Vector('census')
+    >>> cens.is_open()
+    False
+    >>> cens.mapset
+    ''
+    >>> cens.exist()
+    True
+    >>> cens.mapset
+    'PERMANENT'
+    >>> cens.overwrite
+    False
+
+.. _VectorTopo-label:
+
+VectorTopo
+----------
+
+The :class:`~pygrass.vector.VectorTopo` class allows vector maps to be loaded
+along with an accompanying topology. The VectorTopo class interface has all the
+same methods as the basic Vector class, but includes many more methods dependent
+on the topology rules. Consult each class's documentation for a list of the
+methods to compare what each class can do. Using the VectorTopo class is just
+like the Vector class: ::
+
+    >>> from grass.pygrass.vector import VectorTopo
+    >>> municip = VectorTopo('boundary_municp_sqlite')
     >>> municip.is_open()
     False
     >>> municip.mapset
@@ -20,12 +57,106 @@ Instantiation and basic interaction. ::
     'user1'
 
 
+Working with Vector Objects
+---------------------------
+
+As the VectorTopo class is so similar to the Vector class, the following examples
+exclusively demonstrate the VectorTopo class.
+
+To begin using a vector map, it must first be opened: ::
+
+    >>> from grass.pygrass.vector import VectorTopo
+    >>> municip = VectorTopo('boundary_municp_sqlite')
+    >>> municip.open(mode='r')
+
+The ``open()`` method supports a number of option arguments (see the :class:`~pygrass.vector.abstract.Info`
+documentation for a complete list). In particular, the mode argument can take a
+a value of ``r`` for reading, ``w`` for writing, or ``rw`` for reading/writing.
+
+The geometry of a vector map can be read sequentially using the ``next()`` method.
+To return to the beginning, use the ``rewind()`` method.
+
+    >>> municip.next()
+    Boundary(v_id=1)
+    >>> municip.next()
+    Boundary(v_id=2)
+    >>> municip.next()
+    Boundary(v_id=3)
+    >>> municip.rewind()
+    >>> municip.next()
+    Boundary(v_id=1)
+
+If a vector map is opened with the mode ``w`` or ``rw``, then the user can write
+new features to the dataset:
+
+Open a new vector map:
+
+    >>> new = VectorTopo('newvect')
+    >>> new.exist()
+    False
+
+Define the new columns in 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 the geometry feature class and add two points:
 
-Open the map with topology: ::
+    >>> from grass.pygrass.vector.geometry import Point
+    >>> point0 = Point(636981.336043, 256517.602235)
+    >>> point1 = Point(637209.083058, 257970.129540)
 
-    >>> municip.open()
+Write the two points to the map:
+
+    >>> new.write(point0, ('pub', ))
+    >>> new.write(point1, ('resturnat', ))
+
+Commit the db changes:
+
+    >>> new.table.conn.commit()
+    >>> new.table.execute().fetchall()
+    [(1, u'pub'), (2, u'resturnat')]
+
+Close the vector map:
+
+    >>> new.close()
+    >>> new.exist()
+    True
+
+Now we can play with the map:
+
+    >>> new.open(mode='r')
+    >>> new.read(1)
+    Point(636981.336043, 256517.602235)
+    >>> new.read(2)
+    Point(637209.083058, 257970.129540)
+    >>> new.read(1).attrs['name']
+    u'pub'
+    >>> new.read(2).attrs['name']
+    u'resturnat'
+    >>> new.close()
+    >>> new.remove()
+
+Note the ``close()`` and ``remove()`` methods above. The ``close()`` method
+ensure that the files are properly released by the operating system, and will
+also build the topology (if called by the VectorTopo class). Take caution with
+the ``remove()`` method; it is used here because this example map was temporary.
+Calling this method will completely delete the map and its data from the file
+system.
+
+
+More Features of the VectorTopo Class
+-------------------------------------
+
+See the class documentation for a full list of methods, but here are some
+examples using VectorTopo methods:
+
+Get the number of primitives:
 
-    get the number of primitive:
     >>> municip.num_primitive_of('line')
     0
     >>> municip.num_primitive_of('centroid')
@@ -35,7 +166,7 @@ Open the map with topology: ::
 
 
 
-ask for other feature in the vector map: ::
+Get the number of different feature types in the vector map: ::
 
     >>> municip.number_of("areas")
     3579
@@ -52,21 +183,105 @@ ask for other feature in the vector map: ::
         ...
     ValueError: vtype not supported, use one of: 'areas', ..., 'volumes'
 
+Note that the method with raise a  ``ValueError`` if a non-supported vtype is
+specified.
+
+Accessing Attribute Tables
+--------------------------
+
+The GRASS philosophy stipulates that vector map features are independent from
+their attributes, and that a vector map's attribute table(s) should not be
+loaded unless explicitly specified, in case they are not needed.
+
+Accessing a vector map's table(s) requires finding any links to tables, then
+requesting the table from each of the returned links:
+
+    from grass.pygrass.vector import VectorTopo
+    >>> municip = VectorTopo('census')
+    >>> municip.open(mode='r')
+    >>> dblinks = DBlinks(municip.c_mapinfo)
+    >>> dblinks
+    DBlinks([Link(1, census, sqlite)])
+    >>> link = DBlinks[0]
+    Link(1, census, sqlite)
+    >>> table = link.table()
+
+Here, ``DBlinks()`` is a class (:class:`~pygrass.vector.table.DBlinks`) that
+contains all the links of a vector map. Each link is also a class
+(:class:`~pygrass.vector.table.Link`) that contains a specific link's
+parameters. The ``table()`` method of the link class return the linked table as
+a table object (`class:`~pygrass.vector.table.Table`).
+
+Geometry Classes
+----------------
+
+The vector package also includes a number of geometry classes, including Area,
+Boundary, Centroid, Isle, Line, and Point classes. Please consult the
+:mod:`~pygrass.vector.geometry` module for a complete list of methods for these
+classes, as there are many. Some basic examples are given below.
+
+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(0.000000 0.000000 0.000000)
+
+Create a Boundary and calculate its area: ::
 
-Suppose that we want to select all and only the areas that have an
-area bigger than 10000m2: ::
+    >>> bound = Boundary(points=[(0, 0), (0, 2), (2, 2), (2, 0),
+    ...                          (0, 0)])
+    >>> bound.area()
+    4.0
 
-    >>> big = [area for area in municip.viter('areas')
-    ...        if area.alive() and area.area >= 10000]
+Construct a Line feature and find its bounding box: ::
 
-it's pretty easy, isn't it?!? :-)
+    >>> 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)])
+    >>>bbox = line.bbox()
+    >>> bbox
+    Bbox(1.0, -1.0, 2.0, 0.0)
 
-the method "viter" return an iterator object of the vector features,
-in this way no memory is wasted... User can choose on which
-vector features want to iterate...
+Buffer a Line feature and find the buffer centroid:
+
+    >>> line = Line([(0, 0), (0, 2)])
+    >>> area = line.buffer(10)
+    >>> area.boundary
+    Line([Point(-10.000000, 0.000000),...Point(-10.000000, 0.000000)])
+    >>> area.centroid
+    Point(0.000000, 0.000000)
+
+More Examples
+-------------
+
+Find all areas larger than 10000m2: ::
+
+    >>> big = [area for area in municip.viter('areas')
+    ...        if area.alive() and area.area >= 10000]
 
+The PyGrass vector methods make complex operations rather easy. Notice the
+``viter()`` method: this returns an iterator object of the vector features, so
+the user can choose on which vector features to iterate without loading all the
+features into memory.
 
-then you can go on with python stuff like, sort by area dimension: ::
+We can then sort the areas by size: ::
 
     >>> from operator import methodcaller as method
     >>> big.sort(key = method('area'), reverse = True)  # sort the list
@@ -77,7 +292,7 @@ then you can go on with python stuff like, sort by area dimension: ::
     Area(2552) 298356117.948
 
 
-or sort for the number of isles that are contained inside: ::
+Or sort for the number of isles that are contained inside: ::
 
     >>> big.sort(key = lambda x: x.isles.__len__(), reverse = True)
     >>> for area in big[:3]:
@@ -88,7 +303,7 @@ or sort for the number of isles that are contained inside: ::
     Area(872) 42
 
 
-or you may have only the list of the areas that contain isles inside, with: ::
+Or can list only the areas containing isles: ::
 
     >>> area_with_isles = [area for area in big if area.isles]
     >>> area_with_isles                                   # doctest: +ELLIPSIS