figworks 0.8.0__py3-none-any.whl

figworks/__init__.py

@@ -0,0 +1,23 @@
+"""Public FigWorks API."""
+
+from figworks.collection import FigureCollection
+from figworks.core.display import display_svg
+from figworks.figure import Anchor, Figure, Panel, Theme
+from figworks.figure.layout import layout_svgs
+from figworks.matplotlib import compose
+from figworks.style import load_theme
+
+__all__ = [
+    "Anchor",
+    "Figure",
+    "FigureCollection",
+    "Panel",
+    "Theme",
+    "__version__",
+    "compose",
+    "display_svg",
+    "layout_svgs",
+    "load_theme",
+]
+
+__version__ = "0.8.0"

figworks/_export.py

@@ -0,0 +1,34 @@
+"""Internal SVG export helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import cairosvg
+from cairosvg.surface import PDFSurface, cairo
+
+
+class _ReproduciblePDF(PDFSurface):
+    """CairoSVG's PDF surface without the creation date cairo stamps by default.
+
+    The date makes every PDF differ from the last; an empty value omits it.
+    """
+
+    def _create_surface(self, width: float, height: float) -> tuple[Any, float, float]:
+        surface, width, height = super()._create_surface(width, height)
+        surface.set_metadata(cairo.PDF_METADATA_CREATE_DATE, "")
+        return surface, width, height
+
+
+def svg_to_pdf(svg_string: str, path: str | Path) -> None:
+    _ReproduciblePDF.convert(bytestring=svg_string.encode("utf-8"), write_to=str(path))
+
+
+def svg_to_png(svg_string: str, path: str | Path, dpi: int = 300) -> None:
+    # cairosvg's `dpi` only converts physical units, leaving px lengths at one
+    # pixel each. Resolving at the CSS 96 DPI and scaling rasterizes every unit
+    # at `dpi`.
+    cairosvg.svg2png(
+        bytestring=svg_string.encode("utf-8"), write_to=str(path), dpi=96, scale=dpi / 96
+    )

figworks/collection.py

@@ -0,0 +1,206 @@
+"""Regenerate a set of figures from one command.
+
+A *collection* is one set of figures sharing a style, an output directory, and
+a list of formats -- a thesis, a paper, a talk.  Register each figure once, and
+the collection builds, saves, and closes them:
+
+    HERE = Path(__file__).resolve().parent
+
+    THESIS = FigureCollection(outdir=HERE / "figures", style=HERE / "style.md")
+
+    @THESIS.figure("majorana_network")
+    def majorana_network() -> Figure:
+        ...
+
+    if __name__ == "__main__":
+        THESIS.main()
+
+A builder returns either a FigWorks :class:`~figworks.Figure` or a Matplotlib
+figure, and knows nothing about file paths.  Both kinds are written as vector
+files where the format allows, byte-identically from run to run, and only after
+their fonts are checked.  Each collection has its own registry, so a second
+one -- slides with a larger theme, say -- can coexist without mixing figures.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from figworks.style import Theme
+
+# A builder takes no arguments and returns the finished figure.  The collection
+# owns styling, saving, and closing, so builders stay free of file paths.
+type FigureBuilder = Callable[[], Any]
+
+# PDF for LaTeX, SVG for hand editing, PNG for slides and quick previews.
+DEFAULT_FORMATS: tuple[str, ...] = ("pdf", "svg", "png")
+
+
+def git_revision(cwd: Path) -> str:
+    """Short commit the figures were generated from, for provenance."""
+    git = shutil.which("git")
+    if git is None:
+        return "unknown"
+    try:
+        out = subprocess.run(
+            [git, "rev-parse", "--short", "HEAD"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return "unknown"
+    return out.stdout.strip() or "unknown"
+
+
+@dataclass
+class FigureCollection:
+    """One set of figures sharing a style, an output directory, and formats.
+
+    Args:
+        outdir: Where the files are written, one per figure and format.
+        style: The set's style: a built-in name, a path to a ``style.md``, or a
+            loaded :class:`~figworks.style.Theme`.  Every Matplotlib figure is
+            built under the settings it generates.
+        formats: File formats to write, from ``svg``, ``pdf``, and ``png``.
+        dpi: Resolution of PNG output.
+    """
+
+    outdir: Path
+    style: str | Path | Theme = "paper"
+    formats: Sequence[str] = DEFAULT_FORMATS
+    dpi: int = 300
+    builders: dict[str, FigureBuilder] = field(default_factory=dict, init=False)
+
+    def __post_init__(self) -> None:
+        unknown = sorted(set(self.formats) - {"svg", "pdf", "png"})
+        if unknown:
+            raise ValueError(f"unsupported format(s): {', '.join(unknown)}")
+
+    def figure(self, name: str) -> Callable[[FigureBuilder], FigureBuilder]:
+        """Register a figure builder under its output file name, without suffix."""
+
+        def decorator(func: FigureBuilder) -> FigureBuilder:
+            if name in self.builders:
+                raise ValueError(f"Figure {name!r} is already registered.")
+            self.builders[name] = func
+            return func
+
+        return decorator
+
+    def apply_style(self) -> None:
+        """Set Matplotlib to this collection's style, from a clean slate.
+
+        Matplotlib's defaults first, so a run never inherits settings left by
+        an earlier import or notebook session, then the settings the style
+        generates.  :meth:`build` restores the previous settings afterwards.
+        """
+        import matplotlib.pyplot as plt
+
+        from figworks.style import load_theme
+
+        plt.style.use("default")
+        plt.rcParams.update(load_theme(self.style).rc())
+
+    def save_figure(self, name: str, fig: Any, outdir: Path | None = None) -> list[Path]:
+        """Write one figure once per format; returns the paths written."""
+        from matplotlib.figure import Figure as MplFigure
+
+        from figworks.figure.figure import Figure
+        from figworks.matplotlib import save_figure
+
+        outdir = outdir or self.outdir
+        outdir.mkdir(parents=True, exist_ok=True)
+        written = []
+        for suffix in self.formats:
+            path = outdir / f"{name}.{suffix}"
+            if isinstance(fig, Figure):
+                fig.save(path, dpi=self.dpi)
+            elif isinstance(fig, MplFigure):
+                save_figure(fig, path, dpi=self.dpi)
+            else:
+                raise TypeError(
+                    f"figure {name!r} returned {type(fig).__name__}; a builder must "
+                    "return a FigWorks Figure or a Matplotlib figure"
+                )
+            written.append(path)
+        return written
+
+    def build(self, names: Sequence[str], outdir: Path | None = None) -> list[Path]:
+        """Build and save the named figures in the order given; returns the paths.
+
+        Matplotlib's settings are restored afterwards, so building from a
+        notebook leaves its style alone.
+        """
+        import matplotlib.pyplot as plt
+        from matplotlib.figure import Figure as MplFigure
+
+        written: list[Path] = []
+        with plt.rc_context():
+            self.apply_style()
+            for name in names:
+                fig = self.builders[name]()
+                try:
+                    paths = self.save_figure(name, fig, outdir)
+                finally:
+                    if isinstance(fig, MplFigure):
+                        plt.close(fig)
+                    # Plots placed into a FigWorks figure stay open otherwise.
+                    plt.close("all")
+                written += paths
+                print(f"  {name}: " + ", ".join(p.name for p in paths))
+        return written
+
+    def main(self, argv: Sequence[str] | None = None) -> None:
+        """Command-line entry point: ``--list``, ``--all``, or figure names."""
+        import matplotlib
+
+        # Headless here, not on import: a notebook importing FigWorks keeps its backend.
+        matplotlib.use("Agg")
+        prog = Path(sys.argv[0]).name
+        parser = argparse.ArgumentParser(prog=prog, description="Regenerate registered figures.")
+        parser.add_argument(
+            "names", nargs="*", help="figures to build (default: none; use --all or --list)"
+        )
+        parser.add_argument("--all", action="store_true", help="build every figure")
+        parser.add_argument("--list", action="store_true", help="list registered figures and exit")
+        parser.add_argument(
+            "--outdir",
+            type=Path,
+            default=self.outdir,
+            help=f"output directory (default: {self.outdir})",
+        )
+        args = parser.parse_args(argv)
+
+        if not self.builders:
+            parser.error("no figures are registered in this collection")
+
+        if args.list:
+            for name, func in sorted(self.builders.items()):
+                summary = (func.__doc__ or "").strip().splitlines()
+                print(f"{name:<24} {summary[0] if summary else ''}")
+            return
+
+        names = sorted(self.builders) if args.all else list(args.names)
+        if not names:
+            parser.error("no figures requested; pass names, --all, or --list")
+        unknown = [name for name in names if name not in self.builders]
+        if unknown:
+            parser.error(
+                f"unknown figure(s): {', '.join(unknown)}\n"
+                f"registered: {', '.join(sorted(self.builders))}"
+            )
+
+        revision = git_revision(Path.cwd())
+        print(f"Generating {len(names)} figure(s) at revision {revision}")
+        written = self.build(names, args.outdir)
+        print(f"Wrote {len(written)} file(s) to {args.outdir}")

figworks/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core SVG document primitives."""
+
+from figworks.core.document import SVGDocument
+from figworks.core.selectors import Selection
+from figworks.core.units import to_px
+
+__all__ = ["SVGDocument", "Selection", "to_px"]

figworks/core/display.py

@@ -0,0 +1,38 @@
+"""Helpers for displaying SVG output in notebooks and terminals."""
+
+from __future__ import annotations
+
+import base64
+
+
+def display_svg(source: object) -> None:
+    """Render an SVG as an inline image in a Jupyter notebook.
+
+    Accepts an SVG string, a matplotlib figure, or a :class:`figworks.Figure`.
+    Falls back gracefully when IPython is not available.
+    """
+    svg = _to_svg(source)
+    try:
+        from IPython.display import HTML, display
+    except ImportError:
+        print(svg)
+        return
+    data = base64.b64encode(svg.encode("utf-8")).decode("ascii")
+    display(HTML(f'<img src="data:image/svg+xml;base64,{data}" alt="FigWorks SVG"/>'))
+
+
+def _to_svg(source: object) -> str:
+    from matplotlib.figure import Figure as MplFigure
+
+    if isinstance(source, str):
+        return source
+    if isinstance(source, MplFigure):
+        from figworks.matplotlib import mpl_to_svg
+
+        return mpl_to_svg(source)
+    to_string = getattr(getattr(source, "document", None), "to_string", None)
+    if callable(to_string):
+        svg = to_string()
+        if isinstance(svg, str):
+            return svg
+    raise TypeError("Expected an SVG string, a matplotlib Figure, or a FigWorks Figure")

figworks/core/document.py

@@ -0,0 +1,376 @@
+"""Internal SVG document engine."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import svg
+from lxml import etree
+
+from figworks.core.element import (
+    ALIGN,
+    accumulated_scale,
+    copy_element,
+    ensure_defs,
+    fit_transform,
+    local_name,
+    parse_svg,
+    resolve_id_collisions,
+    svg_intrinsic_size,
+    svg_kwargs,
+    svg_physical_size,
+    svg_to_lxml,
+)
+from figworks.core.selectors import Selection, select
+from figworks.core.units import px_decimal, svg_length, to_px
+
+
+class SVGDocument:
+    """Canonical lxml-backed SVG document."""
+
+    def __init__(self, width: str | int | float, height: str | int | float) -> None:
+        self._imports = 0
+        self.width = svg_length(width)
+        self.height = svg_length(height)
+        self.width_px = to_px(width)
+        self.height_px = to_px(height)
+        # The canvas is declared in physical units but every element is placed in
+        # px user units, so the root needs a viewBox to bind the two.  Without it
+        # a renderer maps one user unit to one px at its own default 96 DPI while
+        # sizing the canvas from the physical attributes, and any export above
+        # 96 DPI leaves the content in a corner at the wrong scale.
+        self.root = svg_to_lxml(
+            svg.SVG(
+                viewBox=svg.ViewBoxSpec(0, 0, self.width_px, self.height_px),
+                extra={"version": "1.1"},
+            ),
+            raw={"width": self.width, "height": self.height},
+        )
+
+    def element(self, tag: str, text: str | None = None, **attrs: Any) -> etree._Element:
+        constructors = {
+            "circle": svg.Circle,
+            "ellipse": svg.Ellipse,
+            "g": svg.G,
+            "line": svg.Line,
+            "path": svg.Path,
+            "polyline": svg.Polyline,
+            "rect": svg.Rect,
+            "text": svg.Text,
+        }
+        try:
+            constructor = constructors[tag]
+        except KeyError as exc:
+            raise ValueError(f"Unsupported native SVG element: {tag!r}") from exc
+        return svg_to_lxml(constructor(text=text, **svg_kwargs(attrs)))
+
+    def append(
+        self,
+        element: etree._Element,
+        parent: etree._Element | None = None,
+    ) -> etree._Element:
+        # `parent or self.root` would silently retarget the root: an lxml
+        # element with no children is falsy, so an empty group is discarded.
+        (self.root if parent is None else parent).append(element)
+        return element
+
+    def group(
+        self,
+        id: str | None = None,
+        class_: str | None = None,
+        transform: str | None = None,
+        parent: etree._Element | None = None,
+    ) -> etree._Element:
+        group = svg_to_lxml(
+            svg.G(id=id, class_=None if class_ is None else [class_]),
+            raw={"transform": transform},
+        )
+        return self.append(group, parent)
+
+    def defs(self) -> etree._Element:
+        return ensure_defs(self.root)
+
+    def import_svg(
+        self,
+        svg_string: str,
+        id: str | None = None,
+        transform: str | None = None,
+        parent: etree._Element | None = None,
+        *,
+        namespace: str | None = None,
+    ) -> etree._Element:
+        """Import an SVG document's content as a group, keeping its ids unique.
+
+        Imported ids are kept unless one already exists in this document; a
+        colliding id is prefixed with ``namespace`` (default: ``id``) and its
+        references inside the content follow.  See
+        :func:`~figworks.core.element.resolve_id_collisions`.
+        """
+        if id is not None and self.root.find(f".//*[@id='{id}']") is not None:
+            raise ValueError(f"Id {id!r} is already used in this figure")
+        imported_root = parse_svg(svg_string)
+        group = self.group(id=id, transform=transform, parent=parent)
+        self._imports += 1
+        prefix = namespace or id or f"import{self._imports}"
+        for duplicate in resolve_id_collisions(imported_root, self.root, prefix):
+            # Identical to a definition already in the document: share that one.
+            parent = duplicate.getparent()
+            if parent is not None:
+                parent.remove(duplicate)
+
+        for child in imported_root:
+            if local_name(child) == "defs":
+                self.defs().extend(copy_element(definition) for definition in child)
+            else:
+                group.append(copy_element(child))
+
+        return group
+
+    def placeholder(
+        self,
+        id: str,
+        x: float,
+        y: float,
+        w: float,
+        h: float,
+        label: str | None = None,
+    ) -> etree._Element:
+        """Create a rectangular placeholder that can be filled later by id.
+
+        The placeholder is drawn with a dashed outline so it is visible while
+        composing a figure.
+        """
+        rect = svg_to_lxml(
+            svg.Rect(
+                id=id,
+                class_=["figworks-placeholder"],
+                x=px_decimal(x),
+                y=px_decimal(y),
+                width=px_decimal(w),
+                height=px_decimal(h),
+                fill="none",
+                stroke="#999999",
+                stroke_width=px_decimal(0.5),
+                stroke_dasharray=[4, 3],
+            )
+        )
+        self.append(rect)
+        if label is not None:
+            self.append(
+                svg_to_lxml(
+                    svg.Text(
+                        text=label,
+                        x=px_decimal(x + w / 2),
+                        y=px_decimal(y + h / 2),
+                        class_=["figworks-placeholder-label"],
+                        extra={"data-figworks-placeholder": id},
+                        text_anchor="middle",
+                        dominant_baseline="middle",
+                    )
+                )
+            )
+        return rect
+
+    def fill(
+        self,
+        id: str,
+        svg_string: str,
+        *,
+        preserve_aspect_ratio: bool = True,
+    ) -> etree._Element:
+        """Replace the placeholder (or any element) with imported SVG content.
+
+        The content is positioned and scaled to fit inside the target element's
+        bounding box, swapping vector SVG content in by id.
+
+        Returns the wrapping group that holds the imported content.
+        """
+        targets = self.select(f"#{id}")
+        if len(targets) == 0:
+            raise KeyError(f"No element with id {id!r} in document")
+        target = targets.nodes[0]
+        box = element_box(target)
+        for label in self.root.iter():
+            if label.get("data-figworks-placeholder") == id:
+                parent = label.getparent()
+                if parent is not None:
+                    parent.remove(label)
+        return self._place_in_placeholder(target, box, svg_string, preserve_aspect_ratio)
+
+    def fill_plane(self, id: str, svg_string: str) -> etree._Element:
+        """Fill a unit-square group with SVG content, normalized to fit it.
+
+        The target is a group whose own transform maps content coordinates in
+        ``[0, 1]^2`` onto wherever it belongs -- typically an ``vecview`` scene
+        plane, whose transform sends the unit square onto a rectangle of a world
+        plane, so the content ends up lying *in* the scene rather than on top of
+        it.  This method only normalizes: it leaves the target's transform alone
+        and appends the content beneath it.
+
+        The normalization is non-uniform by construction -- content of any size
+        is mapped onto the same unit square -- so the target rectangle must be
+        shaped to the content's aspect ratio or the content comes out stretched.
+        For an ``vecview`` plane that means ``|u_edge| / |v_edge|`` equal to the
+        content's ``width / height``.
+
+        Returns the wrapping group holding the imported content.
+        """
+        targets = self.select(f"#{id}")
+        if len(targets) == 0:
+            raise KeyError(f"No element with id {id!r} in document")
+        target = targets.nodes[0]
+
+        width, height, min_x, min_y = svg_intrinsic_size(svg_string)
+        if not width or not height:
+            raise ValueError(f"Content for {id!r} has no intrinsic size to normalize")
+
+        shift = f" translate({-min_x:g} {-min_y:g})" if (min_x or min_y) else ""
+        transform = f"scale({1 / width:g} {1 / height:g}){shift}"
+        return self.import_svg(svg_string, transform=transform, parent=target, namespace=id)
+
+    def fill_slot(self, id: str, svg_string: str) -> etree._Element:
+        """Fill an anchor group with SVG content at the content's own physical size.
+
+        The target is a group translated to an anchor point -- typically a
+        VecView ``Scene.slot`` -- whose ``data-align`` names the point of the
+        content's box that sits on the anchor (``center`` when absent).  The
+        content keeps the size its document declares however the enclosing
+        scene was scaled to fit its panel: an 8 pt label stays 8 pt.  The
+        anchor itself moves with the scene.
+
+        Returns the wrapping group holding the imported content.
+        """
+        targets = self.select(f"#{id}")
+        if len(targets) == 0:
+            raise KeyError(f"No element with id {id!r} in document")
+        target = targets.nodes[0]
+
+        align = target.get("data-align", "center")
+        if align not in ALIGN:
+            raise ValueError(
+                f"Slot {id!r} has unknown data-align {align!r}; expected one of {sorted(ALIGN)}"
+            )
+        view_w, view_h, min_x, min_y = svg_intrinsic_size(svg_string)
+        width, height = svg_physical_size(svg_string)
+        if not (view_w and view_h and width and height):
+            raise ValueError(f"Content for {id!r} has no intrinsic size to place")
+
+        fx, fy = ALIGN[align]
+        shift = f" translate({-min_x:g} {-min_y:g})" if (min_x or min_y) else ""
+        transform = (
+            f"scale({1 / accumulated_scale(target):g})"
+            f" translate({-fx * width:g} {-fy * height:g})"
+            f" scale({width / view_w:g} {height / view_h:g}){shift}"
+        )
+        return self.import_svg(svg_string, transform=transform, parent=target, namespace=id)
+
+    def place(
+        self,
+        svg_string: str,
+        x: float,
+        y: float,
+        width: float,
+        height: float,
+        *,
+        id: str | None = None,
+        preserve_aspect_ratio: bool = True,
+        parent: etree._Element | None = None,
+        align: str = "center",
+    ) -> etree._Element:
+        """Place SVG content directly in a layout box."""
+        transform = fit_transform(
+            (x, y, width, height),
+            svg_intrinsic_size(svg_string),
+            preserve_aspect_ratio=preserve_aspect_ratio,
+            align=align,
+        )
+        return self.import_svg(svg_string, id=id, transform=transform, parent=parent)
+
+    def _place_in_placeholder(
+        self,
+        target: etree._Element,
+        box: tuple[float, float, float, float],
+        svg_string: str,
+        preserve_aspect_ratio: bool = True,
+    ) -> etree._Element:
+        x, y, w, h = box
+        parent = target.getparent()
+        if parent is None:
+            parent = self.root
+        index = list(parent).index(target)
+        parent.remove(target)
+
+        transform = fit_transform(
+            (x, y, w, h),
+            svg_intrinsic_size(svg_string),
+            preserve_aspect_ratio=preserve_aspect_ratio,
+        )
+
+        group = self.import_svg(svg_string, namespace=target.get("id"))
+        if not preserve_aspect_ratio:
+            group.set("preserveAspectRatio", "none")
+        parent.insert(index, group)
+        group.set("transform", transform)
+        return group
+
+    def select(self, selector: str) -> Selection:
+        return select(self.root, selector)
+
+    def delete(self, selector: str) -> Selection:
+        return self.select(selector).delete()
+
+    def set_style(self, selector: str, **style: str | int | float) -> Selection:
+        return self.select(selector).set_style(**style)
+
+    def to_string(self) -> str:
+        return etree.tostring(
+            self.root,
+            encoding="unicode",
+            pretty_print=True,
+            xml_declaration=False,
+        )
+
+    def save(self, path: str | Path) -> None:
+        Path(path).write_text(self.to_string(), encoding="utf-8")
+
+
+def extract_path_box(node: etree._Element) -> tuple[float, float, float, float]:
+    """Estimate a bounding box (x, y, w, h) from a node's path data."""
+    d = node.get("d", "") or node.get("points", "")
+    xs: list[float] = []
+    ys: list[float] = []
+    a1, a2 = xs, ys
+    for token in d.split():
+        try:
+            a1.append(float(token))
+            a1, a2 = a2, a1
+        except ValueError:
+            continue
+    if not xs or not ys:
+        return 0.0, 0.0, 0.0, 0.0
+    min_x, min_y = min(xs), min(ys)
+    return min_x, min_y, max(xs) - min_x, max(ys) - min_y
+
+
+def element_box(node: etree._Element) -> tuple[float, float, float, float]:
+    """Return (x, y, width, height) for an element's layout box."""
+    name = etree.QName(node).localname
+    if name in {"image", "rect"}:
+        x = float(node.get("x", 0.0))
+        y = float(node.get("y", 0.0))
+        w = float(node.get("width", 0.0))
+        h = float(node.get("height", 0.0))
+        return x, y, w, h
+    if name in ("path", "polyline"):
+        return extract_path_box(node)
+    if name == "g":
+        boxes = [element_box(child) for child in node]
+        boxes = [box for box in boxes if box[2] and box[3]]
+        if boxes:
+            min_x = min(box[0] for box in boxes)
+            min_y = min(box[1] for box in boxes)
+            max_x = max(box[0] + box[2] for box in boxes)
+            max_y = max(box[1] + box[3] for box in boxes)
+            return min_x, min_y, max_x - min_x, max_y - min_y
+    return 0.0, 0.0, 0.0, 0.0