- This version:
- http://expath.org/spec/geo/20100930
- Latest version:
- http://expath.org/spec/geo
- Editor:
- Peter Rushforth, http://geofunctions.org

This document is also available in these non-normative formats: XML.

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.

1 Introduction

1.1 Namespace conventions

1.2 Error management

2 Description

3 General functions

4 Spatial predicate functions

5 Analysis functions

6 Functions specific to geometry type

6.1 GeometryCollection

6.2 Point

6.3 Curve

6.3.1 LineString, Line, LinearRing

6.4 MultiLineString

6.5 Surface

6.6 Polygon

6.7 MultiSurface, MultiPolygon

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.

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:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:gml="http://www.opengis.net/gml" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:geo="http://expath.org/ns/geo" xmlns:road="http://example.gov/roadworks" version="2.0"> <xsl:output method="text"/> <xsl:variable name="bbox"> <gml:Envelope> <gml:lowerCorner><gml:pos>-63.1335096 46.231024</gml:pos></gml:lowerCorner> <gml:upperCorner><gml:pos>-63.1175626 46.232928</gml:pos></gml:upperCorner> </gml:Envelope> </xsl:variable> <xsl:template match="kml:Placemark[geo:intersects(kml:LineString,$bbox)]"> <!-- convert Placemarks to a CSV record --> <xsl:value-of separator=", " select=" kml:name, kml:ExtendedData/road:PavementType, geo:length(kml:LineString)"/> </xsl:template> </xsl:stylesheet>

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.

`dimension`

($geometry as`node()`

) as`xs:integer?`

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.

`coordinate-dimension`

($geometry as`node()`

) as`xs:integer`

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)`

.

`geometry-type`

($geometry as`node()`

) as`xs:QName?`

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`

.

`srid`

($geometry as`node()`

) as`xs:anyURI?`

Returns the URI of the CRS of the geometry, or the empty sequence if unknown.

`envelope`

($geometry as`node()`

) as`element(gml:Envelope)?`

Returns the gml:Envelope of the specified geometry.

`as-text`

($geometry as`node()`

) as`xs:string?`

Returns the WKT representation of the geometry.

`as-binary`

($geometry as`node()`

) as`xs:base64Binary?`

Returns the base64-encoded Well Known Binary (WKB) representation of the geometry.

`is-empty`

($geometry as`node()`

) as`xs:boolean`

Returns whether the geometry is empty.

`is-simple`

($geometry as`node()`

) as`xs:boolean`

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)).

`is-3d`

($geometry as`node()`

) as`xs:boolean`

Returns whether the geometry has z values.

`is-measured`

($geometry as`node()`

) as`xs:boolean`

Returns whether the geometry has m values.

`boundary`

($geometry as`node()`

) as`element()*`

Returns the boundary of the geometry, in GML. The return value is a sequence of either
`gml:Point`

or `gml:LinearRing`

elements.

`equals`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

is spatially equal to `$another-geometry`

.

`disjoint`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

is spatially disjoint from `$another-geometry`

.

`intersects`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

spatially intersects `$another-geometry`

.

`touches`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

spatially touches `$another-geometry`

.

`crosses`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

spatially crosses `$another-geometry`

.

`within`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

is spatially within `$another-geometry`

.

`contains`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

spatially contains `$another-geometry`

.

`overlaps`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:boolean`

Returns whether `$geometry`

spatially overlaps `$another-geometry`

.

`relate`

($geometry as`node()`

, $another-geometry as`node()`

, $intersection-matrix-pattern as`xs:string`

) as`xs:boolean`

Returns whether relationships between the boundaries, interiors and exteriors of
`$geometry`

and `$another-geometry`

match the pattern specified
in `$intersection-matrix-pattern`

.

`distance`

($geometry as`node()`

, $another-geometry as`node()`

) as`xs:double`

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.

`buffer`

($geometry as`node()`

, $distance as`xs:double`

) as`element()*`

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`

.

`convex-hull`

($geometry as`node()`

) as`element()?`

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`

.

`intersection`

($geometry as`node()`

, $another-geometry as`node()`

) as`element()?`

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`

.

`union`

($geometry as`node()`

, $another-geometry as`node()`

) as`element()?`

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
```

.

`difference`

($geometry as`node()`

, $another-geometry as`node()`

) as`element()?`

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`

.

`sym-difference`

($geometry as`node()`

, $another-geometry as`node()`

) as`element()?`

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`

.

`num-geometries`

($geometry-collection as`node()`

) as`xs:integer`

Returns the number of geometries in `$geometry-collection`

.

`geometry-n`

($geometry-collection as`node()`

) as`node()`

Returns the Nth geometry in `$geometry-collection`

, in GML.

`x`

($point as`node()`

) as`xs:double`

Returns the x-coordinate value for `$point`

.

`y`

($point as`node()`

) as`xs:double`

Returns the y-coordinate value for `$point`

.

`z`

($point as`node()`

) as`xs:double?`

Returns the z-coordinate value for `$point`

, or the empty sequence.

`m`

($point as`node()`

) as`xs:double?`

Returns the m-coordinate value for `$point`

, or the empty sequence.

`length`

($curve as`node()`

) as`xs:double`

Returns the length of `$curve`

.

`start-point`

($curve as`node()`

) as`element(gml:Point)`

Returns the starting point of `$curve`

.

`end-point`

($curve as`node()`

) as`element(gml:Point)`

Returns the end point point of `$curve`

.

`is-closed`

($curve as`node()`

) as`xs:boolean`

Returns true if the curve is closed (start point equals end point).

`is-ring`

($curve as`node()`

) as`xs:boolean`

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):

`num-points`

($line-string as`node()`

) as`xs:integer`

Returns the number of points in the `$line-string`

. A Line is a
LineString with exactly two points. See above for definition of LinearRing.

`point-n`

($line-string as`node()`

, $n as`xs:integer`

) as`node()`

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:

`is-closed`

($multi-line-string as`node()`

) as`xs:boolean`

Returns true if the start point = end point for each `gml:LineString`

in
`$line-string`

.

`length`

($multi-line-string as`node()`

) as`xs:double`

Returns the length of `$multi-line-string`

which is equal to the sum of
the lengths of the component `gml:LineStrings`

.

`area`

($surface as`node()`

) as`xs:double`

Returns the area of `$surface`

in units of its spatial reference system.

`centroid`

($surface as`node()`

) as`node()`

Returns the mathematical centroid of `$surface`

as a
`gml:Point`

. The point is not guaranteed to be on the
`$surface`

.

`point-on-surface`

($surface as`node()`

) as`node()`

Returns a `gml:Point`

guaranteed to be on `$surface`

.

`num-patches`

($polyhedral-surface as`node()`

) as`xs:integer`

Returns the number of component polygons in `$polyhedral-surface`

.

`patch-n`

($polyhedral-surface as`node()`

, $n as`xs:integer`

) as`node()`

Returns the `$n`

-th `gml:Polygon`

in the
`$polyhedral-surface`

.

`bounding-polygons`

($polyhedral-surface as`node()`

, $polygon as`node()`

) as`gml:Polygon*`

Returns a sequence of polygons in `$polyhedral-surface`

that bound the
given `$polygon`

, where `$polygon`

is any polygon in the
surface.

`is-closed`

($polyhedral-surface as`node()`

) as`xs:boolean`

Returns true if the `$polyhedral-surface`

closes on itself, and thus has
no boundary and encloses a solid.

`exterior-ring`

($polygon as`node()`

) as`gml:LineString`

Returns the outer ring of `$polygon`

, in GML.

`num-interior-ring`

($polygon as`node()`

) as`xs:integer`

Returns the number of interior rings in `$polygon`

.

`interior-ring-n`

($polygon as`node()`

, $n as`xs:integer`

) as`gml:LineString`

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:

`area`

($multi-surface as`node()`

) as`xs:double`

Returns the area of `$multi-surface`

in units of its spatial reference system.

`centroid`

($multi-surface as`node()`

) as`gml:Point`

Returns the mathematical centroid of `$multi-surface`

as a
`gml:Point`

. The point is not guaranteed to be on the
`$multi-surface`

.

`point-on-surface`

($multi-surface as`node()`

) as`gml:Point`

Returns a point guaranteed to be on `$multi-surface`

, in GML.

- OGC Simple Feature Access
- Open Geospatial Consortium, Simple Feature access, Part 1 Common Architecture. John R. Herring, Editor
- OGC Geography Markup Language
- OpenGIS Geography Markup Language (GML) Encoding Standard. Clemens Portele, Editor
- OGC Simple Feature SQL Option
- OpenGIS Implementation Specification for Geographic information - Simple feature access - Part 2: SQL option . John R. Herring, Editor
- OGC KML
- OGC KML. Tim Wilson, Editor