From version 7.3.2 the nearestPointOnLine function returns a different segmentIndex when the nearest point is at end of the input line

[EmilJunker]

@smallsaucepan I'm opening this separate issue as you suggested in #2951 (comment).

In short: The change made in #2951 broke my code 😅

Consider the following example:

const lineCoords = [[0, 0], [1, 2], [0, 4]];

const line = turf.lineString(lineCoords);

const pointA = turf.point([-1, 0]);
const pointB = turf.point([1, 1]);
const pointC = turf.point([2, 2]);
const pointD = turf.point([1, 3]);
const pointE = turf.point([-1, 4]);

const nearA = turf.nearestPointOnLine(line, pointA);
const nearB = turf.nearestPointOnLine(line, pointB);
const nearC = turf.nearestPointOnLine(line, pointC);
const nearD = turf.nearestPointOnLine(line, pointD);
const nearE = turf.nearestPointOnLine(line, pointE);

Visualization:

---

Here is a side-by-side comparison of the index properties (or segmentIndex as it's called since v7.3.2) returned by the nearestPointOnLine function between Turf version 7.3.1 and 7.3.2:

	Point position	index in Turf 7.3.1	index/segmentIndex in Turf 7.3.2
nearA	exactly on lineCoords[0]	0	0
nearB	between lineCoords[0] and lineCoords[1]	0	0
nearC	exactly on lineCoords[1]	1	1
nearD	between lineCoords[1] and lineCoords[2]	1	1
nearE	exactly on lineCoords[2]	2	1

As you can see, the index when the nearest point falls on the final line point changed in Turf 7.3.2. This way, it is no longer possible to tell whether the nearest point is on the last line segment or at the end of the last line segment.

I don't want to get into too much detail, but let me just say that for various reasons, it is important for me to be able to recognize when the nearest point is at the end of the input line (or at the end of one of the lines of an input MultiLineString to be exact).

Looking at the documentation, I admit that the new behavior in Turf 7.3.2 arguably makes more sense and adheres more closely to the property description:

turf/packages/turf-nearest-point-on-line/README.md

Line 17 in 5721ddd

* segmentIndex - point was found on the nth segment of the above LineString. Previously `index`

Since the above line consist of three points and two line segments, it makes sense that the only possible segmentIndex values are 0 and 1 (and never 2). I'm therefore not advocating for the change made in #2951 to be reverted. But I still would like Turf to handle this edge case a bit better.

As a simple fix, I would propose to add a boolean property to the point returned by the nearestPointOnLine function that is true if and only if the nearest point exactly falls on the last point of the input line. We could name it isLastLinePoint or something like that.

A more sophisticated solution would be to come up with a system that also handles the intermediate segment "join points" better. For instance, one could argue that the point nearC in the above example that sits exactly between the two line segments should have the segmentIndex 0 instead of 1 (or the user should have the choice which behavior they prefer).

But I'm also open to other ideas or considerations that I might be overlooking 🙂

[EmilJunker]

Here is another idea that would be cleaner, but would also be a breaking change (alas, the minor version 7.3.2 already broke my code, so what gives 😆)

We could change the behavior for all "segment join points", not just for the last one. So when the nearest point falls exactly on the line point at index n (i.e., in Turf 7.3.1 it would have segmentIndex n), we instead give it segmentIndex n-1. In addition, we add a boolean property "isSegmentEnd" that indicates whether the point is at the end of its line segment. And for good measure, we could also add a "isLineEnd" property that indicates whether it's the last line point.

For my example above, this would mean:

	segmentIndex	isSegmentEnd	isLineEnd
nearA	0	false	false
nearB	0	false	false
nearC	0	true	false
nearD	1	false	false
nearE	1	true	true

People who want to restore the behavior from version 7.3.1 could then simply increase the segmentIndex by 1 whenever isSegmentEnd is true. And people who specifically want the behavior from version 7.3.2 could do the same unless the isLineEnd property is also true.

[smallsaucepan]

Thanks for running through that in detail. After discussion with the other maintainers, we're going to treat this as a breaking change and revert the PR that caused it (#2951). This will likely mean re-opening #2946, though we'll see if we can find an alternate fix that avoids that.

Then the behaviour as in v7.3.2 will be re-introduced in v8 (segmentIndex not referring to non-existent segments). While we've only had initial discussions on it, the sentiment is we wouldn't be adding extra return properties though. If I understand your needs the check really should be to compare the two points, and with the indices returned correctly you should be able to do that in your code.

Our MO there is to avoid adding too many meta properties to the return value and it becoming unwieldy. If you think there's a strong case (maybe even a new turf module?) please kick off a discussion and we can work through it!

[EmilJunker]

If I understand your needs the check really should be to compare the two points, and with the indices returned correctly you should be able to do that in your code.

Our MO there is to avoid adding too many meta properties to the return value and it becoming unwieldy. If you think there's a strong case (maybe even a new turf module?) please kick off a discussion and we can work through it!

I think I haven't made my needs clear enough, sorry. I don't need a module that just tells me whether the nearest point is at the end of a line. I really do need a module that does exactly what @turf/nearest-point-on-line is doing, including all the distance calculations and so on. And although the behavior regarding the index properties in v7.3.1 was arguably a bit nonsensical and could refer to nonexistent line segments, it just happened to be perfect for my use case. Here is why:

For various reasons, I will sometimes "chop up" the input line into a MultiLineString. I don't want to make it too complicated, but using my simple example from above, instead of the LineString [[0, 0], [1, 2], [0, 4]], I would have a MultiLineString consisting of [[0, 0], [1, 2]] and [[1, 2], [0, 4]]:

const lineCoords = [
  [[0, 0], [1, 2]],
  [[1, 2], [0, 4]]
];

const line = turf.multiLineString(lineCoords);

const pointA = turf.point([-1, 0]);
const pointB = turf.point([1, 1]);
const pointC = turf.point([2, 2]);
const pointD = turf.point([1, 3]);
const pointE = turf.point([-1, 4]);

const nearA = turf.nearestPointOnLine(line, pointA);
const nearB = turf.nearestPointOnLine(line, pointB);
const nearC = turf.nearestPointOnLine(line, pointC);
const nearD = turf.nearestPointOnLine(line, pointD);
const nearE = turf.nearestPointOnLine(line, pointE);

This looks exactly the same as my earlier example, but the line is now a MultiLineString instead of a LineString. Now have a look at how beautifully the index and multiFeatureIndex properties behaved in v7.3.1:

v7.3.1	index	multiFeatureIndex	index + multiFeatureIndex
nearA	0	0	0
nearB	0	0	0
nearC	1	0	1
nearD	0	1	1
nearE	1	1	2

Notice how the sum index + multiFeatureIndex on a MultiLineString input is exactly the same as the index on a LineString input (cf. table in my first post in this thread).

This is no longer the case in v7.3.2. In particular, it breaks for the point nearC (again, cf. table in my first post):

v7.3.2	segmentIndex	lineStringIndex	segmentIndex + lineStringIndex
nearA	0	0	0
nearB	0	0	0
nearC	0	0	0
nearD	0	1	1
nearE	0	1	1

That is why I would like Turf to handle this better. I'm not saying we should keep the behavior from v7.3.1. But if you are going to make a breaking change in v8 anyway, maybe consider my proposal from #3008 (comment)?

[EmilJunker]

Basically, my proposal for v8 would be to get rid of this line:

turf/packages/turf-nearest-point-on-line/index.ts

Line 151 in 106a956

segmentIndex: wasEnd && i + 1 <= maxSegmentIndex ? i + 1 : i,

And instead simply always set the segmentIndex property to be i and additionally expose the wasEnd property so the user can decide for themselves how the handle the case where the nearest point sits exactly on a line point.

[smallsaucepan]

Let's limit this issue to resolving the regression 👍

For any new proposals please create a discussion, or new issue that we can mark as a Feature. Describe what it is you are trying to achieve, or what quality of the result is relevant. Avoid describing the behaviour relative to what nearestPointOnLine does or used or do.

[EmilJunker]

Let's limit this issue to resolving the regression

Alright, thank you for taking the time to look into this. I'm looking forward to the regression being fixed.

If you fix it and make a new release, please consider also including my latest pull request #3005. I think Turf users would benefit from the old nearestPointOnLine properties being properly marked as deprecated.

For any new proposals please create a discussion, or new issue that we can mark as a Feature.

If the regression is fixed, then I won't have any issue. The way nearestPointOnLine worked in v7.3.1 is perfect for my use case.

But you just hinted that you are going to break my use case again in v8, and I do have an issue with that 😉

If I see the need to open a new issue, I will do that 👍

[smallsaucepan]

But you just hinted that you are going to break my use case again in v8

Not hinting. The behaviour you're relying on is a bug, and will be fixed in v8. If you need something else to meet your needs you will need to describe your use cases in a feature request.