# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
CNC execution spec types.
"""

import builtins
from raygeo import ops
from raygeo.ops import convert
import typing
__all__ = [
    "AggregateGroup",
    "AggregateInput",
    "AggregateOutput",
    "AggregateSpec",
    "ComputePayload",
    "EncodeSpec",
    "LinkMode",
    "MachineParams",
    "Marker",
]

@typing.final
class AggregateGroup:
    r"""
    A group of inputs within an ``AggregateSpec``.
    
    Each group emits its own start/end markers, processes its inputs
    in order (optionally linking consecutive inputs when
    ``link_mode`` is ``Sequential``), and supports per-input placement
    and scaling.
    """
    @property
    def start_markers(self) -> builtins.list[Marker]:
        r"""
        Markers emitted before this group's inputs.
        """
    @property
    def inputs(self) -> builtins.list[AggregateInput]:
        r"""
        Upstream inputs to concatenate (in order).
        """
    @property
    def end_markers(self) -> builtins.list[Marker]:
        r"""
        Markers emitted after this group's inputs.
        """
    @property
    def link_mode(self) -> LinkMode:
        r"""
        Inter-input linking control (default ``LinkMode.none()``).
        """
    def __new__(cls, start_markers: typing.Sequence[Marker], inputs: typing.Sequence[AggregateInput], end_markers: typing.Sequence[Marker], link_mode: typing.Optional[LinkMode] = None) -> AggregateGroup: ...

@typing.final
class AggregateInput:
    r"""
    A single source input in an ``AggregateGroup``.
    
    Identifies an upstream node by key and optionally applies a
    placement matrix and uniform scaling.
    """
    @property
    def source_key(self) -> builtins.str:
        r"""
        Key of the upstream node whose Ops to consume.
        """
    @property
    def placement_matrix(self) -> builtins.list[builtins.list[builtins.float]]:
        r"""
        4×4 placement matrix (row-major) applied to all points in
        the source Ops.
        """
    @property
    def uid(self) -> builtins.str:
        r"""
        Optional UID carried through for marker correlation (not
        used by the pipeline core).
        """
    @property
    def target_dimensions(self) -> tuple[builtins.float, builtins.float]:
        r"""
        Target dimensions for uniform scaling ``(width, height)``.
        When ``(0, 0)`` (default), no scaling is applied.
        """
    def __new__(cls, source_key: builtins.str, placement_matrix: typing.Sequence[typing.Sequence[builtins.float]], uid: builtins.str = '', target_dimensions: tuple[builtins.float, builtins.float] = (0.0, 0.0)) -> AggregateInput: ...

@typing.final
class AggregateOutput:
    r"""
    Result of the ``Aggregate`` stage.
    
    Produced when the pipeline executes an ``AggregateSpec`` and contains
    the concatenated/transformed Ops together with an optional time
    estimate.
    """
    @property
    def ops(self) -> ops.Ops:
        r"""
        The concatenated Ops from all inputs in the aggregate.
        """
    @property
    def time_estimate(self) -> typing.Optional[builtins.float]:
        r"""
        Estimated machining time in seconds, or ``None`` when the
        ``MachineParams`` rates are all zero.
        """
    @property
    def ops_len(self) -> builtins.int:
        r"""
        Number of commands in the aggregated Ops.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class AggregateSpec:
    r"""
    Configuration for the ``Aggregate`` stage.
    
    An aggregate concatenates Ops from multiple upstream nodes, wraps
    them in markers (job/layer/workpiece start/end), applies per-input
    placement and scaling, optionally links consecutive inputs with
    travel moves, and applies batch transformers.
    """
    @property
    def wrap_start(self) -> builtins.list[Marker]:
        r"""
        Markers emitted before all groups (e.g. ``JobStart``).
        """
    @property
    def groups(self) -> builtins.list[AggregateGroup]:
        r"""
        Groups of inputs, each processed in order.
        """
    @property
    def wrap_end(self) -> builtins.list[Marker]:
        r"""
        Markers emitted after all groups (e.g. ``JobEnd``).
        """
    @property
    def machine(self) -> MachineParams:
        r"""
        Machine parameters for time estimation.
        """
    @property
    def transformers(self) -> builtins.list[typing.Any]:
        r"""
        Batch transformers applied to the aggregated Ops.
        """
    def __new__(cls, wrap_start: typing.Sequence[Marker], groups: typing.Sequence[AggregateGroup], wrap_end: typing.Sequence[Marker], machine: MachineParams, transformers: typing.Sequence[typing.Any] = []) -> AggregateSpec: ...

@typing.final
class ComputePayload:
    r"""
    Opaque parameter bundle for a ``Compute`` stage node.
    
    The pipeline's ``StageSpec.Compute`` stores this as an opaque
    ``Any`` — the CNC converter unpacks it during traversal.
    
    :param assembler: The assembler spec that drives this compute.
    :param transformers: Optional list of transformer specs.
    :param state_source_keys: Keys of upstream nodes whose cleared-area
        state should be threaded into this compute (CNC only).
    """
    @property
    def assembler(self) -> typing.Any:
        r"""
        The assembler spec (e.g. ``ContourSpec``, ``AdaptiveClearingSpec``).
        """
    @property
    def transformers(self) -> builtins.list[typing.Any]:
        r"""
        Optional list of transformer specs applied post-assembly.
        """
    @property
    def state_source_keys(self) -> builtins.list[builtins.str]:
        r"""
        Source keys for cleared-area state threading (CNC only).
        """
    def __new__(cls, assembler: typing.Any, transformers: typing.Sequence[typing.Any] = [], state_source_keys: typing.Sequence[builtins.str] = []) -> ComputePayload: ...

@typing.final
class EncodeSpec:
    r"""
    An encode-only compute stage.
    
    The pipeline's generic ``StageSpec`` has no ``Encode`` variant —
    encoding is a CNC concern. Use ``EncodeSpec`` when you need to
    run an encoder through the pipeline.
    """
    @property
    def source_key(self) -> builtins.str:
        r"""
        Key of the upstream node whose Ops to encode.
        """
    @property
    def encoder(self) -> convert.Encoder:
        r"""
        The encoder to use (e.g. ``GcodeSpec``, ``VertexSpec``).
        """
    def __new__(cls, source_key: builtins.str, encoder: convert.Encoder) -> EncodeSpec: ...

@typing.final
class LinkMode:
    r"""
    Controls inter-input linking in an AggregateGroup.
    
    Create via class methods:
      LinkMode.none()
      LinkMode.sequential(safe_z=2.0)
    """
    @property
    def tag(self) -> builtins.str:
        r"""
        Discriminant: ``"none"`` or ``"sequential"``.
        """
    @property
    def safe_z(self) -> builtins.float:
        r"""
        Safe Z height for retract/lift moves (only meaningful when
        ``tag == "sequential"``).
        """
    @classmethod
    def none(cls) -> LinkMode:
        r"""
        Create a ``LinkMode`` with no inter-input linking.
        """
    @classmethod
    def sequential(cls, safe_z: builtins.float) -> LinkMode:
        r"""
        Create a ``LinkMode`` that emits travel moves (retract →
        XY travel → plunge) between consecutive inputs.
        
        :param safe_z: Z height for retract and final lift.
        """

@typing.final
class MachineParams:
    r"""
    Feed/speed rates used for time estimation.
    
    All three fields default to ``0.0``, which disables the time
    estimate (returning ``None``).
    """
    @property
    def default_feed_rate(self) -> builtins.float:
        r"""
        Default feed rate (mm/min) for cutting moves.
        """
    @property
    def default_rapid_rate(self) -> builtins.float:
        r"""
        Default rapid rate (mm/min) for travel moves.
        """
    @property
    def acceleration(self) -> builtins.float:
        r"""
        Acceleration (mm/s²) for time estimation.
        """
    def __new__(cls, default_feed_rate: builtins.float = 0.0, default_rapid_rate: builtins.float = 0.0, acceleration: builtins.float = 0.0) -> MachineParams: ...

class Marker:
    r"""
    Declarative markers for aggregate groups.
    
    Each variant has a ``_tag`` field (always ``True``) required by the
    stub generator; pass it as keyword argument:
    
      Marker.JobStart(_tag=True)
      Marker.LayerStart(uid="my-layer", _tag=True)
      Marker.WorkpieceEnd(uid="my-wp", _tag=True)
    """
    @typing.final
    class JobStart(Marker):
        r"""
        Marks the beginning of a job.
        """
        __match_args__ = ("_tag",)
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, _tag: builtins.bool) -> Marker.JobStart: ...
    
    @typing.final
    class JobEnd(Marker):
        r"""
        Marks the end of a job.
        """
        __match_args__ = ("_tag",)
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, _tag: builtins.bool) -> Marker.JobEnd: ...
    
    @typing.final
    class LayerStart(Marker):
        r"""
        Marks the start of a layer with the given UID.
        """
        __match_args__ = ("uid", "_tag",)
        @property
        def uid(self) -> builtins.str: ...
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, uid: builtins.str, _tag: builtins.bool) -> Marker.LayerStart: ...
    
    @typing.final
    class LayerEnd(Marker):
        r"""
        Marks the end of a layer with the given UID.
        """
        __match_args__ = ("uid", "_tag",)
        @property
        def uid(self) -> builtins.str: ...
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, uid: builtins.str, _tag: builtins.bool) -> Marker.LayerEnd: ...
    
    @typing.final
    class WorkpieceStart(Marker):
        r"""
        Marks the start of a workpiece with the given UID.
        """
        __match_args__ = ("uid", "_tag",)
        @property
        def uid(self) -> builtins.str: ...
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, uid: builtins.str, _tag: builtins.bool) -> Marker.WorkpieceStart: ...
    
    @typing.final
    class WorkpieceEnd(Marker):
        r"""
        Marks the end of a workpiece with the given UID.
        """
        __match_args__ = ("uid", "_tag",)
        @property
        def uid(self) -> builtins.str: ...
        @property
        def _tag(self) -> builtins.bool: ...
        def __new__(cls, uid: builtins.str, _tag: builtins.bool) -> Marker.WorkpieceEnd: ...
    
    ...

