svg-ultralight 0.27.0__py3-none-any.whl → 0.29.0__py3-none-any.whl

svg_ultralight/__init__.py

@@ -10,6 +10,7 @@ from svg_ultralight.bounding_boxes.bound_helpers import (
     new_element_union,
 )
 from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+from svg_ultralight.bounding_boxes.type_bound_confederation import BoundConfederation
 from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
 from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
 from svg_ultralight.bounding_boxes.type_padded_text import PaddedText
@@ -37,8 +38,10 @@ from svg_ultralight.string_conversion import (
     format_numbers,
     format_numbers_in_string,
 )
+from svg_ultralight.transformations import transform_element
 
 __all__ = [
+    "BoundConfederation",
     "BoundElement",
     "BoundingBox",
     "NSMAP",
@@ -59,6 +62,7 @@ __all__ = [
     "new_svg_root",
     "new_svg_root_around_bounds",
     "pad_text",
+    "transform_element",
     "update_element",
     "write_pdf",
     "write_pdf_from_svg",

svg_ultralight/animate.py

@@ -34,7 +34,7 @@ def write_gif(
     :param loop: how many times to loop gif. 0 -> forever
     :effects: write file to gif
     """
-    images = [Image.open(x) for x in pngs]
-    images[0].save(
+    images = [Image.open(x) for x in pngs]  # type: ignore
+    images[0].save(  # type: ignore
         gif, save_all=True, append_images=images[1:], duration=duration, loop=loop
     )

svg_ultralight/bounding_boxes/bound_helpers.py

@@ -18,6 +18,8 @@ from svg_ultralight.constructors import new_element
 if TYPE_CHECKING:
     from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
 
+_Matrix = tuple[float, float, float, float, float, float]
+
 
 def new_element_union(
     *elems: EtreeElement | SupportsBounds, **attributes: float | str

svg_ultralight/bounding_boxes/supports_bounds.py

@@ -16,13 +16,19 @@ Attributes:
 :created: 2023-02-15
 """
 
+from __future__ import annotations
+
 from typing import Protocol
 
+_Matrix = tuple[float, float, float, float, float, float]
+
 
 class SupportsBounds(Protocol):
     """Protocol for objects that can have bounds.
 
     Attributes:
+        transformation (_Matrix): An svg-style transformation matrix.
+        transform (method): Apply a transformation to the object.
         x (float): The minimum x coordinate.
         x2 (float): The maximum x coordinate.
         cx (float): The center x coordinate.
@@ -39,6 +45,22 @@ class SupportsBounds(Protocol):
     set width and height.
     """
 
+    @property
+    def transformation(self) -> _Matrix:
+        """Return an svg-style transformation matrix."""
+        ...
+
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Apply a transformation to the object."""
+        ...
+
     @property
     def x(self) -> float:
         """Return minimum x coordinate."""

svg_ultralight/bounding_boxes/type_bound_confederation.py

@@ -0,0 +1,71 @@
+"""A class to hold a list of bound elements and transform them together.
+
+:author: Shay Hill
+:created: 2024-05-05
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING
+
+from lxml.etree import _Element as EtreeElement  # type: ignore
+
+from svg_ultralight.bounding_boxes.bound_helpers import new_bbox_union
+from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+from svg_ultralight.bounding_boxes.type_bounding_box import HasBoundingBox
+from svg_ultralight.transformations import new_transformation_matrix, transform_element
+
+if TYPE_CHECKING:
+    from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+
+_Matrix = tuple[float, float, float, float, float, float]
+
+
+@dataclasses.dataclass
+class BoundConfederation(HasBoundingBox):
+    """A class to hold a list of bound elements and transform them together.
+
+    This will transform the individual elements in place.
+    """
+
+    blems: list[SupportsBounds | EtreeElement] = dataclasses.field(init=False)
+    bbox: BoundingBox = dataclasses.field(init=False)
+
+    def __init__(self, *blems: SupportsBounds | EtreeElement) -> None:
+        """Initialize the bound confederation.
+
+        :param blems: bound elements to be transformed together
+        """
+        self.blems = list(blems)
+        self.bbox = new_bbox_union(*self.blems)
+
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Transform each bound element in self.blems.
+
+        :param transformation: 2D transformation matrix
+        :param scale: optional scale factor
+        :param dx: optional x translation
+        :param dy: optional y translation
+
+        Keep track of all compounding transformations in order to have a value for
+        self.scale (required for membersh and to provide access to cumulative
+        transforms should this be useful for any reason. This means all
+        transformations must be applied to two bounding boxes: a persistant bbox to
+        keep track of the scale property and a temporary bbox to isolate each
+        transformation.
+        """
+        tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
+        self.bbox.transform(tmat)
+        for blem in self.blems:
+            if isinstance(blem, EtreeElement):
+                _ = transform_element(blem, tmat)
+            else:
+                blem.transform(tmat)

svg_ultralight/bounding_boxes/type_bound_element.py

@@ -15,15 +15,18 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+from svg_ultralight.bounding_boxes.type_bounding_box import HasBoundingBox
+from svg_ultralight.transformations import new_transformation_matrix, transform_element
 
 if TYPE_CHECKING:
     from lxml.etree import _Element as EtreeElement  # type: ignore
 
     from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
 
+_Matrix = tuple[float, float, float, float, float, float]
 
-class BoundElement(SupportsBounds):
+
+class BoundElement(HasBoundingBox):
     """An element with a bounding box.
 
     Updates the element when x, y, x2, y2, width, or height are set.
@@ -43,154 +46,21 @@ class BoundElement(SupportsBounds):
     def _update_elem(self):
         self.elem.attrib["transform"] = self.bbox.transform_string
 
-    @property
-    def x(self) -> float:
-        """The x coordinate of the left edge of the bounding box.
-
-        :return: the x coordinate of the left edge of the bounding box
-        """
-        return self.bbox.x
-
-    @x.setter
-    def x(self, value: float):
-        """Set the x coordinate of the left edge of the bounding box.
-
-        :param value: the new x coordinate of the left edge of the bounding box
-        """
-        self.bbox.x = value
-        self._update_elem()
-
-    @property
-    def x2(self) -> float:
-        """The x coordinate of the right edge of the bounding box.
-
-        :return: the x coordinate of the right edge of the bounding box
-        """
-        return self.bbox.x2
-
-    @x2.setter
-    def x2(self, value: float):
-        """Set the x coordinate of the right edge of the bounding box.
-
-        :param value: the new x coordinate of the right edge of the bounding box
-        """
-        self.bbox.x2 = value
-        self._update_elem()
-
-    @property
-    def cx(self) -> float:
-        """The x coordinate of the center of the bounding box.
-
-        :return: the x coordinate of the center of the bounding box
-        """
-        return self.bbox.cx
-
-    @cx.setter
-    def cx(self, value: float):
-        """Set the x coordinate of the center of the bounding box.
-
-        :param value: the new x coordinate of the center of the bounding box
-        """
-        self.bbox.cx = value
-        self._update_elem()
-
-    @property
-    def y(self) -> float:
-        """The y coordinate of the top edge of the bounding box.
-
-        :return: the y coordinate of the top edge of the bounding box
-        """
-        return self.bbox.y
-
-    @y.setter
-    def y(self, value: float):
-        """Set the y coordinate of the top edge of the bounding box.
-
-        :param value: the new y coordinate of the top edge of the bounding box
-        """
-        self.bbox.y = value
-        self._update_elem()
-
-    @property
-    def y2(self) -> float:
-        """The y coordinate of the bottom edge of the bounding box.
-
-        :return: the y coordinate of the bottom edge of the bounding box
-        """
-        return self.bbox.y2
-
-    @y2.setter
-    def y2(self, value: float):
-        """Set the y coordinate of the bottom edge of the bounding box.
-
-        :param value: the new y coordinate of the bottom edge of the bounding box
-        """
-        self.bbox.y2 = value
-        self._update_elem()
-
-    @property
-    def cy(self) -> float:
-        """The y coordinate of the center of the bounding box.
-
-        :return: the y coordinate of the center of the bounding box
-        """
-        return self.bbox.cy
-
-    @cy.setter
-    def cy(self, value: float):
-        """Set the y coordinate of the center of the bounding box.
-
-        :param value: the new y coordinate of the center of the bounding box
-        """
-        self.bbox.cy = value
-        self._update_elem()
-
-    @property
-    def width(self) -> float:
-        """The width of the bounding box.
-
-        :return: the width of the bounding box
-        """
-        return self.bbox.width
-
-    @width.setter
-    def width(self, value: float):
-        """Set the width of the bounding box.
-
-        :param value: the new width of the bounding box
-        """
-        self.bbox.width = value
-        self._update_elem()
-
-    @property
-    def height(self) -> float:
-        """The height of the bounding box.
-
-        :return: the height of the bounding box
-        """
-        return self.bbox.height
-
-    @height.setter
-    def height(self, value: float):
-        """Set the height of the bounding box.
-
-        :param value: the new height of the bounding box
-        """
-        self.bbox.height = value
-        self._update_elem()
-
-    @property
-    def scale(self) -> float:
-        """The scale of the bounding box.
-
-        :return: the scale of the bounding box
-        """
-        return self.bbox.scale
-
-    @scale.setter
-    def scale(self, value: float):
-        """Set the scale of the bounding box.
-
-        :param value: the scale of the bounding box
-        """
-        self.bbox.scale = value
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Transform the element and bounding box.
+
+        :param transformation: a 6-tuple transformation matrix
+        :param scale: a scaling factor
+        :param dx: the x translation
+        :param dy: the y translation
+        """
+        tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
+        self.bbox.transform(tmat)
+        _ = transform_element(self.elem, tmat)

svg_ultralight/bounding_boxes/type_bounding_box.py

@@ -6,13 +6,16 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+import dataclasses
 
 from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
 from svg_ultralight.string_conversion import format_number
+from svg_ultralight.transformations import mat_apply, mat_dot, new_transformation_matrix
 
+_Matrix = tuple[float, float, float, float, float, float]
 
-@dataclass
+
+@dataclasses.dataclass
 class BoundingBox(SupportsBounds):
     """Mutable bounding box object for svg_ultralight.
 
@@ -21,14 +24,12 @@ class BoundingBox(SupportsBounds):
     :param width: width of the bounding box
     :param height: height of the bounding box
 
-    The below optional parameters, in addition to the required parameters, capture
-    the entire state of a BoundingBox instance.  They could be used to make a copy or
+    The below optional parameter, in addition to the required parameters, captures
+    the entire state of a BoundingBox instance. It could be used to make a copy or
     to initialize a transformed box with the same transform_string as another box.
-    Under most circumstances, they will not be used.
+    Under most circumstances, it will not be used.
 
-    :param scale: scale of the bounding box
-    :param translation_x: x translation of the bounding box
-    :param translation_y: y translation of the bounding box
+    :param _transformation: transformation matrix
 
     Functions that return a bounding box will return a BoundingBox instance. This
     instance can be transformed (uniform scale and translate only). Transformations
@@ -37,10 +38,10 @@ class BoundingBox(SupportsBounds):
     Define the bbox with x=, y=, width=, height=
 
     Transform the BoundingBox by setting these variables. Each time you set x, cx,
-    x2, y, cy, y2, width, or height, private transformation values (_scale,
-    _transform_x, and _transform_y) will be updated.
+    x2, y, cy, y2, width, or height, private transformation value _transformation
+    will be updated.
 
-    The ultimate transformation can be accessed through ``.transformation_string``.
+    The ultimate transformation can be accessed through ``.transform_string``.
     So the workflow will look like :
 
         1. Get the bounding box of an svg element
@@ -78,13 +79,44 @@ class BoundingBox(SupportsBounds):
     _y: float
     _width: float
     _height: float
-    _scale: float = 1.0
-    _translation_x: float = 0.0
-    _translation_y: float = 0.0
+    _transformation: _Matrix = (1, 0, 0, 1, 0, 0)
+
+    @property
+    def transformation(self) -> _Matrix:
+        """Return transformation matrix.
+
+        :return: transformation matrix
+        """
+        return self._transformation
+
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Transform the bounding box by updating the transformation attribute.
+
+        :param transformation: 2D transformation matrix
+        :param scale: scale factor
+        :param dx: x translation
+        :param dy: y translation
+
+        All parameters are optional. Scale, dx, and dy are optional and applied after
+        the transformation matrix if both are given. This shouldn't be necessary in
+        most cases, the four parameters are there to allow transformation arguments
+        to be passed in a variety of ways. Scale, dx, and dy are the sensible values
+        to pass "by hand". The transformation matrix is the sensible argument to pass
+        when applying a transformation from another bounding box instance.
+        """
+        tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
+        self._transformation = mat_dot(tmat, self.transformation)
 
     @property
     def scale(self) -> float:
-        """Read-only scale.
+        """Get scale of the bounding box.
 
         :return: uniform scale of the bounding box
 
@@ -95,7 +127,7 @@ class BoundingBox(SupportsBounds):
         width*scale, height => height*scale, scale => scale*scale. This matches how
         scale works in almost every other context.
         """
-        return self._scale
+        return self.transformation[0]
 
     @scale.setter
     def scale(self, value: float) -> None:
@@ -110,7 +142,7 @@ class BoundingBox(SupportsBounds):
         `scale = 2` -> ignore whatever scale was previously defined and set scale to 2
         `scale *= 2` -> make it twice as big as it was.
         """
-        self._scale = value
+        self.transform(scale=value / self.scale)
 
     @property
     def x(self) -> float:
@@ -118,15 +150,15 @@ class BoundingBox(SupportsBounds):
 
         :return: internal _x value transformed by scale and translation
         """
-        return (self._translation_x + self._x) * self._scale
+        return mat_apply(self.transformation, (self._x, 0))[0]
 
     @x.setter
     def x(self, value: float) -> None:
-        """Update transform values (do not alter self._x).
+        """Update transformation values (do not alter self._x).
 
         :param value: new x value after transformation
         """
-        self._add_transform(1, value - self.x, 0)
+        self.transform(dx=value - self.x)
 
     @property
     def cx(self) -> float:
@@ -142,7 +174,7 @@ class BoundingBox(SupportsBounds):
 
         :param value: new center x value after transformation
         """
-        self._add_transform(1, value - self.cx, 0)
+        self.x += value - self.cx
 
     @property
     def x2(self) -> float:
@@ -154,11 +186,11 @@ class BoundingBox(SupportsBounds):
 
     @x2.setter
     def x2(self, value: float) -> None:
-        """Update transform values (do not alter self._x2).
+        """Update transformation values (do not alter self._x2).
 
         :param value: new x2 value after transformation
         """
-        self._add_transform(1, value - self.x2, 0)
+        self.x += value - self.x2
 
     @property
     def y(self) -> float:
@@ -166,15 +198,15 @@ class BoundingBox(SupportsBounds):
 
         :return: internal _y value transformed by scale and translation
         """
-        return (self._translation_y + self._y) * self._scale
+        return mat_apply(self.transformation, (0, self._y))[1]
 
     @y.setter
     def y(self, value: float) -> None:
-        """Update transform values (do not alter self._y).
+        """Update transformation values (do not alter self._y).
 
         :param value: new y value after transformation
         """
-        self._add_transform(1, 0, value - self.y)
+        self.transform(dy=value - self.y)
 
     @property
     def cy(self) -> float:
@@ -190,7 +222,7 @@ class BoundingBox(SupportsBounds):
 
         :param value: new center y value after transformation
         """
-        self._add_transform(1, 0, value - self.cy)
+        self.y += value - self.cy
 
     @property
     def y2(self) -> float:
@@ -202,11 +234,11 @@ class BoundingBox(SupportsBounds):
 
     @y2.setter
     def y2(self, value: float) -> None:
-        """Update transform values (do not alter self._y).
+        """Update transformation values (do not alter self._y).
 
         :param value: new y2 value after transformation
         """
-        self.y = value - self.height
+        self.y += value - self.y2
 
     @property
     def width(self) -> float:
@@ -214,11 +246,11 @@ class BoundingBox(SupportsBounds):
 
         :return: internal _width value transformed by scale
         """
-        return self._width * self._scale
+        return self._width * self.scale
 
     @width.setter
     def width(self, value: float) -> None:
-        """Update transform values, Do not alter self._width.
+        """Update transformation values, Do not alter self._width.
 
         :param value: new width value after transformation
 
@@ -227,7 +259,7 @@ class BoundingBox(SupportsBounds):
         """
         current_x = self.x
         current_y = self.y
-        self._scale *= value / self.width
+        self.scale *= value / self.width
         self.x = current_x
         self.y = current_y
 
@@ -237,11 +269,11 @@ class BoundingBox(SupportsBounds):
 
         :return: internal _height value transformed by scale
         """
-        return self._height * self._scale
+        return self._height * self.scale
 
     @height.setter
     def height(self, value: float) -> None:
-        """Update transform values, Do not alter self._height.
+        """Update transformation values, Do not alter self._height.
 
         :param value: new height value after transformation
 
@@ -250,33 +282,16 @@ class BoundingBox(SupportsBounds):
         """
         self.width = value * self.width / self.height
 
-    def _add_transform(self, scale: float, translation_x: float, translation_y: float):
-        """Transform the bounding box by updating the transformation attributes.
-
-        :param scale: scale factor
-        :param translation_x: x translation
-        :param translation_y: y translation
-
-        Transformation attributes are _translation_x, _translation_y, and _scale
-        """
-        self._translation_x += translation_x / self._scale
-        self._translation_y += translation_y / self._scale
-        self._scale *= scale
-
     @property
     def transform_string(self) -> str:
         """Transformation property string value for svg element.
 
-        :return: string value for an svg transform attribute.
+        :return: string value for an svg transformation attribute.
 
         Use with
         ``update_element(elem, transform=bbox.transform_string)``
         """
-        scale, trans_x, trans_y = (
-            format_number(x)
-            for x in (self._scale, self._translation_x, self._translation_y)
-        )
-        return f"scale({scale}) translate({trans_x} {trans_y})"
+        return f"matrix({' '.join(map(format_number, self.transformation))})"
 
     def merge(self, *others: BoundingBox) -> BoundingBox:
         """Create a bounding box around all other bounding boxes.
@@ -306,3 +321,181 @@ class BoundingBox(SupportsBounds):
         min_y = min(x.y for x in bboxes)
         max_y = max(x.y + x.height for x in bboxes)
         return BoundingBox(min_x, min_y, max_x - min_x, max_y - min_y)
+
+
+class HasBoundingBox(SupportsBounds):
+    """A parent class for BoundElement and others that have a bbox attribute."""
+
+    def __init__(self, bbox: BoundingBox) -> None:
+        """Initialize the HasBoundingBox instance."""
+        self.bbox = bbox
+
+    @property
+    def transformation(self) -> _Matrix:
+        """The transformation matrix of the bounding box."""
+        return self.bbox.transformation
+
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Transform the element and bounding box.
+
+        :param transformation: a 6-tuple transformation matrix
+        :param scale: a scaling factor
+        :param dx: the x translation
+        :param dy: the y translation
+        """
+        self.bbox.transform(transformation, scale=scale, dx=dx, dy=dy)
+
+    @property
+    def scale(self) -> float:
+        """The scale of the bounding box.
+
+        :return: the scale of the bounding box
+        """
+        return self.transformation[0]
+
+    @scale.setter
+    def scale(self, value: float):
+        """Set the scale of the bounding box.
+
+        :param value: the scale of the bounding box
+        """
+        self.transform(scale=value / self.scale)
+
+    @property
+    def x(self) -> float:
+        """The x coordinate of the left edge of the bounding box.
+
+        :return: the x coordinate of the left edge of the bounding box
+        """
+        return self.bbox.x
+
+    @x.setter
+    def x(self, value: float):
+        """Set the x coordinate of the left edge of the bounding box.
+
+        :param value: the new x coordinate of the left edge of the bounding box
+        """
+        self.transform(dx=value - self.x)
+
+    @property
+    def x2(self) -> float:
+        """The x coordinate of the right edge of the bounding box.
+
+        :return: the x coordinate of the right edge of the bounding box
+        """
+        return self.bbox.x2
+
+    @x2.setter
+    def x2(self, value: float):
+        """Set the x coordinate of the right edge of the bounding box.
+
+        :param value: the new x coordinate of the right edge of the bounding box
+        """
+        self.x += value - self.x2
+
+    @property
+    def cx(self) -> float:
+        """The x coordinate of the center of the bounding box.
+
+        :return: the x coordinate of the center of the bounding box
+        """
+        return self.bbox.cx
+
+    @cx.setter
+    def cx(self, value: float):
+        """Set the x coordinate of the center of the bounding box.
+
+        :param value: the new x coordinate of the center of the bounding box
+        """
+        self.x += value - self.cx
+
+    @property
+    def y(self) -> float:
+        """The y coordinate of the top edge of the bounding box.
+
+        :return: the y coordinate of the top edge of the bounding box
+        """
+        return self.bbox.y
+
+    @y.setter
+    def y(self, value: float):
+        """Set the y coordinate of the top edge of the bounding box.
+
+        :param value: the new y coordinate of the top edge of the bounding box
+        """
+        self.transform(dy=value - self.y)
+
+    @property
+    def y2(self) -> float:
+        """The y coordinate of the bottom edge of the bounding box.
+
+        :return: the y coordinate of the bottom edge of the bounding box
+        """
+        return self.bbox.y2
+
+    @y2.setter
+    def y2(self, value: float):
+        """Set the y coordinate of the bottom edge of the bounding box.
+
+        :param value: the new y coordinate of the bottom edge of the bounding box
+        """
+        self.y += value - self.y2
+
+    @property
+    def cy(self) -> float:
+        """The y coordinate of the center of the bounding box.
+
+        :return: the y coordinate of the center of the bounding box
+        """
+        return self.bbox.cy
+
+    @cy.setter
+    def cy(self, value: float):
+        """Set the y coordinate of the center of the bounding box.
+
+        :param value: the new y coordinate of the center of the bounding box
+        """
+        self.y += value - self.cy
+
+    @property
+    def width(self) -> float:
+        """The width of the bounding box.
+
+        :return: the width of the bounding box
+        """
+        return self.bbox.width
+
+    @width.setter
+    def width(self, value: float):
+        """Set the width of the bounding box.
+
+        :param value: the new width of the bounding box
+        """
+        current_x = self.x
+        current_y = self.y
+        self.scale *= value / self.width
+        self.x = current_x
+        self.y = current_y
+
+    @property
+    def height(self) -> float:
+        """The height of the bounding box.
+
+        :return: the height of the bounding box
+        """
+        return self.bbox.height
+
+    @height.setter
+    def height(self, value: float):
+        """Set the height of the bounding box.
+
+        :param value: the new height of the bounding box
+        """
+        self.width *= value / self.height

svg_ultralight/bounding_boxes/type_padded_text.py

@@ -72,6 +72,8 @@ from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
 if TYPE_CHECKING:
     from lxml.etree import _Element as EtreeElement  # type: ignore
 
+_Matrix = tuple[float, float, float, float, float, float]
+
 
 class PaddedText(SupportsBounds):
     """A line of text with a bounding box and padding."""
@@ -116,11 +118,32 @@ class PaddedText(SupportsBounds):
             self.lmargin, self.capline, self.padded_width, self.padded_height
         )
 
-    def _update(self, attrib: str, value: float) -> None:
-        """Update bbox attribute and keep elem synced."""
-        setattr(self.bbox, attrib, value)
+    @property
+    def transformation(self) -> _Matrix:
+        """The transformation matrix of the bounding box."""
+        return self.bbox.transformation
+
+    def _update_elem(self):
         self.elem.attrib["transform"] = self.bbox.transform_string
 
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+    ):
+        """Transform the element and bounding box.
+
+        :param transformation: a 6-tuple transformation matrix
+        :param scale: a scaling factor
+        :param dx: the x translation
+        :param dy: the y translation
+        """
+        self.bbox.transform(transformation, scale=scale, dx=dx, dy=dy)
+        self._update_elem()
+
     @property
     def tpad(self) -> float:
         """The top padding of this line of text.
@@ -167,7 +190,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The left margin of this line of text.
         """
-        self._update("x", value + self.lpad)
+        self.transform(dx=value + self.lpad - self.bbox.x)
 
     @property
     def rmargin(self) -> float:
@@ -183,7 +206,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The right margin of this line of text.
         """
-        self._update("x2", value - self.rpad)
+        self.transform(dx=value - self.rpad - self.bbox.x2)
 
     @property
     def capline(self) -> float:
@@ -199,7 +222,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The top of this line of text.
         """
-        self._update("y", value + self.tpad)
+        self.transform(dy=value + self.tpad - self.bbox.y)
 
     @property
     def baseline(self) -> float:
@@ -215,7 +238,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The bottom of this line of text.
         """
-        self._update("y2", value - self.bpad)
+        self.transform(dy=value - self.bpad - self.bbox.y2)
 
     @property
     def padded_width(self) -> float:
@@ -239,8 +262,9 @@ class PaddedText(SupportsBounds):
         *and* y2) when scaling.
         """
         baseline = self.baseline
-        self._update("width", width - self.lpad - self.rpad)
+        self.bbox.width = width - self.lpad - self.rpad
         self.baseline = baseline
+        self._update_elem()
 
     @property
     def padded_height(self) -> float:

svg_ultralight/query.py

@@ -118,7 +118,8 @@ def map_ids_to_bounding_boxes(
 
     id2bbox: dict[str, BoundingBox] = {}
     for id_, *bounds in (x.split(",") for x in bb_strings):
-        id2bbox[id_] = BoundingBox(*(float(x) for x in bounds))
+        x, y, width, height = (float(x) for x in bounds)
+        id2bbox[id_] = BoundingBox(x, y, width, height)
     return id2bbox
 
 

svg_ultralight/transformations.py

@@ -0,0 +1,108 @@
+"""Math and conversion for svg-style transformation matrices.
+
+:author: Shay Hill
+:created: 2024-05-05
+"""
+
+from __future__ import annotations
+
+import re
+from contextlib import suppress
+from typing import TYPE_CHECKING, cast
+
+from svg_ultralight.string_conversion import format_number
+
+if TYPE_CHECKING:
+    from lxml.etree import _Element as EtreeElement  # type: ignore
+
+
+_RE_MATRIX = re.compile(r"matrix\(([^)]+)\)")
+
+_Matrix = 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(mat1: _Matrix, mat2: tuple[float, float]) -> tuple[float, float]:
+    """Apply an svg-style transformation matrix to a point.
+
+    :param mat1: transformation matrix (sx, 0, 0, sy, tx, ty)
+    :param mat2: point (x, y)
+    """
+    return mat1[0] * mat2[0] + mat1[4], mat1[3] * mat2[1] + mat1[5]
+
+
+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: 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)
+    scale = scale or 1
+    dx = dx or 0
+    dy = dy or 0
+    return mat_dot((scale, 0, 0, scale, dx, dy), transformation)
+
+
+def transform_element(elem: EtreeElement, matrix: _Matrix) -> EtreeElement:
+    """Apply a transformation matrix to an svg element.
+
+    :param elem: svg element
+    :param matrix: transformation matrix
+    """
+    current = get_transform_matrix(elem)
+    updated = map(format_number, mat_dot(matrix, current))
+    elem.attrib["transform"] = f"matrix({' '.join(updated)})"
+    return elem

{svg_ultralight-0.27.0.dist-info → svg_ultralight-0.29.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: svg-ultralight
-Version: 0.27.0
+Version: 0.29.0
 Summary: a sensible way to create svg files with Python
 Author-email: Shay Hill <shay_public@hotmail.com>
 License: MIT

{svg_ultralight-0.27.0.dist-info → svg_ultralight-0.29.0.dist-info}/RECORD

@@ -1,26 +1,28 @@
-svg_ultralight/__init__.py,sha256=Xyi-aBOAfVNoUg9rHXYVMELehe1kReEyQYL682AcQ1A,1877
-svg_ultralight/animate.py,sha256=JSrBm-59BcNXDF0cGgl4-C89eBunjevZnwZxIWt48TU,1112
+svg_ultralight/__init__.py,sha256=b0cB7zUGr7o3XaKatJeVyHpJLfF26aXsSYZJlVnvBFQ,2079
+svg_ultralight/animate.py,sha256=fE-zRU_uFrZIL9W78fcGz7qmrts8fz5UoWEy7b4xb44,1144
 svg_ultralight/inkscape.py,sha256=M8yTxXOu4NlXnhsMycvEJiIDpnDeiZ_bZakJBM38ZoU,9152
 svg_ultralight/layout.py,sha256=TTETT_8WLBXnQxDGXdAeczCFN5pFo5kKY3Q6zv4FPX4,12238
 svg_ultralight/main.py,sha256=6oNkZfD27UMdP-oYqp5agS_IGcYb8NkUZwM9Zdyb3SA,7287
 svg_ultralight/metadata.py,sha256=Mxgxrxe1Ar4kp2wTT29aadxgHNFaaNLABo29jStiWDg,4201
 svg_ultralight/nsmap.py,sha256=y63upO78Rr-JJT56RWWZuyrsILh6HPoY4GhbYnK1A0g,1244
 svg_ultralight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-svg_ultralight/query.py,sha256=PFyhR9v60JkuksRb0LVkml67nmOxfZW9eCtL-JoH52Y,7270
+svg_ultralight/query.py,sha256=_KQuk4IwhVVDgTT0GZm_gbqNUGp7lMEDM32b_CTTSUA,7320
 svg_ultralight/root_elements.py,sha256=pt9J6mPrnoTAZVF6vKTZoM_o947I8UCj6MbGcD2JUCk,2869
 svg_ultralight/string_conversion.py,sha256=WEmpf75RJmJ2lfJluagAz2wPsz6wM8XvTEwkq4U0vEc,7353
+svg_ultralight/transformations.py,sha256=CT43zaWSmEoWf-rQpFgP_1KX9wL6AzpR0cF8E1fIhAU,3625
 svg_ultralight/unit_conversion.py,sha256=g07nhzXdjPvGcJmkhLdFbeDLrSmbI8uFoVgPo7G62Bg,9258
 svg_ultralight/bounding_boxes/__init__.py,sha256=qUEn3r4s-1QNHaguhWhhaNfdP4tl_B6YEqxtiTFuzhQ,78
-svg_ultralight/bounding_boxes/bound_helpers.py,sha256=D-Qp8yDmn5vIBdaSlBvaWR0F_iRCdotgQqjaRHXBq-8,3397
-svg_ultralight/bounding_boxes/supports_bounds.py,sha256=1yqmZ7PH1bBH-LTIUDzSvKFXkPLXfJM7jJNz0bXurZ4,3926
-svg_ultralight/bounding_boxes/type_bound_element.py,sha256=VKiN4UnC2XlPKapWRHxgtqhO4BuVoe6YkLrirlEP09w,5714
-svg_ultralight/bounding_boxes/type_bounding_box.py,sha256=OqvS6LhfMwnoE4PUwAmHlY0tjY-2YQZQiLY6O2U3vfs,10378
-svg_ultralight/bounding_boxes/type_padded_text.py,sha256=FnwHD54qPMlyOB0yhRgZShQWA_riaaTS9GwD9HnbPm4,14119
+svg_ultralight/bounding_boxes/bound_helpers.py,sha256=YMClhdekeYbzD_ijXDAer-H3moWKN3lUNnZs1UNFFKc,3458
+svg_ultralight/bounding_boxes/supports_bounds.py,sha256=fbHV6mGdeIVV3lS15vBKSrHiHKR7DMg4K5X__4LLmCE,4569
+svg_ultralight/bounding_boxes/type_bound_confederation.py,sha256=PAUa8LSfyw0v2eq8EU2B_V5dlsl7ddrrPIsD-5fWU8U,2602
+svg_ultralight/bounding_boxes/type_bound_element.py,sha256=9RdxH8osOlAvPdWR0Ww9NsasHLPYFDs-MbydoV48x4E,2239
+svg_ultralight/bounding_boxes/type_bounding_box.py,sha256=cDrMp6uwaA--KJIQS2puG10qh8n3TBmiscg-cfk1f3w,16149
+svg_ultralight/bounding_boxes/type_padded_text.py,sha256=QA6PfeO_sQYc5pEXuyfyQ3lRUcZAc4B2BthWXpdt3qQ,14848
 svg_ultralight/constructors/__init__.py,sha256=YcnO0iBQc19aL8Iemw0Y452MBMBIT2AN5nZCnoGxpn0,327
 svg_ultralight/constructors/new_element.py,sha256=VtMz9sPn9rMk6rui5Poysy3vezlOaS-tGIcGbu-SXmY,3406
 svg_ultralight/strings/__init__.py,sha256=Zalrf-ThFz7b7xKELx5lb2gOlBgV-6jk_k_EeSdVCVk,295
 svg_ultralight/strings/svg_strings.py,sha256=RYKMxOHq9abbZyGcFqsElBGLrBX-EjjNxln3s_ibi30,1296
-svg_ultralight-0.27.0.dist-info/METADATA,sha256=6GeOT7ohzqEuzvgofE7pKbI2FnP9H_DRfwV4pNfb5K4,8871
-svg_ultralight-0.27.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-svg_ultralight-0.27.0.dist-info/top_level.txt,sha256=se-6yqM_0Yg5orJKvKWdjQZ4iR4G_EjhL7oRgju-fdY,15
-svg_ultralight-0.27.0.dist-info/RECORD,,
+svg_ultralight-0.29.0.dist-info/METADATA,sha256=hLjRc-xXrwqasclTCthb-BuYGgjPRxMtXwQ-zSAh7qY,8871
+svg_ultralight-0.29.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+svg_ultralight-0.29.0.dist-info/top_level.txt,sha256=se-6yqM_0Yg5orJKvKWdjQZ4iR4G_EjhL7oRgju-fdY,15
+svg_ultralight-0.29.0.dist-info/RECORD,,