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

import builtins
from raygeo.ops import part
import typing
__all__ = [
    "ClearedArea",
]

@typing.final
class ClearedArea:
    def __new__(cls, initial: typing.Optional[typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]] = None) -> ClearedArea:
        r"""
        Create an empty ClearedArea.
        
        :param initial: Optional pre-seeded cleared polygons.
        """
    def expand(self, path: typing.Sequence[tuple[builtins.float, builtins.float]], radius: builtins.float) -> None:
        r"""
        Sweep a disk along a polyline, adding the swept area to the
        cleared set.
        
        :param path: List of ``(x, y)`` points forming the polyline.
        :param radius: Disk radius (mm).
        :complexity: O(n) where n = number of path points
        """
    def expand_step(self, prev: tuple[builtins.float, builtins.float], next: tuple[builtins.float, builtins.float], radius: builtins.float) -> None:
        r"""
        Expand the cleared area by sweeping a disk of *radius* along a
        single segment from *prev* to *next*.
        
        :param prev: Start point ``(x, y)`` of the segment.
        :param next: End point ``(x, y)`` of the segment.
        :param radius: Disk radius (mm).
        """
    def signed_boundary_distance(self, x: builtins.float, y: builtins.float) -> builtins.float:
        r"""
        Signed perpendicular distance to the nearest cleared boundary.
        
        Returns positive when the point is outside the cleared area
        (in uncut material), negative when inside.
        
        :param x: X coordinate of the query point.
        :param y: Y coordinate of the query point.
        :returns: Signed distance in mm.  ``0.0`` means exactly on
                  the boundary.
        """
    def cut(self, polygons: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]) -> None:
        r"""
        Add pre-computed polygons to the cleared set.
        
        :param polygons: List of polygons (each a list of ``(x, y)``
                         vertices) to add.
        :complexity: O(n) where n = total vertices across all polygons
        """
    def query_window(self, bbox: tuple[builtins.float, builtins.float, builtins.float, builtins.float]) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Return fragments whose bounding box overlaps the query window.
        
        :param bbox: Bounding box ``(x_min, y_min, x_max, y_max)``.
        :returns: Fragments intersecting the bounding box.
        :complexity: O(m + k) where m = number of fragments,
                     k = output vertices
        """
    def remaining(self, region: part.StockRegion) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Subtract cleared fragments from the stock, returning the uncut
        portion.
        
        :param region: StockRegion defining the boundary and islands.
        :returns: List of polygons representing the uncut portion.
        :complexity: O(n * m) where n = stock vertices, m = fragments
        """
    def cut_fast(self, polygons: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Add polygons, returning only the newly-added portion.
        Faster than ``cut`` when inputs don't overlap existing fragments
        (skips the full union).
        
        :param polygons: List of polygons to add.
        :returns: List of polygons representing the newly-added portion.
        :complexity: O(n log n) worst case when union required,
                     O(n) when inputs are disjoint from existing fragments
        """
    def frontier(self, region: part.StockRegion, simplify_tol: builtins.float) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Return a unioned, simplified snapshot of the current outer
        boundary, clipped to the stock.
        
        :param region: StockRegion defining the boundary and islands.
        :param simplify_tol: Tolerance in mm for polyline simplification.
        :returns: List of polygons representing the outer boundary.
        :complexity: O(n log n)
        """
    def bites(self, region: part.StockRegion, step_over: builtins.float, tool_radius: builtins.float, simplify_tol: builtins.float) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Compute the "bites" — new material reachable by expanding the
        current frontier outward by *step_over*, clipping to the
        tool-centre envelope, and subtracting already-cleared portions.
        
        :param region: StockRegion defining the boundary and islands.
        :param step_over: Lateral step-over in mm.
        :param tool_radius: Tool radius (mm) for computing the envelope.
        :param simplify_tol: Tolerance in mm for frontier simplification.
        :returns: List of polygons representing the bite regions.
        :complexity: O(n log n)
        """
    def begin_batch(self) -> None:
        r"""
        Begin buffering single-segment expansions.
        
        Subsequent calls to ``expand_batched`` are queued without a
        union.  Call ``commit_batch`` to union all queued sweeps with
        the stored fragments in a single pass.
        
        Calling this while a batch is already active is a no-op.
        """
    def expand_batched(self, prev: tuple[builtins.float, builtins.float], next: tuple[builtins.float, builtins.float], radius: builtins.float) -> None:
        r"""
        Queue a single-segment expansion into the current batch.
        
        The segment swept polygon is stored in the internal buffer.
        Does **not** perform a union until ``commit_batch`` is called.
        
        :param prev: Start point ``(x, y)`` of the segment.
        :param next: End point ``(x, y)`` of the segment.
        :param radius: Disk radius (mm).
        
        .. warning::
            Panics if ``begin_batch`` was not called first.
        """
    def commit_batch(self) -> None:
        r"""
        Union all buffered sweeps with stored fragments in a single pass,
        then rebuild the spatial grid.
        
        After this call the batch is closed (the caller may start a new
        one).
        """
    def commit_batch_local(self) -> None:
        r"""
        Union only the buffered sweeps with nearby overlapping fragments,
        using the spatial grid to avoid touching distant fragments.
        
        After this call the batch is closed (the caller may start a new
        one).
        """
    def get_point_engagement(self, center: tuple[builtins.float, builtins.float], radius: builtins.float) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Evaluate engagement at a point using the signed distance to this
        cleared area's boundary.
        
        :param center: Query point ``(x, y)``.
        :param radius: Disk radius (mm).
        :returns: ``(angle_rad, area, chord_depth)``.
        """
    def get_angular_engagement(self, center: tuple[builtins.float, builtins.float], radius: builtins.float) -> builtins.float:
        r"""
        Compute angular engagement by exact circle-polygon intersection.
        
        Creates a disk polygon at *center* with *radius*, intersects it
        with all nearby cleared fragments, and returns the uncleared
        angular extent in ``[0, 2*pi]``.
        
        :param center: Query point ``(x, y)``.
        :param radius: Disk radius (mm).
        :returns: Uncleared angular extent (radians).
        """
    def cut_area(self, c1: tuple[builtins.float, builtins.float], c2: tuple[builtins.float, builtins.float], radius: builtins.float) -> builtins.float:
        r"""
        Incremental cut area when the tool moves from *c1* to *c2*.
        
        Computes the fresh material area inside the disk at *c2* that is
        not already cleared (crescent area).
        
        :param c1: Previous centre ``(x, y)``.
        :param c2: Next centre ``(x, y)``.
        :param radius: Disk radius (mm).
        :returns: Fresh cut area (mm2).
        """
    def path_engagement(self, path: typing.Sequence[tuple[builtins.float, builtins.float]], radius: builtins.float) -> builtins.list[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Evaluate engagement along a polyline.
        
        :param path: List of ``(x, y)`` points.
        :param radius: Disk radius (mm).
        :returns: List of ``(angle, area, chord_depth)`` tuples.
        """
    def compact_if_needed(self, region: part.StockRegion, tol: builtins.float) -> None:
        r"""
        Compact fragments if total vertex count exceeds the default
        threshold.
        
        :param region: StockRegion defining the boundary and islands.
        :param tol: Vertex simplification tolerance in mm.
        """
    def compact_if_needed_threshold(self, region: part.StockRegion, tol: builtins.float, threshold: builtins.int) -> None:
        r"""
        Compact with an explicit vertex-count threshold.
        
        :param region: StockRegion defining the boundary and islands.
        :param tol: Vertex simplification tolerance in mm.
        :param threshold: Vertex count threshold above which compaction
                          is triggered.
        """
    def total_area(self) -> builtins.float:
        r"""
        Total cleared area.
        
        :returns: Total cleared area in mm2.
        :complexity: O(1)
        """
    def remaining_area(self, region: part.StockRegion) -> builtins.float:
        r"""
        Remaining uncut area (boundary minus islands minus cleared
        fragments).  Only positive-area (CCW) polygons are counted,
        so island holes do not inflate the result.
        
        :param region: StockRegion defining the boundary and islands.
        :returns: Remaining uncut area in mm2.
        """
    def actionable_remaining(self, region: part.StockRegion, inset_distance: builtins.float) -> builtins.float:
        r"""
        Uncleared area **inside the actionable zone** of the pocket.
        
        The actionable zone is the boundary inset by
        ``inset_distance``, with islands buffered by the same amount.
        Material outside this zone -- wall-band slivers thinner than
        ``inset_distance`` -- is excluded, so this metric can gate
        convergence on whether any *actionable* material remains.
        
        ``inset_distance`` is typically ``step_length``: slivers
        thinner than the per-step advance get skipped by the
        stepper, so they should not gate convergence.
        
        :param region: StockRegion defining the boundary and islands.
        :param inset_distance: Inset distance (mm) defining the
                               actionable zone (boundary inset,
                               islands buffered).
        :returns: Actionable remaining area in mm2.
        """
    def fragments(self) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Return the union of all polygons currently tracked as cleared.
        
        Each fragment is a closed polygon (list of ``(x, y)`` vertices)
        representing an area that has already been cut.  The fragment set
        grows as ``cut_fast`` or ``cut`` are called.
        
        This is useful for inspecting which areas have been cleared.
        
        :returns: List of polygons representing the cleared fragments.
        :complexity: O(m) where m = number of fragments
        """
    def __len__(self) -> builtins.int:
        r"""
        Number of cleared fragments.
        
        :returns: Fragment count.
        """
    def envelope(self, region: part.StockRegion, tool_radius: builtins.float) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        The tool-centre envelope (inset of boundary by ``tool_radius``,
        minus islands).
        
        :param region: StockRegion defining the boundary and islands.
        :param tool_radius: Tool radius (mm).
        :returns: List of polygons representing the tool-centre envelope.
        """
    def is_empty(self) -> builtins.bool:
        r"""
        True when no fragments have been recorded.
        
        :returns: ``True`` if no fragments have been recorded.
        """
    def __repr__(self) -> builtins.str: ...

