# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Geometry types and operations for 2D/3D path data.

The central type is Geometry — a mutable sequence of drawing commands
(move, line, arc, bezier) that represents one or more closed or open
paths. Geometry supports construction (add_rect, add_circle, etc.),
analysis (area, distance, bounding rect), and manipulation (transform,
simplify, linearize, fit curves, grow/shrink, split, clip).

Shape sub-modules provide primitive-specific operations: arc bounding
and intersection, bezier splitting and flattening, circle containment
tests, polygon boolean algebra and offsetting, and line intersection.

Algorithm sub-modules provide higher-level geometric processing such
as polyline simplification, smoothing, curve fitting, and Minkowski
sums for toolpath generation.
"""

import builtins
import numpy
import numpy.typing
import typing
from . import algo
from . import shape
from . import types
__all__ = [
    "Arc",
    "Bezier",
    "Geometry",
    "Line",
    "Matrix",
    "Move",
    "algo",
    "shape",
    "types",
]

@typing.final
class Arc:
    r"""
    A circular-arc cutting command.
    """
    @property
    def end(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Endpoint of the arc in 3D space.
        """
    @property
    def center_offset(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Centre offset from the start point (3D).
        """
    @property
    def normal(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Plane normal of the arc. A positive Z component means CCW in XY.
        """
    @property
    def clockwise(self) -> builtins.bool:
        r"""
        Whether the arc is clockwise (computed from the normal).
        """

@typing.final
class Bezier:
    r"""
    A cubic-Bezier curve cutting command.
    """
    @property
    def end(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Endpoint of the curve in 3D space.
        """
    @property
    def control1(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        First control point in 3D space.
        """
    @property
    def control2(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Second control point in 3D space.
        """

@typing.final
class Geometry:
    r"""
    A sequence of geometric commands (Move, Line, Arc, Bezier).
    
    The primary building block for vector geometry in raygeo.
    Geometry objects can be constructed procedurally, parsed from SVG,
    or obtained by converting an :class:`~raygeo.ops.Ops` sequence.
    """
    @property
    def last_move_to(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        The coordinates of the last move-to 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
        """
    @property
    def uniform_scalable(self) -> builtins.bool:
        r"""
        Whether the geometry uses uniform scalable arcs.
        
        :complexity: O(1) time, O(1) space
        """
    @uniform_scalable.setter
    def uniform_scalable(self, value: builtins.bool) -> None:
        r"""
        Set whether the geometry uses uniform scalable arcs.
        
        :complexity: O(1) time, O(1) space
        """
    @property
    def data(self) -> builtins.list[typing.Any]:
        r"""
        The commands as a list of typed command objects.
        
        :complexity: O(n) time, O(n) space
        """
    def __eq__(self, other: object) -> bool:
        r"""
        Check equality with another Geometry.
        
        :complexity: O(n) time, O(1) space
        """
    def __ne__(self, other: object) -> bool:
        r"""
        Check inequality with another Geometry.
        
        :complexity: O(n) time, O(1) space
        """
    def transform(self, matrix: Matrix | types.TransformMatrix) -> Geometry:
        r"""
        Apply an affine transformation matrix.
        
        :param matrix: A :class:`~raygeo.geo.Matrix` or a 4x4 matrix
            as list of lists.
        :returns: A new transformed Geometry.
        :complexity: O(n) time, O(n) space
        """
    def iter_typed_commands(self) -> list[Move | Line | Arc | Bezier]:
        r"""
        Iterate over all commands as typed command objects.
        
        :complexity: O(n) time, O(n) space
        """
    def get_typed_command_at(self, index: int) -> Move | Line | Arc | Bezier | None:
        r"""
        Get the typed command at the given index.
        
        :param index: Command index.
        :complexity: O(1) time, O(1) space
        """
    def __new__(cls) -> Geometry:
        r"""
        Create a new empty Geometry.
        """
    def move_to(self, x: builtins.float, y: builtins.float, z: builtins.float = 0.0) -> Geometry:
        r"""
        Move the pen to the given coordinates.
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :param z: Z coordinate (default 0.0).
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def line_to(self, x: builtins.float, y: builtins.float, z: builtins.float = 0.0) -> Geometry:
        r"""
        Draw a line to the given coordinates.
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :param z: Z coordinate (default 0.0).
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def close_path(self) -> Geometry:
        r"""
        Close the current sub-path.
        
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def arc_to(self, x: builtins.float, y: builtins.float, i: builtins.float = 0.0, j: builtins.float = 0.0, clockwise: builtins.bool = True, z: builtins.float = 0.0) -> Geometry:
        r"""
        Draw an arc to the given coordinates.
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :param i: I offset from current point to center.
        :param j: J offset from current point to center.
        :param clockwise: Whether the arc is clockwise.
        :param z: Z coordinate (default 0.0).
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def bezier_to(self, x: builtins.float, y: builtins.float, c1x: builtins.float, c1y: builtins.float, c2x: builtins.float, c2y: builtins.float, *, c1z: builtins.float = 0.0, c2z: builtins.float = 0.0, z: builtins.float = 0.0) -> Geometry:
        r"""
        Draw a cubic bezier curve.
        
        :param x: End X coordinate.
        :param y: End Y coordinate.
        :param c1x: First control point X.
        :param c1y: First control point Y.
        :param c1z: First control point Z (default 0.0).
        :param c2x: Second control point X.
        :param c2y: Second control point Y.
        :param c2z: Second control point Z (default 0.0).
        :param z: End Z coordinate (default 0.0).
        :returns: The geometry (for method chaining).
        :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 __hash__(self) -> builtins.int:
        r"""
        Return a hash of the geometry data.
        
        :complexity: O(n) time, O(1) space
        """
    def is_empty(self) -> builtins.bool:
        r"""
        Check if the geometry has no commands.
        
        :returns: ``True`` if the geometry has no commands.
        :complexity: O(1) time, O(1) space
        """
    def clear(self) -> Geometry:
        r"""
        Remove all commands from the geometry.
        
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def copy(self) -> Geometry:
        r"""
        Return a deep copy of this geometry.
        
        :returns: A deep copy of the geometry.
        :complexity: O(n) time, O(n) space
        """
    def get_last_point(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Get the last point in the geometry.
        
        :returns: The last point as ``(x, y, z)``, or ``(0, 0, 0)`` if empty.
        :complexity: O(1) time, O(1) space
        """
    def extend(self, other: Geometry) -> Geometry:
        r"""
        Append another geometry's commands to this one.
        
        :param other: The geometry to append.
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def rect(self) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float]:
        r"""
        Return the bounding rectangle (x_min, y_min, x_max, y_max).
        
        :returns: (x_min, y_min, x_max, y_max).
        :complexity: O(n) time, O(1) space
        """
    def segment_bounds(self, index: builtins.int) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float, builtins.float]]:
        r"""
        Return the bounding box of a single segment at the given index.
        Returns None for Move commands or if the index is out of bounds.
        
        :param index: Segment index.
        :returns: (x_min, y_min, x_max, y_max) or None.
        :complexity: O(1) time, O(1) space
        """
    def get_positions_at_distances(self, distances: typing.Sequence[builtins.float]) -> builtins.list[tuple[builtins.int, builtins.float, tuple[builtins.float, builtins.float]]]:
        r"""
        Given a list of distances along the path, returns the corresponding
        (segment_index, t, point) for each distance.
        
        Distances are clamped to [0, total_length].
        
        :param distances: List of distances along the path.
        :returns: List of (segment_index, t, (x, y)) tuples.
        :complexity: O(n + m) time, O(m) space where n is the number of segments and m the number of distances
        """
    def segments_in_frame(self, x1: builtins.float, y1: builtins.float, x2: builtins.float, y2: builtins.float) -> builtins.list[builtins.int]:
        r"""
        Return indices of all segments whose bounding box intersects the
        given rectangle. Excludes Move commands.
        
        :param x1: First corner X.
        :param y1: First corner Y.
        :param x2: Second corner X.
        :param y2: Second corner Y.
        :returns: List of segment indices.
        :complexity: O(n) time, O(n) space
        """
    def distance(self) -> builtins.float:
        r"""
        Return the total path distance.
        
        :returns: The total path distance in mm.
        :complexity: O(n) time, O(1) space
        """
    def area(self) -> builtins.float:
        r"""
        Return the signed area of the geometry.
        
        :returns: The signed area in mm².
        :complexity: O(n) time, O(1) space
        """
    def is_closed(self, tolerance: builtins.float = 1e-06) -> builtins.bool:
        r"""
        Check if the geometry forms a closed path.
        
        :param tolerance: Max gap between start and end point.
        :returns: ``True`` if the geometry forms a closed path.
        :complexity: O(n) time, O(1) space
        """
    def segments(self) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float, builtins.float]]]:
        r"""
        Return the geometry split into segments of connected commands.
        
        :returns: List of segments, each a list of 3D points.
        :complexity: O(n) time, O(n) space
        """
    def get_command_at(self, index: builtins.int) -> typing.Optional[typing.Any]:
        r"""
        Get the command at the given index as a typed command object.
        
        :param index: Command index (negative returns None).
        :returns: The typed command or ``None``.
        :complexity: O(1) time, O(1) space
        """
    def iter_commands(self) -> builtins.list[typing.Any]:
        r"""
        Iterate over all commands as typed command objects.
        
        :returns: List of typed command objects.
        :complexity: O(n) time, O(n) space
        """
    def to_dict(self) -> dict:
        r"""
        Serialize the geometry to a dictionary.
        
        :returns: A dictionary representation of the geometry.
        :complexity: O(n) time, O(n) space
        """
    @classmethod
    def from_dict(cls, data: dict) -> Geometry:
        r"""
        Create a Geometry from a dictionary.
        
        :param data: A dictionary as produced by
            :meth:`to_dict`.
        :returns: A new ``Geometry`` instance.
        :complexity: O(n) time, O(n) space
        """
    @classmethod
    def from_points(cls, points: typing.Any, close: builtins.bool = True) -> Geometry:
        r"""
        Create a Geometry from a sequence of points.
        
        :param points: A sequence of (x, y) or
            (x, y, z) coordinate tuples.
        :param close: Whether to close the path.
        :returns: A new ``Geometry`` instance.
        :complexity: O(n) time, O(n) space
        """
    def filter(self, indices: builtins.set[builtins.int]) -> Geometry:
        r"""
        Return a new Geometry containing only commands at the given
        indices.
        
        :param indices: Set of command indices to keep.
        :returns: A new Geometry with the filtered commands.
        :complexity: O(n) time, O(n) space
        """
    def simplify(self, tolerance: builtins.float) -> Geometry:
        r"""
        Simplify the geometry using Ramer-Douglas-Peucker.
        
        :param tolerance: Maximum deviation from original.
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def linearize(self, tolerance: builtins.float) -> Geometry:
        r"""
        Convert all curves to line segments.
        
        :param tolerance: Maximum deviation from curves.
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def fit_curves(self, tolerance: builtins.float, beziers: builtins.bool = True, arcs: builtins.bool = True, on_progress: typing.Optional[typing.Any] = None) -> Geometry:
        r"""
        Fit curves (beziers and arcs) to the linearized geometry.
        
        :param tolerance: Maximum deviation.
        :param beziers: Whether to fit bezier curves.
        :param arcs: Whether to fit arcs.
        :param on_progress: Optional progress callback called with ``(current, total)``.
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def fit_arcs(self, tolerance: builtins.float) -> Geometry:
        r"""
        Fit arcs only to the linearized geometry.
        
        :param tolerance: Maximum deviation.
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def upgrade_to_scalable(self) -> Geometry:
        r"""
        Convert all arcs to bezier curves for uniform scaling.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def close_gaps(self, tolerance: typing.Optional[builtins.float] = None) -> Geometry:
        r"""
        Close gaps between sub-paths.
        
        :param tolerance: Max gap to close.
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def cleanup(self, tolerance: builtins.float) -> Geometry:
        r"""
        Remove duplicate segments from the geometry.
        
        :param tolerance: Maximum deviation for equality.
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def flip_x(self) -> Geometry:
        r"""
        Mirror the geometry along the X axis.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(1) space
        """
    def flip_y(self) -> Geometry:
        r"""
        Mirror the geometry along the Y axis.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(1) space
        """
    def find_closest_point(self, x: builtins.float, y: builtins.float) -> typing.Optional[tuple[builtins.int, builtins.float, tuple[builtins.float, builtins.float]]]:
        r"""
        Find the closest point on the path to (x, y).
        
        :param x: X coordinate.
        :param y: Y coordinate.
        :returns: Tuple of (segment_index, t, point) or None.
        :complexity: O(n) time, O(1) space
        """
    def get_point_at(self, segment_index: builtins.int, t: builtins.float) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float]]:
        r"""
        Get the point at parameter t on a segment.
        
        :param segment_index: Index of the segment.
        :param t: Parameter in [0, 1].
        :returns: The 3D point or None.
        :complexity: O(1) time, O(1) space
        """
    def get_tangent_at(self, segment_index: builtins.int, t: builtins.float) -> typing.Optional[tuple[builtins.float, builtins.float]]:
        r"""
        Get the tangent vector at parameter t on a segment.
        
        :param segment_index: Index of the segment.
        :param t: Parameter in [0, 1].
        :returns: The normalized tangent vector or None.
        :complexity: O(1) time, O(1) space
        """
    def get_outward_normal_at(self, segment_index: builtins.int, t: builtins.float) -> typing.Optional[tuple[builtins.float, builtins.float]]:
        r"""
        Get the outward normal at parameter t on a segment.
        
        :param segment_index: Index of the segment.
        :param t: Parameter in [0, 1].
        :returns: Normal vector or None.
        :complexity: O(1) time, O(1) space
        """
    def arc_to_as_bezier(self, x: builtins.float, y: builtins.float, i: builtins.float, j: builtins.float, clockwise: builtins.bool = True, z: builtins.float = 0.0) -> Geometry:
        r"""
        Draw an arc, converting it to bezier curves.
        
        :param x: End X coordinate.
        :param y: End Y coordinate.
        :param i: I offset to center.
        :param j: J offset to center.
        :param clockwise: Arc direction.
        :param z: End Z coordinate.
        :returns: The geometry (for method chaining).
        :complexity: O(1) time, O(1) space
        """
    def convert_arcs_to_beziers(self) -> None:
        r"""
        Convert all Arc commands to Bezier curve approximations in-place.
        
        After this call, the geometry will only contain Move, Line, and Bezier
        commands.
        
        :complexity: O(n) time, O(n) space where n = number of commands
        """
    def has_self_intersections(self, fail_on_t_junction: builtins.bool = False) -> builtins.bool:
        r"""
        Check if the geometry has self-intersections.
        
        :param fail_on_t_junction: Whether to fail on T-junctions.
        :returns: ``True`` if the geometry has self-intersections.
        :complexity: O(n²) worst-case time, O(1) space
        """
    def intersects_with(self, other: Geometry) -> builtins.bool:
        r"""
        Check if this geometry intersects with another.
        
        :param other: The other geometry.
        :returns: ``True`` if the geometries intersect.
        :complexity: O(n * m) worst-case time, O(1) space where n and m are the number of segments in each geometry
        """
    def grow(self, amount: builtins.float) -> Geometry:
        r"""
        Offset (grow/shrink) the geometry by the given amount.
        
        :param amount: Positive to grow, negative to shrink.
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def encloses(self, other: Geometry) -> builtins.bool:
        r"""
        Check if this geometry encloses another.
        
        :param other: The potentially enclosed geometry.
        :returns: ``True`` if this geometry encloses the other.
        :complexity: O(n log n) average time, O(n) space
        """
    def remove_inner_edges(self) -> Geometry:
        r"""
        Remove inner edges (shared between contours).
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def split_inner_and_outer_contours(self) -> tuple[builtins.list[Geometry], builtins.list[Geometry]]:
        r"""
        Split contours into inner and outer groups.
        
        :returns: Tuple of ``(inner_contours, outer_contours)``, each a list of Geometry.
        :complexity: O(n log n) average time, O(n) space
        """
    def map_to_frame(self, origin: tuple[builtins.float, builtins.float], p_width: tuple[builtins.float, builtins.float], p_height: tuple[builtins.float, builtins.float], anchor_y: typing.Optional[builtins.float] = None, stable_src_height: typing.Optional[builtins.float] = None, anchor_x: typing.Optional[builtins.float] = None, stable_src_width: typing.Optional[builtins.float] = None) -> Geometry:
        r"""
        Map the geometry into a rectangular frame.
        
        :param origin: Frame origin (x, y).
        :param p_width: Frame width vector.
        :param p_height: Frame height vector.
        :param anchor_y: Y anchor position.
        :param stable_src_height: Stable source height for anchoring.
        :param anchor_x: X anchor position.
        :param stable_src_width: Stable source width for anchoring.
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def split_into_contours(self) -> builtins.list[Geometry]:
        r"""
        Split the geometry into individual contours.
        
        :returns: List of Geometry objects, one per contour.
        :complexity: O(n) time, O(n) space
        """
    def split_into_components(self) -> builtins.list[Geometry]:
        r"""
        Split the geometry into connected components.
        
        :returns: List of Geometry objects, one per connected component.
        :complexity: O(n log n) average time, O(n) space
        """
    def to_polygons(self, tolerance: builtins.float = 0.01) -> builtins.list[builtins.list[tuple[builtins.float, builtins.float]]]:
        r"""
        Convert the geometry to a list of polygons.
        
        :param tolerance: Max deviation for linearization.
        :returns: List of polygons, each a list of ``(x, y)`` vertices.
        :complexity: O(n) time, O(n) space
        """
    def reverse_contour(self) -> Geometry:
        r"""
        Reverse the winding direction of all contours.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def close_all_contours(self) -> Geometry:
        r"""
        Close all open contours in the geometry.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n) time, O(n) space
        """
    def normalize_winding_orders(self) -> Geometry:
        r"""
        Normalize winding orders (outer CCW, inner CW) of all contours.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def filter_to_external_contours(self) -> Geometry:
        r"""
        Filter to only external (outermost) contours.
        
        :returns: The geometry (for method chaining).
        :complexity: O(n log n) average time, O(n) space
        """
    def get_valid_contours_data(self) -> builtins.list[dict]:
        r"""
        Get valid contour data from the geometry's contours.
        
        :returns: List of dicts with keys "geo", "vertices",
            "is_closed", "original_index".
        :complexity: O(n) time, O(n) space
        """
    def __repr__(self) -> builtins.str:
        r"""
        Return a string representation of the geometry.
        
        :complexity: O(n) time, O(n) space
        """

@typing.final
class Line:
    r"""
    A straight-line cutting command.
    """
    @property
    def end(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Endpoint of the line in 3D space.
        """

@typing.final
class Matrix:
    r"""
    A 3x3 affine transformation matrix for 2D graphics.
    
    Provides an object-oriented interface for matrix operations, including
    translations, rotations, and scaling.
    """
    def __matmul__(self, other: Matrix) -> Matrix:
        r"""
        Multiply two matrices (self @ other).
        """
    def __eq__(self, other: object) -> bool:
        r"""
        Check equality with another Matrix.
        """
    def transform_point(self, *args: float | tuple[float, float]) -> tuple[float, float]:
        r"""
        Apply the affine transformation to a 2D point.
        """
    def transform_vector(self, *args: float | tuple[float, float]) -> tuple[float, float]:
        r"""
        Apply the transformation to a 2D vector, ignoring translation.
        """
    def transform_rectangle(self, *args: float | tuple[float, float, float, float]) -> tuple[float, float, float, float]:
        r"""
        Transform a rectangle and return the new axis-aligned bounding box.
        """
    def to_numpy(self) -> numpy.typing.NDArray[numpy.float64]:
        r"""
        Return the matrix as a 3x3 numpy array.
        """
    def to_4x4_numpy(self) -> numpy.typing.NDArray[numpy.float64]:
        r"""
        Return the matrix as a 4x4 numpy array (affine, Z-preserving).
        """
    def get(self, row: int, col: int) -> float:
        r"""
        Get a single element from the 3x3 matrix (row-major indexing).
        """
    def __copy__(self) -> Matrix:
        r"""
        Return a copy of this matrix.
        """
    def __deepcopy__(self, memo: dict) -> Matrix:
        r"""
        Return a deep copy of this matrix.
        """
    def __new__(cls, data: typing.Optional[typing.Any] = None) -> Matrix:
        r"""
        Create a new Matrix.
        
        :param data: Optional 3x3 or 4x4 sequence (list of lists) to initialize
            from. If None, creates an identity matrix.
        """
    @classmethod
    def identity(cls) -> Matrix:
        r"""
        Create an identity matrix.
        """
    @classmethod
    def translation(cls, tx: builtins.float, ty: builtins.float) -> Matrix:
        r"""
        Create a translation matrix.
        
        :param tx: Translation in x.
        :param ty: Translation in y.
        """
    @classmethod
    def scale(cls, sx: builtins.float, sy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Create a scaling matrix.
        
        :param sx: Scale factor for x-axis.
        :param sy: Scale factor for y-axis.
        :param center: Optional (x, y) center point to scale around.
        """
    @classmethod
    def rotation(cls, angle_deg: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Create a rotation matrix.
        
        :param angle_deg: Rotation angle in degrees.
        :param center: Optional (x, y) center point to rotate around.
        """
    @classmethod
    def shear(cls, shx: builtins.float, shy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Create a shearing matrix.
        
        :param shx: Shear factor for x-axis.
        :param shy: Shear factor for y-axis.
        :param center: Optional (x, y) center point to shear around.
        """
    @classmethod
    def compose(cls, tx: builtins.float, ty: builtins.float, angle_deg: builtins.float, sx: builtins.float, sy: builtins.float, skew_angle_deg: builtins.float) -> Matrix:
        r"""
        Compose a matrix from translation, rotation, scale, and skew.
        
        :param tx: Translation x.
        :param ty: Translation y.
        :param angle_deg: Rotation angle in degrees.
        :param sx: Scale x.
        :param sy: Scale y.
        :param skew_angle_deg: Skew angle in degrees.
        :returns: A new Matrix.
        """
    @classmethod
    def flip_horizontal(cls, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Create a horizontal flip matrix.
        """
    @classmethod
    def flip_vertical(cls, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Create a vertical flip matrix.
        """
    def copy(self) -> Matrix:
        r"""
        Return a deep copy of this matrix.
        """
    def __repr__(self) -> builtins.str:
        r"""
        String representation for developers.
        """
    def __str__(self) -> builtins.str:
        r"""
        Human-readable string representation.
        """
    def to_list(self) -> builtins.list[builtins.list[builtins.float]]:
        r"""
        Returns a copy of the matrix data as a list of lists.
        """
    def to_4x4_list(self) -> builtins.list[builtins.list[builtins.float]]:
        r"""
        Converts the matrix to a 4x4 list of lists (row-major).
        The 3x3 Matrix is placed in the top-left 2x2 of the 4x4,
        with translation in the last column, and Z preserved.
        """
    def for_cairo(self) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float, builtins.float, builtins.float]:
        r"""
        Returns the matrix components in Cairo order (xx, yx, xy, yy, x0, y0).
        """
    def to_graphene(self) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float, builtins.float, builtins.float]:
        r"""
        Returns (xx, yx, xy, yy, x0, y0) for GTK/Graphene.
        """
    def get_translation(self) -> tuple[builtins.float, builtins.float]:
        r"""
        Extract the translation component (tx, ty).
        """
    def set_translation(self, tx: builtins.float, ty: builtins.float) -> Matrix:
        r"""
        Returns a new matrix with the same rotation/scale/shear but new
        translation.
        
        :param tx: New translation x.
        :param ty: New translation y.
        """
    def without_translation(self) -> Matrix:
        r"""
        Returns a new matrix with translation set to zero.
        """
    def get_scale(self) -> tuple[builtins.float, builtins.float]:
        r"""
        Extract the signed scale components (sx, sy).
        """
    def get_abs_scale(self) -> tuple[builtins.float, builtins.float]:
        r"""
        Extract the absolute scale components (|sx|, |sy|).
        """
    def get_rotation(self) -> builtins.float:
        r"""
        Extract the rotation angle in degrees.
        """
    def get_x_axis_angle(self) -> builtins.float:
        r"""
        Calculate the angle of the transformed X-axis in degrees.
        """
    def get_y_axis_angle(self) -> builtins.float:
        r"""
        Calculate the angle of the transformed Y-axis in degrees.
        """
    def get_determinant_2x2(self) -> builtins.float:
        r"""
        Calculate the determinant of the top-left 2x2 sub-matrix.
        """
    def is_identity(self) -> builtins.bool:
        r"""
        Check if the matrix is an identity matrix.
        """
    def is_flipped(self) -> builtins.bool:
        r"""
        Check if the matrix includes a reflection (flip).
        """
    def has_zero_scale(self, tolerance: builtins.float = 1e-06) -> builtins.bool:
        r"""
        Check if the matrix has zero scale on any axis.
        
        :param tolerance: Threshold below which a scale is considered zero.
        """
    def is_close(self, other: Matrix, tol: builtins.float = 1e-06) -> builtins.bool:
        r"""
        Check if two matrices are effectively equal within tolerance.
        
        :param other: The matrix to compare against.
        :param tol: The absolute tolerance parameter.
        """
    def pre_translate(self, tx: builtins.float, ty: builtins.float) -> Matrix:
        r"""
        Apply a translation before this matrix's transformation.
        """
    def post_translate(self, tx: builtins.float, ty: builtins.float) -> Matrix:
        r"""
        Apply a translation after this matrix's transformation.
        """
    def pre_scale(self, sx: builtins.float, sy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a scale before this matrix's transformation.
        
        :param sx: Scale factor for x-axis.
        :param sy: Scale factor for y-axis.
        :param center: Optional center point to scale around.
        """
    def post_scale(self, sx: builtins.float, sy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a scale after this matrix's transformation.
        
        :param sx: Scale factor for x-axis.
        :param sy: Scale factor for y-axis.
        :param center: Optional center point to scale around.
        """
    def pre_rotate(self, angle_deg: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a rotation before this matrix's transformation.
        
        :param angle_deg: Rotation angle in degrees.
        :param center: Optional center point to rotate around.
        """
    def post_rotate(self, angle_deg: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a rotation after this matrix's transformation.
        
        :param angle_deg: Rotation angle in degrees.
        :param center: Optional center point to rotate around.
        """
    def pre_shear(self, shx: builtins.float, shy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a shear before this matrix's transformation.
        
        :param shx: Shear factor for x-axis.
        :param shy: Shear factor for y-axis.
        :param center: Optional center point to shear around.
        """
    def post_shear(self, shx: builtins.float, shy: builtins.float, center: typing.Optional[tuple[builtins.float, builtins.float]] = None) -> Matrix:
        r"""
        Apply a shear after this matrix's transformation.
        
        :param shx: Shear factor for x-axis.
        :param shy: Shear factor for y-axis.
        :param center: Optional center point to shear around.
        """
    def invert(self) -> Matrix:
        r"""
        Compute the inverse of the matrix.
        
        Will raise an error if the matrix is singular.
        """
    def decompose(self) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float, builtins.float, builtins.float]:
        r"""
        Decompose the matrix into translation, rotation, scale, and skew.
        
        :returns: (tx, ty, angle_deg, sx, sy, skew_angle_deg).
        """
    @classmethod
    def from_list(cls, data: typing.Sequence[typing.Sequence[builtins.float]]) -> Matrix:
        r"""
        Create a Matrix from a list of lists.
        """

@typing.final
class Move:
    r"""
    A rapid-move command with an endpoint but no cutting.
    """
    @property
    def end(self) -> tuple[builtins.float, builtins.float, builtins.float]:
        r"""
        Endpoint of the move in 3D space.
        """

