GEOS APILink to this heading#

Vad är GEOS?Link to this heading#

gEOS står för Geometry Engine - Open Source och är ett C++-bibliotek som har överförts från Java Topology Suite. GEOS implementerar OpenGIS `Simple Features for SQL`__ rumsliga predikatfunktioner och rumsliga operatorer. GEOS, som nu är ett OSGeo-projekt, utvecklades och underhålls ursprungligen av `Refractions Research`__ i Victoria, Kanada.

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.

• Löst kopplad till GeoDjango. Till exempel: kan GEOSGeometry-objekt användas utanför ett Django-projekt/applikation. Med andra ord behöver du inte ha DJANGO_SETTINGS_MODULE inställd eller använda en databas, etc.

• Ändringsbarhet: GEOSGeometry-objekt kan ändras.

• Testad på flera plattformar.

Skapa en geometriLink to this heading#

GEOSGeometry-objekt kan skapas på flera olika sätt. Det första är att helt enkelt instansiera objektet på någon rumslig indata - följande är exempel på hur man skapar samma geometri från WKT, HEX, WKB och 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

Ett annat alternativ är att använda konstruktören för den specifika geometrityp som du vill skapa. Till exempel: kan ett Point-objekt skapas genom att X- och Y-koordinaterna anges i dess konstruktor:

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

Du kan hämta/ställa in geometrikomponenter med hjälp av Pythons vanliga indexeringstekniker. Vad som returneras beror dock på objektets geometrityp. Till exempel:, indexering på en LineString returnerar en koordinattupel:

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

Detta är basklassen för alla GEOS geometriobjekt. Den initialiseras på det givna geo_input-argumentet och antar sedan rätt geometriunderklass (t.ex. kommer GEOSGeometry('POINT(1 1)'') att skapa ett Point-objekt).

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#

objekt av typen Polygon kan instansieras genom att man skickar in parametrar som representerar ringarna i polygonen. Parametrarna måste antingen vara LinearRing-instanser eller en sekvens som kan användas för att konstruera en 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#

Alla writer-objekt har en write(geom)-metod som returnerar antingen WKB eller WKT för den givna geometrin. Dessutom har WKBWriter-objekten också egenskaper som kan användas för att ändra byteordningen och eller inkludera SRID-värdet (med andra ord EWKB).

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

WKBWriter ger mest kontroll över dess utdata. Som standard returnerar den OGC-kompatibla WKB när dess write-metod anropas. Den har dock egenskaper som gör det möjligt att skapa EWKB, en överuppsättning av WKB-standarden som innehåller ytterligare information. Se WKBWriter.outdim-dokumentationen för mer information om dim-argumentet.

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#

Returnerar geometrins WKB i hexadecimal. Ett exempel:

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#

Denna egenskap kan ställas in för att ändra geometrirepresentationens utdatadimension. Med andra ord, om du har en 3D-geometri ska du ange 3 så att Z-värdet inkluderas i 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#

Ange denna egenskap med ett boolean för att ange om geometrins SRID ska inkluderas i WKB-representationen. Exempel på detta:

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#

En sträng som anger platsen för GEOS C-biblioteket. Vanligtvis används denna inställning endast om GEOS C-biblioteket finns på en plats som inte är standard (t.ex. /home/bob/lib/libgeos_c.so).