GEOS APILink to this heading#

Vad är 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.

FunktionerLink to this heading#

GeoDjango implementerar en Python-wrapper på hög nivå för GEOS-biblioteket, med bland annat följande funktioner:

• Ett BSD-licensierat gränssnitt till GEOS geometrirutiner, implementerat enbart i Python med hjälp av 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.

• Ändringsbarhet: GEOSGeometry-objekt kan ändras.

• Testad på flera plattformar.

Skapa en geometriLink 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(
...     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)

Alla dessa konstruktörer tar nyckelordsargumentet srid. Till exempel:

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

Slutligen finns fabriksmetoden fromfile() som returnerar ett GEOSGeometry-objekt från en fil:

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

Geometrier är pytoniskaLink to this heading#

GEOSGeometry-objekt är ”pythoniska”, med andra ord kan komponenterna nås, modifieras och itereras över med hjälp av Pythons standardkonventioner. Du kan till exempel iterera över koordinaterna i en Point:

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

För alla geometriobjekt kan egenskapen GEOSGeometry.coords användas för att få geometrikoordinaterna som en Python-tupel:

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

Medan indexering på en Polygon kommer att returnera ringen (ett LinearRing-objekt) som motsvarar indexet:

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

Dessutom kan koordinater/komponenter i geometrin läggas till eller ändras, precis som i en Python-lista:

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

Geometrier stöder set-liknande operatorer:

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

GEOSGeometriLink to this heading#

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

Parametrar:

• geo_input – Inmatningsvärde för geometri (sträng eller memoryview)

• srid (int) – identifierare för rumslig referens

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

Parametern srid, om den anges, sätts som SRID för den skapade geometrin om geo_input inte har någon SRID. Om olika SRIDs tillhandahålls genom parametrarna geo_input och srid, uppstår ValueError:

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

Följande indataformat, tillsammans med motsvarande Python-typer, accepteras:

För GeoJSON-formatet ställs SRID in baserat på medlemmen crs. Om crs inte anges är standardvärdet för SRID 4326.

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

Konstruerar en GEOSGeometry från den givna GML-strängen.

PunktLink to this heading#

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

Point-objekt instansieras med argument som representerar punktens komponentkoordinater eller med en enda koordinatsekvens. Till exempel: är följande likvärdiga:

Python console

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

Tomma Point objekt kan instansieras genom att skicka inga argument eller en tom sekvens. Följande är likvärdiga:

Python console

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

LineStringLink to this heading#

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

LineString-objekt instansieras med hjälp av argument som antingen är en sekvens av koordinater eller Point-objekt. Till exempel: är följande likvärdiga:

Python console

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

Dessutom kan LineString-objekt också skapas genom att skicka in en enda sekvens av koordinat- eller Point-objekt:

Python console

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

Tomma LineString-objekt kan instansieras genom att skicka inga argument eller en tom sekvens. Följande är likvärdiga:

Python console

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

closedLink to this definition#

Returnerar om denna LineString är stängd eller inte.

LineärRingLink to this heading#

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

LinearRing-objekt konstrueras på exakt samma sätt som LineString`-objekt, men koordinaterna måste vara slutna, med andra ord måste de första koordinaterna vara desamma som de sista koordinaterna. Exempelvis:

Python console

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

Observera att (0, 0) är den första och sista koordinaten - om de inte var lika skulle ett fel uppstå.

is_counterclockwiseLink to this definition#

Returnerar om denna LinearRing är motsols.

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:

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

Returnerar ett polygonobjekt från den angivna bounding-boxen, en 4-tupel bestående av (xmin, ymin, xmax, ymax).

num_interior_ringsLink to this definition#

Returnerar antalet inre ringar i denna geometri.

MultiPointLink to this heading#

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

MultiPoint-objekt kan instansieras genom att skicka in Point-objekt som argument, eller en enda sekvens av Point-objekt:

Python console

>>> 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-objekt kan instansieras genom att skicka in LineString-objekt som argument, eller en enda sekvens av LineString-objekt:

Python console

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

mergedLink to this definition#

Returnerar en LineString som representerar linjesammanslagningen av alla komponenter i denna MultiLineString.

closedLink to this definition#

Returnerar True om och endast om alla element är stängda.

MultiPolygonLink to this heading#

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

MultiPolygon-objekt kan instansieras genom att skicka Polygon-objekt som argument, eller en enda sekvens av Polygon-objekt:

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 to this heading#

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

GeometryCollection-objekt kan instansieras genom att skicka in andra GEOSGeometry` som argument, eller en enda sekvens av GEOSGeometry`-objekt:

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

FörbereddGeometriLink to this heading#

class PreparedGeometryLink to this definition#

Alla metoder för PreparedGeometry tar ett other argument, som måste vara en GEOSGeometry-instans.

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#

LäsobjektLink to this heading#

I/O-klasserna för läsare returnerar en GEOSGeometry-instans från WKB- och/eller WKT-ingången som ges till deras read(geom)-metod.

class WKBReaderLink to this definition#

Exempel:

Python console

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

class WKTReaderLink to this definition#

Exempel:

Python console

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

Författarens objektLink 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#

Returnerar WKB för den angivna geometrin som ett Python-objekt i form av en buffer. Ett exempel:

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

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

Denna egenskap kan ställas in för att ändra byte-ordningen för geometrirepresentationen.

Byteordning Värde	Beskrivning
0	Big Endian (t.ex. kompatibel med RISC-system)
1	Little Endian (t.ex. kompatibel med x86-system)

Exempel:

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 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 värde	Beskrivning
2	Standard, utdata 2D WKB.
3	Utgång 3D WKB.

Exempel:

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

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

Denna klass gör det möjligt att skriva ut WKT-representationen av en geometri. Se attributen WKBWriter.outdim, trim och precision för detaljer om konstruktörens argument.

write(geom)Link to this definition#

Returnerar WKT för den givna geometrin. Ett exempel:

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

Se WKBWriter.outdim.

trimLink to this definition#

Denna egenskap används för att aktivera eller inaktivera trimning av onödiga decimaler.

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

Denna egenskap styr koordinaternas avrundningsprecision; om den är inställd på ”Ingen” är avrundning inaktiverad.

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

Fotnoter

GEOS_BIBLIOTEK_ SÖKVÄGLink 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).