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

svg_ultralight/__init__.py

@@ -14,6 +14,11 @@ from svg_ultralight.bounding_boxes.bound_helpers import (
     pad_bbox,
     parse_bound_element,
 )
+from svg_ultralight.bounding_boxes.padded_text_initializers import (
+    pad_text,
+    pad_text_ft,
+    pad_text_mix,
+)
 from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
 from svg_ultralight.bounding_boxes.type_bound_collection import BoundCollection
 from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
@@ -25,6 +30,7 @@ from svg_ultralight.constructors.new_element import (
     new_sub_element,
     update_element,
 )
+from svg_ultralight.font_tools.comp_results import check_font_tools_alignment
 from svg_ultralight.inkscape import (
     write_pdf,
     write_pdf_from_svg,
@@ -39,7 +45,6 @@ from svg_ultralight.query import (
     clear_svg_ultralight_cache,
     get_bounding_box,
     get_bounding_boxes,
-    pad_text,
 )
 from svg_ultralight.root_elements import new_svg_root_around_bounds
 from svg_ultralight.string_conversion import (
@@ -63,6 +68,7 @@ __all__ = [
     "PaddedText",
     "SupportsBounds",
     "bbox_dict",
+    "check_font_tools_alignment",
     "clear_svg_ultralight_cache",
     "cut_bbox",
     "deepcopy_element",
@@ -87,6 +93,8 @@ __all__ = [
     "new_svg_root_around_bounds",
     "pad_bbox",
     "pad_text",
+    "pad_text_ft",
+    "pad_text_mix",
     "parse_bound_element",
     "transform_element",
     "update_element",

svg_ultralight/animate.py

@@ -16,13 +16,13 @@ except ModuleNotFoundError as exc:
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    import os
     from collections.abc import Iterable
-    from pathlib import Path
 
 
 def write_gif(
-    gif: str | Path,
-    pngs: Iterable[str] | Iterable[Path] | Iterable[str | Path],
+    gif: str | os.PathLike[str],
+    pngs: Iterable[str] | Iterable[os.PathLike[str]] | Iterable[str | os.PathLike[str]],
     duration: float = 100,
     loop: int = 0,
 ) -> None:

svg_ultralight/bounding_boxes/padded_text_initializers.py

@@ -0,0 +1,184 @@
+"""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.
+
+:author: Shay Hill
+:created: 2025-06-09
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+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 (
+    get_padded_text_info,
+    get_svg_font_attributes,
+)
+from svg_ultralight.font_tools.globs import DEFAULT_FONT_SIZE
+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]
+    )
+
+DEFAULT_Y_BOUNDS_REFERENCE = "{[|gjpqyf"
+
+
+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)
+    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)
+
+
+def pad_text_ft(
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float = DEFAULT_FONT_SIZE,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    **attributes: str | float,
+) -> PaddedText:
+    """Create a new PaddedText instance using 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 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_ = format_attr_dict(**attributes)
+    attributes_.update(get_svg_font_attributes(font))
+    attributes_["font-size"] = attributes_.get("font-size", format_number(font_size))
+
+    elem = new_element("text", text=text, **attributes_)
+    info = get_padded_text_info(
+        font, text, font_size, ascent, descent, y_bounds_reference=y_bounds_reference
+    )
+    return PaddedText(elem, info.bbox, *info.padding, info.line_gap)
+
+
+def pad_text_mix(
+    inkscape: str | os.PathLike[str],
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float = DEFAULT_FONT_SIZE,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    **attributes: str | float,
+) -> 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 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.
+    """
+    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,
+        **attributes,
+    )
+    bbox = padded_inkscape.unpadded_bbox
+    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)

svg_ultralight/bounding_boxes/type_bounding_box.py

@@ -41,6 +41,18 @@ class HasBoundingBox(SupportsBounds):
         y2 = y + self.bbox.base_height
         return (x, y), (x2, y), (x2, y2), (x, y2)
 
+    def values(self) -> tuple[float, float, float, float]:
+        """Get the values of the bounding box.
+
+        :return: x, y, width, height of the bounding box
+        """
+        return (
+            self.bbox.x,
+            self.bbox.y,
+            self.bbox.width,
+            self.bbox.height,
+        )
+
     def _get_transformed_corners(
         self,
     ) -> tuple[

svg_ultralight/bounding_boxes/type_padded_text.py

@@ -66,6 +66,8 @@ from __future__ import annotations
 
 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
@@ -77,6 +79,14 @@ if TYPE_CHECKING:
 
 _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`."""
+)
+
 
 class PaddedText(BoundElement):
     """A line of text with a bounding box and padding."""
@@ -89,6 +99,7 @@ class PaddedText(BoundElement):
         rpad: float,
         bpad: float,
         lpad: float,
+        line_gap: float | None = None,
     ) -> None:
         """Initialize a PaddedText instance.
 
@@ -105,6 +116,7 @@ class PaddedText(BoundElement):
         self.rpad = rpad
         self.base_bpad = bpad
         self.lpad = lpad
+        self._line_gap = line_gap
 
     @property
     def bbox(self) -> BoundingBox:
@@ -153,6 +165,32 @@ class PaddedText(BoundElement):
         self.unpadded_bbox.transform(tmat)
         _ = transform_element(self.elem, tmat)
 
+    @property
+    def line_gap(self) -> float:
+        """The line gap between this line of text and the next.
+
+        :return: The line gap between this line of text and the next.
+        """
+        if self._line_gap is None:
+            raise AttributeError(_no_line_gap_msg)
+        return self._line_gap
+
+    @line_gap.setter
+    def line_gap(self, value: float) -> None:
+        """Set the line gap between this line of text and the next.
+
+        :param value: The new line gap.
+        """
+        self._line_gap = value
+
+    @property
+    def leading(self) -> float:
+        """The leading of this line of text.
+
+        :return: The line gap plus the height of this line of text.
+        """
+        return self.height + self.line_gap
+
     @property
     def tpad(self) -> float:
         """The top padding of this line of text.

svg_ultralight/font_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Mark font_tools as a package.
+
+:author: Shay Hill
+:created: 2025-06-04
+"""

svg_ultralight/font_tools/comp_results.py

@@ -0,0 +1,283 @@
+"""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.
+
+See Enum `FontBboxError` for the possible error codes and their meanings returned by
+`check_font`.
+
+You can use `draw_comparison` to debug or explore differences between fontTools and
+Inkscape.
+
+:author: Shay Hill
+:created: 2025-06-08
+"""
+
+from __future__ import annotations
+
+import enum
+import itertools as it
+import string
+import sys
+from pathlib import Path
+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,
+)
+from svg_ultralight.constructors import new_element
+from svg_ultralight.font_tools.font_info import get_svg_font_attributes
+from svg_ultralight.main import write_svg
+from svg_ultralight.root_elements import new_svg_root_around_bounds
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Iterator
+
+    from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+
+
+class FontBboxError(enum.Enum):
+    """Classify the type of error between Inkscape and fontTools bounding boxes.
+
+    INIT: Use `pad_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` PaddedText constructor.
+    This font may work with other or ascii-only text.
+
+    ELEM_Y: Use `pad_text` or `pad_text_mix` 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
+    `pad_bbox_ft` and `pad_bbox_mix`. You can use either of these functions with a
+    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`.
+
+    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.
+
+    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`.
+
+    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
+    SAFE_ELEM_X, but also does not exist for any font on my system.
+
+    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.
+    """
+
+    INIT = enum.auto()
+    ELEM_Y = enum.auto()
+    SAFE_ELEM_X = enum.auto()
+    LINE_Y = enum.auto()
+    SAFE_LINE_X = enum.auto()
+    NO_ERROR = enum.auto()
+
+
+# ===================================================================================
+#   Produce some commonly used Western UTF-8 characters for test text.
+# ===================================================================================
+
+
+def _get_western_utf8() -> str:
+    """Return a string of the commonly used Western UTF-8 character set."""
+    western = " ".join(
+        [
+            string.ascii_lowercase,
+            string.ascii_uppercase,
+            string.digits,
+            string.punctuation,
+            "áÁéÉíÍóÓúÚñÑäÄëËïÏöÖüÜçÇàÀèÈìÌòÒùÙâÂêÊîÎôÔûÛãÃõÕåÅæÆøØœŒßÿŸ",
+        ]
+    )
+    return western + " "
+
+
+DEFAULT_TEST_TEXT = _get_western_utf8()
+
+
+def _format_bbox_error(
+    bbox_a: BoundingBox, bbox_b: BoundingBox
+) -> tuple[int, int, int, int]:
+    """Return the difference between two bounding boxes as a percentage of height."""
+    width = bbox_a.width
+    height = bbox_a.height
+    diff = (
+        bbox_b.x - bbox_a.x,
+        bbox_b.y - bbox_a.y,
+        bbox_b.width - bbox_a.width,
+        bbox_b.height - bbox_a.height,
+    )
+    scaled_diff = (x / y for x, y in zip(diff, (height, height, width, height)))
+    dx, dy, dw, dh = (int(x * 100) for x in scaled_diff)
+    return dx, dy, dw, dh
+
+
+def check_font_tools_alignment(
+    inkscape: str | os.PathLike[str],
+    font: str | os.PathLike[str],
+    text: str | None = None,
+) -> tuple[FontBboxError, tuple[int, int, int, int] | None]:
+    """Return an error code and the difference b/t Inkscape and fontTools bboxes.
+
+    :param inkscape: path to an Inkscape executable
+    :param font_path: path to the font file
+    :return: a tuple of the error code and the percentage difference between the
+        bounding boxes as a tuple of (dx, dy, dw, dh) or (error, None) if there was
+        an error initializing fontTools.
+    """
+    if text is None:
+        text = DEFAULT_TEST_TEXT
+    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_ft = pad_text_ft(
+            font,
+            text,
+            y_bounds_reference=DEFAULT_Y_BOUNDS_REFERENCE,
+        )
+    except Exception:
+        return FontBboxError.INIT, None
+
+    error = _format_bbox_error(rslt_pt.unpadded_bbox, rslt_ft.unpadded_bbox)
+    if error[1] or error[3]:
+        return FontBboxError.ELEM_Y, error
+    if error[0] or error[2]:
+        return FontBboxError.SAFE_ELEM_X, error
+
+    error = _format_bbox_error(rslt_pt.bbox, rslt_ft.bbox)
+    if error[1] or error[3]:
+        return FontBboxError.LINE_Y, error
+    if error[0] or error[2]:
+        return FontBboxError.SAFE_LINE_X, error
+
+    return FontBboxError.NO_ERROR, None
+
+
+def draw_comparison(
+    inkscape: str | os.PathLike[str],
+    output: str | os.PathLike[str],
+    font: str | os.PathLike[str],
+    text: str | None = None,
+) -> None:
+    """Draw a font in Inkscape and fontTools.
+
+    :param inkscape: path to an Inkscape executable
+    :param output: path to the output SVG file
+    :param font: path to the font file
+    :param text: the text to render. If None, the font name will be used.
+    :effect: Writes an SVG file to the output path.
+
+    Compare the rendering and bounding boxes of a font in Inkscape and fontTools. The
+    bounding boxes drawn will always be accurate, but some fonts will not render the
+    Inkscape version in a browser. Conversely, Inskcape will not render the fontTools
+    version in Inkscape, because Inkscape does not read locally linked fonts. It
+    usually works, and it a good place to start if you'd like to compare fontTools
+    and Inkscape results.
+    """
+    if text is None:
+        text = Path(font).stem
+    font_size = 12
+    font_attributes = get_svg_font_attributes(font)
+    text_elem = new_element("text", text=text, **font_attributes, font_size=font_size)
+    padded_pt = pad_text(inkscape, text_elem)
+    padded_ft = pad_text_ft(
+        font,
+        text,
+        font_size,
+        y_bounds_reference=DEFAULT_Y_BOUNDS_REFERENCE,
+        fill="none",
+        stroke="orange",
+        stroke_width=0.05,
+    )
+
+    root = new_svg_root_around_bounds(pad_bbox(padded_pt.bbox, 10))
+    root.append(
+        new_bbox_rect(
+            padded_pt.unpadded_bbox, fill="none", stroke_width=0.07, stroke="red"
+        )
+    )
+    root.append(
+        new_bbox_rect(
+            padded_ft.unpadded_bbox, fill="none", stroke_width=0.05, stroke="blue"
+        )
+    )
+    root.append(padded_pt.elem)
+    root.append(padded_ft.elem)
+    _ = sys.stdout.write(f"{Path(font).stem} comparison drawn at {output}.\n")
+    _ = write_svg(Path(output), root)
+
+
+def _iter_fonts(*fonts_dirs: Path) -> Iterator[Path]:
+    """Yield a path to each ttf and otf file in the given directories.
+
+    :param fonts_dir: directory to search for ttf and otf files, multiple ok
+    :yield: paths to ttf and otf files in the given directories
+
+    A helper function for _test_every_font_on_my_system.
+    """
+    if not fonts_dirs:
+        return
+    head, *tail = fonts_dirs
+    ttf_files = head.glob("*.[tt][tt][ff]")
+    otf_files = head.glob("*.[oO][tT][fF]")
+    yield from it.chain(ttf_files, otf_files)
+    yield from _iter_fonts(*tail)
+
+
+def _test_every_font_on_my_system(
+    inkscape: str | os.PathLike[str],
+    font_dirs: list[Path],
+    text: str | None = None,
+) -> None:
+    """Test every font on my system."""
+    if not Path(inkscape).with_suffix(".exe").exists():
+        _ = sys.stdout.write(f"Inkscape not found at {inkscape}\n")
+        return
+    font_dirs = [x for x in font_dirs if x.exists()]
+    if not font_dirs:
+        _ = sys.stdout.write("No font directories found.\n")
+        return
+
+    counts = dict.fromkeys(FontBboxError, 0)
+    for font_path in _iter_fonts(*font_dirs):
+        error, diff = check_font_tools_alignment(inkscape, font_path, text)
+        counts[error] += 1
+        if error is not FontBboxError.NO_ERROR:
+            _ = sys.stdout.write(f"Error with {font_path.name}: {error.name} {diff}\n")
+    for k, v in counts.items():
+        _ = sys.stdout.write(f"{k.name}: {v}\n")
+
+
+if __name__ == "__main__":
+    _INKSCAPE = Path(r"C:\Program Files\Inkscape\bin\inkscape")
+    _FONT_DIRS = [
+        Path(r"C:\Windows\Fonts"),
+        Path(r"C:\Users\shaya\AppData\Local\Microsoft\Windows\Fonts"),
+    ]
+    _test_every_font_on_my_system(_INKSCAPE, _FONT_DIRS)
+
+    font = Path(r"C:\Windows\Fonts\arial.ttf")
+    draw_comparison(_INKSCAPE, "temp.svg", font)