Vector2.angleRad(Vector2) returns angle toward -y (instead of toward +y)

[jcornaz]

Issue details

Documentation of Vector2.angleRad(Vector2) states:

return the angle in radians of this vector (point) relative to the given vector. Angles are towards the positive y-axis. (typically counter-clockwise.)

So based on this statement Vector2.Y.angleRad(Vector2.X) should return Math.PI / 2.
But it returns -Math.PI / 2

Reproduction steps/code

System.out.println(Vector2.Y.angleRad(Vector2.X)) // prints "-1.5707964" (which is wrong)

// not passing the argument works as expected
System.out.println(Vector2.Y.angleRad()) // prints "1.5707964" (which is correct)

Version of LibGDX and/or relevant dependencies

1.9.8

Please select the affected platforms

Should not be platform related. This is only math. But I observed the problem on Windows.

[obigu]

It is actually correct, maybe the wording of the docs could be improved.

Basically the key point here is that order matters.
With an Y positive coordinate system, this method will return the counter clock-wise angle between the current Vector and the reference Vector (argument).

If you calculate the counter-clock angle between (0, 1) and (1, 0) you should get 270º which is what
System.out.println(Vector2.Y.angleRad(Vector2.X)) returns.

On the other hand
System.out.println(Vector2.X.angleRad(Vector2.Y)) returns 90º (in radians) as expected.

[jcornaz]

It is actually correct, maybe the wording of the docs could be improved.

Sorry I don't understand. How can Vector2.Y.angleRad(Vector2.X)) return a different value than Vector2.Y.angleRad()?

If you calculate the counter-clock angle between (0, 1) and (1, 0) you should get 270º

It seems we don't have the same definition of "reference". If I draw an arrow from one vector to the other in order to represent the angle. For me "reference" is the vector from which that arrow starts.

In the following picture I consider the black vector to be the reference:

Vector2.angleRad() states:

the angle in radians of this vector (point) relative to the x-axis. Angles are towards the positive y-axis. (typically counter-clockwise)

So the reference is the x-axis (not the instance from which the function is called)

Vector2.angleRad(Vector2 reference) states:

the angle in radians of this vector (point) relative to the given vector. Angles are towards the positive y-axis. (typically counter-clockwise.)

Here the reference is explicitly the argument (not the instance from which the function is called)

Vector2 vector = Vector2.Y;
Vector2 reference = Vector2.X;

System.out.println(vector.angleRad()); // I expect 1.5707964 (and I get it)
System.out.println(vector.angleRad(reference)); // I expect 1.5707964 (and I don't get it)

[jcornaz]

By the way, as a side question, may I ask what is the rationale behind the fact that angle returns value between 0 and 360 while angleRad returns values between -Math.PI and Math.PI?

Why not return values between -180 and 180 for angle for instance? It would be more consistent and simpler if angle(x) was always equal to angleRad(x) * MathUtils.radiansToDegrees.

[obigu]

I do agree that the docs can be improved because "relative to" may be misleading. Using your definitions, Vector2.angleRad(Vector2 argument) returns the angle considering the current Vector is the "reference".
So, in your specific example,
System.out.println(Vector2.Y.angleRad()) calculates the counter-clockwise angle between (0, 1) and (1, 0) which is 90º but System.out.println(Vector2.Y.angleRad(Vector2.X)) calculates the counter-clockwise angle between (1, 0) and (0, 1) which is 270º or -90º.

To your second question I guess the main reason is just that Math.atan2 returns in the range [-Math.pi, +Math.pi] and it's a common convention when working in polar coordinates. It could have been made consistent with degrees but the conversion is trivial and changing it now would break backwards compatibility.

[jcornaz]

Using your definitions, Vector2.angleRad(Vector2 argument) returns the angle considering the current Vector is the "reference"

No. The other way around. And the argument is not named "argument" it is named "reference"!

But let's make it simpler:

Documentation of Vector2.angleRad(Vector2) states that the result is:

the angle in radians of this vector (point) relative to the given vector. Angles are towards the positive y-axis. (typically counter-clockwise.)

In the specific case of using the x-axis as a "given vector" like in Vector2.Y.angleRad(Vector2.X). The result shall be:

the angle in radians of this vector (point) relative to the x-axis. Angles are towards the positive y-axis. (typically counter-clockwise.)

Here we see that this statement is identical to the documentation stated in Vector2.angleRad():

the angle in radians of this vector (point) relative to the x-axis. Angles are towards the positive y-axis. (typically counter-clockwise)

From that premise, it does not matter how one understand "relative to" and "reference". For all vector v, v.angleRad() should return the exact same value than v.angleRad(Vector2.X).

[obigu]

Agree, the javadoc comment was probably copied from one to another and should be inverted on angleRad(Vector2). Alternatively the implementation can be inverted to match the current javadoc.

[jcornaz]

angleRad() is an overload of angleRad(Vector2) . The two functions have to behave in a consistent way. To invert the doc for one of them is not a solution.

Implementation has to be fixed.

[mgsx-dev]

fixed by #5428