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

import builtins
import collections.abc
import raygeo
import typing
from . import resume
from . import routing
from . import tool
__all__ = [
    "AdaptiveClearingSpec",
    "ResumePointNotFoundError",
    "RoutingError",
    "adaptive_clearing",
    "resume",
    "routing",
    "target_area_per_distance",
    "tool",
]

@typing.final
class AdaptiveClearingSpec:
    r"""
    Parameters for the adaptive-clearing assembler.
    """
    @property
    def tool_radius(self) -> builtins.float: ...
    @property
    def step_over(self) -> builtins.float: ...
    @property
    def step_length(self) -> builtins.float: ...
    @property
    def target_z(self) -> builtins.float: ...
    @property
    def safe_z(self) -> builtins.float: ...
    @property
    def max_deflection_deg(self) -> builtins.float: ...
    @property
    def wall_margin(self) -> builtins.float: ...
    @property
    def area_tolerance(self) -> builtins.float: ...
    @property
    def cut_direction(self) -> builtins.str:
        r"""
        ``"cw"`` or ``"ccw"``.
        """
    @property
    def start_pos(self) -> typing.Optional[tuple[builtins.float, builtins.float]]:
        r"""
        Optional override start ``(x, y)``.
        """
    @property
    def start_heading(self) -> typing.Optional[builtins.float]: ...
    @property
    def expansion_batch_size(self) -> builtins.int: ...
    @property
    def trace_path(self) -> typing.Optional[builtins.str]:
        r"""
        Optional path to write a binary trace file.
        """
    @property
    def tolerance(self) -> builtins.float: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(cls, tool_radius: builtins.float = 3.0, step_over: builtins.float = 1.5, step_length: builtins.float = 0.6, target_z: builtins.float = -5.0, safe_z: builtins.float = 2.0, max_deflection_deg: builtins.float = 30.0, wall_margin: builtins.float = 0.0, area_tolerance: builtins.float = 1.0, cut_direction: builtins.str = 'ccw', start_pos: typing.Optional[tuple[builtins.float, builtins.float]] = None, start_heading: typing.Optional[builtins.float] = None, expansion_batch_size: builtins.int = 20, trace_path: typing.Optional[builtins.str] = None, tolerance: builtins.float = 0.1) -> AdaptiveClearingSpec: ...

class ResumePointNotFoundError(builtins.RuntimeError):
    r"""
    Raised when all resume strategies fail to find an engagement point.
    """
    ...

class RoutingError(builtins.RuntimeError):
    r"""
    Raised when all route strategies fail to find a path.
    """
    ...

def adaptive_clearing(part: raygeo.ops.part.Part, tool_radius: float = 3, step_over: float = 1.5, step_length: float = 0.6, target_z: float = -5, safe_z: float = 2, max_deflection_deg: float = 30, wall_margin: float = 0, area_tolerance: float = 1, cut_feed_rate: int = 1200, cut_power: float = 1, start_pos: tuple[float, float] | None = None, start_heading: float | None = None, expansion_batch_size: int = 20, profile: bool = False, cut_direction: str = 'ccw', trace_path: str | None = None, on_progress: collections.abc.Callable[[dict], None] | None = None, batch_size: int = 128) -> raygeo.ops.assembly.AssemblyResult:
    r"""
    Run forward-stepping adaptive clearing.
    
    Starting from the pre-populated cleared area inside *part*,
    uses a constant-engagement stepping solver to generate a
    continuous spiral toolpath from the seed clearing to the
    pocket wall.
    
    The caller is responsible for populating the part's cleared
    area with the entry polygons (e.g. via a workplan built by
    :func:`raygeo.cnc.machining.entry.build_entry_workplan`
    and executed by
    :class:`raygeo.cnc.machining.plan.Workplan`) and
    prepending the entry Ops to the result.
    
    :param part: The part whose ``cleared`` field tracks accumulated
                 workpiece state and whose geometry defines the
                 pocket boundary and islands.
    :param tool_radius: Tool radius in mm (default 3.0).
    :param step_over: Step-over distance (default 1.5).
    :param step_length: Forward step length in mm (default 0.6).
    :param target_z: Cutting Z height (default -5.0).
    :param safe_z: Retract Z height for travel (default 2.0).
    :param max_deflection_deg: Maximum steering deflection per step
                               in degrees (default 30).
    :param wall_margin: Extra clearance between tool and boundary (default 0.0).
    :param area_tolerance: Stop when remaining uncut area drops below
                           this threshold (default 1.0).
    :param cut_feed_rate: Feed rate for cutting moves (default 1200).
    :param cut_power: Laser power for cutting moves (0.0-1.0, default 1.0).
    :param start_pos: Initial tool position (x, y).  When None,
                      auto-detected from the cleared-area frontier.
    :param start_heading: Initial tool heading in radians.  When None,
                          auto-detected as the CCW tangent at start_pos.
    :param expansion_batch_size: Batch cleared-area expansions every
                                 N steps (default 20).  Larger values
                                 improve performance but may slightly
                                 reduce path quality.
    :param profile: Print a profiling report to stdout (default False).
    :param cut_direction: Rotational direction of all cutting moves.
                          ``"cw"`` or ``"ccw"`` (default ``"ccw"``).
    :param trace_path: When set, write a per-step binary trace file for
                       the Python inspector (debug builds only).
    :param on_progress: Optional callback receiving progress dicts.
    :param batch_size: Ops batch size for on_progress (default 128).
    :returns: Ops with cutting commands (entry not included).
    """

def target_area_per_distance(radius: builtins.float, advance: builtins.float, step_length: builtins.float) -> builtins.float:
    r"""
    Target cut-area per unit distance for the engagement solver.
    
    :param radius: Tool radius in mm.
    :param advance: Step-over distance in mm.
    :param step_length: Forward step length in mm.
    :returns: Target area per distance (mm).
    """

