Merge pull request #917 from Turbo87/segment-distance

Geometry: Added distanceSquaredToSegment() function

lib/OpenLayers/Geometry.js

@@ -438,12 +438,39 @@ OpenLayers.Geometry.segmentsIntersect = function(seg1, seg2, options) {
  *     representing endpoint coordinates.
  *
  * Returns:
- * {Object} An object with distance, x, and y properties.  The distance
+ * {Object} An object with distance, along, 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.
+ *     where the shortest distance meets the segment. The along attribute
+ *     describes how far between the two segment points the given point is.
  */
 OpenLayers.Geometry.distanceToSegment = function(point, segment) {
+    var result = OpenLayers.Geometry.distanceSquaredToSegment(point, segment);
+    result.distance = Math.sqrt(result.distance);
+    return result;
+};
+
+/**
+ * Function: OpenLayers.Geometry.distanceSquaredToSegment
+ *
+ * Usually the distanceToSegment function should be used. This variant however
+ * can be used for comparisons where the exact distance is not important.
+ *
+ * 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 squared distance, along, 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. The along
+ *     attribute describes how far between the two segment points the given
+ *     point is.
+ */
+OpenLayers.Geometry.distanceSquaredToSegment = function(point, segment) {
     var x0 = point.x;
     var y0 = point.y;
     var x1 = segment.x1;
@@ -466,7 +493,8 @@ OpenLayers.Geometry.distanceToSegment = function(point, segment) {
         y = y1 + along * dy;
     }
     return {
-        distance: Math.sqrt(Math.pow(x - x0, 2) + Math.pow(y - y0, 2)),
+        distance: Math.pow(x - x0, 2) + Math.pow(y - y0, 2),
-        x: x, y: y
+        x: x, y: y,
+        along: along
     };
 };

tests/Geometry.html

@@ -257,24 +257,23 @@
 
         var cases = [{
             got: dist({x: 0, y: 0}, {x1: 0, y1: 1, x2: 1, y2: 1}),
-            expected: {distance: 1, x: 0, y: 1}
+            expected: {distance: 1, x: 0, y: 1, along: 0}
         }, {
             got: dist({x: 0, y: 0}, {x1: -1, y1: -1, x2: 0, y2: -1}),
-            expected: {distance: 1, x: 0, y: -1}
+            expected: {distance: 1, x: 0, y: -1, along: 1}
         }, {
             got: dist({x: 0, y: 0}, {x1: -1, y1: -1, x2: 1, y2: 1}),
-            expected: {distance: 0, x: 0, y: 0}
+            expected: {distance: 0, x: 0, y: 0, along: 0.5}
         }, {
             got: dist({x: 1, y: 1}, {x1: 2, y1: 0, x2: 2, y2: 3}),
-            expected: {distance: 1, x: 2, y: 1}
+            expected: {distance: 1, x: 2, y: 1, along: 1/3.}
         }, {
             got: dist({x: -1, y: -1}, {x1: -2, y1: -2, x2: -1, y2: -3}),
-            expected: {distance: Math.sqrt(2), x: -2, y: -2}
+            expected: {distance: Math.sqrt(2), x: -2, y: -2, along: 0}
         }, {
             got: dist({x: -1, y: 1}, {x1: -3, y1: 1, x2: -1, y2: 3}),
-            expected: {distance: Math.sqrt(2), x: -2, y: 2}
+            expected: {distance: Math.sqrt(2), x: -2, y: 2, along: 0.5}
         }];
-        
         t.plan(cases.length);
         for(var i=0; i<cases.length; ++i) {
             t.eq(cases[i].got, cases[i].expected, "case " + i);