nearest-point-on-line Rename point properties

EmilJunker · EmilJunker · commit cd34656269b0 · 2025-12-02T14:33:38.000+01:00
diff --git a/packages/turf-nearest-point-on-line/index.ts b/packages/turf-nearest-point-on-line/index.ts
@@ -22,7 +22,7 @@ import { getCoord, getCoords } from "@turf/invariant";
  * @param {Geometry|Feature<Point>|number[]} inputPoint Point to snap from
  * @param {Object} [options={}] Optional parameters
  * @param {Units} [options.units='kilometers'] Supports all valid Turf {@link https://turfjs.org/docs/api/types/Units Units}
- * @returns {Feature<Point>} closest point on the `line` to `point`. The properties object will contain four values: `index`: closest point was found on nth line part, `multiFeatureIndex`: closest point was found on the nth line of the `MultiLineString`, `dist`: distance between pt and the closest point, `location`: distance along the line between start and the closest point, `multiFeatureLocation`: distance along the line between start of the `MultiLineString` where closest point was found and the closest point.
+ * @returns {Feature<Point>} closest point on the `lines` to the `inputPoint`. The point will have the following properties: `lineStringIndex`: closest point was found on the nth LineString (only relevant if input is MultiLineString), `segmentIndex`: closest point was found on nth line segment of the LineString, `totalDistance`: distance along the line from the absolute start of the MultiLineString, `lineDistance`: distance along the line from the start of the LineString where the closest point was found, `segmentDistance`: distance along the line from the start of the line segment where the closest point was found, `pointDistance`: distance to the input point.
  * @example
  * var line = turf.lineString([
  *     [-77.031669, 38.878605],
@@ -47,11 +47,12 @@ function nearestPointOnLine<G extends LineString | MultiLineString>(
 ): Feature<
   Point,
   {
-    dist: number;
-    index: number;
-    multiFeatureIndex: number;
-    location: number;
-    multiFeatureLocation: number;
+    lineStringIndex: number;
+    segmentIndex: number;
+    totalDistance: number;
+    lineDistance: number;
+    segmentDistance: number;
+    pointDistance: number;
     [key: string]: any;
   }
 > {
@@ -61,21 +62,13 @@ function nearestPointOnLine<G extends LineString | MultiLineString>(
 
   const inputPos = getCoord(inputPoint);
 
-  let closestPt: Feature<
-    Point,
-    {
-      dist: number;
-      index: number;
-      multiFeatureIndex: number;
-      location: number;
-      multiFeatureLocation: number;
-    }
-  > = point([Infinity, Infinity], {
-    dist: Infinity,
-    index: -1,
-    multiFeatureIndex: -1,
-    location: -1,
-    multiFeatureLocation: -1,
+  let closestPt = point([Infinity, Infinity], {
+    lineStringIndex: -1,
+    segmentIndex: -1,
+    totalDistance: -1,
+    lineDistance: -1,
+    segmentDistance: -1,
+    pointDistance: Infinity,
   });
 
   let length = 0.0;
@@ -122,24 +115,20 @@ function nearestPointOnLine<G extends LineString | MultiLineString>(
           );
         }
 
-        const lineLocationDist = distance(start, intersectPos, options);
-        const intersectPt = point(intersectPos, {
-          dist: distance(inputPoint, intersectPos, options),
-          multiFeatureIndex: multiFeatureIndex,
-          location: length + lineLocationDist,
-          multiFeatureLocation: multiFeatureLength + lineLocationDist,
-        });
-
-        if (intersectPt.properties.dist < closestPt.properties.dist) {
-          closestPt = {
-            ...intersectPt,
-            properties: {
-              ...intersectPt.properties,
-              // Legacy behaviour where index progresses to next segment # if we
-              // went with the end point this iteration.
-              index: wasEnd ? i + 1 : i,
-            },
-          };
+        const pointDistance = distance(inputPoint, intersectPos, options);
+
+        if (pointDistance < closestPt.properties.pointDistance) {
+          const lineLocationDist = distance(start, intersectPos, options);
+          closestPt = point(intersectPos, {
+            lineStringIndex: multiFeatureIndex,
+            // Legacy behaviour where index progresses to next segment
+            // if we went with the end point this iteration.
+            segmentIndex: wasEnd ? i + 1 : i,
+            totalDistance: length + lineLocationDist,
+            lineDistance: multiFeatureLength + lineLocationDist,
+            segmentDistance: lineLocationDist,
+            pointDistance: pointDistance,
+          });
         }
 
         // update length and multiFeatureLength
diff --git a/packages/turf-nearest-point-on-line/test.ts b/packages/turf-nearest-point-on-line/test.ts
@@ -37,13 +37,16 @@ test("turf-nearest-point-on-line", (t) => {
   for (const { name, filename, geojson } of fixtures) {
     const [line, point] = geojson.features;
     const onLine = nearestPointOnLine(line, point);
-    onLine.properties["marker-color"] = "#F0F";
-    onLine.properties.dist = round(onLine.properties.dist, 6);
-    onLine.properties.location = round(onLine.properties.location, 6);
-    onLine.properties.multiFeatureLocation = round(
-      onLine.properties.multiFeatureLocation,
+    onLine.geometry.coordinates[0] = round(onLine.geometry.coordinates[0], 6);
+    onLine.geometry.coordinates[1] = round(onLine.geometry.coordinates[1], 6);
+    onLine.properties.totalDistance = round(onLine.properties.totalDistance, 6);
+    onLine.properties.lineDistance = round(onLine.properties.lineDistance, 6);
+    onLine.properties.segmentDistance = round(
+      onLine.properties.segmentDistance,
       6
     );
+    onLine.properties.pointDistance = round(onLine.properties.pointDistance, 6);
+    onLine.properties["marker-color"] = "#F0F";
     const between = lineString(
       [onLine.geometry.coordinates, point.geometry.coordinates],
       { stroke: "#F00", "stroke-width": 6 }
@@ -79,9 +82,9 @@ test("turf-nearest-point-on-line - first point", (t) => {
     "pt on start does not move"
   );
   t.equal(
-    Number(snapped.properties.location.toFixed(6)),
+    Number(snapped.properties.totalDistance.toFixed(6)),
     0,
-    "properties.location"
+    "properties.totalDistance"
   );
 
   t.end();
@@ -108,7 +111,7 @@ test("turf-nearest-point-on-line - points behind first point", (t) => {
       first.geometry.coordinates,
       "pt behind start moves to first vertex"
     );
-    expectedLocation.push(Number(snapped.properties.location.toFixed(6)));
+    expectedLocation.push(Number(snapped.properties.totalDistance.toFixed(6)));
   });
 
   const filepath =
@@ -117,7 +120,7 @@ test("turf-nearest-point-on-line - points behind first point", (t) => {
   t.deepEqual(
     loadJsonFileSync(filepath),
     expectedLocation,
-    "properties.location"
+    "properties.totalDistance"
   );
   t.end();
 });
@@ -146,7 +149,7 @@ test("turf-nearest-point-on-line - points in front of last point", (t) => {
       last.geometry.coordinates,
       "pt behind start moves to last vertex"
     );
-    expectedLocation.push(Number(snapped.properties.location.toFixed(6)));
+    expectedLocation.push(Number(snapped.properties.totalDistance.toFixed(6)));
   });
 
   const filepath =
@@ -155,7 +158,7 @@ test("turf-nearest-point-on-line - points in front of last point", (t) => {
   t.deepEqual(
     loadJsonFileSync(filepath),
     expectedLocation,
-    "properties.location"
+    "properties.totalDistance"
   );
   t.end();
 });
@@ -209,7 +212,9 @@ test("turf-nearest-point-on-line - points on joints", (t) => {
           "pt on joint stayed in place"
         );
         if (!expectedLocation[i]) expectedLocation[i] = [];
-        expectedLocation[i][j] = Number(snapped.properties.location.toFixed(6));
+        expectedLocation[i][j] = Number(
+          snapped.properties.totalDistance.toFixed(6)
+        );
       });
   });
 
@@ -218,7 +223,7 @@ test("turf-nearest-point-on-line - points on joints", (t) => {
   t.deepEqual(
     expectedLocation,
     loadJsonFileSync(filepath),
-    "properties.location"
+    "properties.totalDistance"
   );
   t.end();
 });
@@ -249,7 +254,7 @@ test("turf-nearest-point-on-line - points on top of line", (t) => {
     const snapped = nearestPointOnLine(line, pt, { units: "miles" });
     const shift = distance(pt, snapped, { units: "miles" });
     t.true(shift < 0.000001, "pt did not shift far");
-    expectedLocation.push(Number(snapped.properties.location.toFixed(6)));
+    expectedLocation.push(Number(snapped.properties.totalDistance.toFixed(6)));
   }
 
   const filepath =
@@ -258,7 +263,7 @@ test("turf-nearest-point-on-line - points on top of line", (t) => {
   t.deepEqual(
     expectedLocation,
     loadJsonFileSync(filepath),
-    "properties.location"
+    "properties.totalDistance"
   );
   t.end();
 });
@@ -324,11 +329,11 @@ test("turf-nearest-point-on-line - check dist and index", (t) => {
   const pt = point([-92.110576, 41.040649]);
   const snapped = truncate(nearestPointOnLine(line, pt));
 
-  t.equal(snapped.properties.index, 8, "properties.index");
+  t.equal(snapped.properties.segmentIndex, 8, "properties.segmentIndex");
   t.equal(
-    Number(snapped.properties.dist.toFixed(6)),
+    Number(snapped.properties.pointDistance.toFixed(6)),
     0.823802,
-    "properties.dist"
+    "properties.pointDistance"
   );
   t.deepEqual(
     snapped.geometry.coordinates,
@@ -346,9 +351,9 @@ test("turf-nearest-point-on-line -- Issue #691", (t) => {
     [9, 50],
   ]);
   const pointAlong = along(line1, 10);
-  const { location } = nearestPointOnLine(line1, pointAlong).properties;
+  const { totalDistance } = nearestPointOnLine(line1, pointAlong).properties;
 
-  t.false(isNaN(location));
+  t.false(isNaN(totalDistance));
   t.end();
 });
 
@@ -396,9 +401,9 @@ test("turf-nearest-point-on-line -- multifeature index", (t) => {
     ],
   ]);
   t.equal(
-    nearestPointOnLine(multiLine.geometry, pt).properties.multiFeatureIndex,
+    nearestPointOnLine(multiLine.geometry, pt).properties.lineStringIndex,
     1,
-    "multiFeatureIndex"
+    "properties.lineStringIndex"
   );
   t.end();
 });
@@ -422,14 +427,14 @@ test("turf-nearest-point-on-line -- issue 2753 multifeature location", (t) => {
   const nearestToB = nearestPointOnLine(multiLine, ptB, { units: "meters" });
 
   t.equal(
-    Number(nearestToA.properties.multiFeatureLocation.toFixed(6)),
+    Number(nearestToA.properties.lineDistance.toFixed(6)),
     150.296465,
-    "nearestToA multiFeatureLocation"
+    "nearestToA lineDistance"
   );
   t.equal(
-    Number(nearestToB.properties.multiFeatureLocation.toFixed(6)),
+    Number(nearestToB.properties.lineDistance.toFixed(6)),
     157.738215,
-    "nearestToB multiFeatureLocation"
+    "nearestToB lineDistance"
   );
   t.end();
 });
@@ -549,7 +554,7 @@ test("turf-nearest-point-on-line -- issue 2808 redundant point support", (t) =>
   const thePoint = point([10.57846, 49.8468386]);
 
   const nearest = nearestPointOnLine(line1, thePoint); // should not throw
-  t.equal(nearest.properties.dist, 0, "redundant point should not throw");
+  t.equal(nearest.properties.pointDistance, 0, "redundant point support");
 
   t.end();
 });
@@ -563,8 +568,8 @@ test("turf-nearest-point-on-line -- duplicate points on line string shouldn't br
   ]);
   const userPoint = point([-80.191762, 25.885587]);
   const nearest = nearestPointOnLine(line, userPoint, { units: "meters" });
-  t.equal(nearest.properties.dist > 4, true, "dist should be greater than 4");
-  t.equal(nearest.properties.location, 0, "location should be 0");
+  t.equal(nearest.properties.pointDistance > 4, true, "pointDistance be > 4");
+  t.equal(nearest.properties.totalDistance, 0, "totalDistance be 0");
   t.end();
 });
 
diff --git a/packages/turf-nearest-point-on-line/test/out/line-northern-latitude-#344.geojson b/packages/turf-nearest-point-on-line/test/out/line-northern-latitude-#344.geojson
@@ -39,11 +39,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 5.959562,
-        "multiFeatureIndex": 0,
-        "location": 19.748879,
-        "multiFeatureLocation": 19.748879,
-        "index": 1,
+        "lineStringIndex": 0,
+        "segmentIndex": 1,
+        "totalDistance": 19.748879,
+        "lineDistance": 19.748879,
+        "segmentDistance": 1.771897,
+        "pointDistance": 5.959562,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/line1.geojson b/packages/turf-nearest-point-on-line/test/out/line1.geojson
@@ -39,11 +39,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 2.556271,
-        "multiFeatureIndex": 0,
-        "location": 22.137494,
-        "multiFeatureLocation": 22.137494,
-        "index": 1,
+        "lineStringIndex": 0,
+        "segmentIndex": 1,
+        "totalDistance": 22.137494,
+        "lineDistance": 22.137494,
+        "segmentDistance": 3.445915,
+        "pointDistance": 2.556271,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/multiLine1.geojson b/packages/turf-nearest-point-on-line/test/out/multiLine1.geojson
@@ -67,11 +67,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 114.725451,
-        "index": 21,
-        "multiFeatureIndex": 1,
-        "location": 9479.011715,
-        "multiFeatureLocation": 4800.716022,
+        "lineStringIndex": 1,
+        "segmentIndex": 21,
+        "totalDistance": 9479.011715,
+        "lineDistance": 4800.716022,
+        "segmentDistance": 173.221741,
+        "pointDistance": 114.725451,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/multiLine2.geojson b/packages/turf-nearest-point-on-line/test/out/multiLine2.geojson
@@ -48,11 +48,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 390.942725,
-        "index": 0,
-        "multiFeatureIndex": 1,
-        "location": 1656.139708,
-        "multiFeatureLocation": 0,
+        "lineStringIndex": 1,
+        "segmentIndex": 0,
+        "totalDistance": 1656.139708,
+        "lineDistance": 0,
+        "segmentDistance": 0,
+        "pointDistance": 390.942725,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/multiLine3.geojson b/packages/turf-nearest-point-on-line/test/out/multiLine3.geojson
@@ -57,11 +57,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 121.937841,
-        "multiFeatureIndex": 0,
-        "location": 214.735285,
-        "multiFeatureLocation": 214.735285,
-        "index": 0,
+        "lineStringIndex": 0,
+        "segmentIndex": 0,
+        "totalDistance": 214.735285,
+        "lineDistance": 214.735285,
+        "segmentDistance": 214.735285,
+        "pointDistance": 121.937841,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/route1.geojson b/packages/turf-nearest-point-on-line/test/out/route1.geojson
@@ -4792,11 +4792,12 @@
     {
       "type": "Feature",
       "properties": {
-        "dist": 7.876557,
-        "multiFeatureIndex": 0,
-        "location": 183.46844,
-        "multiFeatureLocation": 183.46844,
-        "index": 3104,
+        "lineStringIndex": 0,
+        "segmentIndex": 3104,
+        "totalDistance": 183.46844,
+        "lineDistance": 183.46844,
+        "segmentDistance": 0.044741,
+        "pointDistance": 7.876557,
         "marker-color": "#F0F"
       },
       "geometry": {
diff --git a/packages/turf-nearest-point-on-line/test/out/route2.geojson b/packages/turf-nearest-point-on-line/test/out/route2.geojson
