Three.js: lerp and lerpVectors are not clamped (and it is great), but please fix the docs.

[mnesarco]

Documentation of lerp and lerpVectors says:

alpha - interpolation factor in the closed interval [0, 1].

But implementation is not clamped, unclamped version is more generic and useful than clamped, so just please update the documentation.

https://github.com/mrdoob/three.js/blob/ce97f8b14b19c5130f0c48f27ffe0dec5dce042f/src/math/Vector3.js#L508

[Mugen87]

Would you like to do a PR with the fix? I suppose it's sufficient to do this:

alpha - interpolation factor.

Note: It's necessary to change the docs of lerp() and lerpVectors() for all vector classes (Vector2, Vector3, Vector4).

[WestLangley]

I suppose it's sufficient to do this:

alpha - interpolation factor.

Thing is, the accepted PR did not do that.

[WestLangley]

But implementation is not clamped

_Nowhere_ in the documentation does it say the input is clamped -- nor does it say the output is clamped.

alpha - interpolation factor in the closed interval [0, 1]

Lerp performs linear interpolation _between_ two values. If a value less than zero is passed in, the result is not linear interpolation, it is linear _extrapolation_.

Personally, I would leave the documentation as-is because that is the conventional intent of the lerp method.

If you insist on a change, you can do this:

alpha - interpolation factor, typically in the closed interval [0, 1]

But doing so violates the meaning of "lerp", so I would prefer the existing documentation.

[WestLangley]

three.js does not validate inputs, so a user is free to pass in values outside the nominal range.

This may or may not produce reasonable results. In this case it does produce a reasonable result, but it is not a lerp.

I think the docs should document the method for nominal inputs only.

I would like to reopen this issue so we can further discuss...

[WestLangley]

One more thing... the docs say

Linearly interpolates between this vector and [page:Vector2 v], where alpha is the distance along the line

alpha is not a "distance". If it were, it would be sized in world units (for example, meters).

alpha is unitless; it is a percentage. So the docs should say,

where alpha is the percent distance along the line

I do not think lerp should be documented to accept a negative percentage.

If users want to pass in a negative percentage, that is their business.

[mnesarco]

Hi @WestLangley, The idea was just to document what the current implementation actually does:
If alpha is in [0,1] the result is the interpolation,
but if alpha is outside of [0,1] the result is extrapolation.

Other implementations (i.e. Unity) have both versions: lerp and lerpUnclamped, so another solution is to add new methods but the current implementation covers both cases, so I think it is just needed to clarify that in the docs. The idea is to avoid the need of read the actual source code to decide if we can use the method with alpha outside [0,1] and what is the expected result in that case.

[WestLangley]

@mnesarco Thanks for your reply. It was not intended that a user would pass in a value outside the interval [ 0, 1 ].

Out of curiosity, what was your use case for passing in a negative value for alpha?

[mnesarco]

Hi @WestLangley, I use lerpVectors(v1, v2) method to calculate extrapolated points in the same line represented by v1->v2. I can write a method for it in my code, but I prefer to not reinvent the wheel if the method is already available and does exactly what I need.

I have a segment from A to B, and I need to calculate a point, in the same line but before A, in that case I use lerpVectors(A, B, alpha) with alpha < 0. The same apply for alpha > 1 if I need a point after B but in the same line.

[Mugen87]

Other implementations (i.e. Unity) have both versions: lerp and lerpUnclamped

That sounds like a good solution and makes the implementation more clear.

[mnesarco]

@Mugen87 if you want, I can submit another PR with the new methods and doc updates

[WestLangley]

I think I would keep just one method and make this change to the docs:

alpha - interpolation factor, typically in the closed interval [0, 1]

and then,

where alpha is the percent distance along the line

[WestLangley]

The primary reason is that three.js does not validate inputs.

I hope keeping one method and updating the docs as suggested satisfies @mnesarco 's concerns.