maths.line_intersection
=======================

.. py:module:: maths.line_intersection


Functions
---------

.. autoapisummary::

   maths.line_intersection.determinant
   maths.line_intersection.line_coefficients
   maths.line_intersection.segment_intersection


Module Contents
---------------

.. py:function:: determinant(m00: float, m01: float, m10: float, m11: float) -> float

   Calculates the determinant of a 2x2 matrix:

   | m00  m01 |
   | m10  m11 |

   Args:
       m00 (float): Element in the first row, first column.
       m01 (float): Element in the first row, second column.
       m10 (float): Element in the second row, first column.
       m11 (float): Element in the second row, second column.

   Returns:
       float: The determinant of the matrix.

   Examples:
       # Determinant of the identity matrix (should be 1)
       >>> determinant(1, 0, 0, 1)
       1

       # Determinant of a matrix with two equal rows (should be 0)
       >>> determinant(1, 2, 1, 2)
       0

       # Determinant of a matrix with a negative determinant
       >>> determinant(1, 2, 3, 4)
       -2

       # Determinant of a matrix with larger numbers
       >>> determinant(10, 20, 30, 40)
       -200


.. py:function:: line_coefficients(p1: list[float] | tuple, p2: list[float] | tuple) -> tuple

   Computes the coefficients A, B, C of the line equation Ax + By + C = 0
   from two points.

   Args:
       p1 (List[float] | tuple): First point (x, y).
       p2 (List[float] | tuple): Second point (x, y).

   Returns:
       tuple: Coefficients (A, B, C) of the line equation.

   Examples:
       # Vertical line (x = constant)
       >>> line_coefficients([1, 0], [1, 2])
       (1, 0, 1)

       # Horizontal line (y = constant)
       >>> line_coefficients([0, 1], [2, 1])
       (0.0, -1, 1.0)

       # Diagonal line (positive slope)
       >>> line_coefficients([0, 0], [1, 1])
       (1.0, -1, 0.0)

       # Diagonal line (negative slope)
       >>> line_coefficients([0, 1], [1, 0])
       (-1.0, -1, 1.0)


.. py:function:: segment_intersection(v1: list[float] | tuple, v2: list[float] | tuple, v1_prime: list[float] | tuple, v2_prime: list[float] | tuple, as_segments: bool = True) -> list[float] | None

   Finds the intersection point of two line segments or lines, if it exists.

   Args:
       v1 (List[float] | tuple): First point of the first segment (x, y).
       v2 (List[float] | tuple): Second point of the first segment (x, y).
       v1_prime (List[float] | tuple): First point of the second segment (x, y).
       v2_prime (List[float] | tuple): Second point of the second segment (x, y).
       as_segments (bool):
           treat the inputs as line segments (True)
           or as infinite lines (False).

   Returns:
       List[float] | None:
           Returns the intersection point [x, y] if existent, otherwise None.

   References:
       Cramer's rule: https://en.wikipedia.org/wiki/Cramer%27s_rule

   Examples:
       >>> segment_intersection([0, 0], [1, 1], [1, 0], [0, 1])
       [0.5, 0.5]

       # No intersection
       >>> segment_intersection([0, 0], [1, 1], [2, 2], [3, 3]) is None
       True

       # Parallel lines
       >>> segment_intersection([0, 0], [0, 1], [1, 0], [1, 1]) is None
       True

       # Intersecting infinite lines
       >>> segment_intersection([0, 0], [1, 1], [1, 0], [0, 1], as_segments=False)
       [0.5, 0.5]

       # Parallel infinite lines (ignoring segment boundaries)
       >>> segment_intersection([0, 0], [1, 1], [2, 2], [3, 3], False) is None
       True