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

import builtins
import numpy
import numpy.typing
import raygeo
from raygeo import geo
import typing
__all__ = [
    "SvgMetadata",
    "extract_svg_metadata",
    "geometry_to_svg_path",
    "parse_svg_length",
    "parse_svg_path_data",
    "parse_svg_transform",
    "svg_length_to_mm",
    "svg_length_to_px",
    "svg_string_to_geometries",
    "svg_string_to_geometries_by_layer",
    "svg_string_to_geometry",
    "svg_string_to_geometry_by_layer",
]

@typing.final
class SvgMetadata:
    r"""
    SVG document metadata extracted from an SVG string.
    
    Provides width, height, units and viewBox values parsed from the
    root ``<svg>`` element.
    """
    @property
    def width(self) -> typing.Optional[builtins.float]:
        r"""
        Document width as a numeric value (may be ``None`` if not set).
        """
    @property
    def height(self) -> typing.Optional[builtins.float]:
        r"""
        Document height as a numeric value (may be ``None`` if not set).
        """
    @property
    def width_unit(self) -> builtins.str:
        r"""
        Unit string for the width attribute (e.g. ``"mm"``, ``"in"``, ``"px"``).
        """
    @property
    def height_unit(self) -> builtins.str:
        r"""
        Unit string for the height attribute.
        """
    @property
    def viewbox(self) -> typing.Optional[tuple[builtins.float, builtins.float, builtins.float, builtins.float]]:
        r"""
        ViewBox as ``(min_x, min_y, width, height)``, or ``None``.
        """
    def width_mm(self, dpi: builtins.float = 96.0) -> typing.Optional[builtins.float]:
        r"""
        Convert the document width to millimetres.
        
        :param dpi: Pixels-per-inch for px/unitless conversion (default 96).
        :returns: Width in millimetres, or ``None`` if not set.
        :complexity: O(1)
        """
    def height_mm(self, dpi: builtins.float = 96.0) -> typing.Optional[builtins.float]:
        r"""
        Convert the document height to millimetres.
        
        :param dpi: Pixels-per-inch for px/unitless conversion (default 96).
        :returns: Height in millimetres, or ``None`` if not set.
        :complexity: O(1)
        """
    def width_px(self, dpi: builtins.float = 96.0) -> typing.Optional[builtins.float]:
        r"""
        Convert the document width to pixels.
        
        :param dpi: Pixels-per-inch for conversion (default 96).
        :returns: Width in pixels, or ``None`` if not set.
        :complexity: O(1)
        """
    def height_px(self, dpi: builtins.float = 96.0) -> typing.Optional[builtins.float]:
        r"""
        Convert the document height to pixels.
        
        :param dpi: Pixels-per-inch for conversion (default 96).
        :returns: Height in pixels, or ``None`` if not set.
        :complexity: O(1)
        """
    def __repr__(self) -> builtins.str: ...
    def __richcmp__(self, other: SvgMetadata, op: int) -> builtins.bool: ...

def extract_svg_metadata(svg_str: str) -> SvgMetadata:
    r"""
    Extract width, height, units and viewBox from an SVG string.
    
    :param svg_str: SVG document as a string.
    :returns: SvgMetadata instance with width, height, width_unit,
              height_unit, and viewbox attributes.
    :complexity: O(n) where n = size of SVG document
    """

def geometry_to_svg_path(geometry: raygeo.geo.Geometry, width: int, height: int) -> str:
    r"""
    Convert a normalized Geometry to an SVG path d attribute string.
    
    The geometry coordinates should be in normalized [0, 1] space.
    Coordinates are scaled to pixel dimensions via width and height,
    with the Y axis flipped (SVG Y increases downward).
    
    :param geometry: A Geometry object with normalized coordinates.
    :param width: Target pixel width.
    :param height: Target pixel height.
    :returns: SVG path d attribute string.
    :complexity: O(n) where n = number of commands
    """

def parse_svg_length(length_str: str) -> tuple[float, str]:
    r"""
    Parse an SVG length string into a (value, unit) tuple.
    
    Supports: mm, cm, in, pt, pc, px. Unitless values default to 'px'.
    
    :param length_str: SVG length string (e.g. '10mm', '2.5in', '100').
    :returns: Tuple of (value, unit).
    :complexity: O(1)
    """

def parse_svg_path_data(path_data: str, transform: numpy.typing.NDArray[numpy.float64] | None = None, scale_x: float = 1, scale_y: float = 1) -> list[raygeo.geo.Geometry]:
    r"""
    Parse an SVG path d attribute into a list of Geometry objects.
    
    Supports M/m, L/l, H/h, V/v, C/c, Z/z commands.
    Cubic Bezier curves are flattened to line segments (20 steps).
    
    :param path_data: SVG path d attribute string.
    :param transform: 3x3 affine transformation matrix, or None for identity.
    :param scale_x: X-axis scale factor for coordinate transform.
    :param scale_y: Y-axis scale factor for coordinate transform.
    :returns: List of Geometry objects, one per subpath.
    :complexity: O(n) where n = length of path data
    """

def parse_svg_transform(transform_str: str) -> numpy.typing.NDArray[numpy.float64]:
    r"""
    Parse an SVG transform attribute string (translate only).
    
    Returns a 3x3 identity matrix with translation applied.
    
    :param transform_str: SVG transform attribute value.
    :returns: 3x3 affine transformation matrix as numpy array.
    :complexity: O(1)
    """

def svg_length_to_mm(length_str: str, dpi: float = 96) -> float:
    r"""
    Parse an SVG length string and convert to millimetres.
    
    :param length_str: SVG length string (e.g. '10mm', '2.5in', '100').
    :param dpi: Pixels per inch used for px/unitless conversion (default 96).
    :returns: Length in millimetres.
    :complexity: O(1)
    """

def svg_length_to_px(length_str: str, dpi: float = 96) -> float:
    r"""
    Parse an SVG length string and convert to pixels.
    
    :param length_str: SVG length string (e.g. '10mm', '2.5in', '100').
    :param dpi: Pixels per inch used for px/unitless conversion (default 96).
    :returns: Length in pixels.
    :complexity: O(1)
    """

def svg_string_to_geometries(svg_str: str, scale_x: float = 1, scale_y: float = 1) -> list[raygeo.geo.Geometry]:
    r"""
    Parse an SVG string and extract all path elements as Geometry objects.
    
    Recursively traverses the SVG XML tree, extracting d attributes
    from path elements and converting them to Geometry.
    
    :param svg_str: SVG document as a string.
    :param scale_x: X-axis scale factor for coordinate transform.
    :param scale_y: Y-axis scale factor for coordinate transform.
    :returns: List of Geometry objects from all path elements.
    :complexity: O(n) where n = size of SVG document
    """

def svg_string_to_geometries_by_layer(svg_str: str, scale_x: float = 1, scale_y: float = 1) -> list[tuple[str, list[raygeo.geo.Geometry]]]:
    r"""
    Extract geometries grouped by top-level <g> layer.
    
    Returns a list of (layer_id, geometries) tuples. Only top-level
    <g> elements with an id attribute are treated as layers.
    
    :param svg_str: SVG document as a string.
    :param scale_x: X-axis scale factor for coordinate transform.
    :param scale_y: Y-axis scale factor for coordinate transform.
    :returns: List of (layer_id, geometry_list) tuples.
    :complexity: O(n) where n = size of SVG document
    """

def svg_string_to_geometry(svg_str: str, scale_x: float = 1, scale_y: float = 1) -> raygeo.geo.Geometry:
    r"""
    Parse an SVG string and merge all subpaths into a single Geometry.
    
    Like svg_string_to_geometries but returns one combined Geometry
    instead of a list, avoiding a Python-side merge loop.
    
    :param svg_str: SVG document as a string.
    :param scale_x: X-axis scale factor for coordinate transform.
    :param scale_y: Y-axis scale factor for coordinate transform.
    :returns: A single Geometry containing all paths.
    :complexity: O(n) where n = size of SVG document
    """

def svg_string_to_geometry_by_layer(svg_str: str, scale_x: float = 1, scale_y: float = 1) -> list[tuple[str, raygeo.geo.Geometry]]:
    r"""
    Extract geometries grouped by layer, merged into one Geometry each.
    
    Like svg_string_to_geometries_by_layer but merges each layer's
    subpaths into a single Geometry, avoiding a Python merge loop.
    
    :param svg_str: SVG document as a string.
    :param scale_x: X-axis scale factor for coordinate transform.
    :param scale_y: Y-axis scale factor for coordinate transform.
    :returns: List of (layer_id, merged_geometry) tuples.
    :complexity: O(n) where n = size of SVG document
    """

