irstv/H2GIS — pull request #62 by agouge (2013-12-04 17:23:54+00:00)
Title: Add distance functions

Here we add the following distance functions:

* `ST_ClosestCoordinate(Point point, Geometry geom)`
* `ST_ClosestPoint(geometry geomA, geometry geomB)`
* `ST_FurthestCoordinate(Point point, Geometry geom)`
* `ST_LocateAlong(Geometry geom, double segmentLengthFraction, double offSet)`

### Comparison to GDMS and PostGIS

#### `ST_ClosestCoordinate`

This function was not a part of GDMS or PostGIS but was added for
completeness (cf. `ST_FurthestCoordinate).`

#### `ST_ClosestPoint`

This new H2GIS function is related to the old GDMS function as follows:
```mysql
ST_ClosestPoint(geomA, geomB) = ST_NearestPoints(geomB, geomA)
```
(Note the reversed order.) It returns the 2D point on `geomA` closest to geomB.
Note that the GDMS function `ST_ProjectTo` is just a special case:
```mysql
ST_ClosestPoint((multi)linestring, point) = ST_ProjectTo(point, (multi)linestring)
```
For this reason, we will not implement `ST_ProjectTo` in H2GIS.

*Note*: If the closest point on geomA is not unique (it is easy to imagine an
example where there are infinitely many, mathematically speaking), the point
returned by `ST_ClosestPoint` depends on the orientations of geometries A and
B. If they have the same orientation, the point returned is the first point
found in A. If they have opposite orientation, the point returned is the point
of A closest to the first point found in B. See the unit test.

*Note*: PostGIS has 3D support. See
http://www.postgis.org/docs/ST_3DClosestPoint.html

TODO?: Add `ST_FurthestPoint?` (This is not implemented in JTS)

#### `ST_FurthestCoordinate`

If the furthest coordinate is not unique, we return all furthest coordinates in
a `MULTIPOINT`. If it is unique, it is returned as a `POINT`. (In the java code,
the return type is `Puntal`.)

#### `ST_LocateAlong`

Note: PostGIS does not support polygonal elements. Also their examples
don't seem to correspond to their function signature. See
http://postgis.refractions.net/docs/ST_LocateAlong.html

*TODO?*: Should we take holes into account for polygons? For now we consider
only the exterior ring, but it would be pretty easy to add the holes. @gpetit

### Table

| GDMS | PostGIS | H2GIS |
|------|---------|-------|
| ---	| ---	| `ST_ClosestCoordinate(Point point, Geometry geom)` |
| `ST_NearestPoints(Geometry geomB, Geometry geomA)`	| `ST_ClosestPoint(geometry geomA, geometry geomB)`	| `ST_ClosestPoint(geometry geomA, geometry geomB)` |
| `ST_ProjectTo(Geometry point, Geometry (multi)lineString)`	| `ST_ClosestPoint(Geometry (multi)lineString, Geometry point)`	| `ST_ClosestPoint(Geometry (multi)lineString, Geometry point)` |
| `ST_FurthestPoint(Point point, Geometry geom)`	| ---	| `ST_FurthestCoordinate(Point point, Geometry geom)` |
| `ST_LocateAlong(Geometry geom, double segmentLengthFraction, double offSet)`	| `ST_LocateAlong(Geometry geom, float a_measure, float offset)` |	`ST_LocateAlong(Geometry geom, double segmentLengthFraction, double offSet)` |