Add points are collinear in 3d algorithm to /maths (#5983)

* Add points are collinear in 3d algorithm to /maths

* Apply suggestions from code review in points_are_collinear_3d.py

Thanks to cclauss.

Co-authored-by: Christian Clauss <cclauss@me.com>

* Rename some variables to be more self-documenting.

* Update points_are_collinear_3d.py

Co-authored-by: Christian Clauss <cclauss@me.com>

maths/points_are_collinear_3d.py

@@ -0,0 +1,126 @@
+"""
+Check if three points are collinear in 3D.
+
+In short, the idea is that we are able to create a triangle using three points,
+and the area of that triangle can determine if the three points are collinear or not.
+
+
+First, we create two vectors with the same initial point from the three points,
+then we will calculate the cross-product of them.
+
+The length of the cross vector is numerically equal to the area of a parallelogram.
+
+Finally, the area of the triangle is equal to half of the area of the parallelogram.
+
+Since we are only differentiating between zero and anything else,
+we can get rid of the square root when calculating the length of the vector,
+and also the division by two at the end.
+
+From a second perspective, if the two vectors are parallel and overlapping,
+we can't get a nonzero perpendicular vector,
+since there will be an infinite number of orthogonal vectors.
+
+To simplify the solution we will not calculate the length,
+but we will decide directly from the vector whether it is equal to (0, 0, 0) or not.
+
+
+Read More:
+    https://math.stackexchange.com/a/1951650
+"""
+
+Vector3d = tuple[float, float, float]
+Point3d = tuple[float, float, float]
+
+
+def create_vector(end_point1: Point3d, end_point2: Point3d) -> Vector3d:
+    """
+    Pass two points to get the vector from them in the form (x, y, z).
+
+    >>> create_vector((0, 0, 0), (1, 1, 1))
+    (1, 1, 1)
+    >>> create_vector((45, 70, 24), (47, 32, 1))
+    (2, -38, -23)
+    >>> create_vector((-14, -1, -8), (-7, 6, 4))
+    (7, 7, 12)
+    """
+    x = end_point2[0] - end_point1[0]
+    y = end_point2[1] - end_point1[1]
+    z = end_point2[2] - end_point1[2]
+    return (x, y, z)
+
+
+def get_3d_vectors_cross(ab: Vector3d, ac: Vector3d) -> Vector3d:
+    """
+    Get the cross of the two vectors AB and AC.
+
+    I used determinant of 2x2 to get the determinant of the 3x3 matrix in the process.
+
+    Read More:
+        https://en.wikipedia.org/wiki/Cross_product
+        https://en.wikipedia.org/wiki/Determinant
+
+    >>> get_3d_vectors_cross((3, 4, 7), (4, 9, 2))
+    (-55, 22, 11)
+    >>> get_3d_vectors_cross((1, 1, 1), (1, 1, 1))
+    (0, 0, 0)
+    >>> get_3d_vectors_cross((-4, 3, 0), (3, -9, -12))
+    (-36, -48, 27)
+    >>> get_3d_vectors_cross((17.67, 4.7, 6.78), (-9.5, 4.78, -19.33))
+    (-123.2594, 277.15110000000004, 129.11260000000001)
+    """
+    x = ab[1] * ac[2] - ab[2] * ac[1]  # *i
+    y = (ab[0] * ac[2] - ab[2] * ac[0]) * -1  # *j
+    z = ab[0] * ac[1] - ab[1] * ac[0]  # *k
+    return (x, y, z)
+
+
+def is_zero_vector(vector: Vector3d, accuracy: int) -> bool:
+    """
+    Check if vector is equal to (0, 0, 0) of not.
+
+    Sine the algorithm is very accurate, we will never get a zero vector,
+    so we need to round the vector axis,
+    because we want a result that is either True or False.
+    In other applications, we can return a float that represents the collinearity ratio.
+
+    >>> is_zero_vector((0, 0, 0), accuracy=10)
+    True
+    >>> is_zero_vector((15, 74, 32), accuracy=10)
+    False
+    >>> is_zero_vector((-15, -74, -32), accuracy=10)
+    False
+    """
+    return tuple(round(x, accuracy) for x in vector) == (0, 0, 0)
+
+
+def are_collinear(a: Point3d, b: Point3d, c: Point3d, accuracy: int = 10) -> bool:
+    """
+    Check if three points are collinear or not.
+
+    1- Create tow vectors AB and AC.
+    2- Get the cross vector of the tow vectors.
+    3- Calcolate the length of the cross vector.
+    4- If the length is zero then the points are collinear, else they are not.
+
+    The use of the accuracy parameter is explained in is_zero_vector docstring.
+
+    >>> are_collinear((4.802293498137402, 3.536233125455244, 0),
+    ...               (-2.186788107953106, -9.24561398001649, 7.141509524846482),
+    ...               (1.530169574640268, -2.447927606600034, 3.343487096469054))
+    True
+    >>> are_collinear((-6, -2, 6),
+    ...               (6.200213806439997, -4.930157614926678, -4.482371908289856),
+    ...               (-4.085171149525941, -2.459889509029438, 4.354787180795383))
+    True
+    >>> are_collinear((2.399001826862445, -2.452009976680793, 4.464656666157666),
+    ...               (-3.682816335934376, 5.753788986533145, 9.490993909044244),
+    ...               (1.962903518985307, 3.741415730125627, 7))
+    False
+    >>> are_collinear((1.875375340689544, -7.268426006071538, 7.358196269835993),
+    ...               (-3.546599383667157, -4.630005261513976, 3.208784032924246),
+    ...               (-2.564606140206386, 3.937845170672183, 7))
+    False
+    """
+    ab = create_vector(a, b)
+    ac = create_vector(a, c)
+    return is_zero_vector(get_3d_vectors_cross(ab, ac), accuracy)