nearestPointOnLine

Description

Returns the nearest point on a line to a given point.

If any of the segments in the input line string are antipodal and therefore have an undefined arc, this function will instead return that the point lies on the line.

⚠️ We have begun the process of migrating to different return properties for this function. The new properties we recommend using as of v7.4 are:

• lineStringIndex - point was found on the nth LineString of an input MultiLineString. Previously multiFeatureIndex
• segmentIndex - point was found on the nth segment of the above LineString. Previously index
• totalDistance - distance from the start of the overall MultiLineString. Previously location
• lineDistance - distance from the start of the relevant LineString
• segmentDistance - distance from the start of the relevant segment
• pointDistance - distance between found point is from input reference point. Previously dist

multiFeatureIndex, index, location, and dist continue to work as previously until at least the next major release.

Parameters

Name	Type	Description
lines	Geometry | Feature<LineString | MultiLineString>	Lines to snap to
inputPoint	Geometry | Feature<Point> | Array<number>	Point to snap from
options?	Object	Optional parameters (default {})
options.units?	Units	Supports all valid Turf Units (default 'kilometers')

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.

Examples

var line = turf.lineString([
  [-77.031669, 38.878605],
  [-77.029609, 38.881946],
  [-77.020339, 38.884084],
  [-77.025661, 38.885821],
  [-77.021884, 38.889563],
  [-77.019824, 38.892368],
]);
var inputPoint = turf.point([-77.037076, 38.884017]);

var snapped = turf.nearestPointOnLine(line, inputPoint, { units: "miles" });

Installation

$ npm install @turf/nearest-point-on-line

import { nearestPointOnLine } from "@turf/nearest-point-on-line";
const result = nearestPointOnLine(...);

$ npm install @turf/turf

import * as turf from "@turf/turf";
const result = turf.nearestPointOnLine(...);