GEOS APILink to this heading#

What is GEOS?Link to this heading#

GEOS stands for Geometry Engine - Open Source, and is a C++ library, ported from the Java Topology Suite. GEOS implements 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.

FeaturesLink to this heading#

GeoDjango implements a high-level Python wrapper for the GEOS library, its features include:

• A BSD-licensed interface to the GEOS geometry routines, implemented purely in Python using ctypes.

• Loosely-coupled to GeoDjango. For example, GEOSGeometry objects may be used outside of a Django project/application. In other words, no need to have DJANGO_SETTINGS_MODULE set or use a database, etc.

• Mutability: GEOSGeometry objects may be modified.

• Cross-platform and tested; compatible with Windows, Linux, Solaris, and macOS platforms.

Creating a GeometryLink to this heading#

GEOSGeometry objects may be created in a few ways. The first is to simply instantiate the object on some spatial input – the following are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry('POINT(5 23)') # WKT
>>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX
>>> pnt = GEOSGeometry(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
>>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON

Another option is to use the constructor for the specific geometry type that you wish to create. For example, a Point object may be created by passing in the X and Y coordinates into its constructor:

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)

All these constructors take the keyword argument srid. For example:

>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry('POINT (0 0)', srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)

Finally, there is the fromfile() factory method which returns a GEOSGeometry object from a file:

>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile('/path/to/pnt.wkt')
>>> pnt = fromfile(open('/path/to/pnt.wkt'))

Geometries are PythonicLink to this heading#

GEOSGeometry objects are «Pythonic», in other words components may be accessed, modified, and iterated over using standard Python conventions. For example, you can iterate over the coordinates in a Point:

>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]

With any geometry object, the GEOSGeometry.coords property may be used to get the geometry coordinates as a Python tuple:

>>> pnt.coords
(5.0, 23.0)

You can get/set geometry components using standard Python indexing techniques. However, what is returned depends on the geometry type of the object. For example, indexing on a LineString returns a coordinate tuple:

>>> from django.contrib.gis.geos import LineString
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
>>> line[0]
(0.0, 0.0)
>>> line[-2]
(50.0, 0.0)

Whereas indexing on a Polygon will return the ring (a LinearRing object) corresponding to the index:

>>> from django.contrib.gis.geos import Polygon
>>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) )
>>> poly[0]
<LinearRing object at 0x1044395b0>
>>> poly[0][-2] # second-to-last coordinate of external ring
(50.0, 0.0)

In addition, coordinates/components of the geometry may added or modified, just like a Python list:

>>> line[0] = (1.0, 1.0)
>>> line.pop()
(0.0, 0.0)
>>> line.append((1.0, 1.0))
>>> line.coords
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))

Geometries support set-like operators:

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (2, 2))
>>> ls2 = LineString((1, 1), (3, 3))
>>> print(ls1 | ls2)  # equivalent to `ls1.union(ls2)`
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
>>> print(ls1 & ls2)  # equivalent to `ls1.intersection(ls2)`
LINESTRING (1 1, 2 2)
>>> print(ls1 - ls2)  # equivalent to `ls1.difference(ls2)`
LINESTRING(0 0, 1 1)
>>> print(ls1 ^ ls2)  # equivalent to `ls1.sym_difference(ls2)`
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))

GEOSGeometryLink to this heading#

class GEOSGeometry(geo_input, srid=None)Link to this definition#

Parametry:

• geo_input – Geometry input value (string or buffer)

• srid (int) – spatial reference identifier

This is the base class for all GEOS geometry objects. It initializes on the given geo_input argument, and then assumes the proper geometry subclass (e.g., GEOSGeometry('POINT(1 1)') will create a Point object).

The srid parameter, if given, is set as the SRID of the created geometry if geo_input doesn’t have an SRID. If different SRIDs are provided through the geo_input and srid parameters, ValueError is raised:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry('POINT EMPTY', srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry('SRID=4326;POINT EMPTY', srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry('SRID=1;POINT EMPTY', srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.

The following input formats, along with their corresponding Python types, are accepted:

For the GeoJSON format, the SRID is set based on the crs member. If crs isn’t provided, the SRID defaults to 4326.

classmethod GEOSGeometry.from_gml(gml_string)Link to this definition#

Constructs a GEOSGeometry from the given GML string.

PointLink to this heading#

class Point(x=None, y=None, z=None, srid=None)Link to this definition#

Point objects are instantiated using arguments that represent the component coordinates of the point or with a single sequence coordinates. For example, the following are equivalent:

Code

>>> pnt = Point(5, 23)
>>> pnt = Point([5, 23])

Empty Point objects may be instantiated by passing no arguments or an empty sequence. The following are equivalent:

Code

>>> pnt = Point()
>>> pnt = Point([])

LineStringLink to this heading#

class LineString(*args, **kwargs)Link to this definition#

LineString objects are instantiated using arguments that are either a sequence of coordinates or Point objects. For example, the following are equivalent:

Code

>>> ls = LineString((0, 0), (1, 1))
>>> ls = LineString(Point(0, 0), Point(1, 1))

In addition, LineString objects may also be created by passing in a single sequence of coordinate or Point objects:

Code

>>> ls = LineString( ((0, 0), (1, 1)) )
>>> ls = LineString( [Point(0, 0), Point(1, 1)] )

Empty LineString objects may be instantiated by passing no arguments or an empty sequence. The following are equivalent:

Code

>>> ls = LineString()
>>> ls = LineString([])

closedLink to this definition#

Returns whether or not this LineString is closed.

LinearRingLink to this heading#

class LinearRing(*args, **kwargs)Link to this definition#

LinearRing objects are constructed in the exact same way as LineString objects, however the coordinates must be closed, in other words, the first coordinates must be the same as the last coordinates. For example:

Code

>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))

Notice that (0, 0) is the first and last coordinate – if they were not equal, an error would be raised.

is_counterclockwiseLink to this definition#

Returns whether this LinearRing is counterclockwise.

PolygonLink to this heading#

class Polygon(*args, **kwargs)Link to this definition#

Polygon objects may be instantiated by passing in parameters that represent the rings of the polygon. The parameters must either be LinearRing instances, or a sequence that may be used to construct a LinearRing:

Code

>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
>>> poly = Polygon(ext_coords, int_coords)
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))

classmethod from_bbox(bbox)Link to this definition#

Returns a polygon object from the given bounding-box, a 4-tuple comprising (xmin, ymin, xmax, ymax).

num_interior_ringsLink to this definition#

Returns the number of interior rings in this geometry.

MultiPointLink to this heading#

class MultiPoint(*args, **kwargs)Link to this definition#

MultiPoint objects may be instantiated by passing in Point objects as arguments, or a single sequence of Point objects:

Code

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) )

MultiLineStringLink to this heading#

class MultiLineString(*args, **kwargs)Link to this definition#

MultiLineString objects may be instantiated by passing in LineString objects as arguments, or a single sequence of LineString objects:

Code

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

mergedLink to this definition#

Returns a LineString representing the line merge of all the components in this MultiLineString.

closedLink to this definition#

Returns True if and only if all elements are closed. Requires GEOS 3.5.

MultiPolygonLink to this heading#

class MultiPolygon(*args, **kwargs)Link to this definition#

MultiPolygon objects may be instantiated by passing Polygon objects as arguments, or a single sequence of Polygon objects:

Code

>>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) )
>>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) )
>>> mp = MultiPolygon(p1, p2)
>>> mp = MultiPolygon([p1, p2])

GeometryCollectionLink to this heading#

class GeometryCollection(*args, **kwargs)Link to this definition#

GeometryCollection objects may be instantiated by passing in other GEOSGeometry as arguments, or a single sequence of GEOSGeometry objects:

Code

>>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) )
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))

PreparedGeometryLink to this heading#

class PreparedGeometryLink to this definition#

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

contains(other)Link to this definition#

contains_properly(other)Link to this definition#

covers(other)Link to this definition#

crosses(other)Link to this definition#

disjoint(other)Link to this definition#

intersects(other)Link to this definition#

overlaps(other)Link to this definition#

touches(other)Link to this definition#

within(other)Link to this definition#

Reader ObjectsLink to this heading#

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

class WKBReaderLink to this definition#

Example:

Code

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

class WKTReaderLink to this definition#

Example:

Code

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

Writer ObjectsLink to this heading#

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 value (in other words, EWKB).

class WKBWriter(dim=2)Link to this definition#

WKBWriter provides the most control over its output. By default it returns OGC-compliant WKB when its write method is called. However, it has properties that allow for the creation of EWKB, a superset of the WKB standard that includes additional information. See the WKBWriter.outdim documentation for more details about the dim argument.

write(geom)Link to this definition#

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

Code

>>> 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)Link to this definition#

Returns WKB of the geometry in hexadecimal. Example:

Code

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

byteorderLink to this definition#

This property may 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:

Code

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

outdimLink to this definition#

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

Example:

Code

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

sridLink to this definition#

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

Code

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

class WKTWriter(dim=2, trim=False, precision=None)Link to this definition#

This class allows outputting the WKT representation of a geometry. See the WKBWriter.outdim, trim, and precision attributes for details about the constructor arguments.

write(geom)Link to this definition#

Returns the WKT of the given geometry. Example:

Code

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

outdimLink to this definition#

See WKBWriter.outdim.

trimLink to this definition#

This property is used to enable or disable trimming of unnecessary decimals.

Code

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

precisionLink to this definition#

This property controls the rounding precision of coordinates; if set to None rounding is disabled.

Code

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1.44, 1.66)
>>> wkt_w = WKTWriter()
>>> print(wkt_w.precision)
None
>>> wkt_w.write(pnt)
'POINT (1.4399999999999999 1.6599999999999999)'
>>> wkt_w.precision = 0
>>> wkt_w.write(pnt)
'POINT (1 2)'
>>> wkt_w.precision = 1
>>> wkt_w.write(pnt)
'POINT (1.4 1.7)'

Footnotes

GEOS_LIBRARY_PATHLink to this heading#

A string specifying the location of the GEOS C library. Typically, this setting is only used if the GEOS C library is in a non-standard location (e.g., /home/bob/lib/libgeos_c.so).