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

import builtins
import collections.abc
import raygeo
import typing
__all__ = [
    "ToroidSpec",
    "ToroidalClearSpec",
    "generate_toroid",
    "generate_toroidal_clear",
]

@typing.final
class ToroidSpec:
    r"""
    Parameters for the ``toroid`` (constant-Z trochoid along a carrier)
    assembler.
    """
    @property
    def carrier(self) -> builtins.list[tuple[builtins.float, builtins.float]]:
        r"""
        ``(x, y)`` carrier waypoints.
        """
    @property
    def tool_radius(self) -> builtins.float: ...
    @property
    def step_over(self) -> builtins.float: ...
    @property
    def target_z(self) -> builtins.float: ...
    @property
    def direction(self) -> builtins.str:
        r"""
        ``"CW"`` or ``"CCW"``.
        """
    @property
    def angular_step(self) -> builtins.float: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(cls, carrier: typing.Sequence[tuple[builtins.float, builtins.float]], tool_radius: builtins.float, step_over: builtins.float, target_z: builtins.float, direction: builtins.str = 'CW', angular_step: builtins.float = 0.1) -> ToroidSpec: ...

@typing.final
class ToroidalClearSpec:
    r"""
    Parameters for the ``toroidal_clear`` (ramped Z-descending trochoid)
    assembler.
    """
    @property
    def carrier(self) -> builtins.list[tuple[builtins.float, builtins.float]]:
        r"""
        ``(x, y)`` carrier waypoints.
        """
    @property
    def start(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        ``(x, y, z)`` entry point; ``x, y`` should match ``carrier[0]``,
        ``z`` is the entry height.
        """
    @property
    def target_z(self) -> builtins.float: ...
    @property
    def tool_radius(self) -> builtins.float: ...
    @property
    def step_over(self) -> builtins.float: ...
    @property
    def max_ramp_angle_deg(self) -> builtins.float: ...
    @property
    def direction(self) -> builtins.str:
        r"""
        ``"CW"`` or ``"CCW"``.
        """
    @property
    def angular_step(self) -> builtins.float: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(cls, carrier: typing.Sequence[tuple[builtins.float, builtins.float]], start: tuple[builtins.float, builtins.float, builtins.float], target_z: builtins.float, tool_radius: builtins.float, step_over: builtins.float, max_ramp_angle_deg: builtins.float = 5.0, direction: builtins.str = 'CW', angular_step: builtins.float = 0.1) -> ToroidalClearSpec: ...

def generate_toroid(part: raygeo.ops.part.Part, carrier: collections.abc.Sequence[tuple[float, float]], tool_radius: float, step_over: float, target_z: float, direction: str = 'CW', angular_step: float = 0.1, state: raygeo.ops.state.State | None = None) -> raygeo.ops.assembly.AssemblyResult:
    r"""
    Generate a toroidal (trochoidal) path along a carrier.
    
    Produces a trochoidal looping path that follows the *carrier*
    polyline, clearing a slot of width *tool_radius*.
    
    :param carrier: List of ``(x, y)`` waypoints defining the slot axis.
    :param tool_radius: Tool radius in mm.
    :param step_over: Forward advance per trochoid loop.
    :param target_z: Cutting Z height.
    :param direction: ``"CW"`` or ``"CCW"`` (default ``"CW"``).
    :param angular_step: Angular step in radians (default 0.1).
    :param state: Optional machine state to apply before the path.
    :returns: An :class:`AssemblyResult` with the toroidal path.
    """

def generate_toroidal_clear(part: raygeo.ops.part.Part, carrier: collections.abc.Sequence[tuple[float, float]], start: tuple[float, float, float], target_z: float, tool_radius: float, step_over: float, max_ramp_angle_deg: float = 5, direction: str = 'CW', angular_step: float = 0.1, state: raygeo.ops.state.State | None = None) -> raygeo.ops.assembly.AssemblyResult:
    r"""
    Generate a ramp-down toroidal clear path along a carrier.
    
    Descends Z linearly along the carrier's arc-length at a slope
    capped by ``max_ramp_angle_deg``, zig-zagging back-and-forth along
    the carrier until ``target_z`` is reached, then emits one final
    full forward pass at constant ``target_z``.
    
    :param carrier: 2D polyline ``(x, y)`` waypoints defining the slot axis.
    :param start: ``(x, y, z)`` entry point; ``x, y`` should match ``carrier[0]``,
        ``z`` is the entry height.
    :param target_z: Final cutting Z height.
    :param tool_radius: Tool radius in mm.
    :param step_over: Forward advance per trochoid loop.
    :param max_ramp_angle_deg: Maximum descent angle vs. the XY plane (default 5°).
    :param direction: ``"CW"`` or ``"CCW"`` (default ``"CW"``).
    :param angular_step: Angular step in radians (default 0.1).
    :param state: Optional machine state.
    :returns: An :class:`AssemblyResult` with the ramp-down + flat-final toroidal path.
    """

