svg-ultralight 0.64.0__py3-none-any.whl → 0.73.1__py3-none-any.whl

svg_ultralight/bounding_boxes/type_bounding_box.py

@@ -12,6 +12,7 @@ import math
 from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
 from svg_ultralight.strings import svg_matrix
 from svg_ultralight.transformations import mat_apply, mat_dot, new_transformation_matrix
+from svg_ultralight.unit_conversion import MeasurementArg, to_user_units
 
 _Matrix = tuple[float, float, float, float, float, float]
 
@@ -39,7 +40,7 @@ class HasBoundingBox(SupportsBounds):
         y = self.bbox.base_y
         x2 = x + self.bbox.base_width
         y2 = y + self.bbox.base_height
-        return (x, y), (x2, y), (x2, y2), (x, y2)
+        return (x, y), (x, y2), (x2, y2), (x2, y)
 
     def values(self) -> tuple[float, float, float, float]:
         """Get the values of the bounding box.
@@ -65,12 +66,28 @@ class HasBoundingBox(SupportsBounds):
 
         :return: four corners counter-clockwise starting at top left, transformed by
             self.transformation
+
+        These quadrilateral defined by these corners may not be axis aligned. This is
+        purely for determining the bounds of the transformed box.
         """
         c0, c1, c2, c3 = (
             mat_apply(self.bbox.transformation, c) for c in self._get_input_corners()
         )
         return c0, c1, c2, c3
 
+    @property
+    def corners(
+        self,
+    ) -> tuple[
+        tuple[float, float],
+        tuple[float, float],
+        tuple[float, float],
+        tuple[float, float],
+    ]:
+        """Get the corners of the bbox in the current state. CW from top left."""
+        x, y, x2, y2 = self.x, self.y, self.x2, self.y2
+        return ((x, y), (x, y2), (x2, y2), (x2, y))
+
     def transform(
         self,
         transformation: _Matrix | None = None,
@@ -106,7 +123,7 @@ class HasBoundingBox(SupportsBounds):
     def scale(self) -> tuple[float, float]:
         """Get scale of the bounding box.
 
-        :return: uniform scale of the bounding box
+        :return: x and y scale of the bounding box
 
         Use caution, the scale attribute can cause errors in intuition. Changing
         width or height will change the scale attribute, but not the x or y values.
@@ -301,13 +318,13 @@ class BoundingBox(HasBoundingBox):
     :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
-    will be combined and scored to be passed to new_element as a transform value.
+    instance can be transformed. Transformations will be combined and stored to be
+    passed to new_element as a transform value.
 
     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 value transformation
+    x2, y, cy, y2, width, or height, private transformation value `transformation`
     will be updated.
 
     The ultimate transformation can be accessed through ``.transform_string``.
@@ -316,7 +333,7 @@ class BoundingBox(HasBoundingBox):
         1. Get the bounding box of an svg element
         2. Update the bounding box x, y, width, and height
         3. Transform the original svg element with
-            update_element(elem, transform=bbox.transform_string)
+            svg_ultralight.transform_element(elem, bbox.transformation)
         4. The transformed element will lie in the transformed BoundingBox
 
     In addition to x, y, width, and height, x2 and y2 can be set to establish the
@@ -352,10 +369,10 @@ class BoundingBox(HasBoundingBox):
 
     def __init__(
         self,
-        x: float,
-        y: float,
-        width: float,
-        height: float,
+        x: MeasurementArg,
+        y: MeasurementArg,
+        width: MeasurementArg,
+        height: MeasurementArg,
         transformation: _Matrix = (1, 0, 0, 1, 0, 0),
     ) -> None:
         """Initialize a BoundingBox instance.
@@ -365,10 +382,10 @@ class BoundingBox(HasBoundingBox):
         :param width: width of the bounding box
         :param height: height of the bounding box
         """
-        self.base_x = x
-        self.base_y = y
-        self.base_width = width
-        self.base_height = height
+        self.base_x = to_user_units(x)
+        self.base_y = to_user_units(y)
+        self.base_width = to_user_units(width)
+        self.base_height = to_user_units(height)
         self.transformation = transformation
         self.bbox = self
 

svg_ultralight/bounding_boxes/type_padded_list.py

@@ -32,7 +32,7 @@ from svg_ultralight.attrib_hints import ElemAttrib
 from svg_ultralight.bounding_boxes.bound_helpers import new_bound_union
 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
+from svg_ultralight.bounding_boxes.type_padded_text import PaddedText, new_padded_union
 from svg_ultralight.constructors import update_element
 from svg_ultralight.transformations import new_transformation_matrix
 
@@ -123,12 +123,7 @@ class PaddedList:
 
     def padded_union(self, **attribs: ElemAttrib) -> PaddedText:
         """Return a PaddedText inst where the elem is a `g` of all the padded text."""
-        union = self.tunion(**attribs)
-        tpad = self.tbox.y - self.bbox.y
-        rpad = self.bbox.x2 - self.tbox.x2
-        bpad = self.bbox.y2 - self.tbox.y2
-        lpad = self.tbox.x - self.bbox.x
-        return PaddedText(union.elem, union.bbox, tpad, rpad, bpad, lpad)
+        return new_padded_union(*self.plems, **attribs)
 
     def get_dim(self, dim: str) -> float:
         """Get a dimension from bbox or tbox."""

svg_ultralight/bounding_boxes/type_padded_text.py

@@ -51,35 +51,77 @@ PaddedText instances with sensible defaults.
 
 from __future__ import annotations
 
+import dataclasses
 import math
 from typing import TYPE_CHECKING
 
-from paragraphs import par
-
 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
+from svg_ultralight.constructors.new_element import new_element_union
+from svg_ultralight.transformations import (
+    mat_apply,
+    new_transformation_matrix,
+    transform_element,
+)
 
 if TYPE_CHECKING:
     from lxml.etree import (
         _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
     )
 
+    from svg_ultralight.attrib_hints import ElemAttrib
+
 _Matrix = tuple[float, float, float, float, float, float]
 
-_no_line_gap_msg = par(
-    """No line_gap defined. Line gap is an inherent font attribute defined within a
-    font file. If this PaddedText instance was created with `pad_text` from reference
-    elements, a line_gap was not defined. Reading line_gap from the font file
-    requires creating a PaddedText instance with `pad_text_ft` or `pad_text_mixed`.
-    You can set an arbitrary line_gap after init with `instance.line_gap = value`."""
-)
 
-_no_font_size_msg = par(
-    """No font_size defined. Font size is an inherent font attribute defined within a
-    font file or an argument passed to `pad_text`. Any instance created with a padded
-    text initializer should have this property."""
-)
+@dataclasses.dataclass
+class FontMetrics:
+    """Font metrics."""
+
+    _font_size: float
+    _ascent: float
+    _descent: float
+    _cap_height: float
+    _x_height: float
+    _line_gap: float
+    _scalar: float = dataclasses.field(default=1.0, init=False)
+
+    def scale(self, scalar: float) -> None:
+        """Scale the font metrics by a scalar.
+
+        :param scalar: The scaling factor.
+        """
+        self._scalar *= scalar
+
+    @property
+    def font_size(self) -> float:
+        """The font size."""
+        return self._font_size * self._scalar
+
+    @property
+    def ascent(self) -> float:
+        """Return the ascent."""
+        return self._ascent * self._scalar
+
+    @property
+    def descent(self) -> float:
+        """Return the descent."""
+        return self._descent * self._scalar
+
+    @property
+    def cap_height(self) -> float:
+        """Return the cap height."""
+        return self._cap_height * self._scalar
+
+    @property
+    def x_height(self) -> float:
+        """Return the x height."""
+        return self._x_height * self._scalar
+
+    @property
+    def line_gap(self) -> float:
+        """Return the line gap."""
+        return self._line_gap * self._scalar
 
 
 class PaddedText(BoundElement):
@@ -93,8 +135,7 @@ class PaddedText(BoundElement):
         rpad: float,
         bpad: float,
         lpad: float,
-        line_gap: float | None = None,
-        font_size: float | None = None,
+        metrics: FontMetrics | None = None,
     ) -> None:
         """Initialize a PaddedText instance.
 
@@ -113,8 +154,26 @@ class PaddedText(BoundElement):
         self.rpad = rpad
         self.base_bpad = bpad
         self.lpad = lpad
-        self._line_gap = line_gap
-        self._font_size = font_size
+        self._metrics = metrics
+
+    @property
+    def metrics(self) -> FontMetrics:
+        """The font metrics for this PaddedText.
+
+        :return: The font metrics for this PaddedText.
+        """
+        if self._metrics is None:
+            msg = "No font metrics defined for this PaddedText."
+            raise AttributeError(msg)
+        return self._metrics
+
+    @metrics.setter
+    def metrics(self, value: FontMetrics) -> None:
+        """Set the font metrics for this PaddedText.
+
+        :param value: The new font metrics.
+        """
+        self._metrics = value
 
     @property
     def tbox(self) -> BoundingBox:
@@ -181,17 +240,14 @@ class PaddedText(BoundElement):
             transformed by tmat.
         """
         tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
-        self.unpadded_bbox.transform(tmat, reverse=reverse)
+        self.tbox.transform(tmat, reverse=reverse)
         _ = transform_element(self.elem, tmat, reverse=reverse)
         x_norm = pow(tmat[0] ** 2 + tmat[1] ** 2, 1 / 2)
         self.lpad *= x_norm
         self.rpad *= x_norm
-        if self._line_gap or self._font_size:
+        if self._metrics:
             y_norm = pow(tmat[2] ** 2 + tmat[3] ** 2, 1 / 2)
-            if self._line_gap:
-                self._line_gap *= y_norm
-            if self._font_size:
-                self._font_size *= y_norm
+            self._metrics.scale(y_norm)
 
     def transform_preserve_sidebearings(
         self,
@@ -222,22 +278,152 @@ class PaddedText(BoundElement):
         self.y2 = y2
 
     @property
-    def line_gap(self) -> float:
-        """The line gap between this line of text and the next.
+    def tx(self) -> float:
+        """The x value of the tight element bounding box.
+
+        :return: The x value of the tight element bounding box.
+        """
+        return self.tbox.x
+
+    @tx.setter
+    def tx(self, value: float) -> None:
+        """Set the x value of the tight element bounding box.
+
+        :param value: The new x value of the tight element bounding box.
+        """
+        self.transform(dx=value - self.tbox.x)
+
+    @property
+    def tx2(self) -> float:
+        """The x2 value of the tight element bounding box.
+
+        :return: The x2 value of the tight element bounding box.
+        """
+        return self.tbox.x2
+
+    @tx2.setter
+    def tx2(self, value: float) -> None:
+        """Set the x2 value of the tight element bounding box.
+
+        :param value: The new x2 value of the tight element bounding box.
+        """
+        self.transform(dx=value - self.tbox.x2)
+
+    @property
+    def ty(self) -> float:
+        """The y value of the tight element bounding box.
+
+        :return: The y value of the tight element bounding box.
+        """
+        return self.tbox.y
 
-        :return: The line gap between this line of text and the next.
+    @ty.setter
+    def ty(self, value: float) -> None:
+        """Set the y value of the tight element bounding box.
+
+        :param value: The new y value of the tight element bounding box.
+        """
+        self.transform(dy=value - self.tbox.y)
+
+    @property
+    def ty2(self) -> float:
+        """The y2 value of the tight element bounding box.
+
+        :return: The y2 value of the tight element bounding box.
+        """
+        return self.tbox.y2
+
+    @ty2.setter
+    def ty2(self, value: float) -> None:
+        """Set the y2 value of the tight element bounding box.
+
+        :param value: The new y2 value of the tight element bounding box.
+        """
+        self.transform(dy=value - self.tbox.y2)
+
+    @property
+    def twidth(self) -> float:
+        """The width of the tight element bounding box.
+
+        :return: The width of the tight element bounding box.
         """
-        if self._line_gap is None:
-            raise AttributeError(_no_line_gap_msg)
-        return self._line_gap
+        return self.tbox.width
 
-    @line_gap.setter
-    def line_gap(self, value: float) -> None:
-        """Set the line gap between this line of text and the next.
+    @twidth.setter
+    def twidth(self, value: float) -> None:
+        """Set the width of the tight element bounding box.
 
-        :param value: The new line gap.
+        :param value: The new width of the tight element bounding box.
         """
-        self._line_gap = value
+        self.transform(scale=value / self.tbox.width)
+
+    @property
+    def theight(self) -> float:
+        """The height of the tight element bounding box.
+
+        :return: The height of the tight element bounding box.
+        """
+        return self.tbox.height
+
+    @theight.setter
+    def theight(self, value: float) -> None:
+        """Set the height of the tight element bounding box.
+
+        :param value: The new height of the tight element bounding box.
+        """
+        self.transform(scale=value / self.tbox.height)
+
+    @property
+    def baseline(self) -> float:
+        """The y value of the baseline for the font.
+
+        :return: The baseline y value of this line of text.
+        """
+        return mat_apply(self.tbox.transformation, (0, 0))[1]
+        return self.y2 + (self.metrics.descent)
+
+    @baseline.setter
+    def baseline(self, value: float) -> None:
+        """Set the y value of the baseline for the font.
+
+        :param value: The new baseline y value.
+        """
+        dy = value - self.baseline
+        self.transform(dy=dy)
+
+    @property
+    def capline(self) -> float:
+        """The y value of the top of flat-topped capital letters for the font.
+
+        :return: The capline y value of this line of text.
+        """
+        return self.baseline - self.metrics.cap_height
+
+    @capline.setter
+    def capline(self, value: float) -> None:
+        """Set the capline y value for the font.
+
+        :param value: The new capline y value.
+        """
+        dy = value - self.capline
+        self.transform(dy=dy)
+
+    @property
+    def xline(self) -> float:
+        """The y value of the x-height for the font.
+
+        :return: The xline y value of this line of text.
+        """
+        return self.baseline - self.metrics.x_height
+
+    @xline.setter
+    def xline(self, value: float) -> None:
+        """Set the xline y value for the font.
+
+        :param value: The new xline y value.
+        """
+        dy = value - self.xline
+        self.transform(dy=dy)
 
     @property
     def font_size(self) -> float:
@@ -245,9 +431,7 @@ class PaddedText(BoundElement):
 
         :return: The font size of this line of text.
         """
-        if self._font_size is None:
-            raise AttributeError(_no_font_size_msg)
-        return self._font_size
+        return self.metrics.font_size
 
     @font_size.setter
     def font_size(self, value: float) -> None:
@@ -263,7 +447,7 @@ class PaddedText(BoundElement):
 
         :return: The line gap plus the height of this line of text.
         """
-        return self.height + self.line_gap
+        return self.height + self.metrics.line_gap
 
     @property
     def tpad(self) -> float:
@@ -332,19 +516,6 @@ class PaddedText(BoundElement):
         )
         self.transform(scale=new_scale)
 
-    @property
-    def uniform_scale(self) -> float:
-        """Get uniform scale of the bounding box.
-
-        :return: uniform scale of the bounding box
-        :raises ValueError: if the scale is non-uniform.
-        """
-        scale = self.scale
-        if math.isclose(scale[0], scale[1]):
-            return scale[0]
-        msg = f"Non-uniform scale detected: sx={scale[0]}, sy={scale[1]}"
-        raise ValueError(msg)
-
     @property
     def width(self) -> float:
         """The width of this line of text with padding.
@@ -500,3 +671,19 @@ class PaddedText(BoundElement):
         :param value: The bottom of this line of text.
         """
         self.transform(dy=value - self.bpad - self.tbox.y2)
+
+
+def new_padded_union(*plems: PaddedText, **attributes: ElemAttrib) -> PaddedText:
+    """Create a new PaddedText instance that is the union of multiple PaddedText.
+
+    :param plems: The PaddedText instances to union.
+    :return: A new PaddedText instance that is the union of the input instances.
+    """
+    bbox = BoundingBox.union(*(t.bbox for t in plems))
+    tbox = BoundingBox.union(*(t.tbox for t in plems))
+    tpad = tbox.y - bbox.y
+    rpad = bbox.x2 - tbox.x2
+    bpad = bbox.y2 - tbox.y2
+    lpad = tbox.x - bbox.x
+    elem = new_element_union(*(t.elem for t in plems), **attributes)
+    return PaddedText(elem, tbox, tpad, rpad, bpad, lpad, plems[0]._metrics)  # pyright: ignore[reportPrivateUsage]

svg_ultralight/constructors/new_element.py

@@ -16,6 +16,7 @@ import warnings
 from typing import TYPE_CHECKING
 
 from lxml import etree
+from lxml.etree import _Element as EtreeElement  # pyright: ignore[reportPrivateUsage]
 
 from svg_ultralight.string_conversion import set_attributes
 
@@ -23,9 +24,6 @@ if TYPE_CHECKING:
     from lxml.etree import (
         QName,
     )
-    from lxml.etree import (
-        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
-    )
 
     from svg_ultralight.attrib_hints import ElemAttrib
 
@@ -115,3 +113,39 @@ def deepcopy_element(elem: EtreeElement, **attributes: ElemAttrib) -> EtreeEleme
     elem = copy.deepcopy(elem)
     _ = update_element(elem, **attributes)
     return elem
+
+
+def new_element_union(
+    *elems: EtreeElement | object, **attributes: ElemAttrib
+) -> EtreeElement:
+    """Get the union of any elements found in the given arguments.
+
+    :param elems: EtreeElements or containers like BoundElements, PaddedTexts, or
+        others that have an `elem` attribute that is an EtreeElement. Other arguments
+        will be ignored.
+    :return: a new group element containing all elements.
+
+    This does not support consolidating attributes. E.g., if all elements have the
+    same fill color, this will not be recognized and consolidated into a single
+    attribute for the group. Too many attributes change their behavior when applied
+    to a group.
+    """
+    elements_found: list[EtreeElement] = []
+    for elem in elems:
+        if isinstance(elem, EtreeElement):
+            elements_found.append(elem)
+            continue
+        elem_elem = getattr(elem, "elem", None)
+        if isinstance(elem_elem, EtreeElement):
+            elements_found.append(elem_elem)
+
+    if not elements_found:
+        msg = (
+            "Cannot find any elements to union. "
+            + "At least one argument must be a "
+            + "BoundElement, PaddedText, or EtreeElement."
+        )
+        raise ValueError(msg)
+    group = new_element("g", **attributes)
+    group.extend(elements_found)
+    return group

svg_ultralight/font_tools/comp_results.py

@@ -1,9 +1,9 @@
 """Compare results between Inkscape and fontTools.
 
 Function `check_font_tools_alignment` will let you know if it's relatively safe to
-use `pad_text_mix` or `pad_text_ft`, which improve `pad_text` by assigning `line_gap`
-values to the resulting PaddedText instance and by aligning with the actual descent
-and ascent of a font instead of by attempting to infer these from a referenve string.
+use `pad_text_ft`, which improves `pad_text_inkscape` by assigning `line_gap` values
+to the resulting PaddedText instance and by aligning with the actual descent and
+ascent of a font instead of by attempting to infer these from a referenve string.
 
 See Enum `FontBboxError` for the possible error codes and their meanings returned by
 `check_font`.
@@ -27,8 +27,8 @@ from typing import TYPE_CHECKING
 from svg_ultralight.bounding_boxes.bound_helpers import new_bbox_rect, pad_bbox
 from svg_ultralight.bounding_boxes.padded_text_initializers import (
     DEFAULT_Y_BOUNDS_REFERENCE,
-    pad_text,
     pad_text_ft,
+    pad_text_inkscape,
 )
 from svg_ultralight.constructors import new_element
 from svg_ultralight.font_tools.font_info import FTFontInfo, get_svg_font_attributes
@@ -45,14 +45,14 @@ if TYPE_CHECKING:
 class FontBboxError(enum.Enum):
     """Classify the type of error between Inkscape and fontTools bounding boxes.
 
-    INIT: Use `pad_text`.
+    INIT: Use `pad_text_inkscape`.
 
-    FontTools failed to run. This can happen with fonts that, inentionally or
-    not, do not have the required tables or character sets to build a bounding box
-    around the TEXT_TEXT. You can only use the `pad_text` PaddedText constructor.
-    This font may work with other or ascii-only text.
+    FontTools failed to run. This can happen with fonts that, inentionally or not, do
+    not have the required tables or character sets to build a bounding box around the
+    TEXT_TEXT. You can only use the `pad_text_inkscape` PaddedText constructor. This
+    font may work with other or ascii-only text.
 
-    ELEM_Y: Use `pad_text` or `pad_text_mix` with cautions.
+    ELEM_Y: Use `pad_text_inkscape` with cautions.
 
     The y coordinate of the element bounding box is off by more than 1% of
     the height. This error matters, because the y coordinates are used by
@@ -60,21 +60,21 @@ class FontBboxError(enum.Enum):
     y_bounds_reference element and accept some potential error in `line_gap` or
     explicitly pass `ascent` and `descent` values to `pad_text_ft` or `pad_text_mix`.
 
-    SAFE_ELEM_X: Use `pad_text_mix`.
+    SAFE_ELEM_X:
 
     The y bounds are accurate, but the x coordinate of the element
     bounding box is off by more than 1%. This is called "safe" because it is not used
     by pad_bbox_mix, but you cannot use `pad_text_ft` without expecting BoundingBox
     inaccuracies.
 
-    LINE_Y: Use `pad_text` or `pad_text_mix` with caution.
+    LINE_Y: Use `pad_text_inkscape` with caution.
 
     All of the above match, but the y coordinate of the line bounding box
     (the padded bounding box) is off by more than 1% of the height. This error
     matters as does ELEM_Y, but it does not exist for any font on my system. Fonts
     without ELEM_Y errors should not have LINE_Y errors.
 
-    SAFE_LINE_X: Use `pad_text_mix`.
+    SAFE_LINE_X:
 
     All of the above match, but the x coordinate of the line bounding
     box (the padded bounding box) is off by more than 1%. This is safe or unsafe as
@@ -82,9 +82,9 @@ class FontBboxError(enum.Enum):
 
     NO_ERROR: Use `pad_text_ft`.
 
-    No errors were found. The bounding boxes match within 1% of the height.
-    You can use `pad_text_ft` to get the same result as `pad_text` or `pad_text_mix`
-    without the delay caused by an Inkscape call.
+    No errors were found. The bounding boxes match within 1% of the height. You can
+    use `pad_text_ft` to get the same result as `pad_text_inkscape` without the delay
+    caused by an Inkscape call.
     """
 
     INIT = enum.auto()
@@ -154,7 +154,7 @@ def check_font_tools_alignment(
     try:
         svg_attribs = get_svg_font_attributes(font)
         text_elem = new_element("text", **svg_attribs, text=text)
-        rslt_pt = pad_text(inkscape, text_elem)
+        rslt_pt = pad_text_inkscape(inkscape, text_elem)
         rslt_ft = pad_text_ft(
             font,
             text,
@@ -212,7 +212,7 @@ def draw_comparison(
         stroke="green",
         stroke_width=0.1,
     )
-    padded_pt = pad_text(inkscape, text_elem)
+    padded_pt = pad_text_inkscape(inkscape, text_elem)
     padded_ft = pad_text_ft(
         font,
         text,