[QGIS Commit] r15134 - docs/trunk/english_us/developer_cookbook/source

[svn_qgis at osgeo.org]

Author: wonder
Date: 2011-02-07 14:52:30 -0800 (Mon, 07 Feb 2011)
New Revision: 15134

Modified:
   docs/trunk/english_us/developer_cookbook/source/canvas.rst
   docs/trunk/english_us/developer_cookbook/source/geometry.rst
Log:
Slightly improved geometry section


Modified: docs/trunk/english_us/developer_cookbook/source/canvas.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/canvas.rst	2011-02-07 21:51:36 UTC (rev 15133)
+++ docs/trunk/english_us/developer_cookbook/source/canvas.rst	2011-02-07 22:52:30 UTC (rev 15134)
@@ -5,7 +5,7 @@
 ================
 
 The Map canvas widget is probably the most important widget within QGIS because it
-shows the map composed from overlaid map layers and allows interaction the map and layers.
+shows the map composed from overlaid map layers and allows interaction with the map and layers.
 The canvas shows always a part of the map defined by the current canvas extent.
 The interaction is done through the use of **map tools**: there are tools for
 panning, zooming, identifying layers, measuring, vector editing and others.
@@ -14,12 +14,12 @@
 
 
 Map canvas is implemented as :class:`QgsMapCanvas` class in :mod:`qgis.gui`
-module.  The implementation is based on the `Qt Graphics View framework
-<http://doc.qt.nokia.com/graphicsview.html>`_ This framework generally provides
+module.  The implementation is based on the Qt Graphics View framework.
+This framework generally provides
 a surface and a view where custom graphics items are placed and user can
 interact with them.  We will assume that you are familiar enough with Qt to 
 understand the concepts of the graphics scene, view and items.  If not,
-please read the overview of the framework.
+please make sure to read the `overview of the framework <http://doc.qt.nokia.com/graphicsview.html>`_.
 
 Whenever the map has been panned, zoomed in/out (or some other action
 triggers a refresh), the map is rendered again within the current extent.
@@ -95,7 +95,7 @@
 map tools for map panning and zooming.  Actions are created for activation of
 each tool: panning is done with :class:`QgsMapToolPan`, zooming in/out with a
 pair of :class:`QgsMapToolZoom` instances. The actions are set as checkable and
-later assigned to the tools to allows automatic handling of checked/unchecked
+later assigned to the tools to allow automatic handling of checked/unchecked
 state of the actions -- when a map tool gets activated, its action is marked as
 selected and the action of the previous map tool is deselected. The map tools
 are activated using :func:`setMapTool` method.

Modified: docs/trunk/english_us/developer_cookbook/source/geometry.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/geometry.rst	2011-02-07 21:51:36 UTC (rev 15133)
+++ docs/trunk/english_us/developer_cookbook/source/geometry.rst	2011-02-07 22:52:30 UTC (rev 15134)
@@ -4,22 +4,21 @@
 Geometry Handling
 =================
 
-Points, linestrings, polygons (and more complex shapes) are commonly referred to as geometries. They are represented using :class:`QgsGeometry` class.
+Points, linestrings, polygons that represent a spatial feature are commonly referred to as geometries.
+In QGIS they are represented with :class:`QgsGeometry` class.
+All possible geometry types are nicely shown in `JTS discussion page <http://www.vividsolutions.com/jts/discussion.htm#spatialDataModel>`_.
 
-To extract information from geometry there are accessor functions for every vector type. How do accessors work:
+Sometimes one geometry is actually a collection of simple (single-part) geometries. Such a geometry is called
+multi-part geometry. If it contains just one type of simple geometry, we call it multi-point, multi-linestring or multi-polygon.
+For example, a country consisting of multiple islands can be represented as a multi-polygon.
 
-:func:`asPoint`
-  returns :class:`QgsPoint`
-:func:`asPolyline`
-  returns a list of :class:`QgsPoint` items
-:func:`asPolygon` 
-  returns a list of rings, every ring consists of a list of :class:`QgsPoint` items. First ring is outer, subsequent rings are holes.
+The coordinates of geometries can be in any coordinate reference system (CRS). When fetching features from a layer, associated geometries
+will have coordinates in CRS of the layer.
 
 
+Geometry Construction
+---------------------
 
-You can use :func:`QgsGeometry.isMultipart` to find out whether the feature is multipart. For multipart features there are similar accessor functions:
-:func:`asMultiPoint`, :func:`asMultiPolyline`, :func:`asMultiPolygon()`.
-
 There are several options how to create a geometry:
 
 * from coordinates::
@@ -28,6 +27,13 @@
     gLine = QgsGeometry.fromPolyline( [ QgsPoint(1,1), QgsPoint(2,2) ] )
     gPolygon = QgsGeometry.fromPolygon( [ [ QgsPoint(1,1), QgsPoint(2,2), QgsPoint(2,1) ] ] )
 
+  Coordinates are given using :class:`QgsPoint` class.
+
+  Polyline (Linestring) is represented by a list of points. Polygon is represented by a list of linear rings (i.e. closed linestrings).
+  First ring is outer ring (boundary), optional subsequent rings are holes in the polygon.
+
+  Multi-part geometries go one level further: multi-point is a list of points, multi-linestring is a list of linestrings and multi-polygon is a list of polygons.
+
 * from well-known text (WKT)::
 
     gem = QgsGeometry.fromWkt("POINT (3 4)")
@@ -37,3 +43,48 @@
     g = QgsGeometry()
     g.setWkbAndOwnership(wkb, len(wkb))
 
+
+Access to Geometry
+------------------
+
+First, you should find out geometry type, :func:`wkbType` method is the one to use --- it returns a value from QGis.WkbType enumeration::
+
+  >>> gPnt.wkbType() == QGis.WKBPoint
+  True
+  >>> gLine.wkbType() == QGis.WKBLineString
+  True
+  >>> gPolygon.wkbType() == QGis.WKBPolygon
+  True
+  >>> gPolygon.wkbType() == QGis.WKBMultiPolygon
+  False
+
+As an alternative, one can use :func:`type` method which returns a value from QGis.GeometryType enumeration.
+There is also a helper function :func:`isMultipart` to find out whether a geometry is multipart or not.
+
+To extract information from geometry there are accessor functions for every vector type. How to use accessors::
+
+  >>> gPnt.asPoint()
+  (1,1)
+  >>> gLine.asPolyline()
+  [(1,1), (2,2)]
+  >>> gPolygon.asPolygon()
+  [[(1,1), (2,2), (2,1), (1,1)]]
+
+Note: the tuples (x,y) are not real tuples, they are :class:`QgsPoint` objects,
+the values are accessible with :func:`x` and :func:`y` methods.
+
+For multipart geometries there are similar accessor functions: :func:`asMultiPoint`, :func:`asMultiPolyline`, :func:`asMultiPolygon()`.
+
+
+Geometry Predicates and Operations
+----------------------------------
+
+QGIS uses GEOS library for advanced geometry operations such as geometry predicates (:func:`contains`, :func:`intersects`, ...)
+and set operations (:func:`union`, :func:`difference`, ...)
+
+
+**TODO:**
+
+* :func:`area`, :func:`length`, :func:`distance`
+* :func:`transform`
+* available predicates and set operations