Spatial Functions

This module defines the GenericFunction class, which is the base for the implementation of spatial functions in GeoAlchemy. This module is also where actual spatial functions are defined. Spatial functions supported by GeoAlchemy are defined in this module. See GenericFunction to know how to create new spatial functions.

Note

By convention the names of spatial functions are prefixed by ST_. This is to be consistent with PostGIS’, which itself is based on the SQL-MM standard.

Functions created by subclassing GenericFunction can be called in several ways:

  • By using the func object, which is the SQLAlchemy standard way of calling a function. For example, without the ORM:

    select([func.ST_Area(lake_table.c.geom)])
    

    and with the ORM:

    Session.query(func.ST_Area(Lake.geom))
    
  • By applying the function to a geometry column. For example, without the ORM:

    select([lake_table.c.geom.ST_Area()])
    

    and with the ORM:

    Session.query(Lake.geom.ST_Area())
    
  • By applying the function to a geoalchemy2.elements.WKBElement object (geoalchemy2.elements.WKBElement is the type into which GeoAlchemy converts geometry values read from the database), or to a geoalchemy2.elements.WKTElement object. For example, without the ORM:

    conn.scalar(lake['geom'].ST_Area())
    

    and with the ORM:

    session.scalar(lake.geom.ST_Area())
    

Reference

class geoalchemy2.functions.GenericFunction(*args, **kwargs)[source]

The base class for GeoAlchemy functions.

This class inherits from sqlalchemy.sql.functions.GenericFunction, so functions defined by subclassing this class can be given a fixed return type. For example, functions like ST_Buffer and ST_Envelope have their type attributes set to geoalchemy2.types.Geometry.

This class allows constructs like Lake.geom.ST_Buffer(2). In that case the Function instance is bound to an expression (Lake.geom here), and that expression is passed to the function when the function is actually called.

If you need to use a function that GeoAlchemy does not provide you will certainly want to subclass this class. For example, if you need the ST_TransScale spatial function, which isn’t (currently) natively supported by GeoAlchemy, you will write this:

from geoalchemy2 import Geometry
from geoalchemy2.functions import GenericFunction

class ST_TransScale(GenericFunction):
    name = 'ST_TransScale'
    type = Geometry
class geoalchemy2.functions.ST_Area(*args, **kwargs)

Returns the area of the surface if it is a polygon or multi-polygon. For geometry type area is in SRID units. For geography area is in square meters.

see http://postgis.net/docs/ST_Area.html

class geoalchemy2.functions.ST_AsBinary(*args, **kwargs)

Return the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.

see http://postgis.net/docs/ST_AsBinary.html

class geoalchemy2.functions.ST_AsEWKB(*args, **kwargs)

Return the Well-Known Binary (WKB) representation of the geometry/geography with SRID meta data.

see http://postgis.net/docs/ST_AsEWKB.html

class geoalchemy2.functions.ST_AsEWKT(*args, **kwargs)

Return the Well-Known Text (WKT) representation of the geometry/geography with SRID metadata.

see http://postgis.net/docs/ST_AsEWKT.html

class geoalchemy2.functions.ST_AsGML(*args, **kwargs)

Return the geometry as a GML version 2 or 3 element.

see http://postgis.net/docs/ST_AsGML.html

class geoalchemy2.functions.ST_AsGeoJSON(*args, **kwargs)

Return the geometry as a GeoJSON element.

see http://postgis.net/docs/ST_AsGeoJSON.html

class geoalchemy2.functions.ST_AsKML(*args, **kwargs)

Return the geometry as a KML element. Several variants. Default version=2, default precision=15

see http://postgis.net/docs/ST_AsKML.html

class geoalchemy2.functions.ST_AsRaster(*args, **kwargs)

Converts a PostGIS geometry to a PostGIS raster.

see http://postgis.net/docs/RT_ST_AsRaster.html

Return type: geoalchemy2.types.Raster.

type

alias of Raster

class geoalchemy2.functions.ST_AsSVG(*args, **kwargs)

Returns a Geometry in SVG path data given a geometry or geography object.

see http://postgis.net/docs/ST_AsSVG.html

class geoalchemy2.functions.ST_AsTWKB(*args, **kwargs)

Returns the geometry as TWKB, aka “Tiny Well-Known Binary”

see http://postgis.net/docs/ST_AsTWKB.html

class geoalchemy2.functions.ST_AsText(*args, **kwargs)

Return the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.

see http://postgis.net/docs/ST_AsText.html

class geoalchemy2.functions.ST_Buffer(*args, **kwargs)

For geometry: Returns a geometry that represents all points whose distance from this Geometry is less than or equal to distance. Calculations are in the Spatial Reference System of this Geometry.

For geography: Uses a planar transform wrapper. Introduced in 1.5 support for different end cap and mitre settings to control shape.

see http://postgis.net/docs/ST_Buffer.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Centroid(*args, **kwargs)

Returns the geometric center of a geometry.

see http://postgis.net/docs/ST_Centroid.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Contains(*args, **kwargs)

Returns True if and only if no points of B lie in the exterior of A, and at least one point of the interior of B lies in the interior of A.

see http://postgis.net/docs/ST_Contains.html

class geoalchemy2.functions.ST_ContainsProperly(*args, **kwargs)

Returns True if B intersects the interior of A but not the boundary (or exterior). A does not contain properly itself, but does contain itself.

see http://postgis.net/docs/ST_ContainsProperly.html

class geoalchemy2.functions.ST_CoveredBy(*args, **kwargs)

Returns True if no point in Geometry/Geography A is outside Geometry/Geography B

see http://postgis.net/docs/ST_CoveredBy.html

class geoalchemy2.functions.ST_Covers(*args, **kwargs)

Returns True if no point in Geometry B is outside Geometry A

see http://postgis.net/docs/ST_Covers.html

class geoalchemy2.functions.ST_Crosses(*args, **kwargs)

Returns True if the supplied geometries have some, but not all, interior points in common.

see http://postgis.net/docs/ST_Crosses.html

class geoalchemy2.functions.ST_DFullyWithin(*args, **kwargs)

Returns True if all of the geometries are within the specified distance of one another

see http://postgis.net/docs/ST_DFullyWithin.html

class geoalchemy2.functions.ST_DWithin(*args, **kwargs)

Returns True if the geometries are within the specified distance of one another. For geometry units are in those of spatial reference and for geography units are in meters and measurement is defaulted to use_spheroid=True (measure around spheroid), for faster check, use_spheroid=False to measure along sphere.

see http://postgis.net/docs/ST_DWithin.html

class geoalchemy2.functions.ST_Difference(*args, **kwargs)

Returns a geometry that represents that part of geometry A that does not intersect with geometry B.

see http://postgis.net/docs/ST_Difference.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Disjoint(*args, **kwargs)

Returns True if the Geometries do not “spatially intersect” - if they do not share any space together.

see http://postgis.net/docs/ST_Disjoint.html

class geoalchemy2.functions.ST_Distance(*args, **kwargs)

For geometry type Returns the 2-dimensional cartesian minimum distance (based on spatial ref) between two geometries in projected units. For geography type defaults to return spheroidal minimum distance between two geographies in meters.

see http://postgis.net/docs/ST_Distance.html

class geoalchemy2.functions.ST_Distance_Sphere(*args, **kwargs)

Returns minimum distance in meters between two lon/lat geometries. Uses a spherical earth and radius of 6370986 meters. Faster than ST_Distance_Spheroid, but less accurate. PostGIS versions prior to 1.5 only implemented for points.

see http://postgis.net/docs/ST_Distance_Sphere.html

class geoalchemy2.functions.ST_Dump(*args, **kwargs)

Returns a set of geometry_dump (geom,path) rows, that make up a geometry g1.

see http://postgis.net/docs/ST_Dump.html

Return type: geoalchemy2.types.GeometryDump.

type

alias of GeometryDump

class geoalchemy2.functions.ST_DumpPoints(*args, **kwargs)

Returns a set of geometry_dump (geom,path) rows of all points that make up a geometry.

see http://postgis.net/docs/ST_DumpPoints.html

Return type: geoalchemy2.types.GeometryDump.

type

alias of GeometryDump

class geoalchemy2.functions.ST_Envelope(*args, **kwargs)

Returns a geometry representing the double precision (float8) boundingbox of the supplied geometry.

see http://postgis.net/docs/ST_Envelope.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Equals(*args, **kwargs)

Returns True if the given geometries represent the same geometry. Directionality is ignored.

see http://postgis.net/docs/ST_Equals.html

class geoalchemy2.functions.ST_GeometryN(*args, **kwargs)

Return the 1-based Nth geometry if the geometry is a GEOMETRYCOLLECTION, (MULTI)POINT, (MULTI)LINESTRING, MULTICURVE or (MULTI)POLYGON, POLYHEDRALSURFACE Otherwise, return None.

see http://postgis.net/docs/ST_GeometryN.html

class geoalchemy2.functions.ST_GeometryType(*args, **kwargs)

Return the geometry type of the ST_Geometry value.

see http://postgis.net/docs/ST_GeometryType.html

class geoalchemy2.functions.ST_Height(*args, **kwargs)

Returns the height of the raster in pixels.

see http://postgis.net/docs/RT_ST_Height.html

class geoalchemy2.functions.ST_Intersection(*args, **kwargs)

Returns a geometry that represents the shared portion of geomA and geomB. The geography implementation does a transform to geometry to do the intersection and then transform back to WGS84.

see http://postgis.net/docs/ST_Intersection.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Intersects(*args, **kwargs)

Returns True if the Geometries/Geography “spatially intersect in 2D” - (share any portion of space) and False if they don’t (they are Disjoint). For geography – tolerance is 0.00001 meters (so any points that close are considered to intersect)

see http://postgis.net/docs/ST_Intersects.html

class geoalchemy2.functions.ST_IsValid(*args, **kwargs)

Returns True if the ST_Geometry is well formed.

see http://postgis.net/docs/ST_IsValid.html

class geoalchemy2.functions.ST_Length(*args, **kwargs)

Returns the 2d length of the geometry if it is a linestring or multilinestring. geometry are in units of spatial reference and geography are in meters (default spheroid)

see http://postgis.net/docs/ST_Length.html

class geoalchemy2.functions.ST_NPoints(*args, **kwargs)

Return the number of points (vertices) in a geometry.

see http://postgis.net/docs/ST_NPoints.html

class geoalchemy2.functions.ST_OrderingEquals(*args, **kwargs)

Returns True if the given geometries represent the same geometry and points are in the same directional order.

see http://postgis.net/docs/ST_OrderingEquals.html

class geoalchemy2.functions.ST_Overlaps(*args, **kwargs)

Returns True if the Geometries share space, are of the same dimension, but are not completely contained by each other.

see http://postgis.net/docs/ST_Overlaps.html

class geoalchemy2.functions.ST_Perimeter(*args, **kwargs)

Return the length measurement of the boundary of an ST_Surface or ST_MultiSurface geometry or geography. (Polygon, Multipolygon). geometry measurement is in units of spatial reference and geography is in meters.

see http://postgis.net/docs/ST_Perimeter.html

class geoalchemy2.functions.ST_Project(*args, **kwargs)

Returns a POINT projected from a start point using a distance in meters and bearing (azimuth) in radians.

see http://postgis.net/docs/ST_Project.html

Return type: geoalchemy2.types.Geography.

type

alias of Geography

class geoalchemy2.functions.ST_Relate(*args, **kwargs)

Returns True if this Geometry is spatially related to anotherGeometry, by testing for intersections between the Interior, Boundary and Exterior of the two geometries as specified by the values in the intersectionMatrixPattern. If no intersectionMatrixPattern is passed in, then returns the maximum intersectionMatrixPattern that relates the 2 geometries.

see http://postgis.net/docs/ST_Relate.html

class geoalchemy2.functions.ST_SRID(*args, **kwargs)

Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table.

see http://postgis.net/docs/ST_SRID.html

class geoalchemy2.functions.ST_Simplify(*args, **kwargs)

Returns a “simplified” version of the given geometry using the Douglas-Peucker algorithm

see http://postgis.net/docs/ST_Simplify.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Touches(*args, **kwargs)

Returns True if the geometries have at least one point in common, but their interiors do not intersect.

see http://postgis.net/docs/ST_Touches.html

class geoalchemy2.functions.ST_Transform(*args, **kwargs)

Returns a new geometry with its coordinates transformed to the SRID referenced by the integer parameter.

see http://postgis.net/docs/ST_Transform.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Union(*args, **kwargs)

Returns a geometry that represents the point set union of the Geometries.

see http://postgis.net/docs/ST_Union.html

Return type: geoalchemy2.types.Geometry.

type

alias of Geometry

class geoalchemy2.functions.ST_Value(*args, **kwargs)

Returns the value of a given band in a given columnx, rowy pixel or at a particular geometric point. Band numbers start at 1 and assumed to be 1 if not specified. If exclude_nodata_value is set to false, then all pixels include nodata pixels are considered to intersect and return value. If exclude_nodata_value is not passed in then reads it from metadata of raster.

see http://postgis.net/docs/RT_ST_Value.html

class geoalchemy2.functions.ST_Width(*args, **kwargs)

Returns the width of the raster in pixels.

see http://postgis.net/docs/RT_ST_Width.html

class geoalchemy2.functions.ST_Within(*args, **kwargs)

Returns True if the geometry A is completely inside geometry B

see http://postgis.net/docs/ST_Within.html

class geoalchemy2.functions.ST_X(*args, **kwargs)

Return the X coordinate of the point, or None if not available. Input must be a point.

see http://postgis.net/docs/ST_X.html

class geoalchemy2.functions.ST_Y(*args, **kwargs)

Return the Y coordinate of the point, or None if not available. Input must be a point.

see http://postgis.net/docs/ST_Y.html

class geoalchemy2.functions.ST_Z(*args, **kwargs)

Return the Z coordinate of the point, or None if not available. Input must be a point.

see http://postgis.net/docs/ST_Z.html