Adding distanceTo method to all geometry types. This calculates the shortest distance between any two geometries. For geometries that are entirely contained within polygons, the distance returned will be the distance to the nearest edge. Set the edge option to false to return 0 in cases where one geometry contains another. Details about the distance calculation can be returned by setting the details option true. Details include information about endpoints of the shortest segment between the two geometries. r=ahocevar (closes #1907)

git-svn-id: http://svn.openlayers.org/trunk/openlayers@8836 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Geometry.js

@@ -128,6 +128,28 @@ OpenLayers.Geometry = OpenLayers.Class({
         //
     },
     
+    /**
+     * APIMethod: distanceTo
+     * Calculate the closest distance between two geometries.
+     *
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>} The target geometry.
+     * options - {Object} Optional properties for configuring the distance
+     *     calculation.
+     *
+     * Valid options depend on the specific geometry type.
+     * 
+     * Returns:
+     * {Number | Object} The distance between this geometry and the target.
+     *     If details is true, the return will be an object with distance,
+     *     x0, y0, x1, and x2 properties.  The x0 and y0 properties represent
+     *     the coordinates of the closest point on this geometry. The x1 and y1
+     *     properties represent the coordinates of the closest point on the
+     *     target geometry.
+     */
+    distanceTo: function(geometry, options) {
+    },
+    
     /**
      * Method: atPoint
      * Note - This is only an approximation based on the bounds of the 
@@ -296,3 +318,46 @@ OpenLayers.Geometry.segmentsIntersect = function(seg1, seg2, point) {
     }
     return intersection;
 };
+
+/**
+ * Function: OpenLayers.Geometry.distanceToSegment
+ *
+ * Parameters:
+ * point - {Object} An object with x and y properties representing the
+ *     point coordinates.
+ * segment - {Object} An object with x1, y1, x2, and y2 properties
+ *     representing endpoint coordinates.
+ *
+ * Returns:
+ * {Object} An object with distance, x, and y properties.  The distance
+ *     will be the shortest distance between the input point and segment.
+ *     The x and y properties represent the coordinates along the segment
+ *     where the shortest distance meets the segment.
+ */
+OpenLayers.Geometry.distanceToSegment = function(point, segment) {
+    var x0 = point.x;
+    var y0 = point.y;
+    var x1 = segment.x1;
+    var y1 = segment.y1;
+    var x2 = segment.x2;
+    var y2 = segment.y2;
+    var dx = x2 - x1;
+    var dy = y2 - y1;
+    var along = ((dx * (x0 - x1)) + (dy * (y0 - y1))) /
+                (Math.pow(dx, 2) + Math.pow(dy, 2));
+    var x, y;
+    if(along <= 0.0) {
+        x = x1;
+        y = y1;
+    } else if(along >= 1.0) {
+        x = x2;
+        y = y2;
+    } else {
+        x = x1 + along * dx;
+        y = y1 + along * dy;
+    }
+    return {
+        distance: Math.sqrt(Math.pow(x - x0, 2) + Math.pow(y - y0, 2)),
+        x: x, y: y
+    };
+};