# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Command sequence (Ops) manipulation for CNC motion control.

Ops is a container of ordered commands (move, line, arc, bezier, state
changes like power/feed) that defines a complete machining job. It supports building sequences programmatically (move_to,
line_to, arc_to, etc.), transforming them (translate, rotate, scale,
transform with 4x4 matrices), clipping to rectangles or regions,
linearizing curves, estimating processing time, and serializing to
dict or numpy arrays for persistence.

The module also provides command-type enumerations (CommandType,
CommandCategory, SectionType), machine State tracking (power, feed,
coolant, air_assist, head_coolant, frequency), and an Axis bitflag
for multi-axis machines.
"""

import builtins
import raygeo
from raygeo import geo
from raygeo.image import scan
import typing
from . import assembly
from . import axis
from . import convert
from . import cut
from . import feature
from . import part
from . import state
from . import transform
from . import types
__all__ = [
    "CommandInfo",
    "Ops",
    "OpsSection",
    "OpsSectionRange",
    "assembly",
    "axis",
    "convert",
    "cut",
    "feature",
    "part",
    "state",
    "transform",
    "types",
]

@typing.final
class CommandInfo:
    r"""
    Detailed information about a single command in an Ops sequence.
    
    Returned by :meth:`Ops.inspect` and provides the full set of
    parameters for any command type in a structured form.
    """
    @property
    def type_(self) -> types.CommandType:
        r"""
        The type of this command (e.g. Move, Line, Arc, Bezier, ScanTo, …).
        """
    @property
    def end(self) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Endpoint of the command in 3D space, if applicable.
        """
    @property
    def extra_axes(self) -> typing.Optional[dict]:
        r"""
        Extra axis positions, if any.
        """
    @property
    def state(self) -> typing.Optional[state.State]:
        r"""
        State snapshot at this command, if present.
        """
    @property
    def center_offset(self) -> typing.Optional[tuple[builtins.float, builtins.float]]:
        r"""
        Arc centre offset from start point, if an arc command.
        """
    @property
    def clockwise(self) -> typing.Optional[builtins.bool]:
        r"""
        Whether an arc is clockwise, if an arc command.
        """
    @property
    def control1(self) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        First cubic-Bezier control point, if a Bezier command.
        """
    @property
    def control2(self) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Second cubic-Bezier control point, if a Bezier command.
        """
    @property
    def control(self) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Quadratic-Bezier control point, if a quad. Bezier command.
        """
    @property
    def power_values(self) -> typing.Optional[bytes]:
        r"""
        Per-step power byte values for scan-to commands.
        """
    @property
    def power(self) -> typing.Optional[builtins.float]:
        r"""
        Power level (0–1), if a power-setting command.
        """
    @property
    def feed_rate(self) -> typing.Optional[builtins.int]:
        r"""
        Feed rate setting, if a SetFeedRate command.
        """
    @property
    def rapid_rate(self) -> typing.Optional[builtins.int]:
        r"""
        Rapid rate setting, if a SetRapidRate command.
        """
    @property
    def frequency(self) -> typing.Optional[builtins.int]:
        r"""
        Laser frequency (Hz), if a frequency-setting command.
        """
    @property
    def pulse_width(self) -> typing.Optional[builtins.float]:
        r"""
        Laser pulse width (µs), if a pulse-width-setting command.
        """
    @property
    def head_uid(self) -> typing.Optional[builtins.str]:
        r"""
        Unique identifier of the active head, if a head-setting command.
        """
    @property
    def spindle_rpm(self) -> typing.Optional[builtins.int]:
        r"""
        Spindle RPM, if a SetSpindleRpm command.
        """
    @property
    def coolant(self) -> typing.Optional[state.CoolantMode]:
        r"""
        Coolant mode, if a SetCoolant command.
        """
    @property
    def air_assist(self) -> typing.Optional[state.AirAssistMode]:
        r"""
        Air assist mode, if a SetAirAssist command.
        """
    @property
    def head_coolant(self) -> typing.Optional[state.HeadCoolantMode]:
        r"""
        Head coolant mode, if a SetHeadCoolant command.
        """
    @property
    def duration_ms(self) -> typing.Optional[builtins.float]:
        r"""
        Dwell duration in ms, if a dwell command.
        """
    @property
    def layer_uid(self) -> typing.Optional[builtins.str]:
        r"""
        Unique identifier of the active layer, if a layer-start command.
        """
    @property
    def workpiece_uid(self) -> typing.Optional[builtins.str]:
        r"""
        Unique identifier of the active workpiece, if a workpiece-start command.
        """
    @property
    def section_type(self) -> typing.Optional[types.SectionType]:
        r"""
        Section type, if a section marker.
        """
    def __eq__(self, other: typing.Any) -> builtins.bool: ...

@typing.final
class Ops:
    r"""
    A sequence of machining operations (commands).
    
    ``Ops`` is a container of ordered commands that define a complete
    machining job. It supports building command sequences
    programmatically, transforming them, clipping, serializing, and more.
    
    Use the builder methods (``move_to``, ``line_to``, ``arc_to``, etc.)
    to construct a sequence, or load from geometry/dict/numpy arrays.
    """
    @property
    def scanline_count(self) -> builtins.int:
        r"""
        Return the number of scanline commands in the sequence.
        
        :complexity: O(n) time, O(1) space
        """
    @property
    def last_move_to(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        The last ``(x, y, z)`` endpoint from a MoveTo command.
        
        :complexity: O(1) time, O(1) space
        """
    @last_move_to.setter
    def last_move_to(self, value: tuple[builtins.float, builtins.float, builtins.float]) -> None:
        r"""
        Set the last move-to position.
        
        :complexity: O(1) time, O(1) space
        """
    def transform(self, matrix: geo.types.TransformMatrix) -> None:
        r"""
        Apply a 4x4 affine transformation matrix to all geometry.
        
        See ``geo.types.TransformMatrix`` for the matrix layout.
        
        :param matrix: A 4x4 affine transformation matrix.
        :complexity: O(n) time, O(n) space
        """
    def __new__(cls) -> Ops:
        r"""
        Create a new, empty Ops sequence.
        
        :complexity: O(1) time, O(1) space
        """
    def __len__(self) -> builtins.int:
        r"""
        Return the number of commands.
        
        :complexity: O(1) time, O(1) space
        """
    def __add__(self, other: Ops) -> Ops:
        r"""
        Concatenate two Ops sequences (``ops1 + ops2``).
        
        :complexity: O(n) time, O(n) space
        """
    def __mul__(self, count: builtins.int) -> Ops:
        r"""
        Repeat the ops sequence *count* times (``ops * n``).
        
        :complexity: O(n * k) time, O(n * k) space where k is the repeat count
        """
    def is_empty(self) -> builtins.bool:
        r"""
        Check if the ops sequence is empty.
        
        :returns: ``True`` if the container is empty.
        :complexity: O(1) time, O(1) space
        """
    def len(self) -> builtins.int:
        r"""
        Return the number of commands.
        
        :returns: Number of commands in the container.
        :complexity: O(1) time, O(1) space
        """
    def command_type(self, idx: builtins.int) -> types.CommandType:
        r"""
        Get the :class:`CommandType` at the given index.
        
        :param idx: Command index (negative = from end).
        :returns: The :class:`CommandType` of the command.
        :complexity: O(1) time, O(1) space
        """
    def category(self, idx: builtins.int) -> types.CommandCategory:
        r"""
        Get the :class:`CommandCategory` at the given index.
        
        :param idx: Command index (negative = from end).
        :returns: The category (MOVING, STATE, or MARKER).
        :complexity: O(1) time, O(1) space
        """
    def count_cutting(self) -> builtins.int:
        r"""
        Return the number of cutting commands in this sequence.
        
        Counts all LineTo, ArcTo, BezierTo, QuadraticBezierTo, and
        ScanLine commands.
        
        :returns: Number of cutting commands.
        :complexity: O(n) time, O(1) space
        """
    def count_travel(self) -> builtins.int:
        r"""
        Return the number of travel (MoveTo) commands in this sequence.
        
        :returns: Number of travel commands.
        :complexity: O(n) time, O(1) space
        """
    def is_travel(self, idx: builtins.int) -> builtins.bool:
        r"""
        Check whether the command at *idx* is a travel (non-cutting) move.
        
        :param idx: Command index.
        :returns: True if the command is a travel move.
        :complexity: O(1) time, O(1) space
        """
    def is_cutting(self, idx: builtins.int) -> builtins.bool:
        r"""
        Check whether the command at *idx* is a cutting move.
        
        :param idx: Command index.
        :returns: True if the command is a cutting move.
        :complexity: O(1) time, O(1) space
        """
    def is_state(self, idx: builtins.int) -> builtins.bool:
        r"""
        Check whether the command at *idx* is a state command.
        
        :param idx: Command index.
        :returns: True if the command modifies machine state.
        :complexity: O(1) time, O(1) space
        """
    def is_marker(self, idx: builtins.int) -> builtins.bool:
        r"""
        Check whether the command at *idx* is a marker command.
        
        :param idx: Command index.
        :returns: True if the command is a structural marker (JobStart, LayerStart, etc.).
        :complexity: O(1) time, O(1) space
        """
    def is_scanline(self, idx: builtins.int) -> builtins.bool:
        r"""
        Check whether the command at *idx* is a scanline command.
        
        :param idx: Command index.
        :returns: True if the command is a ScanLine power command.
        :complexity: O(1) time, O(1) space
        """
    def indices_of(self, ct: types.CommandType) -> builtins.list[builtins.int]:
        r"""
        Return all indices where the command type matches *ct*.
        
        :param ct: The :class:`CommandType` to search for.
        :returns: List of matching command indices.
        :complexity: O(n) time, O(n) space
        """
    def distance_at(self, idx: builtins.int, last_point: typing.Optional[tuple[builtins.float, builtins.float, builtins.float]] = None) -> builtins.float:
        r"""
        Compute the distance traveled up to command *idx*.
        
        :param idx: Command index.
        :param last_point: Optional starting point override.
        :returns: Cumulative distance.
        :complexity: O(1) time, O(1) space
        """
    def distance(self) -> builtins.float:
        r"""
        Compute the total distance of all commands.
        
        :returns: Total path distance in mm.
        :complexity: O(n) time, O(1) space
        """
    def cut_distance(self) -> builtins.float:
        r"""
        Compute the total cutting distance (excluding travel moves).
        
        :returns: Total cut distance in mm.
        :complexity: O(n) time, O(1) space
        """
    def endpoint(self, idx: builtins.int) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Get the endpoint coordinates of a moving command.
        
        :param idx: Command index (negative = from end).
        :returns: ``(x, y, z)`` tuple.
        :complexity: O(1) time, O(1) space
        """
    def arc_params(self, idx: builtins.int) -> tuple[builtins.float, builtins.float, builtins.bool]:
        r"""
        Get the arc parameters (center offset i, j, and clockwise flag).
        
        :param idx: Command index.
        :returns: ``(i, j, clockwise)`` tuple.
        :raises TypeError: If the command is not an ArcTo.
        :complexity: O(1) time, O(1) space
        """
    def bezier_params(self, idx: builtins.int) -> tuple[tuple[builtins.float, builtins.float, builtins.float], tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Get the cubic bezier control points.
        
        :param idx: Command index.
        :returns: ``((c1x, c1y, c1z), (c2x, c2y, c2z))`` control points.
        :raises TypeError: If the command is not a BezierTo.
        :complexity: O(1) time, O(1) space
        """
    def quadratic_bezier_params(self, idx: builtins.int) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Get the quadratic bezier control point.
        
        :param idx: Command index.
        :returns: ``(cx, cy, cz)`` control point.
        :raises TypeError: If the command is not a QuadraticBezierTo.
        :complexity: O(1) time, O(1) space
        """
    def scanline_data(self, idx: builtins.int) -> bytes:
        r"""
        Get the raw scanline power data for a scanline command.
        
        :param idx: Command index.
        :returns: Raw bytes of scanline power data.
        :complexity: O(1) time, O(1) space
        """
    def dwell_duration(self, idx: builtins.int) -> builtins.float:
        r"""
        Get the duration (milliseconds) of a Dwell command.
        
        :param idx: Command index.
        :returns: Duration in milliseconds.
        :raises TypeError: If the command is not a Dwell.
        :complexity: O(1) time, O(1) space
        """
    def power(self, idx: builtins.int) -> builtins.float:
        r"""
        Get the power level of a SetPower command.
        
        :param idx: Command index.
        :returns: Power level (0.0–1.0 typically).
        :raises TypeError: If the command is not a SetPower.
        :complexity: O(1) time, O(1) space
        """
    def rate(self, idx: builtins.int) -> builtins.int:
        r"""
        Get the feed/rapid rate from a SetFeedRate or SetRapidRate command.
        
        :param idx: Command index.
        :returns: Rate in mm/s.
        :raises TypeError: If the command is not a rate command.
        :complexity: O(1) time, O(1) space
        """
    def frequency(self, idx: builtins.int) -> builtins.int:
        r"""
        Get the frequency of a SetFrequency command.
        
        :param idx: Command index.
        :returns: Frequency in Hz.
        :raises TypeError: If the command is not a SetFrequency.
        :complexity: O(1) time, O(1) space
        """
    def pulse_width(self, idx: builtins.int) -> builtins.float:
        r"""
        Get the pulse width of a SetPulseWidth command.
        
        :param idx: Command index.
        :returns: Pulse width in microseconds.
        :raises TypeError: If the command is not a SetPulseWidth.
        :complexity: O(1) time, O(1) space
        """
    def spindle_rpm(self, idx: builtins.int) -> builtins.int:
        r"""
        Get the spindle RPM from a SetSpindleRpm command.
        
        :param idx: Command index.
        :returns: Spindle RPM.
        :raises TypeError: If the command is not a SetSpindleRpm.
        :complexity: O(1) time, O(1) space
        """
    def coolant(self, idx: builtins.int) -> state.CoolantMode:
        r"""
        Get the coolant mode from a SetCoolant command.
        
        :param idx: Command index.
        :returns: The coolant mode.
        :raises TypeError: If the command is not a SetCoolant.
        :complexity: O(1) time, O(1) space
        """
    def air_assist(self, idx: builtins.int) -> state.AirAssistMode:
        r"""
        Get the air assist mode from a SetAirAssist command.
        
        :param idx: Command index.
        :returns: The air assist mode.
        :raises TypeError: If the command is not a SetAirAssist.
        :complexity: O(1) time, O(1) space
        """
    def head_coolant(self, idx: builtins.int) -> state.HeadCoolantMode:
        r"""
        Get the head coolant mode from a SetHeadCoolant command.
        
        :param idx: Command index.
        :returns: The head coolant mode.
        :raises TypeError: If the command is not a SetHeadCoolant.
        :complexity: O(1) time, O(1) space
        """
    def head_uid(self, idx: builtins.int) -> builtins.str:
        r"""
        Get the head UID from a SetHead command.
        
        :param idx: Command index.
        :returns: The head identifier.
        :raises TypeError: If the command is not a SetHead.
        :complexity: O(1) time, O(1) space
        """
    def layer_uid(self, idx: builtins.int) -> builtins.str:
        r"""
        Get the layer UID from a LayerStart or LayerEnd command.
        
        :param idx: Command index.
        :returns: The layer identifier.
        :raises TypeError: If the command is not a Layer command.
        :complexity: O(1) time, O(1) space
        """
    def workpiece_uid(self, idx: builtins.int) -> builtins.str:
        r"""
        Get the workpiece UID from a WorkpieceStart or WorkpieceEnd command.
        
        :param idx: Command index.
        :returns: The workpiece identifier.
        :raises TypeError: If the command is not a Workpiece command.
        :complexity: O(1) time, O(1) space
        """
    def section_params(self, idx: builtins.int) -> tuple[types.SectionType, typing.Optional[builtins.str], typing.Optional[types.RasterMode]]:
        r"""
        Get the section type, optional workpiece UID, and optional raster mode from an OpsSection command.
        
        :param idx: Command index.
        :returns: ``(SectionType, Optional[str], Optional[RasterMode])``.
        :raises TypeError: If the command is not an OpsSectionStart or OpsSectionEnd.
        :complexity: O(1) time, O(1) space
        """
    def extra_axes(self, idx: builtins.int) -> typing.Optional[dict]:
        r"""
        Get the extra axes data for a moving command.
        
        :param idx: Command index.
        :returns: Dict mapping axis names to values, or None.
        :complexity: O(1) time, O(1) space
        """
    def state(self, idx: builtins.int) -> typing.Optional[state.State]:
        r"""
        Get the machine state stored on a command (if available).
        
        :param idx: Command index.
        :returns: The :class:`State` at that index, or None.
        :complexity: O(1) time, O(1) space
        """
    def move_to(self, x: builtins.float, y: builtins.float, z: builtins.float = 0.0, extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a rapid (non-cutting) move to the given coordinates.
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :param z: Z coordinate (default 0.0).
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def line_to(self, x: builtins.float, y: builtins.float, z: builtins.float = 0.0, extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a cutting line to the given coordinates.
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :param z: Z coordinate (default 0.0).
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def close_path(self) -> None:
        r"""
        Close the current sub-path by adding a line back to the start.
        
        :complexity: O(1) time, O(1) space
        """
    def arc_to(self, x: builtins.float, y: builtins.float, i: builtins.float, j: builtins.float, clockwise: builtins.bool = True, z: builtins.float = 0.0, extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a circular arc to the given coordinates.
        
        :param x: End X coordinate.
        :param y: End Y coordinate.
        :param i: I offset from current point to arc center.
        :param j: J offset from current point to arc center.
        :param clockwise: Whether the arc is clockwise (default True).
        :param z: End Z coordinate (default 0.0).
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def bezier_to(self, control1: tuple[builtins.float, builtins.float, builtins.float], control2: tuple[builtins.float, builtins.float, builtins.float], end: tuple[builtins.float, builtins.float, builtins.float], extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a cubic bezier curve to the given endpoint.
        
        :param control1: First control point ``(x, y, z)``.
        :param control2: Second control point ``(x, y, z)``.
        :param end: End point ``(x, y, z)``.
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def quadratic_bezier_to(self, control: tuple[builtins.float, builtins.float, builtins.float], end: tuple[builtins.float, builtins.float, builtins.float], extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a quadratic bezier curve to the given endpoint.
        
        :param control: Control point ``(x, y, z)``.
        :param end: End point ``(x, y, z)``.
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def set_power(self, power: builtins.float) -> None:
        r"""
        Set the cutting power for subsequent commands.
        
        :param power: Power level (0.0–1.0).
        :complexity: O(1) time, O(1) space
        """
    def set_feed_rate(self, feed_rate: builtins.float) -> None:
        r"""
        Set the feed rate for subsequent commands.
        
        :param feed_rate: Feed rate in units per second.
        :complexity: O(1) time, O(1) space
        """
    def set_rapid_rate(self, rapid_rate: builtins.float) -> None:
        r"""
        Set the rapid (traverse) rate for subsequent commands.
        
        :param rapid_rate: Rapid rate in units per second.
        :complexity: O(1) time, O(1) space
        """
    def dwell(self, duration_ms: builtins.float) -> None:
        r"""
        Pause execution for a given duration.
        
        :param duration_ms: Dwell duration in milliseconds.
        :complexity: O(1) time, O(1) space
        """
    def set_head(self, head_uid: builtins.str) -> None:
        r"""
        Switch to a specific head by UID.
        
        :param head_uid: The head identifier.
        :complexity: O(1) time, O(1) space
        """
    def set_frequency(self, frequency: builtins.int) -> None:
        r"""
        Set the laser pulse frequency.
        
        :param frequency: Frequency in Hz.
        :complexity: O(1) time, O(1) space
        """
    def set_pulse_width(self, pulse_width: builtins.float) -> None:
        r"""
        Set the laser pulse width.
        
        :param pulse_width: Pulse width in microseconds.
        :complexity: O(1) time, O(1) space
        """
    def set_spindle_rpm(self, rpm: builtins.int) -> None:
        r"""
        Set the spindle RPM for subsequent commands.
        
        :param rpm: Spindle RPM.
        :complexity: O(1) time, O(1) space
        """
    def set_coolant(self, mode: state.CoolantMode) -> None:
        r"""
        Set the coolant mode for subsequent commands.
        
        :param mode: Coolant mode.
        :complexity: O(1) time, O(1) space
        """
    def set_air_assist(self, mode: state.AirAssistMode) -> None:
        r"""
        Set the air assist mode for subsequent commands.
        
        :param mode: Air assist mode.
        :complexity: O(1) time, O(1) space
        """
    def set_head_coolant(self, mode: state.HeadCoolantMode) -> None:
        r"""
        Set the head coolant mode for subsequent commands.
        
        :param mode: Head coolant mode.
        :complexity: O(1) time, O(1) space
        """
    def apply_state(self, state: state.State) -> None:
        r"""
        Emit the state commands needed to reach *state*.
        
        Power is always emitted (default 0.0). All other fields are
        emitted only when set (non-None). Domain-neutral: does not
        decide what values to use, just emits them.
        
        :param state: The target state to apply.
        :complexity: O(k) time where k = number of set fields, O(k) space
        """
    def scan_to(self, x: builtins.float, y: builtins.float, z: builtins.float = 0.0, power_values: typing.Optional[typing.Sequence[builtins.int]] = None, extra: typing.Optional[dict] = None) -> None:
        r"""
        Add a scan-line move with per-pixel power values.
        
        :param x: End X coordinate.
        :param y: End Y coordinate.
        :param z: End Z coordinate (default 0.0).
        :param power_values: Optional per-pixel 8-bit power values.
        :param extra: Optional dict of extra axis values.
        :complexity: O(1) time, O(1) space
        """
    def job_start(self) -> None:
        r"""
        Mark the start of a job.
        
        :complexity: O(1) time, O(1) space
        """
    def job_end(self) -> None:
        r"""
        Mark the end of a job.
        
        :complexity: O(1) time, O(1) space
        """
    def layer_start(self, layer_uid: builtins.str) -> None:
        r"""
        Mark the start of a layer.
        
        :param layer_uid: The layer identifier.
        :complexity: O(1) time, O(1) space
        """
    def layer_end(self, layer_uid: builtins.str) -> None:
        r"""
        Mark the end of a layer.
        
        :param layer_uid: The layer identifier.
        :complexity: O(1) time, O(1) space
        """
    def workpiece_start(self, workpiece_uid: builtins.str) -> None:
        r"""
        Mark the start of a workpiece.
        
        :param workpiece_uid: The workpiece identifier.
        :complexity: O(1) time, O(1) space
        """
    def workpiece_end(self, workpiece_uid: builtins.str) -> None:
        r"""
        Mark the end of a workpiece.
        
        :param workpiece_uid: The workpiece identifier.
        :complexity: O(1) time, O(1) space
        """
    def ops_section_start(self, section_type: types.SectionType, workpiece_uid: builtins.str, *, raster_mode: typing.Optional[types.RasterMode] = None) -> None:
        r"""
        Mark the start of an ops section.
        
        :param section_type: The type of section.
        :param workpiece_uid: The workpiece identifier.
        :param raster_mode: Optional raster mode.
        :raises ValueError: If section_type is RasterFill without a raster_mode,
            or VectorOutline with a raster_mode.
        :complexity: O(1) time, O(1) space
        """
    def ops_section_end(self, section_type: types.SectionType, *, raster_mode: typing.Optional[types.RasterMode] = None) -> None:
        r"""
        Mark the end of an ops section.
        
        :param section_type: The type of section.
        :param raster_mode: Optional raster mode.
        :raises ValueError: If section_type is RasterFill without a raster_mode,
            or VectorOutline with a raster_mode.
        :complexity: O(1) time, O(1) space
        """
    def state_block_start(self, name: typing.Optional[builtins.str]) -> None:
        r"""
        Mark the start of a state block.
        
        :param name: Optional block name.
        :complexity: O(1) time, O(1) space
        """
    def state_block_end(self) -> None:
        r"""
        Mark the end of a state block.
        
        :complexity: O(1) time, O(1) space
        """
    def copy(self) -> Ops:
        r"""
        Return a deep copy of this Ops sequence.
        
        :returns: A new ``Ops`` instance.
        :complexity: O(n) time, O(n) space
        """
    def __copy__(self) -> Ops:
        r"""
        Shallow copy (same as :meth:`copy` since Ops is immutable).
        
        :complexity: O(n) time, O(n) space
        """
    def __deepcopy__(self, _memo: typing.Any) -> Ops:
        r"""
        Deep copy (same as :meth:`copy` since Ops is immutable).
        
        :complexity: O(n) time, O(n) space
        """
    def copy_command_from(self, source: Ops, idx: builtins.int) -> None:
        r"""
        Copy a single command from another Ops sequence into this one.
        
        :param source: The source Ops sequence.
        :param idx: Index of the command to copy.
        :complexity: O(1) time, O(1) space
        """
    def transfer_command_from(self, source: Ops, idx: builtins.int) -> None:
        r"""
        Transfer (move) a single command from another Ops sequence into this one.
        
        :param source: The source Ops sequence.
        :param idx: Index of the command to transfer.
        :complexity: O(1) time, O(1) space
        """
    def extend(self, other: typing.Optional[Ops]) -> None:
        r"""
        Extend this Ops sequence with commands from another.
        
        :param other: The other Ops sequence (or None for no-op).
        :complexity: O(n) time, O(n) space
        """
    def clear(self) -> None:
        r"""
        Remove all commands from this Ops sequence.
        
        :complexity: O(1) time, O(1) space
        """
    def subpath_indices(self) -> builtins.list[builtins.list[builtins.int]]:
        r"""
        Return index ranges for each subpath.
        
        :returns: A list of index lists, one per subpath.
        :complexity: O(n) time, O(n) space
        """
    def split_into_subpaths(self) -> builtins.list[Ops]:
        r"""
        Split this Ops sequence into separate subpaths.
        
        :returns: A list of Ops sequences, one per subpath.
        :complexity: O(n) time, O(n) space
        """
    def split_at(self, command_type: typing.Any) -> builtins.list[Ops]:
        r"""
        Split the sequence at paired markers of the given type.
        
        Returns a list of ``Ops`` sequences. Each matched start/end marker pair
        yields one ``Ops`` containing the markers and their content. Commands
        that fall outside any pair are returned as additional ``Ops`` segments,
        so concatenating all returned sequences reproduces the original.
        
        :param command_type: ``CommandType.LAYER_START``,
            ``WORKPIECE_START``, ``OPS_SECTION_START``, or ``JOB_START``.
        :returns: A list of ``Ops`` sequences.
        :raises ValueError: If ``command_type`` is not a supported start marker.
        :complexity: O(n) time, O(n) space
        """
    def flip_ops(self) -> Ops:
        r"""
        Reverse the order of subpaths.
        
        :returns: A new Ops with subpath order reversed.
        :complexity: O(n) time, O(n) space
        """
    def without_state(self) -> Ops:
        r"""
        Return a copy with all state commands removed.
        
        :returns: A new Ops containing only moving commands.
        :complexity: O(n) time, O(n) space
        """
    def state_at(self, idx: builtins.int) -> state.State:
        r"""
        Return the accumulated state at a given command index.
        
        :param idx: The command index.
        :returns: The state at that point.
        :raises IndexError: If the index is out of range.
        :complexity: O(1) time, O(1) space
        """
    def sub_ops(self, indices: typing.Sequence[builtins.int]) -> Ops:
        r"""
        Extract a subset of commands by index.
        
        :param indices: List of command indices to extract.
        :returns: A new Ops sequence containing only the specified commands.
        :complexity: O(n) time, O(n) space
        """
    def replace_all(self, source: Ops) -> None:
        r"""
        Replace all commands in this sequence with those from another.
        
        :param source: The source Ops sequence.
        :complexity: O(n) time, O(n) space
        """
    def replace_with(self, source: Ops) -> None:
        r"""
        Replace the internal buffer of this sequence with a copy from another.
        
        :param source: The source Ops sequence.
        :complexity: O(n) time, O(n) space
        """
    @classmethod
    def from_geometry(cls, geometry: geo.Geometry) -> Ops:
        r"""
        Create an Ops sequence from a Geometry.
        
        :param geometry: The geometry to convert.
        :returns: A new ``Ops`` instance.
        :complexity: O(n) time, O(n) space
        """
    @staticmethod
    def from_polyline(points: typing.Sequence[tuple[builtins.float, builtins.float, builtins.float]], move_first: builtins.bool = True, state: typing.Optional[state.State] = None) -> Ops:
        r"""
        Build an Ops sequence from a 3-D polyline.
        
        When *move_first* is ``True`` the first point is emitted as a
        MoveTo and subsequent points as LineTo.  When *move_first* is
        ``False`` every point is emitted as a LineTo (useful for
        appending a polyline to an in-progress cut).
        
        When *state* is provided, its commands (power, feed rate, etc.)
        are applied before the polyline points.
        
        :param points: List of ``(x, y, z)`` tuples.
        :param move_first: Whether to emit the first point as a MoveTo.
        :param state: Optional machine state to apply before the path.
        :returns: A new ``Ops`` instance.
        :complexity: O(n) where n = number of points
        """
    def to_geometry(self) -> geo.Geometry:
        r"""
        Convert this Ops sequence back into a Geometry.
        
        :returns: A Geometry representing the same paths.
        :complexity: O(n) time, O(n) space
        """
    def preload_state(self) -> None:
        r"""
        Pre-compute and store the accumulated state at each moving command.
        
        :complexity: O(n) time, O(n) space
        """
    def set_state_on_moving(self, state: state.State) -> None:
        r"""
        Apply a state to all moving commands without an explicit state.
        
        :param state: The state to apply.
        :complexity: O(n) time, O(1) space
        """
    def set_state_at(self, idx: builtins.int, state: state.State) -> None:
        r"""
        Overwrite the state at a specific command index.
        
        :param idx: The command index.
        :param state: The new state.
        :complexity: O(1) time, O(1) space
        """
    def dump(self) -> None:
        r"""
        Print a human-readable dump of all commands.
        
        :complexity: O(n) time, O(n) space
        """
    def inspect(self, idx: builtins.int) -> CommandInfo:
        r"""
        Return detailed information about a single command.
        
        :param idx: The command index.
        :returns: A CommandInfo object with type, endpoint, state, axes, etc.
        :complexity: O(1) time, O(1) space
        """
    def translate(self, dx: builtins.float, dy: builtins.float, dz: builtins.float = 0.0) -> None:
        r"""
        Translate all moving commands by the given offset.
        
        :param dx: X offset.
        :param dy: Y offset.
        :param dz: Z offset (default 0.0).
        :complexity: O(n) time, O(1) space
        """
    def scale(self, sx: builtins.float, sy: builtins.float, sz: builtins.float = 1.0) -> None:
        r"""
        Scale all coordinates by the given factors.
        
        :param sx: X scale factor.
        :param sy: Y scale factor.
        :param sz: Z scale factor (default 1.0).
        :complexity: O(n) time, O(1) space
        """
    def rotate(self, angle_deg: builtins.float, cx: builtins.float, cy: builtins.float) -> None:
        r"""
        Rotate all coordinates around a pivot point.
        
        :param angle_deg: Rotation angle in degrees.
        :param cx: Pivot X coordinate.
        :param cy: Pivot Y coordinate.
        :complexity: O(n) time, O(1) space
        """
    def clip_rect(self, rect: tuple[builtins.float, builtins.float, builtins.float, builtins.float]) -> Ops:
        r"""
        Clip this sequence to a rectangle, keeping only commands inside.
        
        :param rect: ``(x_min, y_min, x_max, y_max)``.
        :returns: A new Ops sequence containing the clipped commands.
        :complexity: O(n) time, O(n) space
        """
    def subtract_regions(self, regions: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]]) -> None:
        r"""
        Subtract polygonal regions from the cutting paths.
        
        :param regions: List of polygons, each being a list of ``(x, y)`` vertices.
        :complexity: O(n * m) time, O(n) space where m is the number of polygon vertices
        """
    def clip_to_regions(self, regions: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]], tolerance: builtins.float = 0.3) -> None:
        r"""
        Clip paths to the given polygonal regions, keeping only what is inside.
        
        :param regions: List of polygons, each being a list of ``(x, y)`` vertices.
        :param tolerance: Approximation tolerance (default 0.3).
        :complexity: O(n * m) time, O(n) space where m is the number of polygon vertices
        """
    def clip_ops_to_regions(self, regions: typing.Sequence[typing.Sequence[tuple[builtins.float, builtins.float]]], tolerance: builtins.float = 0.3) -> None:
        r"""
        Clip paths using polygonal regions as boundaries; keeps what is inside.
        
        :param regions: List of polygons, each being a list of ``(x, y)`` vertices.
        :param tolerance: Approximation tolerance (default 0.3).
        :complexity: O(n * m) time, O(n) space where m is the number of polygon vertices
        """
    def clip_at(self, x: builtins.float, y: builtins.float, width: builtins.float) -> builtins.bool:
        r"""
        Clip at a single vertical swath, keeping commands that intersect the band.
        
        :param x: X coordinate of the left edge.
        :param y: Y coordinate (used to find the relevant segment).
        :param width: Width of the band.
        :returns: True if any commands were kept.
        :complexity: O(n) time, O(1) space
        """
    def translate_layers(self, default_offset: tuple[builtins.float, builtins.float, builtins.float], layer_offsets: typing.Optional[dict] = None) -> None:
        r"""
        Translate each layer by its own offset, with a default fallback.
        
        :param default_offset: The ``(x, y, z)`` offset for layers not listed in layer_offsets.
        :param layer_offsets: Optional dict mapping layer UIDs to ``(x, y, z)`` offsets.
        :complexity: O(n) time, O(1) space
        """
    def transform_layers(self, callback: typing.Any) -> None:
        r"""
        Transform each layer by calling a Python callback with the layer UID and ops.
        
        The callback receives ``(layer_uid: str, layer_ops: Ops)`` and should
        mutate the layer_ops in place.
        
        :param callback: A callable accepting ``(layer_uid, layer_ops)``.
        :complexity: O(n) time, O(n) space
        """
    def transform_moving(self, on_endpoint: typing.Any, on_aux_point: typing.Optional[typing.Any] = None) -> None:
        r"""
        Transform moving commands by calling Python callbacks on each endpoint and aux point.
        
        The ``on_endpoint`` callback receives ``(endpoint, extra_axes)`` and
        should mutate the endpoint list in-place. The optional ``on_aux_point``
        callback receives control points for curve commands.
        
        :param on_endpoint: Callable ``(endpoint, extra_axes) -> None``.
        :param on_aux_point: Optional callable ``(point,) -> None`` for curve control points.
        :complexity: O(n) time, O(1) space
        """
    def linearize(self, idx: builtins.int, start_point: tuple[builtins.float, builtins.float, builtins.float]) -> Ops:
        r"""
        Decompose a curved command into linear segments.
        
        :param idx: Index of the command to linearize.
        :param start_point: The ``(x, y, z)`` start point of the curve.
        :returns: A new Ops containing the linearized sub-commands.
        :raises TypeError: If the command at idx is not a curve or line type.
        :complexity: O(n) time, O(n) space
        """
    def linearize_all(self) -> None:
        r"""
        Replace all curved commands with linear approximations in-place.
        
        :complexity: O(n) time, O(n) space
        """
    def linearize_curves(self) -> None:
        r"""
        Replace only bezier and quadratic bezier curves with linear approximations.
        
        :complexity: O(n) time, O(n) space
        """
    def linearize_arcs(self) -> None:
        r"""
        Replace only arc commands with linear approximations.
        
        :complexity: O(n) time, O(n) space
        """
    def segment_indices(self) -> builtins.list[builtins.list[builtins.int]]:
        r"""
        Return index ranges for each contiguous cutting segment.
        
        :returns: A list of index lists, one per segment.
        :complexity: O(n) time, O(n) space
        """
    def group_by_auxiliary_state(self) -> builtins.list[Ops]:
        r"""
        Group contiguous commands with the same auxiliary state into separate Ops sequences.
        
        Groups by continuity of auxiliary state (coolant, air_assist,
        head_coolant) only. For full parameter-regime grouping, use
        :meth:`OpsSection.state_blocks` with ``StateBlockStart``/``StateBlockEnd`` markers.
        
        :returns: A list of Ops sequences grouped by auxiliary state continuity.
        :complexity: O(n) time, O(n) space
        """
    def sections(self) -> builtins.list[OpsSection]:
        r"""
        Return the logical sections of the ops.
        
        Sections are delimited by ``OpsSectionStart``/``OpsSectionEnd``
        markers and group commands into vector-outline and raster-fill
        portions.
        
        :returns: List of OpsSection objects.
        :complexity: O(n) time, O(n) space
        """
    def section_ranges(self) -> builtins.list[OpsSectionRange]:
        r"""
        Return the section ranges of the ops as index ranges.
        
        Similar to :meth:`sections` but returns contiguous
        index ranges instead of individual index lists.
        
        :returns: List of OpsSectionRange objects.
        :complexity: O(n) time, O(n) space
        """
    def section_content(self, section: OpsSection) -> Ops:
        r"""
        Extract the commands belonging to a section.
        
        :param section: The OpsSection to extract.
        :returns: A new Ops containing only the content of that section.
        :complexity: O(n) time, O(n) space
        """
    def sections_by_type(self, section_type: types.SectionType) -> builtins.list[OpsSection]:
        r"""
        Return sections matching a given section type.
        
        :param section_type: The SectionType to filter by.
        :returns: List of matching OpsSection objects.
        :complexity: O(n) time, O(n) space
        """
    def sections_by_mode(self, raster_mode: types.RasterMode) -> builtins.list[OpsSection]:
        r"""
        Return sections matching a given raster mode.
        
        :param raster_mode: The RasterMode to filter by.
        :returns: List of matching OpsSection objects.
        :complexity: O(n) time, O(n) space
        """
    def state_blocks(self) -> builtins.list[types.StateBlock]:
        r"""
        Return all state blocks across all sections.
        
        :returns: List of StateBlock objects.
        :raises RuntimeError: If state block nesting is invalid.
        :complexity: O(n) time, O(n) space
        """
    def rect(self, include_travel: builtins.bool = False) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float]:
        r"""
        Compute the bounding rectangle of all commands.
        
        :param include_travel: Whether to include travel moves (default False).
        :returns: ``(x_min, y_min, x_max, y_max)``.
        :complexity: O(n) time, O(1) space
        """
    def get_frame(self, power: typing.Optional[builtins.float] = None, feed_rate: typing.Optional[builtins.float] = None) -> Ops:
        r"""
        Extract a frame (first and last endpoints) from the sequence.
        
        :param power: Laser power value (0.0 to 1.0).
        :param feed_rate: Optional feed rate to set on the frame commands.
        :returns: A new Ops containing only the frame endpoints.
        :complexity: O(n) time, O(n) space
        """
    def estimate_time(self, default_feed_rate: builtins.float = 1000.0, default_rapid_rate: builtins.float = 3000.0, acceleration: builtins.float = 1000.0) -> builtins.float:
        r"""
        Estimate the total processing time for this sequence.
        
        :param default_feed_rate: Default feed rate (default 1000.0).
        :param default_rapid_rate: Default rapid rate (default 3000.0).
        :param acceleration: Acceleration value (default 1000.0).
        :returns: Estimated time in seconds.
        :complexity: O(n) time, O(1) space
        """
    def estimate_command_times(self, default_feed_rate: builtins.float = 1000.0, default_rapid_rate: builtins.float = 3000.0, acceleration: builtins.float = 1000.0) -> builtins.list[builtins.float]:
        r"""
        Estimate the time of each individual command in the sequence.
        
        Returns a list with one entry per command. Moving commands
        (MoveTo, LineTo, ArcTo, etc.) yield their estimated execution
        time in seconds. Non-moving commands (state changes, markers)
        yield 0.0.
        
        :param default_feed_rate: Default feed rate (default 1000.0).
        :param default_rapid_rate: Default rapid rate (default 3000.0).
        :param acceleration: Acceleration value (default 1000.0).
        :returns: List of estimated times in seconds, one per command.
        :complexity: O(n) time, O(n) space
        """
    def to_dict(self) -> dict:
        r"""
        Serialize this Ops sequence to a dict suitable for JSON export.
        
        :returns: A Python dict representation.
        :complexity: O(n) time, O(n) space
        """
    @classmethod
    def from_dict(cls, data: dict) -> Ops:
        r"""
        Create an Ops sequence from a dictionary.
        
        :param data: Dictionary as produced by to_dict.
        :returns: A new ``Ops`` instance.
        :complexity: O(n) time, O(n) space
        """
    def to_numpy_arrays(self) -> dict:
        r"""
        Serialize this Ops sequence to numpy arrays.
        
        :returns: A Python dict of numpy arrays.
        :complexity: O(n) time, O(n) space
        """
    @classmethod
    def from_numpy_arrays(cls, arrays: dict) -> Ops:
        r"""
        Create an Ops sequence from numpy arrays.
        
        :param arrays: Dictionary as produced by to_numpy_arrays.
        :returns: A new ``Ops`` instance.
        :complexity: O(n) time, O(n) space
        """
    def apply_tab_gaps(self, clips: typing.Sequence[tuple[builtins.float, builtins.float, builtins.float]]) -> None:
        r"""
        Apply holding tabs as gaps in the toolpath.
        
        For each clip point, the closest subpath is found and a gap of
        the specified width is cut at the nearest point on the path.
        Only ``VECTOR_OUTLINE`` sections are modified.
        
        :param clips: List of ``(x, y, width)`` tuples defining tab positions.
        :complexity: O(n * k) time, O(1) space where k is the number of tab clips
        """
    def apply_tab_power(self, clips: typing.Sequence[tuple[builtins.float, builtins.float, builtins.float]], tab_power: builtins.float, original_power: builtins.float) -> None:
        r"""
        Apply holding tabs by reducing power in tab regions.
        
        Instead of cutting a gap, the power is lowered in the tab
        area so the material stays connected but weaker. Only
        ``VECTOR_OUTLINE`` sections are modified.
        
        :param clips: List of ``(x, y, width)`` tuples defining tab positions.
        :param tab_power: Power level inside tab regions (0.0–1.0).
        :param original_power: Normal cutting power to restore after the tab.
        :complexity: O(n * k) time, O(1) space where k is the number of tab clips
        """
    def merge_overlapping_lines(self, tolerance: builtins.float) -> None:
        r"""
        Merge overlapping line segments across all paths.
        
        Detects line segments that are collinear and overlapping and
        replaces the covered sub-segments with travel moves to avoid
        cutting the same line twice.
        
        :param tolerance: Maximum distance for considering lines collinear.
        :complexity: O(n log n) average time, O(n) space
        """
    def smooth(self, amount: builtins.int, corner_angle_threshold: builtins.float) -> None:
        r"""
        Smooth all line-only segments using a Gaussian filter.
        
        Arcs are linearized first.  Segments containing curves are
        transferred unchanged.  The smoothing operates in place.
        
        :param amount: Smoothing strength (0-100).  0 is a no-op.
        :param corner_angle_threshold: Corners with an internal angle
            (in degrees) smaller than this are preserved.
        :complexity: O(n * k) time, O(n) space where k is the kernel size
        """
    def apply_overscan(self, distance_mm: builtins.float) -> None:
        r"""
        Apply overscan to raster lines.
        
        Extends raster line start/end points by ``distance_mm`` along
        the line direction, adding zero-power lead-in and lead-out
        segments for constant engraving velocity.
        
        :param distance_mm: Overscan distance in millimeters.
        :complexity: O(n) time, O(n) space
        """
    def apply_bidir_scan_offset(self, offset_mm: builtins.float) -> None:
        r"""
        Correct X misalignment between left-to-right and right-to-left
        raster passes.
        
        For every raster pass (a ``MoveTo`` followed by a ``ScanLine``),
        if the pass runs right-to-left, both the entry ``MoveTo`` and
        the ``ScanLine`` endpoint are shifted along X by ``offset_mm``.
        Left-to-right passes are left untouched.
        
        :param offset_mm: Offset in millimeters to apply to RTL passes.
        :complexity: O(n) time, O(n) space
        """
    def apply_multipass(self, passes: builtins.int, z_step_down: builtins.float) -> None:
        r"""
        Repeats the ops sequence multiple times, optionally stepping
        down the Z axis after each pass.
        
        :param passes: Total number of passes (must be >= 1).
        :param z_step_down: Z distance to move down after each pass.
        :complexity: O(n * passes) time, O(n * passes) space
        """
    def apply_lead_in_out(self, lead_in_mm: builtins.float, lead_out_mm: builtins.float) -> None:
        r"""
        Apply lead-in and lead-out to vector contour paths.
        
        For each contour within a VECTOR_OUTLINE section, extends the
        toolpath with zero-power lead-in and lead-out segments along
        the tangent direction at the path start and end.
        
        :param lead_in_mm: Lead-in distance in millimeters.
        :param lead_out_mm: Lead-out distance in millimeters.
        :complexity: O(n) time, O(n) space
        """
    def optimize_travel(self, allow_flip: builtins.bool = True, preserve_first: builtins.bool = False, preserve_order: typing.Sequence[builtins.str] = [], progress_cb: typing.Optional[typing.Any] = None) -> None:
        r"""
        Optimize travel distance by reordering segments.
        
        Performs two-level optimization: workpiece-level reordering
        (when workpiece markers are present) and segment-level
        nearest-neighbor + 2-opt refinement.
        
        :param allow_flip: Whether to allow flipping subpaths.
        :param preserve_first: Keep the first workpiece in place.
        :param preserve_order: Workpiece UIDs whose order to preserve.
        :param progress_cb: Optional callable(progress, message).
        :complexity: O(n²) average time, O(n) space
        """
    def apply_transformers(self, transformers: typing.Sequence[typing.Any], progress_cb: typing.Optional[typing.Any] = None) -> None:
        r"""
        Apply a batch of transformers in a single call.
        
        The *transformers* list may contain any of the typed spec
        objects defined in :mod:`raygeo.ops.transform` (``SmoothSpec``,
        ``OptimizeSpec``, ``MergeLinesSpec``, ``OverscanSpec``,
        ``LeadInOutSpec``, ``MultiPassSpec``, ``CropSpec``,
        ``TabsSpec``, ``BidirScanOffsetSpec``). The transformers are
        sorted by execution phase (geometry refinement -> path
        interruption -> post-processing) and applied in order.
        
        :param transformers: List of typed spec objects.
        :param progress_cb: Optional callable ``(progress, message)``
            that also exposes an ``is_cancelled()`` method; called
            before each transformer. If ``is_cancelled()`` returns
            ``True`` the loop aborts before the next transformer.
        :raises TypeError: If any element is not a known spec type.
        :raises RuntimeError: If the loop was cancelled.
        """
    def to_vertex_arrays(self) -> typing.Any:
        r"""
        Encode all commands into GPU-friendly vertex arrays.
        
        Returns four flat numpy arrays:
        ``(powered_vertices, powered_colors, travel_vertices,
        zero_power_vertices)``.
        
        Powered vertices and colors are paired (2 vertices + 2 colors
        per segment).  Travel and zero-power vertices are also paired
        (2 vertices per segment).  All vertex data is 3-component
        (x, y, z); colors are 4-component (r, g, b, a).
        
        :returns: Tuple of ``(powered_vertices[N,3], powered_colors[N,4],
            travel_vertices[M,3], zero_power_vertices[K,3])`` as float32
            arrays.
        :complexity: O(n) time, O(n) space
        """
    def to_gcode(self, dialect: convert.GcodeDialectSpec, context_dict: dict) -> dict:
        r"""
        Encode this Ops sequence into G-code text.
        
        Takes a typed dialect specification and an encoding context as a
        plain dict (JSON-serialisable). Returns a dict with the G-code
        text and bidirectional op-to-line index maps.
        
        :param dialect: A :class:`raygeo.ops.convert.GcodeDialectSpec` instance.
        :param context_dict: JSON-serialisable dict matching the Rust
            ``EncodeContext`` schema.
        :returns: ``{"text": str, "op_to_machine_code": {int: [int]},
            "machine_code_to_op": {int: int}}``
        :raises ValueError: If deserialization fails.
        """
    @staticmethod
    def from_power_modulated_image(gray_image: typing.Any, alpha: typing.Any, pixels_per_mm: tuple[builtins.float, builtins.float], offset_x_mm: builtins.float, offset_y_mm: builtins.float, line_interval_mm: builtins.float, sample_interval_mm: builtins.float, min_power: builtins.float = 0.0, max_power: builtins.float = 1.0, step_power: builtins.float = 1.0, num_power_levels: builtins.int = 256, angle: builtins.float = 0.0, scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED, dot_width_correction_mm: builtins.float = 0.0) -> Ops:
        r"""
        Rasterise a grayscale image with power-modulated scans.
        
        Samples the image along scan lines and computes per-pixel power
        values from the grayscale intensity and alpha channel, then
        emits move-to/scan-to commands with the modulated power.
        
        :param gray_image: 2-D grayscale image (0 = black, 255 = white).
        :param alpha: 2-D alpha mask (0 = transparent/no emission).
        :param pixels_per_mm: ``(x, y)`` pixel density in px/mm.
        :param offset_x_mm: Global X offset in mm.
        :param offset_y_mm: Global Y offset in mm.
        :param line_interval_mm: Spacing between scan lines in mm.
        :param sample_interval_mm: Output sample spacing in mm.
        :param min_power: Minimum power fraction (for white pixels).
        :param max_power: Maximum power fraction (for black pixels).
        :param step_power: Global power multiplier.
        :param num_power_levels: Number of quantised power levels.
        :param angle: Scan angle in degrees.
        :param scan_mode: ``ScanMode.SEGMENTED`` or ``ScanMode.FULL_SWEEP``.
        :param dot_width_correction_mm: Shortens laser firing by this
            distance at each end of every engraved run, compensating
            for the laser spot's physical width. Geometry is unaffected.
        :returns: A new :class:`Ops` container.
        :complexity: O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line
        """
    @staticmethod
    def from_mask_scan(mask: typing.Any, pixels_per_mm: tuple[builtins.float, builtins.float], offset_x_mm: builtins.float, offset_y_mm: builtins.float, line_interval_mm: builtins.float, step_power: builtins.float = 1.0, angle: builtins.float = 0.0, scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED, dot_width_correction_mm: builtins.float = 0.0) -> Ops:
        r"""
        Rasterise a binary mask into scan-to commands.
        
        Generates scan lines covering the mask's bounding box, samples
        the mask along each line, and emits move-to/scan-to commands
        for each non-zero segment (or the full sweep).
        
        :param mask: 2-D binary mask array.
        :param pixels_per_mm: ``(x, y)`` pixel density in px/mm.
        :param offset_x_mm: Global X offset in mm.
        :param offset_y_mm: Global Y offset in mm.
        :param line_interval_mm: Spacing between scan lines in mm.
        :param step_power: Power value (0-1) for exposed pixels.
        :param angle: Scan angle in degrees.
        :param scan_mode: ``ScanMode.SEGMENTED`` or ``ScanMode.FULL_SWEEP``.
        :param dot_width_correction_mm: Shortens laser firing by this
            distance at each end of every engraved run, compensating
            for the laser spot's physical width. Geometry is unaffected.
        :returns: A new :class:`Ops` container.
        :complexity: O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line
        """
    @staticmethod
    def from_mask_lines(mask: typing.Any, pixels_per_mm: tuple[builtins.float, builtins.float], offset_x_mm: builtins.float, offset_y_mm: builtins.float, line_interval_mm: builtins.float, z: builtins.float = 0.0, angle: builtins.float = 0.0, scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED) -> Ops:
        r"""
        Rasterise a binary mask into line-to commands (no power).
        
        Similar to :meth:`from_mask_scan` but emits move-to/line-to
        commands with a Z offset instead of scan-to with power values.
        Useful for simple contour or hatch patterns.
        
        :param mask: 2-D binary mask array.
        :param pixels_per_mm: ``(x, y)`` pixel density in px/mm.
        :param offset_x_mm: Global X offset in mm.
        :param offset_y_mm: Global Y offset in mm.
        :param line_interval_mm: Spacing between scan lines in mm.
        :param z: Z offset for the lines in mm.
        :param angle: Scan angle in degrees.
        :param scan_mode: ``ScanMode.SEGMENTED`` or ``ScanMode.FULL_SWEEP``.
        :returns: A new :class:`Ops` container.
        :complexity: O(h * w + n * p) where h, w = image dimensions, n = scan lines, p = pixels per line
        """
    @staticmethod
    def from_multi_pass_image(gray_image: typing.Any, pixels_per_mm: tuple[builtins.float, builtins.float], offset_x_mm: builtins.float, offset_y_mm: builtins.float, line_interval_mm: builtins.float, num_depth_levels: builtins.int, z_step_down: builtins.float, angle: builtins.float = 0.0, angle_increment: builtins.float = 0.0, scan_mode: scan.ScanMode = scan.ScanMode.SEGMENTED) -> Ops:
        r"""
        Rasterise a grayscale image as multiple Z-depth passes.
        
        Decomposes the grayscale image into *num_depth_levels* layers
        by depth-slicing, then rasterises each layer with a progressive
        Z offset and optional per-pass angle increment.
        
        :param gray_image: 2-D grayscale image (0 = black, 255 = white).
        :param pixels_per_mm: ``(x, y)`` pixel density in px/mm.
        :param offset_x_mm: Global X offset in mm.
        :param offset_y_mm: Global Y offset in mm.
        :param line_interval_mm: Spacing between scan lines in mm.
        :param num_depth_levels: Number of depth layers to produce.
        :param z_step_down: Z decrement per depth layer in mm.
        :param angle: Initial scan angle in degrees.
        :param angle_increment: Angle added per depth layer in degrees.
        :param scan_mode: ``ScanMode.SEGMENTED`` or ``ScanMode.FULL_SWEEP``.
        :returns: A new :class:`Ops` container.
        :complexity: O(d * (h * w + n * p)) where d = depth levels, h, w = image dims, n = scan lines, p = pixels per line
        """

@typing.final
class OpsSection:
    r"""
    A section of operations parsed into marker and content index groups.
    
    Produced by :meth:`Ops.sections` when splitting an Ops sequence
    into logical sections based on ``OpsSectionStart``/``OpsSectionEnd`` markers.
    """
    @property
    def section_type(self) -> typing.Optional[types.SectionType]:
        r"""
        The type of this section (VectorOutline or RasterFill), if any.
        """
    @property
    def raster_mode(self) -> typing.Optional[types.RasterMode]:
        r"""
        The raster mode of this section, if any.
        """
    @property
    def marker_indices(self) -> builtins.list[builtins.int]:
        r"""
        Indices of the section-marker commands (start/end) for this section.
        """
    @property
    def content_indices(self) -> builtins.list[builtins.int]:
        r"""
        Indices of the content commands belonging to this section.
        """
    def content(self, ops: Ops) -> Ops:
        r"""
        Extract the content commands of this section from an Ops sequence.
        
        :param ops: The Ops sequence containing this section.
        :returns: A new Ops containing only the content of this section.
        :complexity: O(n) time, O(n) space
        """
    def state_blocks(self, ops: Ops) -> builtins.list[types.StateBlock]:
        r"""
        Return the state blocks within this section.
        
        :param ops: The parent Ops sequence.
        :returns: List of StateBlock objects.
        :raises RuntimeError: If state block nesting is invalid.
        :complexity: O(n) time, O(n) space
        """
    def state_block_content(self, ops: Ops, block: types.StateBlock) -> Ops:
        r"""
        Extract a specific state block's content as Ops.
        
        :param ops: The parent Ops sequence.
        :param block: The StateBlock to extract.
        :returns: A new Ops containing only the block's content.
        :complexity: O(n) time, O(n) space
        """
    def state_blocks_by_name(self, ops: Ops, pattern: builtins.str) -> builtins.list[types.StateBlock]:
        r"""
        Find state blocks by name pattern (``*`` prefix match or exact).
        
        :param ops: The parent Ops sequence.
        :param pattern: Name pattern (``"cell-*"`` for prefix, ``"labels"`` for exact).
        :returns: List of matching StateBlock objects.
        :raises RuntimeError: If state block nesting is invalid.
        :complexity: O(n) time, O(n) space
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class OpsSectionRange:
    r"""
    A contiguous range of indices that belong to a section.
    
    Similar to :class:`OpsSection` but stores start/end index ranges
    instead of individual index lists. Produced by :meth:`Ops.section_ranges`.
    """
    @property
    def section_type(self) -> typing.Optional[types.SectionType]:
        r"""
        The type of this section range (VectorOutline or RasterFill), if any.
        """
    @property
    def raster_mode(self) -> typing.Optional[types.RasterMode]:
        r"""
        The raster mode of this section range, if any.
        """
    @property
    def marker_indices(self) -> builtins.list[builtins.int]:
        r"""
        Indices of the section-marker commands that bracket this range.
        """
    @property
    def content_indices(self) -> builtins.list[builtins.int]:
        r"""
        Starting index of the content within this section range.
        """
    def content(self, ops: Ops) -> Ops:
        r"""
        Extract the content commands of this section range from an Ops sequence.
        
        :param ops: The Ops sequence containing this section.
        :returns: A new Ops containing only the content of this section range.
        :complexity: O(n) time, O(n) space
        Extract the content commands of this section range from an Ops sequence.
        
        :param ops: The Ops sequence containing this section.
        :returns: A new Ops containing only the content of this section range.
        :complexity: O(n) time, O(n) space
        """
    def __repr__(self) -> builtins.str: ...

