Geo Module

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

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

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

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

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

6 Functions specific to geometry type

num-geometries($geometry-collection as node()) as xs:integer

geometry-n($geometry-collection as node()) as node()

x($point as node()) as xs:double

y($point as node()) as xs:double

z($point as node()) as xs:double?

m($point as node()) as xs:double?

length($curve as node()) as xs:double

start-point($curve as node()) as element(gml:Point)

end-point($curve as node()) as element(gml:Point)

is-closed($curve as node()) as xs:boolean

is-ring($curve as node()) as xs:boolean

num-points($line-string as node()) as xs:integer

point-n($line-string as node(), 
        $n as xs:integer) as node()

is-closed($multi-line-string as node()) as xs:boolean

length($multi-line-string as node()) as xs:double

area($surface as node()) as xs:double

centroid($surface as node()) as node()

point-on-surface($surface as node()) as node()

num-patches($polyhedral-surface as node()) as xs:integer

patch-n($polyhedral-surface as node(), 
        $n as xs:integer) as node()

bounding-polygons($polyhedral-surface as node(), 
                  $polygon as node()) as gml:Polygon*

is-closed($polyhedral-surface as node()) as xs:boolean

exterior-ring($polygon as node()) as gml:LineString

num-interior-ring($polygon as node()) as xs:integer

interior-ring-n($polygon as node(),
                $n as xs:integer) as gml:LineString

area($multi-surface as node()) as xs:double

centroid($multi-surface as node()) as gml:Point

point-on-surface($multi-surface as node()) as gml:Point