svg-ultralight 0.64.0__py3-none-any.whl

svg_ultralight/image_ops.py

@@ -0,0 +1,156 @@
+"""Crop an image before converting to binary and including in the svg file.
+
+This optional module requires the Pillow library. Create an svg image element with a
+rasterized image positioned inside a bounding box.
+
+:author: Shay Hill
+:created: 2024-11-20
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from paragraphs import par
+
+try:
+    from PIL import Image
+
+    if TYPE_CHECKING:
+        from PIL.Image import Image as ImageType
+except ImportError as err:
+    msg = par(
+        """PIL is not installed. Install it using 'pip install Pillow' to use
+        svg_ultralight.image_ops module."""
+    )
+    raise ImportError(msg) from err
+
+import base64
+import io
+
+from lxml import etree
+
+from svg_ultralight import NSMAP
+from svg_ultralight.bounding_boxes.bound_helpers import bbox_dict
+from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
+from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+from svg_ultralight.constructors import new_element
+
+if TYPE_CHECKING:
+    import os
+
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore [reportPrivateUsage]
+    )
+
+
+def _symmetric_crop(
+    image: ImageType, center: tuple[float, float] | None = None
+) -> ImageType:
+    """Crop an image symmetrically around a center point.
+
+    :param image: PIL.Image instance
+    :param center: optional center point for cropping. Proportions of image with and
+        image height, so the default value, (0.5, 0.5), is the true center of the
+        image.  (0.4, 0.5) would crop 20% off the right side of the image.
+    :return: PIL.Image instance
+    """
+    if center is None:
+        return image
+
+    if not all(0 < x < 1 for x in center):
+        msg = "Center must be between (0, 0) and (1, 1)"
+        raise ValueError(msg)
+
+    xd, yd = (min(x, 1 - x) for x in center)
+    left, right = sorted(x * image.width for x in (center[0] - xd, center[0] + xd))
+    top, bottom = sorted(x * image.height for x in (center[1] - yd, center[1] + yd))
+
+    return image.crop((left, top, right, bottom))
+
+
+def _crop_image_to_bbox_ratio(
+    image: ImageType, bbox: BoundingBox, center: tuple[float, float] | None
+) -> ImageType:
+    """Crop an image to the ratio of a bounding box.
+
+    :param image: PIL.Image instance
+    :param bbox: BoundingBox instance
+    :param center: optional center point for cropping. Proportions of image with and
+        image height, so the default value, (0.5, 0.5), is the true center of the
+        image. (0.4, 0.5) would crop 20% off the right side of the image.
+    :return: PIL.Image instance
+
+    This crops the image to the specified ratio. It's not a resize, so it will cut
+    off the top and bottom or the sides of the image to fit the ratio.
+    """
+    image = _symmetric_crop(image, center)
+    width, height = image.size
+
+    ratio = bbox.width / bbox.height
+    if width / height > ratio:
+        new_width = height * ratio
+        left = (width - new_width) / 2
+        right = width - left
+        return image.crop((left, 0, right, height))
+    new_height = width / ratio
+    top = (height - new_height) / 2
+    bottom = height - top
+    return image.crop((0, top, width, bottom))
+
+
+def _get_svg_embedded_image_str(image: ImageType) -> str:
+    """Return the string you'll need to embed an image in an svg.
+
+    :param image: PIL.Image instance
+    :return: argument for xlink:href
+    """
+    in_mem_file = io.BytesIO()
+    image.save(in_mem_file, format="PNG")
+    _ = in_mem_file.seek(0)
+    img_bytes = in_mem_file.read()
+    base64_encoded_result_bytes = base64.b64encode(img_bytes)
+    base64_encoded_result_str = base64_encoded_result_bytes.decode("ascii")
+    return "data:image/png;base64," + base64_encoded_result_str
+
+
+def new_image_blem(
+    filename: str | os.PathLike[str],
+    bbox: BoundingBox | None = None,
+    center: tuple[float, float] | None = None,
+) -> BoundElement:
+    """Create a new svg image element inside a bounding box.
+
+    :param filename: filename of source image
+    :param bbox: bounding box for the image
+    :param center: center point for cropping. Proportions of image width and image
+        height, so the default value, (0.5, 0.5), is the true center of the image.
+        (0.4, 0.5) would crop 20% off the right side of the image.
+    :return: a BoundElement element with the cropped image embedded
+    """
+    image = Image.open(filename)
+    if bbox is None:
+        bbox = BoundingBox(0, 0, image.width, image.height)
+    image = _crop_image_to_bbox_ratio(Image.open(filename), bbox, center)
+    svg_image = new_element("image", **bbox_dict(bbox))
+    svg_image.set(
+        etree.QName(NSMAP["xlink"], "href"), _get_svg_embedded_image_str(image)
+    )
+    return BoundElement(svg_image, bbox)
+
+
+def new_image_elem_in_bbox(
+    filename: str | os.PathLike[str],
+    bbox: BoundingBox | None = None,
+    center: tuple[float, float] | None = None,
+) -> EtreeElement:
+    """Create a new svg image element inside a bounding box.
+
+    :param filename: filename of source image
+    :param bbox: bounding box for the image
+    :param center: center point for cropping. Proportions of image width and image
+        height, so the default value, (0.5, 0.5), is the true center of the image.
+        (0.4, 0.5) would crop 20% off the right side of the image.
+    :return: an etree image element with the cropped image embedded
+    """
+    return new_image_blem(filename, bbox, center).elem

svg_ultralight/inkscape.py

@@ -0,0 +1,261 @@
+"""Operations on existing svg files.
+
+This module contains Inkscape calls for manipulating svg files after they have been
+created, but not necessarily written to disk. These are just wrappers around
+selections from the Inkscape command line interface.
+
+Inkscape cli calls generally take the form
+
+   inkscape --some-option input_filename.svg --export-filename=export_filename.svg
+
+This module allows you to optionally make these calls with svg root elements instead
+of filenames. In such cases, the root elements will be written to a temporary file,
+the Inkscape CLI called, and something returned.
+
+:author: Shay Hill
+:created: 2023-02-14
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import TYPE_CHECKING
+
+from lxml import etree
+
+from svg_ultralight import main
+
+if TYPE_CHECKING:
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+
+def write_png_from_svg(
+    inkscape: str | os.PathLike[str],
+    svg: str | os.PathLike[str],
+    png: str | os.PathLike[str] | None = None,
+) -> str:
+    """Convert an svg file to a png.
+
+    :param inkscape: path to inkscape executable
+    :param svg: path to svg file
+    :param png: optional path to png output file
+    :return: png filename
+    :effects: creates a new png from svg filename
+    :raises ValueError: if unable to write png. This could result from an error with
+        Inkscape.
+
+    If no output png path is given, the output path will be inferred from the ``svg``
+    filename.
+    """
+    inkscape = Path(inkscape).with_suffix("")  # remove .exe if present
+    png = str(Path(svg).with_suffix(".png")) if png is None else str(png)
+
+    # inkscape versions >= 1.0
+    options = [f'"{svg}"', "--export-type=png", f'--export-filename="{png}"']
+    return_code = subprocess.call(f'"{inkscape}" ' + " ".join(options))
+    if return_code == 0:
+        return png
+
+    # inkscape versions < 1.0
+    return_code = subprocess.call(f'"{inkscape}" -f "{svg}" -e "{png}"')
+    if return_code == 0:
+        return png
+
+    msg = f"failed to write {png} with inkscape {inkscape}"
+    raise ValueError(msg)
+
+
+def write_png(
+    inkscape: str | os.PathLike[str],
+    png: str | os.PathLike[str],
+    root: EtreeElement,
+    stylesheet: str | os.PathLike[str] | None = None,
+) -> str:
+    """Create a png file without writing an intermediate svg file.
+
+    :param inkscape: path to inkscape executable
+    :param png: path to output png file
+    :param root: root node of your svg geometry
+    :param stylesheet: optional path to css stylesheet
+    :return: png filename (the same you input as ``png``)
+    :effects: creates a new png file
+
+    This just creates a tempfile, writes the svg to the tempfile, then calls
+    ``write_png_from_svg`` with the tempfile. This isn't faster (it might be slightly
+    slower), but it keeps the filesystem clean when you only want the png.
+    """
+    with NamedTemporaryFile(mode="wb", delete=False) as svg_file:
+        svg = main.write_svg(svg_file, root, stylesheet)
+    _ = write_png_from_svg(inkscape, svg, png)
+    os.unlink(svg)
+    return str(png)
+
+
+def write_pdf_from_svg(
+    inkscape: str | os.PathLike[str],
+    svg: str | os.PathLike[str],
+    pdf: str | os.PathLike[str] | None = None,
+) -> str:
+    """Convert an svg file to a pdf.
+
+    :param inkscape: path to inkscape executable
+    :param svg: path to svg file
+    :param pdf: optional path to png output file
+    :return: pdf filename
+    :effects: creates a new pfd from svg filename
+    :raises ValueError: if unable to write pdf. This could result from an error with
+        Inkscape.
+
+    If no output png path is given, the output path will be inferred from the ``svg``
+    filename.
+    """
+    inkscape = Path(inkscape).with_suffix("")  # remove .exe if present
+    pdf = str(Path(svg).with_suffix(".pdf")) if pdf is None else str(pdf)
+
+    # inkscape versions >= 1.0
+    options = [f'"{svg}"', "--export-type=pdf", f'--export-filename="{pdf}"']
+    return_code = subprocess.call(f'"{inkscape}" ' + " ".join(options))
+    if return_code == 0:
+        return pdf
+
+    # inkscape versions < 1.0
+    return_code = subprocess.call(f'"{inkscape}" -f "{svg}" -e "{pdf}"')
+    if return_code == 0:
+        return pdf
+
+    msg = f"failed to write {pdf} from {svg}"
+    raise ValueError(msg)
+
+
+def write_pdf(
+    inkscape: str | os.PathLike[str],
+    pdf: str | os.PathLike[str],
+    root: EtreeElement,
+    stylesheet: str | os.PathLike[str] | None = None,
+) -> str:
+    """Create a pdf file without writing an intermediate svg file.
+
+    :param inkscape: path to inkscape executable
+    :param pdf: path to output pdf file
+    :param root: root node of your svg geometry
+    :param stylesheet: optional path to css stylesheet
+    :return: pdf filename (the same you input as ``pdf``)
+    :effects: creates a new pdf file
+
+    This just creates a tempfile, writes the svg to the tempfile, then calls
+    ``write_pdf_from_svg`` with the tempfile. This isn't faster (it might be slightly
+    slower), but it keeps the filesystem clean when you only want the pdf.
+    """
+    with NamedTemporaryFile(mode="wb", delete=False) as svg_file:
+        svg = main.write_svg(svg_file, root, stylesheet)
+    _ = write_pdf_from_svg(inkscape, svg, pdf)
+    os.unlink(svg)
+    return str(pdf)
+
+
+def export_text_to_path(
+    inkscape: str | os.PathLike[str],
+    input_file: str | os.PathLike[str],
+    export_file: str | os.PathLike[str],
+) -> str:
+    """Export copy of svg file with text converted to paths.
+
+    :param inkscape: Path to inkscape executable.
+    :param input_file: Path to svg file.
+    :param export_file: Path to result.
+    :return: Path to result.
+    :effect: Writes to export_file.
+
+    Find any text objects in an svg file and convert them to paths.
+    """
+    inkscape = Path(inkscape).with_suffix("")  # remove .exe if present
+    command = [
+        str(inkscape),
+        "--export-text-to-path",
+        "--export-plain-svg",
+        str(input_file),
+        f"--export-filename={export_file}",
+    ]
+    _ = subprocess.call(command)
+    return str(export_file)
+
+
+def convert_text_to_path(
+    inkscape: str | os.PathLike[str], root: EtreeElement
+) -> EtreeElement:
+    """Convert text to path in a root svg element.
+
+    :param inkscape: Path to inkscape executable.
+    :param root: SVG root element.
+    :return: SVG root element with text converted to path.
+    """
+    with tempfile.NamedTemporaryFile(suffix=".svg", delete=False) as f:
+        _ = main.write_svg(f, root)
+        temp_input = f.name
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_export = Path(temp_dir) / "export.svg"
+        _ = export_text_to_path(inkscape, temp_input, temp_export)
+        root = etree.parse(temp_export).getroot()
+    os.unlink(temp_input)
+    return root
+
+
+def write_root(
+    inkscape: str | os.PathLike[str],
+    filename: str | os.PathLike[str],
+    root: EtreeElement,
+    *,
+    do_text_to_path: bool = True,
+    do_svg: bool = True,
+    do_png: bool | str | os.PathLike[str] = False,
+    do_pdf: bool | str | os.PathLike[str] = False,
+) -> EtreeElement:
+    """Save xml in multiple file formats, optionally updating text to paths.
+
+    :param inkscape: Path to the Inkscape executable or command.
+    :param filename: Path to the output svg file.
+    :param root: The XML element to be saved.
+    :param do_text_to_path: Whether to convert text to paths.
+    :param do_svg: Whether to save the file in SVG format.
+    :param do_png: Whether to save the file in PNG format. If True, the output
+        filename will be generated from the filename argument. Optionally
+        explicity specify an output path.
+    :param do_pdf: Whether to save the file in PDF format. If True, the output
+        filename will be generated from the filename argument. Optionally
+        explicity specify an output path.
+    :return: The XML element that was saved.
+
+    This is an umbrella function over the other functions in this module. If you
+    have Inkscape installed, this function will likeley be a better choice than
+    `write_svg`, even if it will not accept IO objects as filename arguments.
+
+    The largest errors between Inkscape and browsers have to do with text. If the
+    browser doesn't know about your font (even if it *should*), your svg will
+    not look the same in your browser (or book) as it does in Inkscape. It's
+    good practice to save all svg images with text using this function.
+    """
+    output_svg = Path(filename).with_suffix(".svg")
+    output_png = output_svg.with_suffix(".png") if isinstance(do_png, bool) else do_png
+    output_pdf = output_svg.with_suffix(".pdf") if isinstance(do_pdf, bool) else do_pdf
+
+    if do_text_to_path and next(root.itertext(), None) is not None:
+        root = convert_text_to_path(inkscape, root)
+    if do_svg:
+        _ = main.write_svg(output_svg, root)
+    if do_png:
+        if do_svg:
+            _ = write_png_from_svg(inkscape, output_svg, output_png)
+        else:
+            _ = write_png(inkscape, output_png, root)
+    if do_pdf:
+        if do_svg:
+            _ = write_pdf_from_svg(inkscape, output_svg, output_pdf)
+        else:
+            _ = write_pdf(inkscape, output_pdf, root)
+    return root