# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Polyline smoothing using Gaussian kernels.

Provides Gaussian kernel computation and circular/linear polyline
smoothing with configurable corner angle thresholds to preserve
sharp features.
"""

import collections.abc
from raygeo.geo import types
import typing
__all__ = [
    "blend_tangent",
    "build_smoothed_path",
    "chaikin_corner_cut",
    "compute_gaussian_kernel",
    "shortcut_path",
    "smooth_circularly",
    "smooth_path",
    "smooth_polyline_3d",
    "smooth_sub_segment",
]

def blend_tangent(link: collections.abc.Sequence[tuple[float, float]], prev_tail: collections.abc.Sequence[tuple[float, float]], next_head: collections.abc.Sequence[tuple[float, float]], margin: float) -> list[tuple[float, float]]:
    r"""
    Insert tangent extension points at both ends of a connecting polyline.
    
    Returns a new polyline with points inserted to ensure it meets
    the adjacent polylines tangentially (G1 continuity).
    
    :param link: Connecting polyline as a list of (x, y) tuples.
    :param prev_tail: Last 2+ points of the preceding polyline.
    :param next_head: First 2+ points of the following polyline.
    :param margin: Extension distance along the tangent direction.
    :returns: Modified polyline with tangent extension points inserted.
    """

def build_smoothed_path(last: tuple[float, float], first: tuple[float, float], waypoints: collections.abc.Sequence[tuple[float, float]] = [], uncleared: collections.abc.Sequence[collections.abc.Sequence[tuple[float, float]]] = [], clearance: float = 1, smoothing_amount: int = 120) -> list[tuple[float, float]]:
    r"""
    Build a smooth path between two points via multi-stage processing.
    
    Pipeline:
    1. Prepends *last* and appends *first* to *waypoints*.
    2. Resamples for point density.
    3. Iteratively shortcuts removable waypoints (collision-checked).
    4. Applies aggressive Gaussian smoothing with per-point collision
       checking so points near obstacles are preserved while open
       areas are fully rounded.
    
    :param last: Start point (x, y).
    :param first: End point (x, y).
    :param waypoints: Intermediate waypoints between *last* and *first*.
    :param uncleared: Obstacle polygons to avoid.
    :param clearance: Minimum distance from obstacles.
    :param smoothing_amount: Gaussian smoothing amount (0-200, default 120).
    :returns: Smoothed path as a list of (x, y) tuples.
    """

def chaikin_corner_cut(points: collections.abc.Sequence[tuple[float, float]], obstacles: collections.abc.Sequence[collections.abc.Sequence[tuple[float, float]]] = [], clearance: float = 1, iterations: int = 6) -> list[tuple[float, float]]:
    r"""
    Round sharp corners using Chaikin corner cutting with collision checking.
    
    Corners sharper than 45° are cut; gently curving sections are left
    untouched.  Each cut point is collision-tested against *obstacles*
    at *clearance* distance; if the cut would collide, the original
    corner is preserved.
    
    :param points: Polyline as a list of (x, y) tuples.
    :param obstacles: List of obstacle polygons (each a list of (x, y)).
    :param clearance: Minimum distance from obstacles (default 1.0).
    :param iterations: Number of Chaikin cutting passes (default 6).
    :returns: Corner-smoothed polyline as a list of (x, y) tuples.
    """

def compute_gaussian_kernel(amount: int) -> tuple[list[float], float]:
    r"""
    Compute a Gaussian kernel of the given size.
    
    :param amount: Kernel size.
    :returns: Tuple of (kernel_values, sigma).
    :complexity: O(k) time, O(k) space
    """

def shortcut_path(points: collections.abc.Sequence[tuple[float, float]], obstacles: collections.abc.Sequence[collections.abc.Sequence[tuple[float, float]]], clearance: float) -> list[tuple[float, float]]:
    r"""
    Iteratively remove interior waypoints whose direct connection
    (prev → next) is collision-free, repeating until no more points
    can be removed.  Endpoints are always preserved.
    
    :param points: Polyline as a list of (x, y) tuples.
    :param obstacles: List of obstacle polygons (each a list of (x, y)).
    :param clearance: Minimum distance the path must keep from obstacles.
    :returns: Shortcutted polyline as a list of (x, y) tuples.
    :complexity: O(n²) worst-case time, O(n) space
    """

def smooth_circularly(points: collections.abc.Sequence[types.Point3D], kernel: collections.abc.Sequence[float]) -> list[types.Point3D]:
    r"""
    Smooth a closed polyline circularly.
    
    :param points: Sequence of 3D points to smooth.
    :param kernel: Gaussian kernel values.
    :returns: Smoothed points.
    :complexity: O(n * k) time, O(n) space where k is the kernel size and n the number of points
    """

def smooth_path(points: collections.abc.Sequence[tuple[float, float]], obstacles: collections.abc.Sequence[collections.abc.Sequence[tuple[float, float]]], clearance: float, smoothing_amount: int = 50) -> list[tuple[float, float]]:
    r"""
    Smooth a polyline while avoiding obstacles.
    
    Two-phase constrained smoothing:
    
    1. **Shortcut** – greedily removes intermediate waypoints whose
       direct connection stays clear of all *obstacles* by at least
       *clearance*.
    2. **Gaussian relaxation** – iteratively applies Gaussian smoothing,
       reverting any point whose smoothed position would violate the
       clearance constraint.
    
    Endpoints are always preserved.
    
    :param points: Polyline as a list of (x, y) tuples.
    :param obstacles: List of obstacle polygons (each a list of (x, y)).
    :param clearance: Minimum distance the path must keep from obstacles.
    :param smoothing_amount: Gaussian smoothing amount 0–200 (default 50).
                             0 applies shortcut only.
    :returns: Smoothed polyline as a list of (x, y) tuples.
    """

def smooth_polyline_3d(points: collections.abc.Sequence[types.Point3D], amount: int, corner_angle_threshold: float, is_closed: typing.Optional[bool] = None) -> list[types.Point3D]:
    r"""
    Smooth a 3D polyline using Gaussian smoothing.
    
    :param points: Sequence of 3D points to smooth.
    :param amount: Smoothing amount (kernel size).
    :param corner_angle_threshold: Angle threshold for preserving corners.
    :param is_closed: Whether the polyline is closed.
    :returns: Smoothed 3D points.
    :complexity: O(n * k) time, O(n) space where k is the kernel size and n the number of points
    """

def smooth_sub_segment(points: collections.abc.Sequence[types.Point3D], kernel: collections.abc.Sequence[float]) -> list[types.Point3D]:
    r"""
    Smooth a sub-segment of a polyline.
    
    :param points: Sequence of 3D points to smooth.
    :param kernel: Gaussian kernel values.
    :returns: Smoothed points.
    :complexity: O(n * k) time, O(n) space where k is the kernel size and n the number of points
    """

