math: fix vec2,3,4 project not using the right formulas (fix #25811) (#25813)

Author: gw-dev101

vlib/math/vec/vec2.v

@@ -221,6 +221,17 @@ pub fn (v Vec2[T]) magnitude_y() T {
 }
 
 // dot returns the dot product of `v` and `u`.
+// The dot product is a scalar value that represents the magnitude of one vector
+// projected onto another vector.
+// It is calculated by multiplying the corresponding components of the vectors
+// and summing the results.
+// example:
+// ```v
+// v := vec2[f32](3, 4) //magnitude = 5
+// u := vec2[f32](5, 6) //magnitude = 7.81
+// dot := v.dot(u) // 3*5 + 4*6 = 15 + 24 = 39
+// 	(dot) // Output: 39
+// ```
 pub fn (v Vec2[T]) dot(u Vec2[T]) T {
 	return (v.x * u.x) + (v.y * u.y)
 }
@@ -253,9 +264,22 @@ pub fn (v Vec2[T]) perpendicular(u Vec2[T]) Vec2[T] {
 }
 
 // project returns the projected vector.
+// The projection of vector `u` onto vector `v` is the orthogonal projection
+// of `u` onto a straight line parallel to `v` that passes through the origin.
+// This is equivalent to the vector projection of `u` onto the unit vector in the direction of `v`.
+// and is given by the formula: proj_v(u) = (u · v / |v|^2) * v
+// where "·" denotes the dot product and |v| is the magnitude of vector `v`.
+// If `u` is a zero vector, the result will also be a zero vector.
+// example:
+// ```v
+// v := vec2[f32](3, 4)
+// u := vec2[f32](5, 6)
+// proj := v.project(u)
+// println(proj) // Output: vec2[f32](3.61, 4.81)
+// ```
 pub fn (v Vec2[T]) project(u Vec2[T]) Vec2[T] {
-	percent := v.dot(u) / u.dot(v)
-	return u.mul_scalar(percent)
+	scale := u.dot(v) / v.dot(v)
+	return v.mul_scalar(scale)
 }
 
 // rotate_around_cw returns the vector `v` rotated *clockwise* `radians` around an origin vector `o` in Cartesian space.
@@ -351,6 +375,15 @@ pub fn (p1 Vec2[T]) angle_towards(p2 Vec2[T]) T {
 }
 
 // angle returns the angle in radians of the vector.
+// example:
+// ```v
+// v := vec2[f32](3.0, 4.0)
+// a := v.angle()
+// assert a == 0.64 (approximate value in radians)
+// w := vec2[f32](0.0, 1.0)
+// b := w.angle()
+// assert b == 1.57 (approximate value in radians)
+// ```
 pub fn (v Vec2[T]) angle() T {
 	$if T is f64 {
 		return math.atan2(v.y, v.x)
@@ -361,12 +394,8 @@ pub fn (v Vec2[T]) angle() T {
 
 // abs sets `x` and `y` field values to their absolute values.
 pub fn (mut v Vec2[T]) abs() {
-	if v.x < 0 {
-		v.x = math.abs(v.x)
-	}
-	if v.y < 0 {
-		v.y = math.abs(v.y)
-	}
+	v.x = math.abs(v.x)
+	v.y = math.abs(v.y)
 }
 
 // clean returns a vector with all fields of this vector set to zero (0) if they fall within `tolerance`.
@@ -392,6 +421,14 @@ pub fn (mut v Vec2[T]) clean_tolerance[U](tolerance U) {
 }
 
 // inv returns the inverse, or reciprocal, of the vector.
+// If a field is zero, its inverse is also set to zero to avoid division by zero.
+// the direction the vector points is generally not preserved, but
+// the magnitude of each field is inverted.
+// example:
+// ```v
+// v := vec2[f32](2.0, 4.0)
+// inv_v := v.inv() // inv_v == vec2[f32](0.5, 0.25)
+// ```
 pub fn (v Vec2[T]) inv() Vec2[T] {
 	return Vec2[T]{
 		x: if v.x != 0 { T(1) / v.x } else { 0 }
@@ -400,6 +437,13 @@ pub fn (v Vec2[T]) inv() Vec2[T] {
 }
 
 // normalize normalizes the vector.
+// A normalized vector has the same direction as the original vector but a magnitude of 1.
+// If the vector has a magnitude of 0, a zero vector is returned since we cannot find the direction of a zero-length vector.
+// example:
+// ```v
+// v := vec2[f32](3.0, 4.0)//magnitude = 5.0
+// n := v.normalize() // n == vec2[f32](0.6, 0.8) // magnitude = 1.0
+// ```
 pub fn (v Vec2[T]) normalize() Vec2[T] {
 	m := v.magnitude()
 	if m == 0 {
@@ -412,6 +456,12 @@ pub fn (v Vec2[T]) normalize() Vec2[T] {
 }
 
 // sum returns a sum of all the fields.
+// example:
+// ```v
+// v := vec2[f32](3.0, 4.0)
+// s := v.sum()
+// assert s == 7.0
+// ```
 pub fn (v Vec2[T]) sum() T {
 	return v.x + v.y
 }

vlib/math/vec/vec2_test.v

@@ -1,4 +1,4 @@
-import math { close, radians, veryclose }
+import math { close, is_nan, radians, tolerance, veryclose }
 import math.vec
 
 fn test_vec2_int() {
@@ -228,3 +228,74 @@ fn test_vec2_rotate_around_ccw_2() {
 	assert close(v.x, -1.0)
 	assert close(v.y, -1.0)
 }
+
+// Test for Vec2 projection
+//
+fn test_vec2_project_onto_basic() {
+	u := vec.vec2(3.0, 4.0) // magnitude 5 vector
+	v := vec.vec2(5.0, 6.0) // magnitude ~7.81 vector
+	// hand-computed:
+	// u·v = 5*3 + 6*4 = 39
+	// |v|^2 = 3^2 + 4^2 = 25
+	// scale = 39/25 = 1.56
+	// proj = scale * v = (1.56*3, 1.56*4) = (4.68, 6.24)
+	proj := u.project(v)
+	assert tolerance(proj.x, 4.68, vec.vec_epsilon)
+	assert tolerance(proj.y, 6.24, vec.vec_epsilon)
+}
+
+// Test for Vec2 projection onto zero vector
+// project v into the null vector
+fn test_vec2_project_onto_zero() {
+	u := vec.vec2(0.0, 0.0)
+	v := vec.vec2(5.0, 6.0)
+	proj := u.project(v)
+	// must be nan
+	assert is_nan(proj.x)
+	assert is_nan(proj.y)
+}
+
+// Test for Vec2 projection of zero vector
+// project a null vector
+fn test_vec2_project_zero_vector() {
+	u := vec.vec2(3.0, 4.0)
+	v := vec.vec2(0.0, 0.0)
+	proj := u.project(v)
+	assert proj.x == 0.0
+	assert proj.y == 0.0
+}
+
+// Test for Vec2 projection onto itself
+//
+fn test_vec2_project_onto_self() {
+	u := vec.vec2(3.0, 4.0)
+	proj := u.project(u)
+	assert veryclose(proj.x, u.x)
+	assert veryclose(proj.y, u.y)
+}
+
+// Test for Vec2 projection onto orthogonal vector
+//
+fn test_vec2_project_onto_orthogonal() {
+	u := vec.vec2(1.0, 0.0)
+	v := vec.vec2(0.0, 1.0)
+	proj := u.project(v)
+	// more sensitive to floating point errors so i think close is better here
+	assert close(proj.x, 0.0)
+	assert close(proj.y, 0.0)
+}
+
+// Test for Vec2 projection with negative components
+//
+fn test_vec2_project_negative_components() {
+	u := vec.vec2(-3.0, 4.0)
+	v := vec.vec2(5.0, -6.0)
+	// hand-computed:
+	// u·v = 5*-3 + -6*4 = -15 - 24 = -39
+	// |v|^2 = -3^2 + 4^2 = 9 + 16 = 25
+	// scale = -39/25 = -1.56
+	// proj = scale * v = (-1.56*-3, -1.56*4) = (4.68, -6.24)
+	proj := u.project(v)
+	assert tolerance(proj.x, 4.68, vec.vec_epsilon)
+	assert tolerance(proj.y, -6.24, vec.vec_epsilon)
+}

vlib/math/vec/vec3.v

@@ -260,9 +260,18 @@ pub fn (v Vec3[T]) perpendicular(u Vec3[T]) Vec3[T] {
 }
 
 // project returns the projected vector.
+// The projection of vector `u` onto vector `v` is the orthogonal projection
+// of `u` onto a straight line parallel to `v` that passes through the origin.
+// This is equivalent to the vector projection of `u` onto the unit vector in the direction of `v`.
+// and is given by the formula: proj_v(u) = (u · v / |v|^2) * v
+// where "·" denotes the dot product and |v| is the magnitude of vector `v`.
+// If `u` is a zero vector, the result will also be a zero vector.
+// example:
+// TODO: add examples
+// ```
 pub fn (v Vec3[T]) project(u Vec3[T]) Vec3[T] {
-	percent := v.dot(u) / u.dot(v)
-	return u.mul_scalar(percent)
+	scale := T(u.dot(v) / v.dot(v))
+	return v.mul_scalar(scale)
 }
 
 // eq returns a bool indicating if the two vectors are equal.

vlib/math/vec/vec3_test.v

@@ -1,3 +1,4 @@
+import math { veryclose }
 import math.vec
 
 fn test_vec3_int() {
@@ -88,3 +89,45 @@ fn test_vec3_f64_utils_2() {
 	assert invv2.y == 0.5
 	assert invv2.z == 0.25
 }
+
+// sample tests for vec3 projection
+fn test_vec3_project_onto_basic() {
+	u := vec.vec3(3.0, 4.0, 0.0) // magnitude 5 vector
+	v := vec.vec3(5.0, 6.0, 0.0) // magnitude ~7.81 vector
+	// hand-computed:
+	// u·v = 5*3 + 6*4 + 0*0 = 39
+	// |v|^2 = 3^2 + 4^2 +0^2 = 25
+	// scale = 39/25 = 1.56
+	// proj = scale * v = (1.56*3, 1.56*4, 1.56*0) = (4.68, 6.24, 0)
+	proj := u.project(v)
+	assert veryclose(proj.x, 4.68)
+	assert veryclose(proj.y, 6.24)
+	assert veryclose(proj.z, 0.0)
+}
+
+// Test for Vec3 projection onto zero vector
+//
+fn test_vec3_project_onto_zero() {
+	u := vec.vec3(3.0, 4.0, 0.0)
+	v := vec.vec3(0.0, 0.0, 0.0)
+	proj := u.project(v)
+	assert proj.x == 0.0
+	assert proj.y == 0.0
+	assert proj.z == 0.0
+}
+
+// Test for vec3 projection at an angle
+//
+fn test_vec3_project_onto_angle() {
+	u := vec.vec3(1.0, 0.0, 0.0) // magnitude 1 vector
+	v := vec.vec3(1.0, 1.0, 0.0) // magnitude sqrt(2) vector
+	// hand-computed:
+	// u·v = 1*1 + 0*1 + 0*0 = 1
+	// |v|^2 = 1^2 + 0^2 +0^2 = 1
+	// scale = 1/1 = 1
+	// proj = scale * v = (1*1, 1*0, 1*0) = (1, 0, 0)
+	proj := u.project(v)
+	assert veryclose(proj.x, 1.0)
+	assert veryclose(proj.y, 0.0)
+	assert veryclose(proj.z, 0.0)
+}

vlib/math/vec/vec4.v

@@ -276,9 +276,18 @@ pub fn (v Vec4[T]) perpendicular(u Vec4[T]) Vec4[T] {
 }
 
 // project returns the projected vector.
+// The projection of vector `u` onto vector `v` is the orthogonal projection
+// of `u` onto a straight line parallel to `v` that passes through the origin.
+// This is equivalent to the vector projection of `u` onto the unit vector in the direction of `v`.
+// and is given by the formula: proj_v(u) = (u · v / |v|^2) * v
+// where "·" denotes the dot product and |v| is the magnitude of vector `v`.
+// If `u` is a zero vector, the result will also be a zero vector.
+// example:
+// TODO: add examples
+// ```
 pub fn (v Vec4[T]) project(u Vec4[T]) Vec4[T] {
-	percent := v.dot(u) / u.dot(v)
-	return u.mul_scalar(percent)
+	scale := u.dot(v) / v.dot(v)
+	return v.mul_scalar(scale)
 }
 
 // eq returns a bool indicating if the two vectors are equal.

vlib/math/vec/vec4_test.v

@@ -97,3 +97,29 @@ fn test_vec4_f64_utils_2() {
 	assert invv2.z == 0.25
 	assert invv2.w == 1.0
 }
+
+// sample tests for vec4 projection
+fn test_vec4_project_onto_basic() {
+	u := vec.vec4(3.0, 4.0, 0.0, 0.0) // magnitude 5 vector
+	v := vec.vec4(5.0, 6.0, 0.0, 0.0) // magnitude ~7.81 vector
+	// hand-computed:
+	// u·v = 5*3 + 6*4 + 0*0 + 0*0 = 39
+	// |v|^2 = 3^2 + 4^2 +0^2 +0^2 = 25
+	proj := u.project(v)
+	assert proj.x == 3.0
+	assert proj.y == 4.0
+	assert proj.z == 0.0
+	assert proj.w == 0.0
+}
+
+// Test for Vec4 projection onto zero vector
+//
+fn test_vec4_project_onto_zero() {
+	u := vec.vec4(3.0, 4.0, 0.0, 0.0)
+	v := vec.vec4(0.0, 0.0, 0.0, 0.0)
+	proj := u.project(v)
+	assert proj.x == 0.0
+	assert proj.y == 0.0
+	assert proj.z == 0.0
+	assert proj.w == 0.0
+}