svg-ultralight 0.38.0__py3-none-any.whl → 0.39.1__py3-none-any.whl

svg_ultralight/bounding_boxes/type_padded_text.py

@@ -12,7 +12,7 @@ There is a getter and setter for each of the four padding values. These *do not*
 the text element. For instance, if you decrease the left padding, the left margin
 will move, *not* the text element.
 
-There is a getter and setter for each of lmargin, rmargin, baseline, and capline.
+_There is a getter and setter for each of lmargin, rmargin, baseline, and capline.
 These *do* move the element, but do not scale it. For instance, if you move the
 leftmargin to the left, the right margin (and the text element with it) will move to
 the left.
@@ -66,8 +66,9 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
 from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+from svg_ultralight.transformations import new_transformation_matrix, transform_element
 
 if TYPE_CHECKING:
     from lxml.etree import (
@@ -77,7 +78,7 @@ if TYPE_CHECKING:
 _Matrix = tuple[float, float, float, float, float, float]
 
 
-class PaddedText(SupportsBounds):
+class PaddedText(BoundElement):
     """A line of text with a bounding box and padding."""
 
     def __init__(
@@ -99,14 +100,14 @@ class PaddedText(SupportsBounds):
         :param lpad: Left padding.
         """
         self.elem = elem
-        self.bbox = bbox
+        self.unpadded_bbox = bbox
         self.base_tpad = tpad
         self.rpad = rpad
         self.base_bpad = bpad
         self.lpad = lpad
 
     @property
-    def padded_bbox(self) -> BoundingBox:
+    def bbox(self) -> BoundingBox:
         """Return a BoundingBox around the margins and cap/baseline.
 
         :return: A BoundingBox around the margins and cap/baseline.
@@ -117,22 +118,27 @@ class PaddedText(SupportsBounds):
         instance around multiple text elements (a <g> elem).
         """
         return BoundingBox(
-            self.lmargin, self.capline, self.padded_width, self.padded_height
+            self.x,
+            self.y,
+            self.width,
+            self.height,
         )
 
-    @property
-    def transformation(self) -> _Matrix:
-        """The transformation matrix of the bounding box."""
-        return self.bbox.transformation
+    @bbox.setter
+    def bbox(self, value: BoundingBox) -> None:
+        """Set the bounding box of this PaddedText.
 
-    def _update_elem(self):
-        self.elem.attrib["transform"] = self.bbox.transform_string
+        :param value: The new bounding box.
+        :effects: The text element is transformed to fit the new bounding box.
+        """
+        msg = "Cannot set bbox of PaddedText, use transform() instead."
+        raise NotImplementedError(msg)
 
     def transform(
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: float | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):
@@ -143,8 +149,9 @@ class PaddedText(SupportsBounds):
         :param dx: the x translation
         :param dy: the y translation
         """
-        self.bbox.transform(transformation, scale=scale, dx=dx, dy=dy)
-        self._update_elem()
+        tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
+        self.unpadded_bbox.transform(tmat)
+        _ = transform_element(self.elem, tmat)
 
     @property
     def tpad(self) -> float:
@@ -152,7 +159,7 @@ class PaddedText(SupportsBounds):
 
         :return: The scaled top padding of this line of text.
         """
-        return self.base_tpad * self.bbox.scale
+        return self.base_tpad * self.unpadded_bbox.scale[1]
 
     @tpad.setter
     def tpad(self, value: float) -> None:
@@ -160,7 +167,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The new top padding.
         """
-        self.base_tpad = value / self.bbox.scale
+        self.base_tpad = value / self.unpadded_bbox.scale[1]
 
     @property
     def bpad(self) -> float:
@@ -168,7 +175,7 @@ class PaddedText(SupportsBounds):
 
         :return: The scaled bottom padding of this line of text.
         """
-        return self.base_bpad * self.bbox.scale
+        return self.base_bpad * self.unpadded_bbox.scale[1]
 
     @bpad.setter
     def bpad(self, value: float) -> None:
@@ -176,82 +183,18 @@ class PaddedText(SupportsBounds):
 
         :param value: The new bottom padding.
         """
-        self.base_bpad = value / self.bbox.scale
+        self.base_bpad = value / self.unpadded_bbox.scale[1]
 
     @property
-    def lmargin(self) -> float:
-        """The left margin of this line of text.
-
-        :return: The left margin of this line of text.
-        """
-        return self.bbox.x - self.lpad
-
-    @lmargin.setter
-    def lmargin(self, value: float) -> None:
-        """Set the left margin of this line of text.
-
-        :param value: The left margin of this line of text.
-        """
-        self.transform(dx=value + self.lpad - self.bbox.x)
-
-    @property
-    def rmargin(self) -> float:
-        """The right margin of this line of text.
-
-        :return: The right margin of this line of text.
-        """
-        return self.bbox.x2 + self.rpad
-
-    @rmargin.setter
-    def rmargin(self, value: float) -> None:
-        """Set the right margin of this line of text.
-
-        :param value: The right margin of this line of text.
-        """
-        self.transform(dx=value - self.rpad - self.bbox.x2)
-
-    @property
-    def capline(self) -> float:
-        """The top of this line of text.
-
-        :return: The top of this line of text.
-        """
-        return self.bbox.y - self.tpad
-
-    @capline.setter
-    def capline(self, value: float) -> None:
-        """Set the top of this line of text.
-
-        :param value: The top of this line of text.
-        """
-        self.transform(dy=value + self.tpad - self.bbox.y)
-
-    @property
-    def baseline(self) -> float:
-        """The bottom of this line of text.
-
-        :return: The bottom of this line of text.
-        """
-        return self.bbox.y2 + self.bpad
-
-    @baseline.setter
-    def baseline(self, value: float) -> None:
-        """Set the bottom of this line of text.
-
-        :param value: The bottom of this line of text.
-        """
-        self.transform(dy=value - self.bpad - self.bbox.y2)
-
-    @property
-    def padded_width(self) -> float:
+    def width(self) -> float:
         """The width of this line of text with padding.
 
         :return: The scaled width of this line of text with padding.
         """
-        return self.bbox.width + self.lpad + self.rpad
+        return self.unpadded_bbox.width + self.lpad + self.rpad
 
-    @padded_width.setter
-    def padded_width(self, width: float) -> None:
+    @width.setter
+    def width(self, value: float) -> None:
         """Scale to padded_width = width without scaling padding.
 
         :param width: The new width of this line of text.
@@ -263,27 +206,34 @@ class PaddedText(SupportsBounds):
         baseline is near y2 (y + height) not y. So, we preserve baseline (alter y
         *and* y2) when scaling.
         """
-        baseline = self.baseline
-        self.bbox.width = width - self.lpad - self.rpad
-        self.baseline = baseline
-        self._update_elem()
+        y2 = self.y2
+
+        no_margins_old = self.unpadded_bbox.width
+        no_margins_new = value - self.lpad - self.rpad
+        scale = no_margins_new / no_margins_old
+        self.transform(scale=(scale, scale))
+
+        self.y2 = y2
 
     @property
-    def padded_height(self) -> float:
+    def height(self) -> float:
         """The height of this line of text with padding.
 
         :return: The scaled height of this line of text with padding.
         """
-        return self.bbox.height + self.tpad + self.bpad
+        return self.unpadded_bbox.height + self.tpad + self.bpad
 
-    @padded_height.setter
-    def padded_height(self, height: float) -> None:
-        """Scale to padded_height = height without scaling padding.
+    @height.setter
+    def height(self, value: float) -> None:
+        """Scale to height without scaling padding.
 
         :param height: The new height of this line of text.
         :effects: the text_element bounding box is scaled to height - tpad - bpad.
         """
-        self.padded_width *= height / self.padded_height
+        y2 = self.y2
+        scale = value / self.height
+        self.transform(scale=(scale, scale))
+        self.y2 = y2
 
     @property
     def x(self) -> float:
@@ -291,15 +241,31 @@ class PaddedText(SupportsBounds):
 
         :return: The left margin of this line of text.
         """
-        return self.lmargin
+        return self.unpadded_bbox.x - self.lpad
 
     @x.setter
     def x(self, value: float) -> None:
         """Set the left margin of this line of text.
 
-        :param value: The new left margin of this line of text.
+        :param value: The left margin of this line of text.
+        """
+        self.transform(dx=value + self.lpad - self.unpadded_bbox.x)
+
+    @property
+    def cx(self) -> float:
+        """The horizontal center of this line of text.
+
+        :return: The horizontal center of this line of text.
+        """
+        return self.x + self.width / 2
+
+    @cx.setter
+    def cx(self, value: float) -> None:
+        """Set the horizontal center of this line of text.
+
+        :param value: The horizontal center of this line of text.
         """
-        self.lmargin = value
+        self.x += value - self.cx
 
     @property
     def x2(self) -> float:
@@ -307,134 +273,65 @@ class PaddedText(SupportsBounds):
 
         :return: The right margin of this line of text.
         """
-        return self.rmargin
+        return self.unpadded_bbox.x2 + self.rpad
 
     @x2.setter
     def x2(self, value: float) -> None:
         """Set the right margin of this line of text.
 
-        :param value: The new right margin of this line of this text.
+        :param value: The right margin of this line of text.
         """
-        self.rmargin = value
+        self.transform(dx=value - self.rpad - self.unpadded_bbox.x2)
 
     @property
     def y(self) -> float:
-        """The capline of this line of text.
+        """The top of this line of text.
 
-        :return: The capline of this line of text.
+        :return: The top of this line of text.
         """
-        return self.capline
+        return self.unpadded_bbox.y - self.tpad
 
     @y.setter
     def y(self, value: float) -> None:
-        """Set the capline of this line of text.
-
-        :param value: The new capline of this line of text.
-        """
-        self.capline = value
-
-    @property
-    def y2(self) -> float:
-        """The baseline of this line of text.
-
-        :return: The baseline of this line of text.
-        """
-        return self.baseline
-
-    @y2.setter
-    def y2(self, value: float) -> None:
-        """Set the baseline of this line of text.
-
-        :param value: The new baseline of this line of text.
-        """
-        self.baseline = value
-
-    @property
-    def width(self) -> float:
-        """The width of this line of text with padding.
-
-        :return: The scaled width of this line of text with padding.
-        """
-        return self.padded_width
-
-    @width.setter
-    def width(self, value: float) -> None:
-        """Scale to width without scaling padding.
-
-        :param value: The new width of this line of text.
-        :effects: the text_element bounding box is scaled to width - lpad - rpad.
-
-        Svg_Ultralight BoundingBoxes preserve x and y when scaling. This is
-        consistent with how rectangles, viewboxes, and anything else defined by x, y,
-        width, height behaves in SVG. This is unintuitive for text, because the
-        baseline is near y2 (y + height) not y. So, we preserve baseline (alter y
-        *and* y2) when scaling.
-        """
-        baseline = self.baseline
-        self.padded_width = value
-        self.baseline = baseline
-
-    @property
-    def height(self) -> float:
-        """The height of this line of text with padding.
-
-        :return: The scaled height of this line of text with padding.
-        """
-        return self.padded_height
-
-    @height.setter
-    def height(self, value: float) -> None:
-        """Scale to height without scaling padding.
-
-        :param value: The new height of this line of text.
-        :effects: the text_element bounding box is scaled to height - tpad - bpad.
-        """
-        self.padded_height = value
-
-    @property
-    def cx(self) -> float:
-        """The x coordinate of the center between margins.
-
-        :return: the x coordinate of the center between margins
-        """
-        return self.lmargin + self.padded_width / 2
-
-    @cx.setter
-    def cx(self, value: float):
-        """Set the x coordinate of the center between margins.
+        """Set the top of this line of text.
 
-        :param value: the new x coordinate of the center between margins
+        :param value: The top of this line of text.
         """
-        self.lmargin = value - self.padded_width / 2
+        self.transform(dy=value + self.tpad - self.unpadded_bbox.y)
 
     @property
     def cy(self) -> float:
-        """The y coordinate of the center between baseline and capline.
+        """The horizontal center of this line of text.
 
-        :return: the y coordinate of the center between baseline and capline
+        :return: The horizontal center of this line of text.
         """
-        return self.capline + self.padded_height / 2
+        return self.y + self.height / 2
 
     @cy.setter
-    def cy(self, value: float):
-        """Set the y coordinate of the center between baseline and capline.
+    def cy(self, value: float) -> None:
+        """Set the horizontal center of this line of text.
 
-        :param value: the new y coordinate of the center between baseline and capline
+        :param value: The horizontal center of this line of text.
         """
-        self.capline = value - self.padded_height / 2
+        self.y += value - self.cy
 
     @property
-    def scale(self) -> float:
-        """The scale of the text element.
+    def y2(self) -> float:
+        """The bottom of this line of text.
 
-        :return: the scale of the text element
+        :return: The bottom of this line of text.
         """
-        return self.bbox.scale
+        return self.unpadded_bbox.y2 + self.bpad
 
-    @scale.setter
-    def scale(self, value: float):
-        """Set the scale of the text element.
+    @y2.setter
+    def y2(self, value: float) -> None:
+        """Set the bottom of this line of text.
 
-        :param value: the new scale of the text element
+        :param value: The bottom of this line of text.
         """
-        self.bbox.scale = value
+        self.transform(dy=value - self.bpad - self.unpadded_bbox.y2)
+
+    lmargin = x
+    rmargin = x2
+    capline = y
+    baseline = y2

svg_ultralight/layout.py

@@ -144,11 +144,11 @@ def pad_and_scale(
     """Expand and scale the pad argument. If necessary, scale image.
 
     :param viewbox: viewbox to pad (x, y, width height)
-    :param pad: padding to add around image, in user units or inches. if a
+    :param pad: padding to add around image, in user units or inches. If a
         sequence, it should be (top, right, bottom, left). if a single float or
-        string, it will be applied to all sides. if two floats, top and bottom
-        then left and right. if three floats, top, left and right, then bottom.
-        if four floats, top, right, bottom, left.
+        string, it will be applied to all sides. If two floats, top and bottom
+        then left and right. If three floats, top, left and right, then bottom.
+        If four floats, top, right, bottom, left.
     :param print_width: width of print area, in user units (float), a string
         with a unit specifier (e.g., "452mm"), or just a unit specifier (e.g.,
         "pt")
@@ -169,7 +169,7 @@ def pad_and_scale(
     If the width and height *are* specified, the user units become whatever they
     need to be to fit that requirement. For instance, if the viewbox width is 96
     and the width argument is "1in", then the user units are *still* pixels,
-    because there are 96 pixels in an inch. If the viewbox with is 2 and the
+    because there are 96 pixels in an inch. If the viewbox width is 2 and the
     width argument is "1in", then the user units are 1/2 of an inch (i.e., 48
     pixels) each, because there are 2 user units in an inch. If the viewbox
     width is 3 and the width argument is "1yd", the each user unit is 1 foot.
@@ -195,17 +195,26 @@ def pad_and_scale(
     the unit designators without changing the scale.
 
     Print aspect ratio is ignored. Viewbox aspect ratio is preserved. For
-    instance, If you take a 100x100 unit image then pass pad="0.25in" and
-    print_width="12in", the output image will be 12.5 inches across. Whatever
-    geometry was visible in the original viewbox will be much larger, but the
-    padding will still be 0.25 inches. If you want to use padding and need a
-    specific output image size, remember to subtract the padding width from your
-    print_width or print_height.
+    instance, if you created two images
+
+    * x_=0, y_=0, width_=1, height_=2, pad_="0.25in", print_width_="6in"
+
+    * x_=0, y_=0, width_=1, height_=2, pad_="0.25in", print_width_="12in"
+
+    ... (note that the images only vary in print_width_), the first image would be
+    rendered at 6.5x12.5 inches and the second at 12.5x24.5 inches. The visible
+    content in the viewbox would be exactly twice as wide in the larger image, but
+    the padding would remain 0.25 in both images. Despite setting `print_width_` to
+    exactly 6 or 12 inches, you would not get an image exactly 6 or 12 inches wide.
+    Despite a viewbox aspect ratio of 1:2, you would not get an output image of
+    exactly 1:2. If you want to use padding and need a specific output image size or
+    aspect ratio, remember to subtract the padding width from your print_width or
+    print_height.
 
     Scaling attributes are returned as a dictonary that can be "exploded" into
     the element constructor, e.g., {"width": "12.5in", "height": "12.5in"}.
 
-    * If neighther a print_width nor print_height is specified, no scaling
+    * If neither a print_width nor print_height is specified, no scaling
       attributes will be returned.
 
     * If either is specified, both a width and height will be returned (even if
@@ -242,7 +251,7 @@ def pad_and_scale(
     a 16" x 9" image with viwebox(0, 0, 14, 7), pad_="1in", print_width_="14in"
     ... then scale the printout with dpu_=2 to get a 32" x 18" image with the
     same viewbox. This means the padding will be 2" on all sides, but the image
-    will be identical (just twice as large) as the 16" x 9" image.
+    will be identical (just twice as wide and twice as high) as the 16" x 9" image.
     """
     pads = expand_pad_arg(pad)
 

svg_ultralight/query.py

@@ -63,7 +63,7 @@ def _fill_ids(*elem_args: EtreeElement) -> None:
 
 
 def _normalize_views(elem: EtreeElement) -> None:
-    """Create a square viewbox for any element with an svg tag.
+    """Create a square viewBox for any element with an svg tag.
 
     :param elem: an etree element
 
@@ -110,51 +110,61 @@ def map_elems_to_bounding_boxes(
         IMPORTANT: path cannot end with ``.exe``.
         Use something like ``"C:\\Program Files\\Inkscape\\inkscape"``
     :param elem_args: xml element (written to a temporary file then queried)
-    :return: svg elements (and a bounding box for the entire svg file as ``svg``)
-        mapped to BoundingBox(x, y, width, height)
-    :effects: temporarily adds an id attribute if any ids are missing. Non-unique ids
-        will break this function.
-
-    Bounding boxes are relative to svg viewbox. If viewbox x == -10,
+    :return: input svg elements and any descendents of those elements mapped
+        `BoundingBox(x, y, width, height)`
+        So return dict keys are the input elements themselves with one exception: a
+        string key, "svg", is mapped to a bounding box around all input elements.
+    :effects: temporarily adds an id attribute if any ids are missing. These are
+        removed if the function completes. Existing, non-unique ids will break this
+        function.
+
+    Bounding boxes are relative to svg viewBox. If, for instance, viewBox x == -10,
     all bounding-box x values will be offset -10. So, everything is wrapped in a root
-    element with a "normalized" viewbox, (viewbox=(0, 0, 1, 1)) then any child root
-    elements ("child root elements" sounds wrong, but it works) viewboxes are
-    normalized as well. This works even with a root element around a root element, so
-    input elem_args can be root elements or "normal" elements like "rect", "circle",
-    or "text" or a mixture of both.
+    element, `envelope` with a "normalized" viewBox, `viewBox=(0, 0, 1, 1)`. That
+    way, any child root elements ("child root elements" sounds wrong, but it works)
+    viewBoxes are normalized as well. This works even with a root element around a
+    root element, so input elem_args can be root elements or "normal" elements like
+    "rect", "circle", or "text" or a mixture of both. Bounding boxes output here will
+    work as expected in any viewBox.
 
     The ``inkscape --query-all svg`` call will return a tuple:
 
     (b'svg1,x,y,width,height\\r\\elem1,x,y,width,height\\r\\n', None)
     where x, y, width, and height are strings of numbers.
 
-    This calls the command and formats the output into a dictionary.
-
-    Scaling arguments ("width", "height") to new_svg_root transform the bounding
-    boxes in non-useful ways.  This copies all elements except the root element in to
-    a (0, 0, 1, 1) root. This will put the boxes where you'd expect them to be, no
-    matter what root you use.
+    This calls the command and formats the output into a dictionary. There is a
+    little extra complexity to handle cases with duplicate elements. Inkscape will
+    map bounding boxes to element ids *if* those ids are unique. If Inkscape
+    encounters a duplicate ID, Inkscape will map the bounding box of that element to
+    a string like "rect1". If you pass unequal elements with the same id, I can't
+    help you, but you might pass the same element multiple times. If you do this,
+    Inkscape will find a bounding box for each occurrence, map the first occurrence
+    to the id, then map subsequent occurrences to a string like "rect1". This
+    function will handle that.
     """
     if not elem_args:
         return {}
     _fill_ids(*elem_args)
-    envelope = _envelop_copies(*elem_args)
 
+    envelope = _envelop_copies(*elem_args)
     with NamedTemporaryFile(mode="wb", delete=False, suffix=".svg") as svg_file:
         svg = write_svg(svg_file, envelope)
     with Popen(f'"{inkscape}" --query-all {svg}', stdout=PIPE) as bb_process:
         bb_data = str(bb_process.communicate()[0])[2:-1]
     os.unlink(svg_file.name)
+
     bb_strings = re.split(r"[\\r]*\\n", bb_data)[:-1]
     id2bbox = dict(map(_split_bb_string, bb_strings))
 
     elem2bbox: dict[EtreeElement | Literal["svg"], BoundingBox] = {}
     for elem in _iter_elems(*elem_args):
-        elem2bbox[elem] = id2bbox.pop(elem.attrib["id"])
-        if elem.attrib["id"].startswith(_TEMP_ID_PREFIX):
+        elem_id = elem.attrib.get("id")
+        if not (elem_id):  # id removed in a previous loop
+            continue
+        elem2bbox[elem] = id2bbox[elem_id]
+        if elem_id.startswith(_TEMP_ID_PREFIX):
             del elem.attrib["id"]
-    ((_, scene_bbox),) = id2bbox.items()
-    elem2bbox["svg"] = scene_bbox
+    elem2bbox["svg"] = BoundingBox.merged(*id2bbox.values())
     return elem2bbox
 
 

svg_ultralight/transformations.py

@@ -52,13 +52,19 @@ def mat_dot(mat1: _Matrix, mat2: _Matrix) -> _Matrix:
     return (aa, bb, cc, dd, ee, ff)
 
 
-def mat_apply(mat1: _Matrix, mat2: tuple[float, float]) -> tuple[float, float]:
+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 (sx, 0, 0, sy, tx, ty)
+    :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)
     """
-    return mat1[0] * mat2[0] + mat1[4], mat1[3] * mat2[1] + mat1[5]
+    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:
@@ -99,7 +105,7 @@ def get_transform_matrix(elem: EtreeElement) -> _Matrix:
 def new_transformation_matrix(
     transformation: _Matrix | None = None,
     *,
-    scale: float | None = None,
+    scale: tuple[float, float] | float | None = None,
     dx: float | None = None,
     dy: float | None = None,
 ) -> _Matrix:
@@ -109,10 +115,17 @@ def new_transformation_matrix(
     svg-style transformation matrix.
     """
     transformation = transformation or (1, 0, 0, 1, 0, 0)
-    scale = scale or 1
+
+    if isinstance(scale, float):
+        scale_x, scale_y = (scale, scale)
+    elif scale is None:
+        scale_x, scale_y = (1, 1)
+    else:
+        scale_x, scale_y = cast("tuple[float, float]", scale)
+
     dx = dx or 0
     dy = dy or 0
-    return mat_dot((scale, 0, 0, scale, dx, dy), transformation)
+    return mat_dot((scale_x, 0, 0, scale_y, dx, dy), transformation)
 
 
 def transform_element(elem: EtreeElement, matrix: _Matrix) -> EtreeElement: