Implemented the Line.project

buildconfig/stubs/pygame/geometry.pyi

@@ -197,3 +197,6 @@ class Line:
     def scale_ip(self, factor_and_origin: Point, /) -> None: ...
     def flip_ab(self) -> Line: ...
     def flip_ab_ip(self) -> None: ...
+    def project(
+        self, point: tuple[float, float], clamp: bool = False
+    ) -> tuple[float, float]: ...

docs/reST/ref/geometry.rst

@@ -740,3 +740,27 @@
          .. versionadded:: 2.5.3
 
       .. ## Line.flip_ab_ip ##
+
+   .. method:: project
+
+         | :sl:`projects the line onto the given line`
+         | :sg:`project(point: tuple[float, float], clamp=False) -> tuple[float, float]`
+
+         This method takes in a point and one boolean keyword argument clamp. It outputs an orthogonally projected point onto the line.
+         If clamp is True it makes sure that the outputted point will be on the line segment.
+
+
+         .. figure:: code_examples/project.png
+            :alt: project method image
+
+            Example of how it projects the point on to the line purplish point is the point we want to project and the blue point is what you would get as a result
+
+
+         .. figure:: code_examples/project_clamp.png
+            :alt: project do_clamp=True image
+
+            Example of what the clamp argument changes if it is true it stays on the line segment
+
+         .. versionadded:: 2.5.4
+
+      .. ## Line.project ##

src_c/doc/geometry_doc.h

@@ -45,3 +45,4 @@
 #define DOC_LINE_SCALEIP "scale_ip(factor, origin) -> None\nscale_ip(factor_and_origin) -> None\nscales the line by the given factor from the given origin in place"
 #define DOC_LINE_FLIPAB "flip_ab() -> Line\nflips the line a and b points"
 #define DOC_LINE_FLIPABIP "flip_ab_ip() -> None\nflips the line a and b points, in place"
+#define DOC_LINE_PROJECT "project(point: tuple[float, float], clamp=False) -> tuple[float, float]\nprojects the line onto the given line"

src_c/line.c

@@ -179,6 +179,66 @@ _line_scale_helper(pgLineBase *line, double factor, double origin)
     return 1;
 }
 
+void
+_normalize_vector(double *vector)
+{
+    double length = sqrt(vector[0] * vector[0] + vector[1] * vector[1]);
+    // check to see if the vector is zero
+    if (length == 0) {
+        vector[0] = 0;
+        vector[1] = 0;
+    }
+    else {
+        vector[0] /= length;
+        vector[1] /= length;
+    }
+}
+
+double
+_length_of_vector(double *vector)
+{
+    return sqrt(vector[0] * vector[0] + vector[1] * vector[1]);
+}
+
+static PyObject *
+_line_project_helper(pgLineBase *line, double *point, int clamp)
+{
+    // this is a vector that goes from one point of the line to another
+    double line_vector[2] = {line->bx - line->ax, line->by - line->ay};
+
+    // this is a vector that goes from the start of the line to the point we
+    // are projecting onto the line
+    double vector_from_line_start_to_point[2] = {point[0] - line->ax,
+                                                 point[1] - line->ay};
+
+    double dot_product =
+        (vector_from_line_start_to_point[0] * line_vector[0] +
+         vector_from_line_start_to_point[1] * line_vector[1]) /
+        (line_vector[0] * line_vector[0] + line_vector[1] * line_vector[1]);
+
+    double projection[2] = {dot_product * line_vector[0],
+                            dot_product * line_vector[1]};
+
+    if (clamp) {
+        if (projection[0] * projection[0] + projection[1] * projection[1] >
+            line_vector[0] * line_vector[0] +
+                line_vector[1] * line_vector[1]) {
+            projection[0] = line_vector[0];
+            projection[1] = line_vector[1];
+        }
+        else if (dot_product < 0) {
+            projection[0] = 0;
+            projection[1] = 0;
+        }
+    }
+
+    double projected_point[2] = {line->ax + projection[0],
+                                 line->ay + projection[1]};
+
+    return pg_tuple_couple_from_values_double(projected_point[0],
+                                              projected_point[1]);
+}
+
 static PyObject *
 pg_line_scale(pgLineObject *self, PyObject *const *args, Py_ssize_t nargs)
 {
@@ -219,6 +279,33 @@ pg_line_scale_ip(pgLineObject *self, PyObject *const *args, Py_ssize_t nargs)
     Py_RETURN_NONE;
 }
 
+static PyObject *
+pg_line_project(pgLineObject *self, PyObject *const *args, Py_ssize_t nargs,
+                PyObject *kwnames)
+{
+    double point[2] = {0.f, 0.f};
+    int clamp = 0;
+
+    if (nargs >= 1) {
+        if (!pg_TwoDoublesFromObj(args[0], &point[0], &point[1])) {
+            return RAISE(PyExc_TypeError,
+                         "project requires a sequence of two numbers");
+        }
+    }
+
+    if (kwnames != NULL) {
+        clamp = PyObject_IsTrue(args[nargs]);
+    }
+
+    PyObject *projected_point;
+    if (!(projected_point =
+              _line_project_helper(&pgLine_AsLine(self), point, clamp))) {
+        return NULL;
+    }
+
+    return projected_point;
+}
+
 static struct PyMethodDef pg_line_methods[] = {
     {"__copy__", (PyCFunction)pg_line_copy, METH_NOARGS, DOC_LINE_COPY},
     {"copy", (PyCFunction)pg_line_copy, METH_NOARGS, DOC_LINE_COPY},
@@ -231,6 +318,8 @@ static struct PyMethodDef pg_line_methods[] = {
     {"scale", (PyCFunction)pg_line_scale, METH_FASTCALL, DOC_LINE_SCALE},
     {"scale_ip", (PyCFunction)pg_line_scale_ip, METH_FASTCALL,
      DOC_LINE_SCALEIP},
+    {"project", (PyCFunction)pg_line_project, METH_FASTCALL | METH_KEYWORDS,
+     DOC_LINE_PROJECT},
     {NULL, NULL, 0, NULL}};
 
 static PyObject *

test/geometry_test.py

@@ -2201,6 +2201,24 @@ def test_meth_update(self):
         with self.assertRaises(TypeError):
             line.update(1, 2, 3)
 
+    def test_meth_project(self):
+        line = Line(0, 0, 100, 100)
+        test_point1 = (25, 75)
+        test_clamp_point1 = (100, 300)
+        test_clamp_point2 = (-50, -150)
+
+        projected_point = line.project(test_point1)
+        self.assertEqual(math.ceil(projected_point[0]), 50)
+        self.assertEqual(math.ceil(projected_point[1]), 50)
+
+        projected_point = line.project(test_clamp_point1, do_clamp=True)
+        self.assertEqual(math.ceil(projected_point[0]), 100)
+        self.assertEqual(math.ceil(projected_point[1]), 100)
+
+        projected_point = line.project(test_clamp_point2, do_clamp=True)
+        self.assertEqual(math.ceil(projected_point[0]), 0)
+        self.assertEqual(math.ceil(projected_point[1]), 0)
+
     def test__str__(self):
         """Checks whether the __str__ method works correctly."""
         l_str = "Line((10.1, 10.2), (4.3, 56.4))"