Geo Module A geospatial API w3c-designation EXPath Candidate 30 September 2010 XML Peter Rushforth http://geofunctions.org

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.

Must be ignored, but is required by the schema...

 langusage

revisiondesc
Introduction

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)

Namespace conventions

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 management

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

 Description

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.

 General functions 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.

 Spatial predicate functions 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.

 Analysis functions 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.

 Functions specific to geometry type GeometryCollection 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.

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

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

LineString, Line, LinearRing

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

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.

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

 Polygon 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, MultiPolygon

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.

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