GEOS stands for Geometry Engine - Open Source, and is a C++ port of the Java Topology Suite, implementing the OpenGIS Simple Features for SQL spatial predicate functions and spatial operators. GEOS, now an OSGeo project, was initially developed and maintained by Refractions Research of Victoria, Canada.
Thus, the Python ctypes [2] package was used to wrap the GEOS C API to bring the rich capabilities of GEOS to Python and GeoDjango.
Features:
The Point object may be initialized with either a tuple, or individual parameters. For example:
>>> from django.contrib.gis.geos import Point
>>> p = Point((5, 23)) # 2D point, passed in as a tuple
>>> p = Point(5, 23, 8) # 3D point, passed in with individual parameters
LineString objects initialize on a given sequence. For example, the constructor may take lists, tuples, NumPy arrays of X,Y[,Z] pairs, or Point objects. If Point objects are used, ownership of the points is not transferred to the LineString object. Examples:
>>> from django.contrib.gis.geos import LineString, Point
>>> ls = LineString((1, 1), (2, 2))
>>> ls = LineString([(1, 1), (2, 2)])
>>> ls = LineString(Point(1, 1), Point(2, 2))
>>> from numpy import array
>>> ls = LineString(array([(1, 1), (2, 2)]))
LinearRing objects are subclasses of LineString; however, an error will be raised if the points used during initialization are not closed (the first point is equal to the last point):
>>> from django.contrib.gis.geos import LinearRing
>>> lr = LinearRing((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> lr = LinearRing((0, 0), (0, 1))
GEOS_ERROR: IllegalArgumentException: points must form a closed linestring
Polygons are composed of an exterior ring (the shell), and may also have interior rings that denote areas excluded from the exterior.
>>> from django.contrib.gis.geos import Point
>>> from django.contrib.gis.geos import MultiPoint
>>> p1 = Point((0,0))
>>> p2 = Point((1,2))
>>> mp = MultiPoint(p1, p2)
>>> mp
<MultiPoint object>
>>> mp[0].wkt
'POINT (0.0000000000000000 0.0000000000000000)'
>>> len(mp)
2
>>> [ p.wkt for p in mp ]
['POINT (0.0000000000000000 0.0000000000000000)', 'POINT (1.0000000000000000 2.0000000000000000)']
>>> mp.ring
False
GEOS geometry objects may be created from strings using the fromstr() factory, or using the constructor for each geometry object (as described above):
>>> from django.contrib.gis.geos import fromstr
>>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)
The srid keyword may be used to set the spatial reference system identifier number for the geometry. This will be used to conduct any needed transformations for spatial lookups and geographic model creation. It should be noted that fromstr is a shortcut to the constructor for the base GEOSGeometry object.
Returns the “extended” Well-Known Text of the geometry. This representation is specific to PostGIS and is a superset of the OGC WKT standard. [8] Essentially the SRID is prepended to the WKT representation, for example SRID=4326;POINT(5 23). Please note that this does not include the 3dm, 3dz, and 4d information that PostGIS supports in its EWKT representations.
Returns the HEXEWKB PostGIS canonical representation of the geometry. This representation is specific to PostGIS, and is not a standard.
Returns the GeoJSON representation of the geometry. Requires GDAL.
Returns a KML (Keyhole Markup Language) representation of the geometry. This should only be used for geometries with an SRID of 4326 (WGS84), but this restriction is not enforced.
Returns an OGRGeometry object from the data in the GEOSGeometry.
Returns the Well-Known Binary of the geometry (an OGC standard). The WKB data is returned Python buffer object.
Returns the Well-Known Text of the geometry (an OGC standard).
Returns whether or not the set of points in the geometry is empty.
Returns a boolean indicating whether the geometry is valid.
A Geometry is simple if and only if the only self-intersections are at boundary points. For example, a LineString object is not simple if it intersects itself. Thus, LinearRing and Polygon objects are always simple because they do not intersect themselves.
Returns a boolean indicating whether the geometry is a LinearRing.
Returns a boolean indicating whether the geometry is three-dimensional.
All of the following spatial predicate methods take another GEOS Geometry instance (other) as an argument.
Returns the boundary as a newly allocated Geometry object.
The centroid is equal to the centroid of the set of component Geometries of highest dimension (since the lower-dimension geometries contribute zero “weight” to the centroid).
Returns the smallest convex Polygon that contains all the points in the Geometry.
This property returns the extent of this geometry as a 4-tuple, consisting of (xmin, ymin, xmax, ymax).
This property returns the area of the Geometry.
Returns the distance between the closest points on this Geometry and the given geom (another GEOSGeometry object). GEOS distance calculations are linear – in other words, GEOS will not perform a spherical calculation even if the SRID is in a geographic coordinate system.
Returns the length of this Geometry (e.g., 0 for point or the circumfrence of a Polygon).
Returns an OGR SpatialReference object corresponding to the SRID of the geometry or None. Requires GDAL.
Transforms the geometry according to the given transformation object, which may be an integer SRID, spatial reference WKT string, a PROJ.4 string, or a SpatialReference object. By default, the geometry is transformed in-place and nothing is returned. However if the clone keyword is set, then the geometry is not modified and a transformed clone is returned instead. Requires GDAL.
Footnotes
| [1] | See Sean Gillies, Geometries for Python (blog post explaining rationale for abandoning GEOS support); see also Sean’s message on the geos-devel mailing list, Mar. 5, 2007 |
| [2] | See generally Python’s ctypes documentation, at Ch. 14.14. |
| [3] | Specifically, GEOSGeometry was introduced in revision 5008 on April 15th, 2007. |
| [4] | See Sean Gillies, Geometries for Python Update, April 16th 2007 (“The ctypes-based geometry module in r5008 looks kickass. I’m checking it out now.”). |
| [5] | Sean Gillies, Proposal to launch the Shapely Project, May 1, 2007. |
| [6] | Justin Bronn, RE: Proposal to launch the Shapely project, May 1, 2007. |
| [7] | Sean Gillies, Proposal to change Shapely license from LGPL to BSD, Nov. 20, 2007. |
| [8] | See PostGIS EWKB, EWKT and Canonical Forms, PostGIS documentation at Ch. 4.1.2. |