============================= Geographic Database Functions ============================= .. module:: django.contrib.gis.db.models.functions :synopsis: Geographic Database Functions .. versionadded:: 1.9 The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django. Example:: >>> from django.contrib.gis.db.models.functions import Length >>> Track.objects.annotate(length=Length('line')).filter(length__gt=100) Not all backends support all functions, so refer to the documentation of each function to see if your database backend supports the function you want to use. If you call a geographic function on a backend that doesn't support it, you'll get a ``NotImplementedError`` exception. Function's summary: ================== ======================= ====================== =================== ================== ===================== Measurement Relationships Operations Editors Output format Miscellaneous ================== ======================= ====================== =================== ================== ===================== :class:`Area` :class:`BoundingCircle` :class:`Difference` :class:`ForceRHR` :class:`AsGeoJSON` :class:`MemSize` :class:`Distance` :class:`Centroid` :class:`Intersection` :class:`Reverse` :class:`AsGML` :class:`NumGeometries` :class:`Length` :class:`Envelope` :class:`SymDifference` :class:`Scale` :class:`AsKML` :class:`NumPoints` :class:`Perimeter` :class:`PointOnSurface` :class:`Union` :class:`SnapToGrid` :class:`AsSVG` :class:`Transform` :class:`GeoHash` :class:`Translate` ================== ======================= ====================== =================== ================== ===================== Area ---- .. class:: Area(expression, **extra) *Availability*: MySQL, Oracle, PostGIS, SpatiaLite Accepts a single geographic field or expression and returns the area of the field as an :class:`~django.contrib.gis.measure.Area` measure. On MySQL, a raw float value is returned, as it's not possible to automatically determine the unit of the field. AsGeoJSON --------- .. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a `GeoJSON `_ representation of the geometry. Note that the result is not a complete GeoJSON structure but only the ``geometry`` key content of a GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`. Example:: >>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json {"type":"Point","coordinates":[-87.65018,41.85039]} ===================== ===================================================== Keyword Argument Description ===================== ===================================================== ``bbox`` Set this to ``True`` if you want the bounding box to be included in the returned GeoJSON. ``crs`` Set this to ``True`` if you want the coordinate reference system to be included in the returned GeoJSON. ``precision`` It may be used to specify the number of significant digits for the coordinates in the GeoJSON representation -- the default value is 8. ===================== ===================================================== AsGML ----- .. class:: AsGML(expression, version=2, precision=8, **extra) *Availability*: Oracle, PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a `Geographic Markup Language (GML)`__ representation of the geometry. Example:: >>> qs = Zipcode.objects.annotate(gml=AsGML('poly')) >>> print(qs[0].gml) -147.78711,70.245363 ... -147.78711,70.245363 ===================== ===================================================== Keyword Argument Description ===================== ===================================================== ``precision`` Not used on Oracle. It may be used to specify the number of significant digits for the coordinates in the GML representation -- the default value is 8. ``version`` Not used on Oracle. It may be used to specify the GML version used, and may only be values of 2 or 3. The default value is 2. ===================== ===================================================== __ https://en.wikipedia.org/wiki/Geography_Markup_Language AsKML ----- .. class:: AsKML(expression, precision=8, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a `Keyhole Markup Language (KML)`__ representation of the geometry. Example:: >>> qs = Zipcode.objects.annotate(kml=AsKML('poly')) >>> print(qs[0].kml) -103.04135,36.217596,0 ... -103.04135,36.217596,0 ===================== ===================================================== Keyword Argument Description ===================== ===================================================== ``precision`` This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8. ===================== ===================================================== __ https://developers.google.com/kml/documentation/ AsSVG ----- .. class:: AsSVG(expression, relative=False, precision=8, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a `Scalable Vector Graphics (SVG)`__ representation of the geometry. ===================== ===================================================== Keyword Argument Description ===================== ===================================================== ``relative`` If set to ``True``, the path data will be implemented in terms of relative moves. Defaults to ``False``, meaning that absolute moves are used instead. ``precision`` This keyword may be used to specify the number of significant digits for the coordinates in the SVG representation -- the default value is 8. ===================== ===================================================== __ http://www.w3.org/Graphics/SVG/ BoundingCircle -------------- .. class:: BoundingCircle(expression, num_seg=48, **extra) *Availability*: `PostGIS `__ Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry. Centroid -------- .. class:: Centroid(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts a single geographic field or expression and returns the ``centroid`` value of the geometry. Difference ---------- .. class:: Difference(expr1, expr2, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric difference, that is the part of geometry A that does not intersect with geometry B. Distance -------- .. class:: Distance(expr1, expr2, spheroid=None, **extra) *Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the distance between them, as a :class:`~django.contrib.gis.measure.Distance` object. On MySQL, a raw float value is returned, as it's not possible to automatically determine the unit of the field. On backends that support distance calculation on geodetic coordinates, the proper backend function is automatically chosen depending on the SRID value of the geometries (e.g. ``ST_Distance_Sphere`` on PostGIS). When distances are calculated with geodetic (angular) coordinates, as is the case with the default WGS84 (4326) SRID, you can set the ``spheroid`` keyword argument to decide if the calculation should be based on a simple sphere (less accurate, less resource-intensive) or on a spheroid (more accurate, more resource-intensive). In the following example, the distance from the city of Hobart to every other :class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity`` queryset is calculated:: >>> 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 ... .. note:: Because the ``distance`` attribute is a :class:`~django.contrib.gis.measure.Distance` object, you can easily express the value in the units of your choice. For example, ``city.distance.mi`` is the distance value in miles and ``city.distance.km`` is the distance value in kilometers. See :doc:`measure` for usage details and the list of :ref:`supported_units`. Envelope -------- .. class:: Envelope(expression, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry. ForceRHR -------- .. class:: ForceRHR(expression, **extra) *Availability*: `PostGIS `__ Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all of the vertices follow the right-hand rule. GeoHash ------- .. class:: GeoHash(expression, **extra) *Availability*: PostGIS Accepts a single geographic field or expression and returns a `GeoHash`__ representation of the geometry. __ https://en.wikipedia.org/wiki/Geohash Intersection ------------ .. class:: Intersection(expr1, expr2, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric intersection between them. Length ------ .. class:: Length(expression, spheroid=True, **extra) *Availability*: MySQL, Oracle, PostGIS, SpatiaLite Accepts a single geographic linestring or multilinestring field or expression and returns its length as an :class:`~django.contrib.gis.measure.Distance` measure. On MySQL, a raw float value is returned, as it's not possible to automatically determine the unit of the field. On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can specify if the calculation should be based on a simple sphere (less accurate, less resource-intensive) or on a spheroid (more accurate, more resource-intensive) with the ``spheroid`` keyword argument. MemSize ------- .. class:: MemSize(expression, **extra) *Availability*: PostGIS Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes. NumGeometries ------------- .. class:: NumGeometries(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts a single geographic field or expression and returns the number of geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field); otherwise returns ``None``. NumPoints --------- .. class:: NumPoints(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts a single geographic field or expression and returns the number of points in the first linestring in the geometry field; otherwise returns ``None``. Perimeter --------- .. class:: Perimeter(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite (≥ 4.0) Accepts a single geographic field or expression and returns the perimeter of the geometry field as a :class:`~django.contrib.gis.measure.Distance` object. On MySQL, a raw float value is returned, as it's not possible to automatically determine the unit of the field. PointOnSurface -------------- .. class:: PointOnSurface(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts a single geographic field or expression and returns a ``Point`` geometry guaranteed to lie on the surface of the field; otherwise returns ``None``. Reverse ------- .. class:: Reverse(expression, **extra) *Availability*: PostGIS, Oracle, SpatiaLite (≥ 4.0) Accepts a single geographic field or expression and returns a geometry with reversed coordinates. Scale ----- .. class:: Scale(expression, x, y, z=0.0, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a geometry with scaled coordinates by multiplying them with the ``x``, ``y``, and optionally ``z`` parameters. SnapToGrid ---------- .. class:: SnapToGrid(expression, *args, **extra) *Availability*: PostGIS, SpatiaLite (≥ 3.1) Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given. =================== ===================================================== Number of Arguments Description =================== ===================================================== 1 A single size to snap both the X and Y grids to. 2 X and Y sizes to snap the grid to. 4 X, Y sizes and the corresponding X, Y origins. =================== ===================================================== SymDifference ------------- .. class:: SymDifference(expr1, expr2, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters. Transform --------- .. class:: Transform(expression, srid, **extra) *Availability*: PostGIS, Oracle, SpatiaLite Accepts a geographic field or expression and a SRID integer code, and returns the transformed geometry to the spatial reference system specified by the ``srid`` parameter. .. note:: What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS. Translate --------- .. class:: Translate(expression, x, y, z=0.0, **extra) *Availability*: PostGIS, SpatiaLite Accepts a single geographic field or expression and returns a geometry with its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric parameters. Union ----- .. class:: Union(expr1, expr2, **extra) *Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the union of both geometries.