Geometry Handling

Points, linestrings, polygons that represent a spatial feature are commonly referred to as geometries. In QGIS they are represented with QgsGeometry class. All possible geometry types are nicely shown in JTS discussion page.

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.

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

There are several options how to create a geometry:

  • from coordinates:

    gPnt = QgsGeometry.fromPoint(QgsPoint(1,1))
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 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)")

  • from well-known binary (WKB):

    g = QgsGeometry()
g.setWkbAndOwnership(wkb, len(wkb))

Access to Geometry

First, you should find out geometry type, 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 type() method which returns a value from QGis.GeometryType enumeration. There is also a helper function 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 QgsPoint objects, the values are accessible with x() and y() methods.

For multipart geometries there are similar accessor functions: asMultiPoint(), asMultiPolyline(), asMultiPolygon().

Geometry Predicates and Operations

QGIS uses GEOS library for advanced geometry operations such as geometry predicates (contains(), intersects(), ...) and set operations (union(), difference(), ...)

TODO:

  • area(), length(), distance()
  • transform()
  • available predicates and set operations