# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Line segment geometry queries.

Provides line-line intersection (infinite lines), line-segment intersection,
closest point on a line or segment to a given point, line-segment-vs-polygon
intersections, point-on-segment tests, point-in-rectangle tests, rectangle
containment checks, and angle-at-vertex computation.
"""

from raygeo.geo import types
import typing
__all__ = [
    "does_line_cross_polygon",
    "does_line_segment_intersect_circle",
    "does_line_segment_intersect_rect",
    "get_angle_at_vertex",
    "get_interior_angle",
    "get_line_closest_point",
    "get_line_line_intersection",
    "get_line_segment_closest_point",
    "get_line_segment_intersection",
    "get_line_segment_length",
    "get_line_segment_polygon_intersections",
    "get_point_line_distance",
    "get_segment_segment_distance",
    "interpolated_segment_3d",
    "is_point_on_line_segment",
    "longest_line_through_point",
]

def does_line_cross_polygon(a: types.Point, b: types.Point, polygon: list[types.Point]) -> bool:
    r"""
    Check if a line segment crosses the interior of a polygon.
    
    Returns ``True`` when the segment *strictly* crosses the polygon
    boundary — touching a vertex or grazing an edge at an endpoint is
    **not** considered a crossing.
    
    :param a: Segment start point (x, y).
    :param b: Segment end point (x, y).
    :param polygon: Polygon vertices [(x1, y1), (x2, y2), ...].
    :returns: ``True`` if the segment crosses the polygon interior.
    :complexity: O(n) time, O(1) space
    """

def does_line_segment_intersect_circle(p1: types.Point, p2: types.Point, circle_center: types.Point, circle_radius: float) -> bool:
    r"""
    Check if a line segment intersects a circle.
    
    :param p1: Start of the line segment.
    :param p2: End of the line segment.
    :param circle_center: Circle center (x, y).
    :param circle_radius: Circle radius.
    :returns: True if the segment intersects the circle.
    :complexity: O(1) time, O(1) space
    """

def does_line_segment_intersect_rect(p1: types.Point, p2: types.Point, rect: types.Rect) -> bool:
    r"""
    Check if a line segment intersects a rectangle.
    
    :param p1: Start of the line segment.
    :param p2: End of the line segment.
    :param rect: Rectangle (x_min, y_min, x_max, y_max).
    :returns: True if the segment intersects the rectangle.
    :complexity: O(1) time, O(1) space
    """

def get_angle_at_vertex(p0: types.Point, p1: types.Point, p2: types.Point) -> float:
    r"""
    Compute the angle at vertex p1.
    
    :param p0: Previous point.
    :param p1: Vertex point.
    :param p2: Next point.
    :returns: Angle in radians.
    :complexity: O(1) time, O(1) space
    """

def get_interior_angle(p0: types.Point, p1: types.Point, p2: types.Point) -> float:
    r"""
    Interior angle at vertex ``p1`` formed by edges ``p0→p1`` and ``p1→p2``.
    
    Returns 0.0 when any two adjacent points coincide (degenerate input).
    
    :param p0: Previous point.
    :param p1: Vertex point.
    :param p2: Next point.
    :returns: Angle in radians in ``[0, π]``.
    :complexity: O(1) time, O(1) space
    """

def get_line_closest_point(line_p1: types.Point, line_p2: types.Point, x: float, y: float) -> types.Point:
    r"""
    Get the closest point on an **infinite line** to a given point.
    The result may lie beyond the segment endpoints (unclamped projection).
    
    :param line_p1: First point on the line.
    :param line_p2: Second point on the line.
    :param x: X coordinate of target point.
    :param y: Y coordinate of target point.
    :returns: Closest point (x, y) on the infinite line.
    :complexity: O(1) time, O(1) space
    """

def get_line_line_intersection(p1: types.Point, p2: types.Point, p3: types.Point, p4: types.Point) -> typing.Optional[types.Point]:
    r"""
    Get the intersection of two infinite lines.
    
    :param p1: First point on line 1.
    :param p2: Second point on line 1.
    :param p3: First point on line 2.
    :param p4: Second point on line 2.
    :returns: Intersection point (x, y) or None.
    :complexity: O(1) time, O(1) space
    """

def get_line_segment_closest_point(seg_p1: types.Point, seg_p2: types.Point, x: float, y: float) -> tuple[float, types.Point, float]:
    r"""
    Get closest point on a line segment to a point.
    
    :param seg_p1: Start of the line segment.
    :param seg_p2: End of the line segment.
    :param x: X coordinate of target point.
    :param y: Y coordinate of target point.
    :returns: Tuple of (parameter, closest_point, distance).
    :complexity: O(1) time, O(1) space
    """

def get_line_segment_intersection(p1: types.Point, p2: types.Point, p3: types.Point, p4: types.Point) -> typing.Optional[types.Point]:
    r"""
    Get the intersection of two line segments.
    
    :param p1: Start of segment 1.
    :param p2: End of segment 1.
    :param p3: Start of segment 2.
    :param p4: End of segment 2.
    :returns: Intersection point (x, y) or None.
    :complexity: O(1) time, O(1) space
    """

def get_line_segment_length(p1: types.Point, p2: types.Point) -> float:
    r"""
    Compute the length of a line segment.
    
    :param p1: Start point (x, y).
    :param p2: End point (x, y).
    :returns: Distance between the two points.
    :complexity: O(1) time, O(1) space
    """

def get_line_segment_polygon_intersections(p1: types.Point, p2: types.Point, polygon: typing.Sequence[types.Polygon]) -> list[float]:
    r"""
    Get t-values where a line segment intersects a polygon.
    
    :param p1: Start of the line segment.
    :param p2: End of the line segment.
    :param polygon: Polygon to check against.
    :returns: List of t-values of intersection points.
    :complexity: O(n) time, O(1) space
    """

def get_point_line_distance(point: types.Point, line_p1: types.Point, line_p2: types.Point) -> float:
    r"""
    Get the distance from a point to a **line segment**.
    The projection is clamped to the segment, so distance is measured to
    the nearest endpoint when the perpendicular falls outside.
    
    :param point: Point (x, y).
    :param line_p1: First point on the segment.
    :param line_p2: Second point on the segment.
    :returns: Distance (clamped to segment).
    :complexity: O(1) time, O(1) space
    """

def get_segment_segment_distance(a: tuple[float, float], b: tuple[float, float], c: tuple[float, float], d: tuple[float, float]) -> float:
    r"""
    Minimum Euclidean distance between two line segments.
    
    :param a: Start of segment 1.
    :param b: End of segment 1.
    :param c: Start of segment 2.
    :param d: End of segment 2.
    :returns: Minimum distance between the two segments.
    :complexity: O(1) time, O(1) space
    """

def interpolated_segment_3d(from_x: float, from_y: float, to_x: float, to_y: float, z: float, n: int) -> list[tuple[float, float, float]]:
    r"""
    Generate linearly interpolated 3D points along a 2D segment.
    
    Returns *n* points from *from* to *to* at height *z*.  The start is
    **not** included; the end *is* included.
    
    :param from_x: X coordinate of the start.
    :param from_y: Y coordinate of the start.
    :param to_x: X coordinate of the end.
    :param to_y: Y coordinate of the end.
    :param z: Z height for all points.
    :param n: Number of points to generate.
    :returns: List of ``(x, y, z)`` points.
    :complexity: O(n) time, O(1) space
    """

def is_point_on_line_segment(point: types.Point, seg_p1: types.Point, seg_p2: types.Point) -> bool:
    r"""
    Check if a point is on a line segment.
    
    :param point: Point (x, y) to test.
    :param seg_p1: Start of the line segment.
    :param seg_p2: End of the line segment.
    :returns: True if the point lies on the segment.
    :complexity: O(1) time, O(1) space
    """

def longest_line_through_point(pt: tuple[float, float], bbox: tuple[float, float, float, float]) -> tuple[tuple[float, float], tuple[float, float]]:
    r"""
    Find the longest axis-aligned line through a point within a rectangle.
    
    Returns ``(start, end)`` — a horizontal line when the bounding box
    is wider than tall, otherwise a vertical line.
    
    :param pt: ``(x, y)`` point.
    :param bbox: ``(x_min, y_min, x_max, y_max)`` rectangle.
    :returns: ``((x1, y1), (x2, y2))`` start and end of the line.
    :complexity: O(1) time, O(1) space
    """

