svg-ultralight 0.64.0__py3-none-any.whl

svg_ultralight/strings/svg_strings.py

@@ -0,0 +1,106 @@
+"""Explicit string formatting calls for arguments that aren't floats or strings.
+
+:author: Shay Hill
+:created: 10/30/2020
+
+The `string_conversion` module will format floats or strings. Some other formatters can
+make things easier.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from svg_ultralight.string_conversion import format_number
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+_MAX_8BIT = 255
+_BIG_INT = 2**32 - 1
+
+
+def _float_to_8bit_int(clipped_float: float) -> int:
+    """Convert a float between 0 and 255 to an int between 0 and 255.
+
+    :param float_: a float in the closed interval [0 .. 255]. Values outside this
+        range will be clipped.
+    :return: an int in the closed interval [0 .. 255]
+
+    Convert color floats [0 .. 255] to ints [0 .. 255] without rounding, which "short
+    changes" 0 and 255.
+    """
+    clipped_float = min(_MAX_8BIT, max(0, clipped_float))
+    if clipped_float % 1:
+        high_int = int(clipped_float / _MAX_8BIT * _BIG_INT)
+        return high_int >> 24
+    return int(clipped_float)
+
+
+def svg_ints(floats: Iterable[float]) -> str:
+    """Space-delimited ints.
+
+    :param floats: and number of floats
+    :return: each float rounded to an int, space delimited
+    """
+    return " ".join(str(round(x)) for x in floats)
+
+
+def svg_floats(floats: Iterable[float]) -> str:
+    """Space-delimited floats.
+
+    :param floats: and number of floats
+    :return: each float formatted, space delimited
+
+    matrix strings, svg viewBox, and other attributes need space-delimited floats.
+    """
+    return " ".join(format_number(x) for x in floats)
+
+
+def svg_float_tuples(tuples: Iterable[tuple[float, float]]) -> str:
+    """Space-delimited tuples.
+
+    :param tuples: [(a, b), (c, d)]
+    :return: "a,b c,d"
+    """
+    tuple_strings = [",".join(format_number(n) for n in t) for t in tuples]
+    return " ".join(tuple_strings)
+
+
+# ===================================================================================
+#   Specific string formats
+# ===================================================================================
+
+
+def svg_color_tuple(rgb_floats: tuple[float, float, float]) -> str:
+    """Turn an rgb tuple (0-255, 0-255, 0-255) into an svg color definition.
+
+    :param rgb_floats: (0-255, 0-255, 0-255)
+    :return: "rgb(128,128,128)"
+    """
+    r, g, b = map(_float_to_8bit_int, rgb_floats)
+    return f"rgb({r},{g},{b})"
+
+
+def svg_matrix(floats: Iterable[float]) -> str:
+    """Create a matrix string for the svg transform attribute.
+
+    a: scale x
+    b: skew y
+    c: skew x
+    d: scale y
+    e: translate x
+    f: translate y
+    :return: "matrix(a,b,c,d,e,f)"
+
+    The matrix() function defines a transformation in the 2D space. The six values
+    represent a 3x3 matrix that is used to perform linear transformations such as
+    translation, scaling, rotation, and skewing on SVG elements.
+    """
+    try:
+        a, b, c, d, e, f = floats
+    except ValueError as e:
+        msg = "svg_matrix() needs exactly 6 floats."
+        raise ValueError(msg) from e
+    return f"matrix({svg_floats((a, b, c, d, e, f))})"

svg_ultralight/transformations.py

@@ -0,0 +1,152 @@
+"""Math and conversion for svg-style transformation matrices.
+
+:author: Shay Hill
+:created: 2024-05-05
+"""
+
+from __future__ import annotations
+
+import numbers
+import re
+from contextlib import suppress
+from typing import TYPE_CHECKING, TypeAlias, cast
+
+from svg_ultralight.strings import svg_matrix
+
+if TYPE_CHECKING:
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+
+RE_MATRIX = re.compile(r"matrix\(([^)]+)\)")
+
+_Matrix: TypeAlias = tuple[float, float, float, float, float, float]
+
+
+def mat_dot(mat1: _Matrix, mat2: _Matrix) -> _Matrix:
+    """Matrix multiplication for svg-style matrices.
+
+    :param mat1: transformation matrix (sx, 0, 0, sy, tx, ty)
+    :param mat2: transformation matrix (sx, 0, 0, sy, tx, ty)
+
+    Svg uses an unusual matrix format. For 3x3 transformation matrix
+
+    [[00, 01, 02],
+     [10, 11, 12],
+     [20, 21, 22]]
+
+    The svg matrix is
+    (00, 10, 01, 11, 02, 12)
+
+    Values 10 and 01 are only used for skewing, which is not supported by a bounding
+    box. Values 00 and 11 will always be identical for symmetric scaling, which is
+    the only scaling implemented in my BoundingBox classes. However, all six values
+    are implemented in case this function is used in other contexts.
+    """
+    aa = sum(mat1[x] * mat2[y] for x, y in ((0, 0), (2, 1)))
+    bb = sum(mat1[x] * mat2[y] for x, y in ((1, 0), (3, 1)))
+    cc = sum(mat1[x] * mat2[y] for x, y in ((0, 2), (2, 3)))
+    dd = sum(mat1[x] * mat2[y] for x, y in ((1, 2), (3, 3)))
+    ee = sum(mat1[x] * mat2[y] for x, y in ((0, 4), (2, 5))) + mat1[4]
+    ff = sum(mat1[x] * mat2[y] for x, y in ((1, 4), (3, 5))) + mat1[5]
+    return (aa, bb, cc, dd, ee, ff)
+
+
+def mat_apply(matrix: _Matrix, point: tuple[float, float]) -> tuple[float, float]:
+    """Apply an svg-style transformation matrix to a point.
+
+    :param mat1: transformation matrix (a, b, c, d, e, f) describing a 3x3 matrix
+        with an implied third row of (0, 0, 1)
+        [[a, c, e], [b, d, f], [0, 0, 1]]
+    :param mat2: point (x, y)
+    """
+    a, b, c, d, e, f = matrix
+    x, y = point
+    result_x = a * x + c * y + e
+    result_y = b * x + d * y + f
+    return result_x, result_y
+
+
+def mat_invert(tmat: _Matrix) -> _Matrix:
+    """Invert a 2D transformation matrix in svg format."""
+    a, b, c, d, e, f = tmat
+    det = a * d - b * c
+    if det == 0:
+        msg = "Matrix is not invertible"
+        raise ValueError(msg)
+    return (
+        d / det,
+        -b / det,
+        -c / det,
+        a / det,
+        (c * f - d * e) / det,
+        (b * e - a * f) / det,
+    )
+
+
+def get_transform_matrix(elem: EtreeElement) -> _Matrix:
+    """Get the transformation matrix from an svg element.
+
+    :param element: svg element
+    """
+    transform = elem.attrib.get("transform")
+    if not transform:
+        return (1, 0, 0, 1, 0, 0)
+    values_str = ""
+    with suppress(AttributeError):
+        values_str = cast("re.Match[str]", RE_MATRIX.match(transform)).group(1)
+    with suppress(ValueError):
+        aa, bb, cc, dd, ee, ff = (float(val) for val in values_str.split())
+        return (aa, bb, cc, dd, ee, ff)
+    msg = f"Could not parse transformation matrix from {transform}"
+    raise ValueError(msg)
+
+
+def new_transformation_matrix(
+    transformation: _Matrix | None = None,
+    *,
+    scale: tuple[float, float] | float | None = None,
+    dx: float | None = None,
+    dy: float | None = None,
+) -> _Matrix:
+    """Create a new transformation matrix.
+
+    This takes the standard arguments in the BoundingBox classes and returns an
+    svg-style transformation matrix.
+    """
+    transformation = transformation or (1, 0, 0, 1, 0, 0)
+
+    if isinstance(scale, (float, int, numbers.Real)):
+        scale_x, scale_y = (scale, scale)
+    elif scale is None:
+        scale_x, scale_y = (1, 1)
+    else:
+        scale_x, scale_y = scale
+
+    dx = dx or 0
+    dy = dy or 0
+    return mat_dot((float(scale_x), 0, 0, float(scale_y), dx, dy), transformation)
+
+
+def transform_element(
+    elem: EtreeElement, matrix: _Matrix, *, reverse: bool = False
+) -> EtreeElement:
+    """Apply a transformation matrix to an svg element.
+
+    :param elem: svg element
+    :par m matrix: transformation matrix
+
+    :param reverse: If you have a transformation matrix, A, and wish to apply an
+    additional transform, B, the result is B @ A. This is how an element can be
+    cumulatively transformed in svg.
+
+    If the element is transformed by A and is a part of a GROUP transformed by B,
+    then the result is the reverse: A @ B.
+    """
+    current = get_transform_matrix(elem)
+    if reverse:
+        elem.attrib["transform"] = svg_matrix(mat_dot(current, matrix))
+    else:
+        elem.attrib["transform"] = svg_matrix(mat_dot(matrix, current))
+    return elem

svg_ultralight/unit_conversion.py

@@ -0,0 +1,247 @@
+"""Convert between absolute units.
+
+Model everything in user units, then use "width" and "height" in the svg root element
+to scale these units to the desired size.
+
+I borrowed test values and and conventions from Inkscape's `inkek.units.py`.
+
+:author: Shay Hill
+:created: 2023-02-12
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import re
+
+from svg_ultralight.string_conversion import format_number
+
+# units per inch
+_UPI = 96
+
+# units per centimeter
+_UPC = 96 / 2.54
+
+
+class Unit(enum.Enum):
+    """SVG Units of measurement.
+
+    Value is (unit conversion, unit specifier)
+
+    The unit specifier string are how various units are identified in SVG.
+    e.g., "44in"
+    """
+
+    IN = "in", _UPI  # inches
+    PT = "pt", 4 / 3  # points
+    PX = "px", 1  # pixels
+    MM = "mm", _UPC / 10  # millimeters
+    CM = "cm", _UPC  # centimeters
+    M = "m", _UPC * 100  # meters
+    KM = "km", _UPC * 100000  # kilometers
+    Q = "Q", _UPC / 40  # quarter-millimeters
+    PC = "pc", _UPI / 6  # picas
+    YD = "yd", _UPI * 36  # yards
+    FT = "ft", _UPI * 12  # feet
+    USER = "", 1  # "user units" without a unit specifier
+
+
+# the arguments this module will attempt to interpret as a string with a unit specifier
+MeasurementArg = (
+    float
+    | str
+    | tuple[str, str]
+    | tuple[float, str]
+    | tuple[str, Unit]
+    | tuple[float, Unit]
+    | Unit
+)
+
+_UNIT_SPECIFIER2UNIT = {x.value[0]: x for x in Unit}
+
+_UNIT_SPECIFIERS = [x.value[0] for x in Unit]
+_NUMBER = r"([-+]?[0-9]+(\.[0-9]*)?|[-+]?\.[0-9]+)([eE][-+]?[0-9]+)?"
+_UNIT_RE = re.compile(rf"(?P<unit>{'|'.join(_UNIT_SPECIFIERS)})")
+_NUMBER_RE = re.compile(rf"(?P<number>{_NUMBER})")
+_NUMBER_AND_UNIT = re.compile(rf"^{_NUMBER_RE.pattern}{_UNIT_RE.pattern}$")
+
+
+def _parse_unit(measurement_arg: MeasurementArg) -> tuple[float, Unit]:
+    """Split the value and unit from a string.
+
+    :param measurement_arg: The value to parse (e.g. "55.32px")
+    :return: A tuple of the value and Unit
+    :raise ValueError: If the value cannot be parsed
+
+    Take a value such as "55.32px" and return (55.32, Unit.PX). Preserves non-units,
+    so "55.32" returns (55.32, Unit.USER) These are actually pixels, but you don't
+    want "px" in your viewbox calls. It is best to work in non-specified "user units"
+    and then set the svg width and height to an specified unit.
+
+    Can handle a lot of args:
+
+    | arg type      | example            | result             |
+    | ------------- | ------------------ | ------------------ |
+    | float         | 55.32              | (55.32, Unit.USER) |
+    | str           | "55.32px"          | (55.32, Unit.PX)   |
+    | str           | "55.32"            | (55.32, Unit.USER) |
+    | str           | "px"               | (0.0, Unit.PX)     |
+    | (str, str)    | ("55.32", "px")    | (55.32, Unit.PX)   |
+    | (float, str)  | (55.32, "px")      | (55.32, Unit.PX)   |
+    | (str, Unit)   | ("55.32", Unit.PX) | (55.32, Unit.PX)   |
+    | (float, Unit) | (55.32, Unit.PX)   | (55.32, Unit.PX)   |
+    | Unit          | Unit.PX            | (0.0, Unit.PX)     |
+    | Measurement   | Measurement("3in") | (3.0, Unit.IN)     |
+
+    """
+    failure_msg = f"Cannot parse value and unit from {measurement_arg}"
+    unit: str | Unit
+    try:
+        if isinstance(measurement_arg, tuple):
+            number, unit = float(measurement_arg[0]), measurement_arg[1]
+            if isinstance(unit, Unit):
+                return number, unit
+            return number, _UNIT_SPECIFIER2UNIT[unit]
+
+        if isinstance(measurement_arg, (int, float)):
+            return _parse_unit((measurement_arg, ""))
+
+        if isinstance(measurement_arg, Unit):
+            return _parse_unit((0, measurement_arg))
+
+        if number_unit := _NUMBER_AND_UNIT.match(str(measurement_arg)):
+            return _parse_unit((number_unit["number"], number_unit["unit"]))
+
+        if unit_only := _UNIT_RE.match(str(measurement_arg)):
+            return _parse_unit((0, unit_only["unit"]))
+
+    except (ValueError, KeyError) as e:
+        raise ValueError(failure_msg) from e
+
+    raise ValueError(failure_msg)
+
+
+@dataclasses.dataclass
+class Measurement:
+    """Measurement with unit of measurement.
+
+    Converts to and stores the value in user units. Also retains the input units so
+    you can update the value then convert back.
+    """
+
+    value: float
+    native_unit: Unit
+
+    def __init__(self, measurement_arg: MeasurementArg) -> None:
+        """Create a measurement from a string or float.
+
+        :param measurement_arg: a float (user units) or string with unit specifier.
+        :raises ValueError: if the input units cannot be identified
+        """
+        value, self.native_unit = _parse_unit(measurement_arg)
+        self.value = value * self.native_unit.value[1]
+
+    def get_value(self, unit: Unit | None = None) -> float:
+        """Get the measurement in the specified unit.
+
+        :param unit: optional unit to convert to
+        :return: value in specified units
+
+        It's best to do all math with self.value, but this is here for conversion
+        with less precision loss.
+        """
+        if unit is None:
+            return self.value
+        if isinstance(unit, str):
+            unit = _UNIT_SPECIFIER2UNIT[unit]
+        return self.value / unit.value[1]
+
+    def get_tuple(self, unit: Unit | None = None) -> tuple[float, Unit]:
+        """Get the measurement as a tuple of value and unit.
+
+        :param unit: optional unit to convert to
+        :return: value in specified as a tuple
+        """
+        return self.get_value(unit), unit or Unit.USER
+
+    def get_str(self, unit: Unit | None = None) -> str:
+        """Get the measurement in the specified unit as a string.
+
+        :param optional unit: the unit to convert to
+        :return: the measurement in the specified unit as a string
+
+        The input arguments for groups of measurements are less flexible than for
+        single measurements. Single measurements can be defined by something like
+        `(1, "in")`, but groups can be passed as single or tuples, so there is no way
+        to differentiate between (1, "in") and "1in" or (1, "in") as ("1", "0in").
+        That is a limitation, but doint it that way preserved the flexibility (and
+        backwards compatibility) of being able to define padding as "1in" everywhere
+        or (1, 2, 3, 4) for top, right, bottom, left.
+
+        The string from this method is different from the string in the `get_svg`
+        method, because this string will print a full printable precision, while the
+        svg string will print a reduced precision. So this string can be used to as
+        an argument to pad or print_width without losing precision.
+        """
+        value, unit = self.get_tuple(unit)
+        return f"{value}{unit.value[0]}"
+
+    def get_svg(self, unit: Unit | None = None) -> str:
+        """Get the measurement in the specified unit as it would be written in svg.
+
+        :param optional unit: the unit to convert to
+        :return: the measurement in the specified unit, always as a string
+
+        Rounds values to 6 decimal places as recommended by svg guidance online.
+        Higher precision just changes file size without imroving quality.
+        """
+        _, unit = self.get_tuple(unit)
+        value_as_str = format_number(self.get_value(unit))
+        return f"{value_as_str}{unit.value[0]}"
+
+    def __add__(self, other: Measurement) -> Measurement:
+        """Add two measurements.
+
+        :param other: the other measurement
+        :return: the sum of the two measurements in self native unit
+        """
+        result = Measurement(self.native_unit)
+        result.value = self.value + other.value
+        return result
+
+    def __sub__(self, other: Measurement) -> Measurement:
+        """Subtract two measurements.
+
+        :param other: the other measurement
+        :return: the difference of the two measurements in self native unit
+        """
+        result = Measurement(self.native_unit)
+        result.value = self.value - other.value
+        return result
+
+    def __mul__(self, scalar: float) -> Measurement:
+        """Multiply a measurement by a scalar.
+
+        :param scalar: the scalar to multiply by
+        :return: the measurement multiplied by the scalar in self native unit
+        """
+        result = Measurement(self.native_unit)
+        result.value = self.value * scalar
+        return result
+
+    def __rmul__(self, scalar: float) -> Measurement:
+        """Multiply a measurement by a scalar.
+
+        :param scalar: the scalar to multiply by
+        :return: the measurement multiplied by the scalar in self native unit
+        """
+        return self.__mul__(scalar)
+
+    def __truediv__(self, scalar: float) -> Measurement:
+        """Divide a measurement by a scalar.
+
+        :param scalar: the scalar to divide by
+        :return: the measurement divided by the scalar in self native unit
+        """
+        return self.__mul__(1.0 / scalar)