@turf/nearest-point-on-line/dist/esm/index.d.ts

Finds the nearest point on a line to a given point

import { LineString, MultiLineString, Feature, Point } from 'geojson';
import { Coord, Units } from '@turf/helpers';

/**
 * 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.
 *
 * @function
 * @param {Geometry|Feature<LineString|MultiLineString>} lines Lines to snap to
 * @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 `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],
 *     [-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';
 */
declare function nearestPointOnLine<G extends LineString | MultiLineString>(lines: Feature<G> | G, inputPoint: Coord, options?: {
    units?: Units;
}): Feature<Point, {
    lineStringIndex: number;
    segmentIndex: number;
    totalDistance: number;
    lineDistance: number;
    segmentDistance: number;
    pointDistance: number;
    /** @deprecated use `lineStringIndex` instead */
    multiFeatureIndex: number;
    /** @deprecated use `segmentIndex` instead */
    index: number;
    /** @deprecated use `totalDistance` instead */
    location: number;
    /** @deprecated use `pointDistance` instead */
    dist: number;
    [key: string]: any;
}>;

export { nearestPointOnLine as default, nearestPointOnLine };