GEOS APILink para este cabeçalho#

What is GEOS?Link para este cabeçalho#

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 para este cabeçalho#

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

Creating a GeometryLink para este cabeçalho#

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(
...     memoryview(
...         b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@"
...     )
... )  # WKB
>>> 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 para este cabeçalho#

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 para este cabeçalho#

class GEOSGeometry(geo_input, srid=None, *, max_geom_collections=198)Link para esta definição#

Parâmetros:

• geo_input – Geometry input value (string or memoryview)

• srid (int) – spatial reference identifier

• max_geom_collections – maximum number of nested (WKT) or total (WKB) geometry collections accepted before parsing is refused

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 para esta definição#

Constructs a GEOSGeometry from the given GML string.

PointLink para este cabeçalho#

class Point(x=None, y=None, z=None, srid=None)Link para esta definição#

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:

Python console

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

Python console

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

LineStringLink para este cabeçalho#

class LineString(*args, **kwargs)Link para esta definição#

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

Python console

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

Python console

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

Python console

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

closedLink para esta definição#

Returns whether or not this LineString is closed.

LinearRingLink para este cabeçalho#

class LinearRing(*args, **kwargs)Link para esta definição#

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:

Python console

>>> 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 para esta definição#

Returns whether this LinearRing is counterclockwise.

PolygonLink para este cabeçalho#

class Polygon(*args, **kwargs)Link para esta definição#

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:

Python console

>>> 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 para esta definição#

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

num_interior_ringsLink para esta definição#

Returns the number of interior rings in this geometry.

MultiPointLink para este cabeçalho#

class MultiPoint(*args, **kwargs)Link para esta definição#

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

Python console

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

MultiLineStringLink para este cabeçalho#

class MultiLineString(*args, **kwargs)Link para esta definição#

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

Python console

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

mergedLink para esta definição#

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

closedLink para esta definição#

Returns True if and only if all elements are closed.

MultiPolygonLink para este cabeçalho#

class MultiPolygon(*args, **kwargs)Link para esta definição#

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

Python console

>>> 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 para este cabeçalho#

class GeometryCollection(*args, **kwargs)Link para esta definição#

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

Python console

>>> 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 para este cabeçalho#

class PreparedGeometryLink para esta definição#

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

contains(other)Link para esta definição#

contains_properly(other)Link para esta definição#

covers(other)Link para esta definição#

crosses(other)Link para esta definição#

disjoint(other)Link para esta definição#

intersects(other)Link para esta definição#

overlaps(other)Link para esta definição#

touches(other)Link para esta definição#

within(other)Link para esta definição#

Objetos de LeituraLink para este cabeçalho#

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

class WKBReaderLink para esta definição#

Example:

Python console

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

class WKTReaderLink para esta definição#

Example:

Python console

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

Writer ObjectsLink para este cabeçalho#

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 para esta definição#

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 para esta definição#

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

Python console

>>> 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 para esta definição#

Returns WKB of the geometry in hexadecimal. Example:

Python console

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

byteorderLink para esta definição#

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

Byteorder Value	Descrição
0	Big Endian (e.g., compatible with RISC systems)
1	Little Endian (e.g., compatible with x86 systems)

Example:

Python console

>>> 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 para esta definição#

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	Descrição
2	The default, output 2D WKB.
3	Output 3D WKB.

Example:

Python console

>>> 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 para esta definição#

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

Python console

>>> 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 para esta definição#

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 para esta definição#

Returns the WKT of the given geometry. Example:

Python console

>>> 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 para esta definição#

See WKBWriter.outdim.

trimLink para esta definição#

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

Python console

>>> 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 para esta definição#

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

Notas de rodapé

GEOS_LIBRARY_PATHLink para este cabeçalho#

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