[GRASS-SVN] r61941 - grass/trunk/lib/python/docs/src
svn_grass at osgeo.org
svn_grass at osgeo.org
Sat Sep 13 19:15:47 PDT 2014
Author: lucadelu
Date: 2014-09-13 19:15:47 -0700 (Sat, 13 Sep 2014)
New Revision: 61941
Modified:
grass/trunk/lib/python/docs/src/pygrass_raster.rst
grass/trunk/lib/python/docs/src/pygrass_vector.rst
Log:
pygrass doc: extended (contribution Jarrett Keifer)
Modified: grass/trunk/lib/python/docs/src/pygrass_raster.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_raster.rst 2014-09-14 02:13:00 UTC (rev 61940)
+++ grass/trunk/lib/python/docs/src/pygrass_raster.rst 2014-09-14 02:15:47 UTC (rev 61941)
@@ -6,16 +6,15 @@
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 @@
========================== ======================= ======== ============
-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 @@
.. _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 @@
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 @@
.. _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 @@
[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 @@
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 @@
.. _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
-
Modified: grass/trunk/lib/python/docs/src/pygrass_vector.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_vector.rst 2014-09-14 02:13:00 UTC (rev 61940)
+++ grass/trunk/lib/python/docs/src/pygrass_vector.rst 2014-09-14 02:15:47 UTC (rev 61941)
@@ -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 @@
'user1'
+Working with Vector Objects
+---------------------------
-Open the map with topology: ::
+As the VectorTopo class is so similar to the Vector class, the following examples
+exclusively demonstrate the VectorTopo class.
- >>> municip.open()
+To begin using a vector map, it must first be opened: ::
- get the number of primitive:
+ >>> 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:
+
+ >>> from grass.pygrass.vector.geometry import Point
+ >>> point0 = Point(636981.336043, 256517.602235)
+ >>> point1 = Point(637209.083058, 257970.129540)
+
+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:
+
>>> municip.num_primitive_of('line')
0
>>> municip.num_primitive_of('centroid')
@@ -35,7 +166,7 @@
-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,22 +183,106 @@
...
ValueError: vtype not supported, use one of: 'areas', ..., 'volumes'
+Note that the method with raise a ``ValueError`` if a non-supported vtype is
+specified.
-Suppose that we want to select all and only the areas that have an
-area bigger than 10000m2: ::
+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: ::
+
+ >>> bound = Boundary(points=[(0, 0), (0, 2), (2, 2), (2, 0),
+ ... (0, 0)])
+ >>> bound.area()
+ 4.0
+
+Construct a Line feature and find its bounding box: ::
+
+ >>> 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)
+
+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]
-it's pretty easy, isn't it?!? :-)
+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.
-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...
+We can then sort the areas by size: ::
-
-then you can go on with python stuff like, sort by area dimension: ::
-
>>> from operator import methodcaller as method
>>> big.sort(key = method('area'), reverse = True) # sort the list
>>> for area in big[:3]:
@@ -77,7 +292,7 @@
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 @@
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
More information about the grass-commit
mailing list