# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Motion-path assembly: turning raw geometry primitives into Ops.

Functions in this module compose geo-layer primitives (polylines, arcs,
polygons) into complete motion sequences represented as Ops objects.
They decide traversal order, linking strategy, lead-in/out, overscan,
and tab insertion — concerns that belong to motion assembly rather
than pure geometry.

Each assembler exposes a spec class (e.g.
:class:`~raygeo.ops.assembly.contour.ContourSpec`) implementing the
Rust ``Assembler`` trait; :class:`Assembler` wraps any spec so callers
can drive it through the trait.
"""

import builtins
from raygeo import ops
from raygeo.ops.cut import search
from raygeo.ops import part
import typing
from . import adaptive
from . import contour
from . import frame
from . import helix
from . import material_test_grid
from . import profile
from . import ramp
from . import raster
from . import shrinkwrap
from . import slot
from . import spiral
from . import toroid
from . import wavefront
__all__ = [
    "Assembler",
    "AssemblyOutput",
    "AssemblyResult",
    "adaptive",
    "contour",
    "frame",
    "helix",
    "material_test_grid",
    "profile",
    "ramp",
    "raster",
    "shrinkwrap",
    "slot",
    "spiral",
    "toroid",
    "wavefront",
]

@typing.final
class Assembler:
    r"""
    Python-visible wrapper around an assembler spec.
    
    Construct as ``Assembler(spec)`` where `spec` is an instance of
    one of the assembler spec classes under `raygeo.ops.assembly.*`
    (e.g. :class:`~raygeo.ops.assembly.contour.ContourSpec`). Callers
    that drive the `Assembler` trait hold an `Assembler` instance.
    """
    @property
    def spec(self) -> typing.Any:
        r"""
        The wrapped Python-side spec object. Type-erased here;
        dispatched to a concrete `Box<dyn Assembler>` by
        [`PyAssembler::into_core`].
        """
    def __new__(cls, spec: typing.Any) -> Assembler:
        r"""
        Construct an `Assembler` wrapping a spec object.
        
        :param spec: An assembler spec instance (e.g.
            :class:`~raygeo.ops.assembly.contour.ContourSpec`).
        """
    def __repr__(self) -> builtins.str: ...
    def cache_key(self, part: part.Part, tag: builtins.str) -> typing.Optional[tuple[builtins.str, builtins.int]]:
        r"""
        Compute a cache key for this assembler against the given part.
        
        Returns ``None`` for assemblers that opt out of caching, or
        a ``(tag, payload_hash)`` tuple for assemblers that opt in.
        """

@typing.final
class AssemblyOutput:
    r"""
    The output of an assembler, packaged for caching.
    
    Produced by
    :meth:`Assembler.store_cache() <raygeo.ops.assembly.Assembler.store_cache>`
    and consumed by
    :meth:`Assembler.restore_cache() <raygeo.ops.assembly.Assembler.restore_cache>`.
    
    Carries the assembled ``Ops``, metadata, and optional post-assembly
    cleared fragments for face-state restoration on cache hit.
    """
    @property
    def ops(self) -> ops.Ops:
        r"""
        The assembled Ops.
        """
    @property
    def is_scalable(self) -> builtins.bool:
        r"""
        Whether the Ops may be uniformly scaled during aggregation.
        """
    @property
    def source_dimensions(self) -> typing.Optional[tuple[builtins.float, builtins.float]]:
        r"""
        Source ``(width_mm, height_mm)`` of the part that produced the Ops.
        """
    @property
    def cleared_fragments(self) -> typing.Optional[builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]]:
        r"""
        Post-assembly cleared fragments (``list[list[(x, y)]]``), or
        ``None`` for assemblers that don't touch ``FaceState.cleared``.
        """
    def __new__(cls, ops: ops.Ops, is_scalable: builtins.bool = False, source_dimensions: typing.Optional[tuple[builtins.float, builtins.float]] = None, cleared_fragments: typing.Optional[typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]] = None) -> AssemblyOutput: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class AssemblyResult:
    r"""
    Universal return type for every assembly-level generator.
    
    Returned by assemblers such as ``generate_helix``,
    ``generate_toroidal_clear``, ``generate_slot``, and all other
    assembly-level motion functions.  Contains the generated ``Ops``
    sequence, the set of polygons that this operation clears, and the
    tool pose at the start and end of the path.
    """
    @property
    def ops(self) -> ops.Ops: ...
    @property
    def start(self) -> search.ToolPose: ...
    @property
    def end(self) -> search.ToolPose: ...
    @property
    def trace(self) -> typing.Optional[typing.Any]: ...
    def __new__(cls) -> AssemblyResult: ...
    @staticmethod
    def from_ops(ops: ops.Ops, start: tuple[builtins.float, builtins.float, builtins.float], end: tuple[builtins.float, builtins.float, builtins.float]) -> AssemblyResult:
        r"""
        Construct an AssemblyResult from ops, start, and end poses.
        """
    def write_trace(self, path: builtins.str, source: builtins.str, label: builtins.str) -> None:
        r"""
        Write this result's trace events to a trace file.
        
        Emits a root "workplan" span with one child assembler span
        containing either the self-traced events or a minimal
        init/exit pair.
        """
    def __repr__(self) -> builtins.str: ...

