New module @turf/nearest-point-to-line

[stebogit]

/**
 * Returns the closest {@link Point|point}, of a {@link FeatureCollection|collection} of points, to a {@link LineString|line}.
 * The returned point has a `dist` property indicating its distance to the line.
 *
 * @name nearestPointToLine
 * @param {FeatureCollection|GeometryCollection<Point>} points collection
 * @param {Geometry|Feature<LineString>} line Feature
 * @param {string} [units=kilometers] can be degrees, radians, miles, or kilometers
 * @returns {Feature<Point>} the closest point
 * @example
 * var points = featureCollection([point([0, 0]), point([0.5, 0.5])]);
 * var line = lineString([[1,1], [-1,1]]);
 *
 * var nearest = turf.nearestPointToLine(points, line);
 *
 * //addToMap
 * var addToMap = [nearest, line];
 */
module.exports = function (points, line, units) {

Ref #198

Not sure though how to interpret this discussion:

How would the case of a parallel line be handled? There is no single closest point.

If in doubt @morganherlocker the answer is c - we'll just place something artibitralily 😜!

I don't see the case of parallel lines here @morganherlocker and @rowanwins.

[rowanwins]

Looks good @stebogit , it's taken a long time between drinks on this module.

The only other thought is what we if we have 2 points at exactly the same distance? Could we pass back an array of points?

[rowanwins]

@param {string} [units=kilometers] can be degrees, radians, miles, or kilometer

My only comment would be saying that this is for the output property. So perhaps
@param {string} [units=kilometers] unit of the output distance property, can be degrees, radians, miles, or kilometer

[rowanwins]

I'd call the output property distance (rather than dist) because it's slightly more explicit/obvious.

Perhaps this should be an upstream change in @turf/pointOnLine as well...

Just my personal preference

[stebogit]

@rowanwins I found some issues with (I think) the @turf/point-to-line-distance when testing for two points at the same distance, so I'll be working on that.
Thanks for the suggestion so far. 👍

[stebogit]

@rowanwins @DenisCarriere
Guys I need your input here, cause I can't figure it out myself... 🤔
I am convinced that in both the following two examples the points should be at the same distance from the line in the middle, but for the second case @turf/point-to-line-distance gives like 0.000011m difference and I don't understand if they are truly not at the same distance or is the new module that is actually miscalculating (for the first example with the line N-S it returns equal distance).
Suggestions?

https://gist.github.com/anonymous/491d71542965d44b07f19a14b20a94d5?short_path=000ca83

https://gist.github.com/anonymous/dae55177159c3275f141b2accb96d1f4?short_path=5a48b33

[DenisCarriere]

I am convinced that in both the following two examples the points should be at the same distance from the line in the middle

I wouldn't worry too much about the 0.000011m difference, we can definitely add them to the test cases and look into this later.

The only other thought is what we if we have 2 points at exactly the same distance? Could we pass back an array of points?

I don't think we should return an Array of points (or FeatureCollection of Points), the expected output would be a single point and the chances that a point would fall exactly within a 0.000001 distance would be very slim. Any points which fall exactly on the same distance would simply be ignored and the first closest point would be returned.

I'd call the output property distance (rather than dist) because it's slightly more explicit/obvious.

We've been using dist in the past modules, I would stick with that naming convention instead of a more explicit name (which I normally do prefer).

[DenisCarriere]

This would only allow Geometry LineString and not a Feature<LineString>:

Correct definition for both Geometry & Feature support:

type LineString = GeoJSON.Feature<GeoJSON.LineString> | GeoJSON.LineString;

[DenisCarriere]

Should we also support LineString as a Geometry?

/**
 * @param {Feature<LineString>|LineString} line Line Feature

[DenisCarriere]

Missing units as an optional param

[DenisCarriere]

Could we also support GeometryCollection

[DenisCarriere]

Updated a few things:

• GeometryCollection support
• Geometry LineString support (also for @turf/point-to-line-distance)
• Add tests for TypeScript
• Update JSDocs
• Update test/in to GeometryCollection
• Add @turf/circle to debug output

CC: @stebogit

[DenisCarriere]

Easier to preview the test outputs when using GeometryCollection:

[stebogit]

Yay!! 🎉
Thanks @DenisCarriere for fixing what needed to be fixed! 😃