This proposal provides a geospatial API function interface for XPath 2.0. It defines commonly used and implemented function signatures from the Open Geospatial Consortium Simple Features Common Access API version 1.2, and has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other XPath 2.0 usage.
The EXPath Geo module defines functions that may be applied to well-formed valid geometries conforming to the Open Geospatial Consortium (OGC) Simple Feature (SF) data model. Typically, such features will be encoded as Geography Markup Language geometries. Other encodings, for example KML, may also be supported by an implementation.
Consult the OGC SF specification for a complete description of the data model and API. (OGC 06-103r3)
The module defined by this document defines functions in the namespace
http://expath.org/ns/geo. In this document, the geo
prefix, when used, is bound to this namespace URI.
Error codes are defined in the namespace http://expath.org/ns/error. In
this document, the err prefix, when used, is bound to this namespace
URI.
Error conditions are identified by a code (a QName). When such an error
condition is reached during the execution of a function, a dynamic error is thrown,
with the corresponding error code (as if the standard XPath function
error had been called).
This EXPath Geo module specification describes a set of functions which are a transcription of functions of the same name from the Open Geospatial Consoritium (OGC) Simple Feature (SF) access specification, version 1.2.. As such, the function and parameter names use the dash-separated convention. This differs from the capitalization conventions of the SF functions in other specs, such as Simple Features for SQL.
OGC SF is a widely and deeply adopted standard which specifies an object data model for spatial (geometry) types. It is abstract in the sense that it does not prescribe a mapping of that model to a specific technology platform or language. At the same time, it does leverage concrete data types (such as double). Other related specifications describe the mapping of the OGC SF to specific technologies, such as SQL databases, COM or CORBA object environments.
The Open Geospatial Consortium was an early adopter of XML technology. With the notable exception of operations, OGC Geography Markup Language (GML) provides, among other things, a mapping of the Simple Features data model to XML Schema-based XML technology. While GML provides a sophisticated data modelling environment for development of application schemas for creation, validation and transmission of geographic information in XML, there is an obvious requirement to enable standards-based processing of XML-encoded geographic information. While XSLT, and more recently XQuery, combine superb abilities to access data via XPath, and process any aspect of data encoded in XML, they have heretofore not been typically used to process geographic data by the majority of geomatics programmers. This is largely due to a lack of common support for the OGC SF API in the XSLT and XQuery environments. The EXPath geo module aims to provide an independent specification against which XPath 2.0-based languages such as XSLT and XQuery may implement the OGC SF specification. The manner in which the API is implemented is out of scope to the module: the functions might be implemented as XSLT or XQuery functions, or as extension functions ‘built in’ to the language processor for reasons of efficiency. It is hoped that by providing a specification for function syntax and return types, use of the EXPath Geo module will be implementation-independent and thus portable and interoperable.
The data model envisioned by EXPath Geo module is abstract in the sense that it may be possible for module implementers to support more than one encoding on input. Output data types are specified in GML and XML Schema, where appropriate. All that is necessary is that the input geometry be transformable to the model specified by OGC SF and supported by the EXPath implementation. For example, since the KML geometry model is an implementation of some aspects of OGC SF, it could be supported by an EXPath Geo implementation.
As an example, consider an XSLT stylesheet which is designed to selectively transform Placemarks from a KML document within a given bounding box, into a CSV file:
Implementations are not limited to GML, KML, nor even XML, on input. It is possible that geometries encoded as “Well Known Text”, GeoJSON, or even “Well Known Binary”, among other possibilities, could be supported by an implementation.
Returns the number of dimensions of the geometry ie. -1 (null) 0 (point),1 (line),2 (area). Always less than or equal to the dimension of the coordinate space.
Returns the number of dimensions of the coordinate reference system of the geometry.
ie.
2,3,4 dimensional coordinate space; always greater than or equal to the value returned
by dimension($geometry).
Returns the name of the geometry type in the GML namespace, or the empty sequence.
Must
be one of gml:Point, gml:Curve, gml:LineString,
gml:Surface, gml:Polygon, gml:MultiPoint,
gml:MultiCurve, gml:MultiLineString,
gml:MultiSurface, or gml:MultiPolygon.
Returns the URI of the CRS of the geometry, or the empty sequence if unknown.
Returns the gml:Envelope of the specified geometry.
Returns the WKT representation of the geometry.
Returns the base64-encoded Well Known Binary (WKB) representation of the geometry.
Returns whether the geometry is empty.
Returns whether the geometry is simple (ie. does not self-intersect and does not pass through the same point more than once (may be a ring)).
Returns whether the geometry has z values.
Returns whether the geometry has m values.
Returns the boundary of the geometry, in GML. The return value is a sequence of either
gml:Point or gml:LinearRing elements.
Returns whether $geometry is spatially equal to $another-geometry.
Returns whether $geometry is spatially disjoint from $another-geometry.
Returns whether $geometry spatially intersects $another-geometry.
Returns whether $geometry spatially touches $another-geometry.
Returns whether $geometry spatially crosses $another-geometry.
Returns whether $geometry is spatially within $another-geometry.
Returns whether $geometry spatially contains $another-geometry.
Returns whether $geometry spatially overlaps $another-geometry.
Returns whether relationships between the boundaries, interiors and exteriors of
$geometry and $another-geometry match the pattern specified
in $intersection-matrix-pattern.
Returns the shortest distance, in the units of the spatial reference system of
$geometry, between the geometries, where that distance is the distance
between a point on each of the geometries.
Returns a sequence of zero or more polygonal geometries representing the buffer by
$distance of $geometry, in the spatial reference system of
$geometry. The returned elements must be either gml:Polygon
or gml:MultiPolygon.
Returns the convex hull geometry of $geometry in GML, or the empty
sequence. The returned element must be either gml:Polygon,
gml:LineString or gml:Point.
Returns the intersection geometry of $geometry with
$another-geometry, in GML. The returned element must be either
gml:Point, gml:LineString, gml:Polygon,
gml:MultiPoint, gml:MultiLineString or
gml:MultiPolygon.
Returns the union geometry of $geometry with
$another-geometry, in GML. The returned element must be either
gml:Point, gml:Curve, gml:LineString,
gml:Surface, gml:Polygon, gml:MultiPoint,
gml:MultiCurve, gml:MultiLineString or gml:
MultiPolygon.
Returns the difference geometry of $geometry with
$another-geometry, in GML. The returned element must be either
gml:Point, gml:Curve, gml:LineString,
gml:Surface, gml:Polygon, gml:MultiPoint,
gml:MultiCurve, gml:MultiLineString or
gml:MultiPolygon.
Returns the symmetric difference geometry of $geometry with
$another-geometry, in GML. The returned element must be either
gml:Point, gml:Curve, gml:LineString,
gml:Surface, gml:Polygon, gml:MultiPoint,
gml:MultiCurve, gml:MultiLineString or
gml:MultiPolygon.
Returns the number of geometries in $geometry-collection.
Returns the Nth geometry in $geometry-collection, in GML.
Returns the x-coordinate value for $point.
Returns the y-coordinate value for $point.
Returns the z-coordinate value for $point, or the empty sequence.
Returns the m-coordinate value for $point, or the empty sequence.
Returns the length of $curve.
Returns the starting point of $curve.
Returns the end point point of $curve.
Returns true if the curve is closed (start point equals end point).
Returns true if the curve is closed and simple (start point equals end point and does not pass through the same point more than once.
In addition to those functions applicable to all Curves, LineString also defines the following functions (Line and LinearRing being specializations of LineString):
Returns the number of points in the $line-string. A Line is a
LineString with exactly two points. See above for definition of LinearRing.
Returns the Nth point in $line-string, as a gml:Point.
MultiLineString is a subclass of GeometryCollection and so implements functions applicable to that type. In addition, the following functions may be applied to MultiLineString elements:
Returns true if the start point = end point for each gml:LineString in
$line-string.
Returns the length of $multi-line-string which is equal to the sum of
the lengths of the component gml:LineStrings.
Returns the area of $surface in units of its spatial reference system.
Returns the mathematical centroid of $surface as a
gml:Point. The point is not guaranteed to be on the
$surface.
Returns a gml:Point guaranteed to be on $surface.
Returns the number of component polygons in $polyhedral-surface.
Returns the $n-th gml:Polygon in the
$polyhedral-surface.
Returns a sequence of polygons in $polyhedral-surface that bound the
given $polygon, where $polygon is any polygon in the
surface.
Returns true if the $polyhedral-surface closes on itself, and thus has
no boundary and encloses a solid.
Returns the outer ring of $polygon, in GML.
Returns the number of interior rings in $polygon.
Returns the $n-th interior ring of $polygon, in GML.
MultiSurface and MultiPolygon are GeometryCollections, and so implement functions applicable to that type. They also support the following functions:
Returns the area of $multi-surface in units of its spatial reference system.
Returns the mathematical centroid of $multi-surface as a
gml:Point. The point is not guaranteed to be on the
$multi-surface.
Returns a point guaranteed to be on $multi-surface, in GML.