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 and tested; compatible with Windows, Linux, Solaris, and macOS platforms.

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

Parâmetros:

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

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

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

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.

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:

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

Code

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

Code

>>> 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. Requires GEOS 3.5.

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:

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

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

Exemplo

Code

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

class WKTReaderLink para esta definição#

Exemplo

Code

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

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

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

Exemplo

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

Exemplo

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

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

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

See WKBWriter.outdim.

trimLink para esta definição#

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