GEOS API¶

Background¶

What is GEOS?¶

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.

Why the new API?¶

The GEOS SWIG wrapper is no longer maintained, and requires the installation of SWIG. [1]
The PCL implementation is over 2K+ lines of C and would make PCL a requisite package for the GeoDjango application stack.
Cross-platform compatibility.

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:

A BSD-licensed interface to the GEOS geometry routines, implemented purely in Python using ctypes.
Loosely-coupled to GeoDjango. For example, GEOS geometry objects may be used outside a django project/application (no need to have DJANGO_SETTINGS_MODULE set, etc.)
Mutability. GEOS Geometry objects may be modified.
Cross-platform and tested. GeoDjango GEOS geometries are well-tested and compatible with Windows, Linux, Solaris, and Mac OS X platforms.

Geometry Objects¶

`Point`¶

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) # Same, passed in with individual parameters

The srid keyword may be used to specify the SRID for the point:

>>> pnt = Point(5, 23, srid=4326)

Additionally, 3D geometries may be created by specifing a Z value:

>>> pnt_3d = Point(5, 23, 17) # Also: Point( (5, 23, 17) )
>>> pnt_3d.hasz
True
>>> pnt_3d.z
17

Properties¶

`x`¶

This property sets or retrieves the X coordinate for the point.

`y`¶

This property sets or retrieves the Y coordinate for the point.

`z`¶

This property sets or retrieves the Z (3D) coordinate for the point. If the point has no Z coordinate, None is returned.

`LineString` and `LinearRing`¶

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

Methods¶

`LineString(coords)`¶

`x`¶

This property returns the X values in a list, or a NumPy array (if installed).

`y`¶

This property returns the Y values in a list, or a NumPy array (if installed).

`z`¶

This property returns the Z values in a list, or a NumPy array (if installed).

`Polygon`¶

Polygons are composed of an exterior ring (the shell), and may also have interior rings that denote areas excluded from the exterior.

Methods¶

`Polygon(rings)`¶

The Polygon initializes on arguments that are either LinearRing instances or may be accepted by the LinearRing constructor.

`from_bbox(bbox)`¶

New in version 1.1.

Returns a new Polygon object for the given bounding box. The bounding box should be a four-tuple comprising the X and Y minimum values followed by the X and Y maximum values. For example:

>>> from django.contrib.gis.geos import Polygon
>>> bbox = (0, 0, 5, 5)
>>> poly = Polygon.from_bbox(bbox)
>>> print poly
POLYGON ((0.0000000000000000 0.0000000000000000, 0.0000000000000000 5.0000000000000000, 5.0000000000000000 5.0000000000000000, 5.0000000000000000 0.0000000000000000, 0.0000000000000000 0.0000000000000000))

`shell`, `exterior_ring`¶

Returns a LinearRing corresponding to the exterior ring, or shell, of the Polygon.

`num_interior_rings`¶

Returns the number of interior rings contained in the Polygon.

Geometry Collections¶

`MultiPoint`¶

>>> 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

`MultiLineString`¶

`MultiPolygon`¶

Methods¶

`cascaded_union`¶

New in version 1.1.

Note

Use of this method requires at least GEOS 3.1.

`GeometryCollection`¶

Prepared Geometries¶

In order to obtain a prepared geometry, just access the prepared property on any GEOSGeometry object. Once you have a PreparedGeometry instance its spatial predicate methods, listed below, may be used with other GEOSGeometry objects. An operation with a prepared geometry can be orders of magnitude faster – the more complex the geometry that is prepared, the larger the speedup in the operation.

Note

GEOS 3.1 is required in order to use prepared geometries.

For example:

>>> from django.contrib.gis.geos import Point, Polygon
>>> poly = Polygon.from_bbox((0, 0, 5, 5))
>>> prep_poly = poly.prepared
>>> prep_poly.contains(Point(2.5, 2.5))
True

`PreparedGeometry`¶

All methods on PreparedGeometry take an other argument, which must be a GEOSGeometry object.

`contains(other)`¶

`contains_properly(other)`¶

`covers(other)`¶

`intersects(other)`¶

I/O Objects¶

Inside GEOS, I/O classes are used to output geometries to WKT, WKB, and EWKB. GeoDjango allows access to these I/O classes if finer-grained control of serialization is required. Typically,

Reader Objects¶

The reader I/O classes simply return a GEOSGeometry instance from the WKB and/or WKT input given to their read(geom) method.

`WKBReader`¶

Example:

>>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader()
>>> wkb_r.read('0101000000000000000000F03F000000000000F03F')
<Point object at 0x103a88910>

`WKTReader`¶

Example:

>>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader()
>>> wkt_r.read('POINT(1 1)')
<Point object at 0x103a88b50>

Writer Objects¶

All writer objects have a write(geom) method that returns either the WKB or WKT of the given geometry. In addition, WKBWriter objects also have properties that may be used to change the byte order, and or include the SRID and 3D values (in other words, EWKB).

`WKBWriter`¶

The WKBWriter provides the most control over its output. By default it returns OGC-compliant WKB when it’s write method is called. However, it has properties that

`write(geom)`¶

Returns the WKB of the given geometry as a Python buffer object. Example:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>

`write_hex(geom)`¶

Returns WKB of the geometry in hexadecimal. Example:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'

`byteorder`¶

This property may be be set to change the byte-order of the geometry representation.

Byteorder Value	Description
0	Big Endian (e.g., compatible with RISC systems)
1	Little Endian (e.g., compatible with x86 systems)

Example:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1)
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.byteorder = 0
'00000000013FF00000000000003FF0000000000000'

`outdim`¶

This property may be set to change the output dimension of the geometry representation. In other words, if you have a 3D geometry then set to 3 so that the Z value is included in the WKB.

Outdim Value	Description
2	The default, output 2D WKB.
3	Output 3D EWKB.

Example:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> wkb_w.outdim
2
>>> pnt = Point(1, 1, 1)
>>> wkb_w.write_hex(pnt) # By default, no Z value included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.outdim = 3 # Tell writer to include Z values
>>> wkb_w.write_hex(pnt)
'0101000080000000000000F03F000000000000F03F000000000000F03F'

`srid`¶

Set this property with a boolean to indicate whether the SRID of the geometry should be included with the WKB representation. Example:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1, srid=4326)
>>> wkb_w.write_hex(pnt) # By default, no SRID included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.srid = True # Tell writer to include SRID
>>> wkb_w.write_hex(pnt)
'0101000020E6100000000000000000F03F000000000000F03F'

`WKTWriter`¶

`write(geom)`¶

Returns the WKT of the given geometry. Example:

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'

API¶

Creation¶

`GEOSGeometry(geo_input, srid=None)`¶

Geometries may be created using the GEOSGeometry constructor; geo_input may be any of the following types of data:

Input Type	Python Type	Example
WKT	`str` / `unicode`	`'POINT(5 23)'`
EWKT	`str` / `unicode`	`'SRID=4326;POINT(5 23)'`
HEX	`str` / `unicode`	`'010100000000000000000014400000000000003740'`
HEXEWKB	`str` / `unicode`	`''0101000020E610000000000000000014400000000000003740'`
GeoJSON	`str` / `unicode`	`'{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'`
WKB	`buffer`	`buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')`

While this may seem like an acronym soup, all are standardized geospatial data formats or extensions thereof.

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.

`fromfile(file_h)`¶

This factory creates a GEOS geometry from the given file name or an open file handle (1.1 only):

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile('/home/bob/geom.wkt')

`fromstr(string)`¶

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)

It should be noted that fromstr is a shortcut to the constructor for the base GEOSGeometry object.

Geometry Properties¶

`empty`¶

Returns whether or not the set of points in the geometry is empty.

`geom_type`¶

Returns a string corresponding to the type of geometry. For example:

>>> pnt = GEOSGeometry('POINT(5 23)')
>>> pnt.geom_type
'Point'

`geom_typeid`¶

Returns the GEOS geometry type identification number. The following table shows the value for each geometry type:

Geometry	ID
`Point`	0
`LineString`	1
`LinearRing`	2
`Polygon`	3
`MultiPoint`	4
`MultiLineString`	5
`MultiPolygon`	6
`GeometryCollection`	7

`hasz`¶

Returns a boolean indicating whether the geometry is three-dimensional.

`num_coords`, `num_points`¶

Returns the total number of coordinates in this geometry. For polygons and collections, this is the cumulative number of all coordinates from the component geometries.

`ring`¶

Returns a boolean indicating whether the geometry is a LinearRing.

`simple`¶

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.

`valid`¶

Returns a boolean indicating whether the geometry is valid.

Output Properties¶

`ewkt`¶

Returns the “extended” Well-Known Text of the geometry. This representation is specific to PostGIS and is a super set 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.

`hex`¶

Returns the WKB of this Geometry in hexadecimal form. Please note that the SRID and Z values are not included in this representation because it is not a part of the OGC specification (use the hexewkb property instead).

`hexewkb`¶

New in version 1.2.

Returns the EWKB of this Geometry in hexadecimal form. This is an extension of the WKB specification that includes SRID and Z values that are a part of this geometry.

Note

GEOS 3.1 is required if you want valid 3D HEXEWKB.

`json`, `geojson`¶

Returns the GeoJSON representation of the geometry. Requires GDAL.

`kml`¶

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.

`ogr`¶

Returns an OGR OGRGeometry object correspondg to the GEOS geometry. Consult the OGRGeometry documentation for more information.

Note

Requires GDAL.

`wkb`¶

Returns the WKB (Well-Known Binary) representation of this Geometry as a Python buffer. SRID and Z values are not included, use the ewkb property instead.

`ewkb`¶

New in version 1.2.

Return the EWKB representation of this Geometry as a Python buffer. This is an extension of the WKB specification that includes any SRID and Z values that are a part of this geometry.

Note

GEOS 3.1 is required if you want valid 3D EWKB.

`wkt`¶

Returns the Well-Known Text of the geometry (an OGC standard).

Spatial Predicate Methods¶

All of the following spatial predicate methods take another GEOS Geometry instance (other) as an argument.

`contains(other)`¶

Returns True if within(other) is False.

`crosses(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is T*T****** (for a point and a curve,a point and an area or a line and an area) 0******** (for two curves).

`disjoint(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is FF*FF****.

`equals(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is T*F**FFF*.

`equals_exact(other, tolerance=0)`¶

Returns true if the two Geometries are exactly equal, up to a specified tolerance. The tolerance value should be a floating point number representing the error tolerance in the comparison, e.g., poly1.equals_exact(poly2, 0.001) will compare equality to within one thousandth of a unit.

`intersects(other)`¶

Returns True if disjoint(other) is False.

`overlaps(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is T*T***T** (for two points or two surfaces) 1*T***T** (for two curves).

`relate_pattern(other, pattern)`¶

Returns true if the elements in the DE-9IM intersection matrix for this geometry and the other matches the given pattern – a string of nine characters from the alphabet: {T, F, *, 0}.

`touches(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is FT*******, F**T***** or F***T****.

`within(other)`¶

Returns true if the DE-9IM intersection matrix for the two Geometries is T*F**F***.

Topological Methods¶

`buffer(width, quadsegs=8)`¶

Returns a geometry that represents all points whose distance from this geometry is less than or equal to the given width. The optional quadsegs keyword sets the number of segments used to approximate a quarter circle (defaults is 8).

`difference(other)`¶

Returns a geometry representing the points making up this geometry that do not make up other.

`intersection(other)`¶

Returns a geometry representing the points shared by this geometry and other.

`relate(other)`¶

Returns the DE-9IM intersection matrix for this geometry and the other.

`simplify(tolerance=0.0, preserve_topology=False)`¶

Returns the geometry, simplified using the Douglas-Peucker algorithm to the specified tolerance (higher tolerance => less points). If no tolerance provided, defaults to 0.

By default, this function does not preserve topology - e.g. polygons can be split, collapse to lines or disappear holes can be created or disappear, and lines can cross. By specifying preserve_topology=True, the result will have the same dimension and number of components as the input. This is significantly slower.

`sym_difference(other)`¶

Returns a set combining the points in this geometry not in other, and the points in other not in this geometry.

`union(other)`¶

Returns a Geometry representing all the points in this Geometry and other.

Topological Properties¶

`boundary`¶

Returns the boundary as a newly allocated Geometry object.

`centroid`¶

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).

`convex_hull`¶

Returns the smallest convex Polygon that contains all the points in the Geometry.

`envelope`¶

Returns a Polygon that represents the bounding envelope of this geometry.

`point_on_surface`¶

Computes and returns a Point guaranteed to be on the interior of this geometry.

Other Properties & Methods¶

`extent`¶

This property returns the extent of this geometry as a 4-tuple, consisting of (xmin, ymin, xmax, ymax).

`area`¶

This property returns the area of the Geometry.

`distance(geom)`¶

Returns the distance between the closest points on this Geometry and the given geom (another GEOSGeometry object).

Note

GEOS distance calculations are linear – in other words, GEOS will not perform a spherical calculation even if the SRID specifies a geographic coordinate system.

`length`¶

Returns the length of this Geometry (e.g., 0 for point or the circumference of a Polygon).

`prepared`¶

New in version 1.1.

Note

Support for prepared geometries requires GEOS 3.1.

Returns a GEOS PreparedGeometry for the contents of this geometry. PreparedGeometry objects are optimized for the contains, intersects, and covers operations. Refer to the Prepared Geometries documentation for more information.

`srs`¶

Returns an OGR SpatialReference object corresponding to the SRID of the geometry or None. Consult the SpatialReference documentation for more information about these objects.

Note

Requires GDAL.

`transform(ct, clone=False)`¶

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.

Note

GDAL and PROJ.4 are required to perform coordinate system transformations.

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.

Navigation

GEOS API¶

Background¶

What is GEOS?¶

Why the new API?¶

Related Work¶

Geometry Objects¶

Point¶

Properties¶

x¶

y¶

z¶

LineString and LinearRing¶

Methods¶

LineString(coords)¶

x¶

y¶

z¶

Polygon¶

Methods¶

Polygon(rings)¶

from_bbox(bbox)¶

shell, exterior_ring¶

num_interior_rings¶

Geometry Collections¶

MultiPoint¶

MultiLineString¶

MultiPolygon¶

Methods¶

cascaded_union¶

GeometryCollection¶

Prepared Geometries¶

PreparedGeometry¶

contains(other)¶

contains_properly(other)¶

covers(other)¶

intersects(other)¶

I/O Objects¶

Reader Objects¶

WKBReader¶

WKTReader¶

Writer Objects¶

WKBWriter¶

write(geom)¶

write_hex(geom)¶

byteorder¶

outdim¶

srid¶

WKTWriter¶

write(geom)¶

API¶

Creation¶

GEOSGeometry(geo_input, srid=None)¶

fromfile(file_h)¶

fromstr(string)¶

Geometry Properties¶

empty¶

geom_type¶

geom_typeid¶

hasz¶

num_coords, num_points¶

ring¶

simple¶

valid¶

Output Properties¶

ewkt¶

hex¶

hexewkb¶

json, geojson¶

kml¶

ogr¶

wkb¶

ewkb¶

wkt¶

Spatial Predicate Methods¶

contains(other)¶

crosses(other)¶

disjoint(other)¶

equals(other)¶

equals_exact(other, tolerance=0)¶

`Point`¶

`x`¶

`y`¶

`z`¶

`LineString` and `LinearRing`¶

`LineString(coords)`¶

`x`¶

`y`¶

`z`¶

`Polygon`¶

`Polygon(rings)`¶

`from_bbox(bbox)`¶

`shell`, `exterior_ring`¶

`num_interior_rings`¶

`MultiPoint`¶

`MultiLineString`¶

`MultiPolygon`¶

`cascaded_union`¶

`GeometryCollection`¶

`PreparedGeometry`¶

`contains(other)`¶

`contains_properly(other)`¶

`covers(other)`¶

`intersects(other)`¶

`WKBReader`¶

`WKTReader`¶

`WKBWriter`¶

`write(geom)`¶

`write_hex(geom)`¶

`byteorder`¶

`outdim`¶

`srid`¶

`WKTWriter`¶

`write(geom)`¶

`GEOSGeometry(geo_input, srid=None)`¶

`fromfile(file_h)`¶

`fromstr(string)`¶

`empty`¶

`geom_type`¶

`geom_typeid`¶

`hasz`¶

`num_coords`, `num_points`¶

`ring`¶

`simple`¶

`valid`¶

`ewkt`¶

`hex`¶

`hexewkb`¶

`json`, `geojson`¶

`kml`¶

`ogr`¶

`wkb`¶

`ewkb`¶

`wkt`¶

`contains(other)`¶

`crosses(other)`¶

`disjoint(other)`¶

`equals(other)`¶

`equals_exact(other, tolerance=0)`¶

`intersects(other)`¶

`overlaps(other)`¶

`relate_pattern(other, pattern)`¶

`touches(other)`¶

`within(other)`¶

`buffer(width, quadsegs=8)`¶

`difference(other)`¶

`intersection(other)`¶

`relate(other)`¶

`simplify(tolerance=0.0, preserve_topology=False)`¶

`sym_difference(other)`¶

`union(other)`¶

`boundary`¶

`centroid`¶

`convex_hull`¶

`envelope`¶

`point_on_surface`¶

`extent`¶

`area`¶

`distance(geom)`¶

`length`¶