@turf/nearest-point-on-line

nearestPointOnLine

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

• lines (Geometry | Feature<(LineString | MultiLineString)>) Lines to snap to

• inputPoint (Geometry | Feature<Point> | Array<number>) Point to snap from

• options Object Optional parameters (optional, default {})

  • options.units Units Supports all valid Turf Units (optional, default 'kilometers')

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'});

//addToMap
var addToMap = [line, inputPoint, snapped];
snapped.properties['marker-color'] = '#00f';

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.

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

Installation

Install this single module individually:

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

Or install the all-encompassing @turf/turf module that includes all modules as functions:

$ npm install @turf/turf