# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
from raygeo.ops.part import cleared_area
import typing
__all__ = [
    "StepResult",
    "StepStatus",
    "StepperOptions",
    "step",
]

@typing.final
class StepResult:
    r"""
    Result of a single forward step.
    
    Contains the next centre position, updated heading,
    solver iteration count, and the final status.
    """
    @property
    def next(self) -> tuple[builtins.float, builtins.float]:
        r"""
        Next centre position ``(x, y)``.
        """
    @property
    def heading(self) -> builtins.float:
        r"""
        Updated heading angle in radians.
        """
    @property
    def cut_area(self) -> builtins.float:
        r"""
        The incremental cut area (crescent) for this step.
        """
    @property
    def iters(self) -> builtins.int:
        r"""
        Number of solver iterations used.
        """
    @property
    def iteration_angle(self) -> builtins.float:
        r"""
        Solver steering angle (radians). Only non-zero for
        ``step``.
        """
    @property
    def status(self) -> StepStatus:
        r"""
        Step completion status.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class StepStatus:
    r"""
    Status of a single step or cut segment.
    
    One of ``Ok`` (normal), ``BoundaryHit`` (hit pocket boundary),
    ``LostEngagement`` (no uncut material), or ``NoConvergence``
    (solver failed to converge).
    """
    @classmethod
    def ok(cls) -> StepStatus:
        r"""
        Normal step completion.
        :returns: ``StepStatus.ok``
        """
    @classmethod
    def boundary_hit(cls) -> StepStatus:
        r"""
        Hit pocket boundary.
        :returns: ``StepStatus.boundary_hit``
        """
    @classmethod
    def lost_engagement(cls) -> StepStatus:
        r"""
        No uncut material found.
        :returns: ``StepStatus.lost_engagement``
        """
    @classmethod
    def no_convergence(cls) -> StepStatus:
        r"""
        Solver failed to converge.
        :returns: ``StepStatus.no_convergence``
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class StepperOptions:
    r"""
    Configuration options for :func:`step`.
    
    Holds the constant parameters for the adaptive stepper.
    """
    @property
    def target_area_pd(self) -> builtins.float:
        r"""
        Target cut-area per unit distance.
        """
    @target_area_pd.setter
    def target_area_pd(self, value: builtins.float) -> None:
        r"""
        Target cut-area per unit distance.
        """
    @property
    def step_length(self) -> builtins.float:
        r"""
        Forward step length in mm.
        """
    @step_length.setter
    def step_length(self, value: builtins.float) -> None:
        r"""
        Forward step length in mm.
        """
    @property
    def radius(self) -> builtins.float:
        r"""
        Disk radius in mm.
        """
    @radius.setter
    def radius(self, value: builtins.float) -> None:
        r"""
        Disk radius in mm.
        """
    @property
    def max_deflection(self) -> builtins.float:
        r"""
        Maximum steering deflection in radians.
        """
    @max_deflection.setter
    def max_deflection(self, value: builtins.float) -> None:
        r"""
        Maximum steering deflection in radians.
        """
    @property
    def valid_area(self) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Valid tool-centre region polygons.
        """
    @valid_area.setter
    def valid_area(self, value: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]) -> None:
        r"""
        Valid tool-centre region polygons.
        """
    @property
    def angle_min(self) -> builtins.float:
        r"""
        Minimum trial deflection angle in radians.
        """
    @angle_min.setter
    def angle_min(self, value: builtins.float) -> None:
        r"""
        Minimum trial deflection angle in radians.
        """
    @property
    def angle_max(self) -> builtins.float:
        r"""
        Maximum trial deflection angle in radians.
        """
    @angle_max.setter
    def angle_max(self, value: builtins.float) -> None:
        r"""
        Maximum trial deflection angle in radians.
        """
    @property
    def dir_sign(self) -> builtins.float:
        r"""
        Directional bias sign: ``+1.0`` for CW, ``-1.0`` for CCW,
        ``0.0`` for no bias.
        """
    @dir_sign.setter
    def dir_sign(self, value: builtins.float) -> None:
        r"""
        Directional bias sign: ``+1.0`` for CW, ``-1.0`` for CCW,
        ``0.0`` for no bias.
        """
    def __new__(cls, target_area_pd: builtins.float, step_length: builtins.float, radius: builtins.float, max_deflection: builtins.float, valid_area: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]], angle_min: builtins.float = -0.7853981633974483, angle_max: builtins.float = 0.7853981633974483, dir_sign: builtins.float = 0.0) -> StepperOptions: ...
    def __repr__(self) -> builtins.str: ...

def step(cleared: cleared_area.ClearedArea, pos: tuple[builtins.float, builtins.float], heading: builtins.float, predicted_angle: builtins.float, opts: StepperOptions) -> StepResult:
    r"""
    Perform one forward step using the area-based adaptive solver.
    
    :param cleared: ``ClearedArea`` instance.
    :param pos: Current centre position ``(x, y)``.
    :param heading: Smoothed heading angle (radians).
    :param predicted_angle: Predicted steering angle from history.
    :param opts: ``StepperOptions`` instance with fixed parameters.
    :returns: ``StepResult`` with the next position and updated heading.
    """

