Geografiska databasfunktioner

De funktioner som dokumenteras på den här sidan ger användare tillgång till geografiska databasfunktioner som kan användas i anteckningar, aggregeringar eller filter i Django.

Exempel:

>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)

Alla backends stöder inte alla funktioner, så läs dokumentationen för varje funktion för att se om din databasbackend stöder den funktion du vill använda. Om du anropar en geografisk funktion på en backend som inte stöder den, får du ett NotImplementedError undantag.

Mått

Area

class Area(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar fältets area som ett Area-mått.

MySQL och SpatiaLite utan LWGEOM/RTTOPO stöder inte områdesberäkningar på geografiska SRS:er.

Avstånd

class Distance(expr1, expr2, spheroid=None, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar avståndet mellan dem, som ett Distance-objekt. På MySQL returneras ett rått floatvärde när koordinaterna är geodetiska.

På backends som stöder avståndsberäkning på geodetiska koordinater väljs automatiskt rätt backend-funktion beroende på geometriernas SRID-värde (t.ex. ST_DistanceSphere på PostGIS).

När avstånd beräknas med geodetiska (vinkel-) koordinater, vilket är fallet med standard SRID:en WGS84 (4326), kan du ange nyckelordsargumentet spheroid för att bestämma om beräkningen ska baseras på en enkel sfär (mindre noggrann, mindre resurskrävande) eller på en sfäroid (mer noggrann, mer resurskrävande).

I följande exempel beräknas avståndet från staden Hobart till alla andra PointField i frågeuppsättningen AustraliaCity:

>>> from django.contrib.gis.db.models.functions import Distance
>>> pnt = AustraliaCity.objects.get(name="Hobart").point
>>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):
...     print(city.name, city.distance)
...
Wollongong 990071.220408 m
Shellharbour 972804.613941 m
Thirroul 1002334.36351 m
...

Observera

Eftersom attributet distance är ett Distance-objekt kan du enkelt uttrycka värdet i de enheter du väljer. Till exempel: är city.distance.mi avståndsvärdet i miles och city.distance.km är avståndsvärdet i kilometer. Se Mätobjekt för detaljer om användning och listan över Stödda enheter.

GeometryDistance

class GeometryDistance(expr1, expr2, **extra)[source]

Tillgänglighet: PostGIS

Accepterar två geografiska fält eller uttryck och returnerar avståndet mellan dem. När den används i en order_by()-klausul ger den indexassisterade resultatuppsättningar för närmaste granne.

Längd

class Length(expression, spheroid=True, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Tar emot ett geografiskt fält eller uttryck med en eller flera strängar och returnerar dess längd som ett Distance-mått.

I PostGIS och SpatiaLite, när koordinaterna är geodetiska (vinkel), kan du ange om beräkningen ska baseras på en enkel sfär (mindre exakt, mindre resurskrävande) eller på en sfäroid (mer exakt, mer resurskrävande) med nyckelordsargumentet ”sfäroid”.

MySQL stöder inte längdberäkningar på geografiska SRS:er.

Perimeter

class Perimeter(expression, **extra)[source]

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar geometriområdets omkrets som ett Distance-objekt.

Relationer

”Azimut

class Azimuth(point_a, point_b, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Returnerar azimut i radianer för det segment som definieras av de givna punktgeometrierna, eller None om de två punkterna sammanfaller. Azimuten är vinkelrefererad från norr och är positiv medurs: norr = 0; öster = π/2; söder = π; väster = 3π/2.

BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra)[source]

Tillgänglighet: PostGIS, Oracle, SpatiaLite 5.1+

Accepterar ett enda geografiskt fält eller uttryck och returnerar den minsta cirkelpolygon som helt kan innehålla geometrin.

Parametern num_seg används endast på PostGIS.

Changed in Django 5.1:

Stöd för SpatiaLite 5.1+ har lagts till.

Centroid

class Centroid(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar geometrins centroid-värde.

Närmaste punkt

class ClosestPoint(expr1, expr2, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den 2-dimensionella punkt på geometri A som ligger närmast geometri B.

Kuvert

class Envelope(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar den geometri som representerar geometrins begränsningsbox.

LineLocatePoint

class LineLocatePoint(linestring, point, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Returnerar en flottör mellan 0 och 1 som representerar platsen för den närmaste punkten på linjestring till den angivna punkten, som en bråkdel av 2D-linjens längd.

PointOnSurface

class PointOnSurface(expression, **extra)[source]

Tillgänglighet: PostGIS, MariaDB, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en geometrisk Point som garanterat ligger på fältets yta; annars returneras None.

Åtgärder

”Skillnad

class Difference(expr1, expr2, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den geometriska skillnaden, det vill säga den del av geometri A som inte skär geometri B.

Intersektion

class Intersection(expr1, expr2, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den geometriska skärningspunkten mellan dem.

SymDifference

class SymDifference(expr1, expr2, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Tar emot två geografiska fält eller uttryck och returnerar den geometriskt symmetriska skillnaden (union utan intersektion) mellan de angivna parametrarna.

Union

class Union(expr1, expr2, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar sammanslagningen av de båda geometrierna.

Redigerare

ForcePolygonCW

class ForcePolygonCW(expression, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en modifierad version av polygonen/multipolygonen där alla yttre ringar är orienterade medurs och alla inre ringar är orienterade moturs. Icke-polygonala geometrier returneras oförändrade.

MakeValid

class MakeValid(expr)[source]

Tillgänglighet: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepterar ett geografiskt fält eller uttryck och försöker konvertera värdet till en giltig geometri utan att förlora någon av de ingående hörnen. Geometrier som redan är giltiga returneras utan ändringar. Enkla polygoner kan bli en multipolygon och resultatet kan ha en lägre dimension än indata.

Reverse

class Reverse(expression, **extra)[source]

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en geometri med omvända koordinater.

Skala

class Scale(expression, x, y, z=0.0, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Tar emot ett enda geografiskt fält eller uttryck och returnerar en geometri med skalade koordinater genom att multiplicera dem med parametrarna x, y och eventuellt z.

SnapToGrid

class SnapToGrid(expression, *args, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en geometri med alla punkter knäppta till det angivna rutnätet. Hur geometrin knäpps till rutnätet beror på hur många numeriska argument (antingen float, integer eller long) som anges.

Antal argument

Beskrivning

1

En enda storlek för att fästa både X- och Y-rutnätet till.

2

X- och Y-storlekar för att fästa rutnätet.

4

X- och Y-storlekar och motsvarande X- och Y-ursprung.

Transform

class Transform(expression, srid, **extra)[source]

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Tar emot ett geografiskt fält eller uttryck och en SRID-heltalskod och returnerar den transformerade geometrin till det rumsliga referenssystem som anges av parametern srid.

Observera

Vilket rumsligt referenssystem ett heltals-SRID motsvarar kan bero på vilken rumslig databas som används. Med andra ord är de SRID-nummer som används för Oracle inte nödvändigtvis desamma som de som används av PostGIS.

Translate

class Translate(expression, x, y, z=0.0, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Tar emot ett enda geografiskt fält eller uttryck och returnerar en geometri med koordinaterna förskjutna med de numeriska parametrarna x, y och eventuellt z.

Inmatningsformat

FrånWKB

class FromWKB(expression, srid=0, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Skapar geometri från Well-known binary (WKB) representation. Det valfria argumentet srid gör det möjligt att ange SRID för den resulterande geometrin. srid ignoreras i Oracle.

Changed in Django 5.1:

Argumentet srid lades till.

FrånWKT

class FromWKT(expression, srid=0, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Skapar geometri från Well-known text (WKT) representation. Det valfria argumentet srid gör det möjligt att ange SRID för den resulterande geometrin. srid ignoreras i Oracle.

Changed in Django 5.1:

Argumentet srid lades till.

Utdata format

AsGeoJSON

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en GeoJSON representation av geometrin. Observera att resultatet inte är en komplett GeoJSON-struktur utan endast nyckelinnehållet geometry i en GeoJSON-struktur. Se även GeoJSON Serializer.

Exempel:

>>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
{"type":"Point","coordinates":[-87.65018,41.85039]}

Sökord Argument

Beskrivning

bbox

Ställ in detta på True om du vill att bounding box ska ingå i den returnerade GeoJSON. Ignoreras på Oracle.

crs

Sätt detta till True om du vill att koordinatreferenssystemet ska ingå i den returnerade GeoJSON. Ignoreras på MySQL och Oracle.

precision

Det kan användas för att ange antalet signifikanta siffror för koordinaterna i GeoJSON-representationen - standardvärdet är 8. Ignoreras i Oracle.

AsGML

class AsGML(expression, version=2, precision=8, **extra)[source]

Tillgänglighet: Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `Geographic Markup Language (GML)`__-representation av geometrin.

Exempel:

>>> qs = Zipcode.objects.annotate(gml=AsGML("poly"))
>>> print(qs[0].gml)
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...
-147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>

Sökord Argument

Beskrivning

precision

Anger antalet signifikanta siffror för koordinaterna i GML-representationen – standardvärdet är 8. Ignoreras i Oracle.

version

Anger vilken GML-version som ska användas: 2 (standard) eller 3.

AsKML

class AsKML(expression, precision=8, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `Keyhole Markup Language (KML)`__-representation av geometrin.

Exempel:

>>> qs = Zipcode.objects.annotate(kml=AsKML("poly"))
>>> print(qs[0].kml)
<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...
-103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>

Sökord Argument

Beskrivning

precision

Detta nyckelord kan användas för att ange antalet signifikanta siffror för koordinaterna i KML-representationen - standardvärdet är 8.

AsSVG

class AsSVG(expression, relative=False, precision=8, **extra)[source]

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en SVG-representation (SVG = Scalable Vector Graphics) av geometrin.

Sökord Argument

Beskrivning

relativ

Om inställningen är True implementeras sökvägsdata i form av relativa förflyttningar. Standardvärdet är False, vilket innebär att absoluta förflyttningar används istället.

precision

Detta nyckelord kan användas för att ange antalet signifikanta siffror för koordinaterna i SVG-representationen - standardvärdet är 8.

AsWKB

class AsWKB(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en Well-known binary (WKB)-representation av geometrin.

Exempel:

>>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

AsWKT

class AsWKT(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en Well-known text (WKT)-representation av geometrin.

Exempel:

>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'

GeoHash

class GeoHash(expression, precision=None, **extra)[source]

Tillgänglighet: MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `GeoHash`__-representation av geometrin.

Nyckelordsargumentet precision styr antalet tecken i resultatet.

Diverse

IsEmpty

class IsEmpty(expr)[source]

Tillgänglighet: PostGIS

Accepterar ett geografiskt fält eller uttryck och testar om värdet är en tom geometri. Returnerar True om dess värde är tomt och False annars.

IsValid

class IsValid(expr)[source]

Tillgänglighet: MySQL, PostGIS, Oracle, SpatiaLite

Tar emot ett geografiskt fält eller uttryck och testar om värdet är välformat. Returnerar True om dess värde är en giltig geometri och False annars.

MemSize

class MemSize(expression, **extra)[source]

Tillgänglighet: PostGIS

Accepterar ett enda geografiskt fält eller uttryck och returnerar den minnesstorlek (antal byte) som det geometriska fältet tar.

NumGeometries

class NumGeometries(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar antalet geometrier om geometrifältet är en samling (t.ex. ett fält GEOMETRYCOLLECTION eller MULTI*). Returnerar 1 för enstaka geometrier.

På MySQL returneras None för enstaka geometrier.

NumPoints

class NumPoints(expression, **extra)[source]

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar antalet punkter i en geometri.

På MySQL returneras None för alla geometrier som inte är LINESTRING.