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 ageoalchemy2.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 likeST_Buffer
andST_Envelope
have theirtype
attributes set togeoalchemy2.types.Geometry
.This class allows constructs like
Lake.geom.ST_Buffer(2)
. In that case theFunction
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. Forgeography
area is in square meters.
-
class
geoalchemy2.functions.
ST_AsBinary
(*args, **kwargs)¶ Return the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.
-
class
geoalchemy2.functions.
ST_AsEWKB
(*args, **kwargs)¶ Return the Well-Known Binary (WKB) representation of the geometry/geography with SRID meta data.
-
class
geoalchemy2.functions.
ST_AsEWKT
(*args, **kwargs)¶ Return the Well-Known Text (WKT) representation of the geometry/geography with SRID metadata.
-
class
geoalchemy2.functions.
ST_AsGML
(*args, **kwargs)¶ Return the geometry as a GML version 2 or 3 element.
-
class
geoalchemy2.functions.
ST_AsGeoJSON
(*args, **kwargs)¶ Return the geometry as a GeoJSON element.
-
class
geoalchemy2.functions.
ST_AsKML
(*args, **kwargs)¶ Return the geometry as a KML element. Several variants. Default version=2, default precision=15
-
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
geoalchemy2.types.Raster
-
-
class
geoalchemy2.functions.
ST_AsSVG
(*args, **kwargs)¶ Returns a Geometry in SVG path data given a geometry or geography object.
-
class
geoalchemy2.functions.
ST_AsTWKB
(*args, **kwargs)¶ Returns the geometry as TWKB, aka “Tiny Well-Known Binary”
-
class
geoalchemy2.functions.
ST_AsText
(*args, **kwargs)¶ Return the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.
-
class
geoalchemy2.functions.
ST_Azimuth
(*args, **kwargs)¶ Returns the angle in radians from the horizontal of the vector defined by pointA and pointB. Angle is computed clockwise from down-to-up: on the clock: 12=0; 3=PI/2; 6=PI; 9=3PI/2.
-
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
geoalchemy2.types.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
geoalchemy2.types.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.
-
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.
-
class
geoalchemy2.functions.
ST_CoveredBy
(*args, **kwargs)¶ Returns
True
if no point in Geometry/Geography A is outside Geometry/Geography B
-
class
geoalchemy2.functions.
ST_Covers
(*args, **kwargs)¶ Returns
True
if no point in Geometry B is outside Geometry A
-
class
geoalchemy2.functions.
ST_Crosses
(*args, **kwargs)¶ Returns
True
if the supplied geometries have some, but not all, interior points in common.
-
class
geoalchemy2.functions.
ST_DFullyWithin
(*args, **kwargs)¶ Returns
True
if all of the geometries are within the specified distance of one another
-
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 touse_spheroid=True
(measure around spheroid), for faster check,use_spheroid=False
to measure along sphere.
-
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
geoalchemy2.types.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.
-
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.
-
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.
-
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
geoalchemy2.types.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
geoalchemy2.types.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
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_Equals
(*args, **kwargs)¶ Returns
True
if the given geometries represent the same geometry. Directionality is ignored.
-
class
geoalchemy2.functions.
ST_GeogFromText
(*args, **kwargs)¶ Returns a geography object from the well-known text or extended well-known representation.
see http://postgis.net/docs/ST_GeogFromText.html
Return type:
geoalchemy2.types.Geography
.-
type
¶ alias of
geoalchemy2.types.Geography
-
-
class
geoalchemy2.functions.
ST_GeomFromEWKB
(*args, **kwargs)¶ Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known binary (EWKB) representation.
see http://postgis.net/docs/ST_GeomFromEWKB.html
Return type:
geoalchemy2.types.Geometry
.-
type
¶ alias of
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_GeomFromEWKT
(*args, **kwargs)¶ Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known text (EWKT) representation.
see http://postgis.net/docs/ST_GeomFromEWKT.html
Return type:
geoalchemy2.types.Geometry
.-
type
¶ alias of
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_GeomFromText
(*args, **kwargs)¶ Constructs a PostGIS ST_Geometry object from the OGC Well-Known text representation.
see http://postgis.net/docs/ST_GeomFromText.html
Return type:
geoalchemy2.types.Geometry
.-
type
¶ alias of
geoalchemy2.types.Geometry
-
-
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, returnNone
.
-
class
geoalchemy2.functions.
ST_GeometryType
(*args, **kwargs)¶ Return the geometry type of the
ST_Geometry
value.
-
class
geoalchemy2.functions.
ST_Height
(*args, **kwargs)¶ Returns the height of the raster in pixels.
-
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
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_Intersects
(*args, **kwargs)¶ Returns
True
if the Geometries/Geography “spatially intersect in 2D” - (share any portion of space) andFalse
if they don’t (they are Disjoint). For geography – tolerance is 0.00001 meters (so any points that close are considered to intersect)
-
class
geoalchemy2.functions.
ST_IsValid
(*args, **kwargs)¶ Returns
True
if theST_Geometry
is well formed.
-
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)
-
class
geoalchemy2.functions.
ST_LineLocatePoint
(*args, **kwargs)¶ Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.
-
class
geoalchemy2.functions.
ST_LineMerge
(*args, **kwargs)¶ Returns a (set of) LineString(s) formed by sewing together the constituent line work of a MULTILINESTRING.
see http://postgis.net/docs/ST_LineMerge.html
Return type:
geoalchemy2.types.Geometry
.-
type
¶ alias of
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_LineSubstring
(*args, **kwargs)¶ Return a linestring being a substring of the input one starting and ending at the given fractions of total 2d length. Second and third arguments are float8 values between 0 and 1. This only works with LINESTRINGs. To use with contiguous MULTILINESTRINGs use in conjunction with ST_LineMerge.If ‘start’ and ‘end’ have the same value this is equivalent to ST_LineInterpolatePoint.
see http://postgis.net/docs/ST_LineSubstring.html
Return type:
geoalchemy2.types.Geometry
.-
type
¶ alias of
geoalchemy2.types.Geometry
-
-
class
geoalchemy2.functions.
ST_NPoints
(*args, **kwargs)¶ Return the number of points (vertices) in a geometry.
-
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.
-
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.
-
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.
-
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
geoalchemy2.types.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.
-
class
geoalchemy2.functions.
ST_SRID
(*args, **kwargs)¶ Returns the spatial reference identifier for the
ST_Geometry
as defined inspatial_ref_sys
table.
-
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
geoalchemy2.types.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.
-
class
geoalchemy2.functions.
ST_Transform
(*args, **kwargs)¶ Return 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
geoalchemy2.types.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
geoalchemy2.types.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 tofalse
, then all pixels include nodata pixels are considered to intersect and return value. Ifexclude_nodata_value
is not passed in then reads it from metadata of raster.
-
class
geoalchemy2.functions.
ST_Width
(*args, **kwargs)¶ Returns the width of the raster in pixels.
-
class
geoalchemy2.functions.
ST_Within
(*args, **kwargs)¶ Returns
True
if the geometry A is completely inside geometry B
-
class
geoalchemy2.functions.
ST_X
(*args, **kwargs)¶ Return the X coordinate of the point, or
None
if not available. Input must be a point.
-
class
geoalchemy2.functions.
ST_Y
(*args, **kwargs)¶ Return the Y coordinate of the point, or
None
if not available. Input must be a point.
-
class
geoalchemy2.functions.
ST_Z
(*args, **kwargs)¶ Return the Z coordinate of the point, or
None
if not available. Input must be a point.