svg-ultralight 0.64.0__py3-none-any.whl

svg_ultralight/bounding_boxes/padded_text_initializers.py

@@ -0,0 +1,442 @@
+"""Functions that create PaddedText instances.
+
+Three variants:
+
+- `pad_text`: uses Inkscape to measure text bounds
+
+- `pad_text_ft`: uses fontTools to measure text bounds (faster, and you get line_gap)
+
+- `pad_text_mix`: uses Inkscape and fontTools to give true ascent, descent, and
+  line_gap while correcting some of the layout differences between fontTools and
+  Inkscape.
+
+There is a default font size for pad_text if an element is passed. There is also a
+default for the other pad_text_ functions, but it taken from the font file and is
+usually 1024, so it won't be easy to miss. The default for standard pad_text is to
+prevent surprises if Inksape defaults to font-size 12pt while your browser defaults
+to 16px.
+
+:author: Shay Hill
+:created: 2025-06-09
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, overload
+
+from svg_ultralight.attrib_hints import ElemAttrib
+from svg_ultralight.bounding_boxes.bound_helpers import pad_bbox
+from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
+from svg_ultralight.bounding_boxes.type_padded_text import PaddedText
+from svg_ultralight.constructors import new_element, update_element
+from svg_ultralight.font_tools.font_info import (
+    FTFontInfo,
+    get_padded_text_info,
+    get_svg_font_attributes,
+)
+from svg_ultralight.query import get_bounding_boxes
+from svg_ultralight.string_conversion import format_attr_dict, format_number
+
+if TYPE_CHECKING:
+    import os
+
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+    from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
+
+DEFAULT_Y_BOUNDS_REFERENCE = "{[|gjpqyf"
+
+# A default font size for pad_text if font-size is not specified in the reference
+# element.
+DEFAULT_FONT_SIZE_FOR_PAD_TEXT = 12.0  # Default font size for pad_text if not specified
+
+
+def pad_text(
+    inkscape: str | os.PathLike[str],
+    text_elem: EtreeElement,
+    y_bounds_reference: str | None = None,
+    *,
+    font: str | os.PathLike[str] | None = None,
+) -> PaddedText:
+    r"""Create a PaddedText instance from a text element.
+
+    :param inkscape: path to an inkscape executable on your local file system
+        IMPORTANT: path cannot end with ``.exe``.
+        Use something like ``"C:\\Program Files\\Inkscape\\inkscape"``
+    :param text_elem: an etree element with a text tag
+    :param y_bounds_reference: an optional string to use to determine the ascent and
+        capline of the font. The default is a good choice, which approaches or even
+        meets the ascent of descent of most fonts without using utf-8 characters. You
+        might want to use a letter like "M" or even "x" if you are using an all-caps
+        string and want to center between the capline and baseline or if you'd like
+        to center between the baseline and x-line.
+    :param font: optionally add a path to a font file to use for the text element.
+        This is going to conflict with any font-family, font-style, or other
+        font-related attributes *except* font-size. You likely want to use
+        `font_tools.new_padded_text` if you're going to pass a font path, but you can
+        use it here to compare results between `pad_text` and `new_padded_text`.
+    :return: a PaddedText instance
+    """
+    if y_bounds_reference is None:
+        y_bounds_reference = DEFAULT_Y_BOUNDS_REFERENCE
+    if font is not None:
+        _ = update_element(text_elem, **get_svg_font_attributes(font))
+    if "font-size" not in text_elem.attrib:
+        text_elem.attrib["font-size"] = format_number(DEFAULT_FONT_SIZE_FOR_PAD_TEXT)
+    rmargin_ref = deepcopy(text_elem)
+    capline_ref = deepcopy(text_elem)
+    _ = rmargin_ref.attrib.pop("id", None)
+    _ = capline_ref.attrib.pop("id", None)
+    rmargin_ref.attrib["text-anchor"] = "end"
+    capline_ref.text = y_bounds_reference
+
+    bboxes = get_bounding_boxes(inkscape, text_elem, rmargin_ref, capline_ref)
+    bbox, rmargin_bbox, capline_bbox = bboxes
+
+    tpad = bbox.y - capline_bbox.y
+    rpad = -rmargin_bbox.x2
+    bpad = capline_bbox.y2 - bbox.y2
+    lpad = bbox.x
+    return PaddedText(
+        text_elem,
+        bbox,
+        tpad,
+        rpad,
+        bpad,
+        lpad,
+        font_size=float(text_elem.attrib["font-size"]),
+    )
+
+
+@overload
+def pad_chars_ft(
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> BoundElement: ...
+
+
+@overload
+def pad_chars_ft(
+    font: str | os.PathLike[str],
+    text: list[str],
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> list[BoundElement]: ...
+
+
+def pad_chars_ft(
+    font: str | os.PathLike[str],
+    text: str | list[str],
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> BoundElement | list[BoundElement]:
+    """Create a bound group of paths for each character in the text.
+
+    Create a bound group of path elements, one for each character in the text. This
+    will provide less utility in most respects than `pad_text_ft`, but will be useful
+    for animations and other effects where individual characters need to be
+    addressed.
+    """
+    attributes.update(attrib or {})
+    attributes_ = format_attr_dict(**attributes)
+    attributes_.update(get_svg_font_attributes(font))
+
+    _ = attributes_.pop("font-size", None)
+    _ = attributes_.pop("font-family", None)
+    _ = attributes_.pop("font-style", None)
+    _ = attributes_.pop("font-weight", None)
+    _ = attributes_.pop("font-stretch", None)
+
+    input_one_text_item = False
+    if isinstance(text, str):
+        input_one_text_item = True
+        text = [text]
+    elems: list[BoundElement] = []
+
+    font_info = FTFontInfo(font)
+    try:
+        for text_item in text:
+            text_info = get_padded_text_info(
+                font_info,
+                text_item,
+                font_size,
+                ascent,
+                descent,
+                y_bounds_reference=y_bounds_reference,
+            )
+            elem = text_info.new_chars_group_element(**attributes_)
+            bbox = pad_bbox(text_info.bbox, text_info.padding)
+            elems.append(BoundElement(elem, bbox))
+    finally:
+        font_info.font.close()
+    if input_one_text_item:
+        return elems[0]
+    return elems
+
+
+def _remove_svg_font_attributes(attributes: dict[str, ElemAttrib]) -> dict[str, str]:
+    """Remove svg font attributes from the attributes dict.
+
+    These are either not required when explicitly passing a font file, not relevant,
+    or not supported by fontTools.
+    """
+    attributes_ = format_attr_dict(**attributes)
+    keys_to_remove = [
+        "font-size",
+        "font-family",
+        "font-style",
+        "font-weight",
+        "font-stretch",
+    ]
+    return {k: v for k, v in attributes_.items() if k not in keys_to_remove}
+
+
+@overload
+def pad_text_ft(
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> PaddedText: ...
+
+
+@overload
+def pad_text_ft(
+    font: str | os.PathLike[str],
+    text: list[str],
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> list[PaddedText]: ...
+
+
+def pad_text_ft(
+    font: str | os.PathLike[str],
+    text: str | list[str],
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> PaddedText | list[PaddedText]:
+    """Create a new PaddedText instance using fontTools.
+
+    :param font: path to a font file.
+    :param text: the text of the text element or a list of text strings.
+    :param font_size: the font size to use.
+    :param ascent: the ascent of the font. If not provided, it will be calculated
+        from the font file.
+    :param descent: the descent of the font. If not provided, it will be calculated
+        from the font file.
+    :param y_bounds_reference: optional character or string to use as a reference
+        for the ascent and descent. If provided, the ascent and descent will be the y
+        extents of the capline reference. This argument is provided to mimic the
+        behavior of the query module's `pad_text` function. `pad_text` does no
+        inspect font files and relies on Inkscape to measure reference characters.
+    :param attrib: optionally pass additional attributes as a mapping instead of as
+        anonymous kwargs. This is useful for pleasing the linter when unpacking a
+        dictionary into a function call.
+    :param attributes: additional attributes to set on the text element. There is a
+        chance these will cause the font element to exceed the BoundingBox of the
+        PaddedText instance.
+    :return: a PaddedText instance with a line_gap defined. If a list of strings is
+        given for parameter `text`, a list of PaddedText instances is returned.
+    """
+    attributes.update(attrib or {})
+    attributes_ = _remove_svg_font_attributes(attributes)
+
+    input_one_text_item = False
+    if isinstance(text, str):
+        input_one_text_item = True
+        text = [text]
+
+    font_info = FTFontInfo(font)
+
+    try:
+        elems: list[PaddedText] = []
+        for text_item in text:
+            ti = get_padded_text_info(
+                font_info,
+                text_item,
+                font_size,
+                ascent,
+                descent,
+                y_bounds_reference=y_bounds_reference,
+            )
+            elem = ti.new_element(**attributes_)
+            plem = PaddedText(elem, ti.bbox, *ti.padding, ti.line_gap, ti.font_size)
+            elems.append(plem)
+    finally:
+        font_info.font.close()
+    if input_one_text_item:
+        return elems[0]
+    return elems
+
+
+@overload
+def wrap_text_ft(
+    font: str | os.PathLike[str],
+    text: str,
+    width: float,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+) -> list[str]: ...
+
+
+@overload
+def wrap_text_ft(
+    font: str | os.PathLike[str],
+    text: list[str],
+    width: float,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+) -> list[list[str]]: ...
+
+
+def wrap_text_ft(
+    font: str | os.PathLike[str],
+    text: str | list[str],
+    width: float,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+) -> list[str] | list[list[str]]:
+    """Wrap text to fit within the width of the font's bounding box."""
+    input_one_text_item = False
+    if isinstance(text, str):
+        input_one_text_item = True
+        text = [text]
+
+    all_wrapped: list[list[str]] = []
+    font_info = FTFontInfo(font)
+
+    def get_width(line: str) -> float:
+        ti = get_padded_text_info(
+            font_info,
+            line,
+            font_size,
+            ascent,
+            descent,
+            y_bounds_reference=y_bounds_reference,
+        )
+        return ti.bbox.width
+
+    try:
+        for text_item in text:
+            words = text_item.split()
+            if not words:
+                all_wrapped.append([])
+                continue
+            wrapped: list[str] = [words.pop(0)]
+            while words:
+                next_word = words.pop(0)
+                test_line = f"{wrapped[-1]} {next_word}"
+                if get_width(test_line) <= width:
+                    wrapped[-1] = test_line
+                else:
+                    wrapped.append(next_word)
+            all_wrapped.append(wrapped)
+    finally:
+        font_info.font.close()
+    if input_one_text_item:
+        return all_wrapped[0]
+    return all_wrapped
+
+
+def pad_text_mix(
+    inkscape: str | os.PathLike[str],
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float | None = None,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> PaddedText:
+    """Use Inkscape text bounds and fill missing with fontTools.
+
+    :param font: path to a font file.
+    :param text: the text of the text element.
+    :param font_size: the font size to use.
+    :param ascent: the ascent of the font. If not provided, it will be calculated
+        from the font file.
+    :param descent: the descent of the font. If not provided, it will be calculated
+        from the font file.
+    :param y_bounds_reference: optional character or string to use as a reference
+        for the ascent and descent. If provided, the ascent and descent will be the y
+        extents of the capline reference. This argument is provided to mimic the
+        behavior of the query module's `pad_text` function. `pad_text` does no
+        inspect font files and relies on Inkscape to measure reference characters.
+    :param attrib: optionally pass additional attributes as a mapping instead of as
+        anonymous kwargs. This is useful for pleasing the linter when unpacking a
+        dictionary into a function call.
+    :param attributes: additional attributes to set on the text element. There is a
+        chance these will cause the font element to exceed the BoundingBox of the
+        PaddedText instance.
+    :return: a PaddedText instance with a line_gap defined.
+    """
+    attributes.update(attrib or {})
+    elem = new_element("text", text=text, **attributes)
+    padded_inkscape = pad_text(inkscape, elem, y_bounds_reference, font=font)
+    padded_fonttools = pad_text_ft(
+        font,
+        text,
+        font_size,
+        ascent,
+        descent,
+        y_bounds_reference=y_bounds_reference,
+        attrib=attributes,
+    )
+    bbox = padded_inkscape.tbox
+    rpad = padded_inkscape.rpad
+    lpad = padded_inkscape.lpad
+    if y_bounds_reference is None:
+        tpad = padded_fonttools.tpad
+        bpad = padded_fonttools.bpad
+    else:
+        tpad = padded_inkscape.tpad
+        bpad = padded_inkscape.bpad
+    return PaddedText(
+        elem, bbox, tpad, rpad, bpad, lpad, padded_fonttools.line_gap, font_size
+    )

svg_ultralight/bounding_boxes/supports_bounds.py

@@ -0,0 +1,167 @@
+"""A protocol for objects that support bounds.
+
+This module defines a protocol for objects that can have bounds. Existing and
+future types like BoundingBox, BoundElement, and PaddedText can be arranged,
+aligned, and uniformly scaled by reading and setting their bounds. This is the
+interface needed to support such alignment.
+
+Attributes:
+    x (float): The minimum x coordinate. x2 (float): The maximum x coordinate.
+    cx (float): The center x coordinate. y (float): The minimum y coordinate. y2
+    (float): The maximum y coordinate. cy (float): The center y coordinate.
+    width (float): The width of the object. height (float): The height of the
+    object. scale (float): The scale of the object.
+
+:author: Shay Hill
+: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.
+        y (float): The minimum y coordinate.
+        y2 (float): The maximum y coordinate.
+        cy (float): The center y coordinate.
+        width (float): The width of the object.
+        height(float): The height of the object.
+        scale ((float, float)): The x and yx and y scale of the object.
+
+    There is no setter for scale. Scale is a function of width and height.
+    Setting scale would be ambiguous. because the typical implementation of
+    scale would modify the x and y coordinates. If you want to scale an object,
+    set width and height.
+    """
+
+    def transform(
+        self,
+        transformation: _Matrix | None = None,
+        *,
+        scale: tuple[float, float] | float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+        reverse: bool = False,
+    ) -> None:
+        """Apply a transformation to the object."""
+        ...
+
+    @property
+    def x(self) -> float:
+        """Return minimum x coordinate."""
+        ...
+
+    @x.setter
+    def x(self, value: float) -> None:
+        """Set minimum x coordinate.
+
+        :param value: The minimum x coordinate.
+        """
+
+    @property
+    def x2(self) -> float:
+        """Return maximum x coordinate."""
+        ...
+
+    @x2.setter
+    def x2(self, value: float) -> None:
+        """Set maximum x coordinate.
+
+        :param value: The maximum x coordinate.
+        """
+
+    @property
+    def cx(self) -> float:
+        """Return center x coordinate."""
+        ...
+
+    @cx.setter
+    def cx(self, value: float) -> None:
+        """Set center x coordinate.
+
+        :param value: The center x coordinate.
+        """
+
+    @property
+    def y(self) -> float:
+        """Return minimum y coordinate."""
+        ...
+
+    @y.setter
+    def y(self, value: float) -> None:
+        """Set minimum y coordinate.
+
+        :param value: The minimum y coordinate.
+        """
+
+    @property
+    def y2(self) -> float:
+        """Return maximum y coordinate."""
+        ...
+
+    @y2.setter
+    def y2(self, value: float) -> None:
+        """Set maximum y coordinate.
+
+        :param value: The maximum y coordinate.
+        """
+
+    @property
+    def cy(self) -> float:
+        """Return center y coordinate."""
+        ...
+
+    @cy.setter
+    def cy(self, value: float) -> None:
+        """Set center y coordinate.
+
+        :param value: The center y coordinate.
+        """
+
+    @property
+    def width(self) -> float:
+        """Return width of the object."""
+        ...
+
+    @width.setter
+    def width(self, value: float) -> None:
+        """Set width of the object.
+
+        :param value: The width of the object.
+        """
+
+    @property
+    def height(self) -> float:
+        """Return height of the object."""
+        ...
+
+    @height.setter
+    def height(self, value: float) -> None:
+        """Set height of the object.
+
+        :param value: The height of the object.
+        """
+
+    @property
+    def scale(self) -> tuple[float, float]:
+        """Return scale of the object."""
+        ...
+
+    @scale.setter
+    def scale(self, value: tuple[float, float]) -> None:
+        """Return scale of the object.
+
+        :param value: The scale of the object.
+        """
+        ...

svg_ultralight/bounding_boxes/type_bound_collection.py

@@ -0,0 +1,74 @@
+"""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  # pyright: ignore[reportPrivateUsage]
+
+from svg_ultralight.bounding_boxes.bound_helpers import new_bbox_union
+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.supports_bounds import SupportsBounds
+    from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+
+_Matrix = tuple[float, float, float, float, float, float]
+
+
+@dataclasses.dataclass
+class BoundCollection(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 collection.
+
+        :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: tuple[float, float] | float | None = None,
+        dx: float | None = None,
+        dy: float | None = None,
+        reverse: bool = False,
+    ) -> 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
+        :param reverse: Transform the element as if it were in a <g> element
+            transformed by tmat.
+
+        Keep track of all compounding transformations in order to have a value for
+        self.scale (required for members 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, reverse=reverse)
+            else:
+                blem.transform(tmat, reverse=reverse)