plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/registry.py

@@ -0,0 +1,82 @@
+"""The registries of named things: ``color_maps``, ``markers``, ``styles`` and
+``layers`` (plot types), each with ``add(name, value)``, ``names()`` and ``get(name)``."""
+
+from collections.abc import Callable
+from typing import Any
+
+__all__ = ["Registry", "color_maps", "markers", "styles", "layers"]
+
+
+class Registry:
+    """Named values of one kind: ``add`` registers one (a name taken is replaced),
+    ``names`` lists them, ``get`` returns one (``ValueError`` for an unknown name)."""
+
+    __slots__ = ("kind", "_add", "_names", "_get")
+
+    def __init__(self, kind: str, add: Callable[..., None],
+                 names: Callable[..., list[str]], get: Callable[[str], Any]) -> None:
+        self.kind = kind
+        self._add, self._names, self._get = add, names, get
+
+    def add(self, name: str, value: Any, **options: Any) -> None:
+        """Register ``value`` as ``name`` (``options``: those of the kind's ``add``, such as
+        a color map's ``replace``)."""
+        self._add(name, value, **options)
+
+    def names(self, **options: Any) -> list[str]:
+        """The registered names, sorted (``options``: those of the kind's, such as a color
+        map's ``kind``)."""
+        return self._names(**options)
+
+    def get(self, name: str) -> Any:
+        """The value registered as ``name``."""
+        return self._get(name)
+
+    def __contains__(self, name: object) -> bool:
+        """Whether ``get(name)`` finds a value (aliases such as ``"o"`` included)."""
+        if not isinstance(name, str):
+            return False
+        try:
+            self._get(name)
+        except (KeyError, ValueError):
+            return False
+        return True
+
+    def __repr__(self) -> str:
+        return f"<registry of {self.kind}s: {len(self.names())}>"
+
+
+def _color_maps() -> Registry:
+    from .color import maps
+    return Registry("color map", maps.add_color_map, maps.color_map_names, maps.ColorMap)
+
+
+def _markers() -> Registry:
+    from . import markers as m
+    return Registry("marker", m.add_marker, lambda: sorted(m.MARKERS),
+                    lambda name: m.resolve(name)[0])
+
+
+def _styles() -> Registry:
+    from . import styles as s
+    return Registry("style", s.add_style, s.names, s.settings)
+
+
+def _layers() -> Registry:
+    from . import layers as la
+    return Registry("layer", la.add_layer, lambda: sorted(la.layer_types()), la.layer_type)
+
+
+#: Color maps of every kind: ``add(name, ColorMap or colors, replace=False, kind=None)`` (a
+#: bundled name only with ``replace=True``; not a ``"_r"`` name); ``get`` gives a
+#: ``ColorMap`` (``"_r"``: reversed; a variant word first: in that variant).
+color_maps = _color_maps()
+#: Marker shapes: ``add(name, vec_io Path or path data in a unit box)``; ``get`` gives the
+#: ``Path``.
+markers = _markers()
+#: Styles: ``add(name, dict of settings with an optional "base")``; ``get`` gives every key
+#: of the style's chain, ``DEFAULTS`` included (values as given).
+styles = _styles()
+#: Plot types: ``add(name, factory)`` adds ``plot.<name>(…)``, ``figure.<name>(…)`` and
+#: ``facets.<name>(…)``; ``get`` gives the factory.
+layers = _layers()

plot_io/render.py

@@ -0,0 +1,480 @@
+"""Drawing and output of figures.
+
+A figure is laid out first (:func:`plot_io.layout.layout`: every area measured into bands,
+the grid solved, each area placed into a frozen geometry); drawing reads that geometry and
+the settings' colors and widths, and draws the layers of each plot in its axes.  All
+lengths here are px.  Output is vec_io's (:meth:`vec_io.Document.write`): plot_io maps its
+own options (``quality``, resolutions, the background, ``simplify``, ``fonts``) and passes
+the rest.
+"""
+
+import contextlib
+import os
+from collections.abc import Generator
+from typing import Any
+
+import vec_io
+from vec_io.convert import FORMATS
+
+from . import text as _text
+from .canvas import Canvas
+from .color.values import resolve_color
+from .figure import output_quality
+from .layers.context import DrawContext
+from .layout import Geometry, layout
+from .settings import dpi, overriding, simplify_value
+from .spec import rendering, set_boxes
+from .states import z_key
+from .text import draw_paragraphs, draw_run
+from .titles import document_title
+
+__all__ = ["draw", "save", "write", "size", "Geometry", "layout", "draw_geometry"]
+
+
+def draw_layers(call: Any, ctx: Any, overlay: bool = False) -> None:
+    """Draw a call's layers (``overlay``: its value labels, drawn after every layer of the
+    plot)."""
+    c = ctx.for_call(call)
+    for layer in call.layers:
+        if layer.overlay == overlay:
+            seg = layer.options.get("segment")
+            if seg is None:
+                lay = layer.columns(c)
+                lay.geom.draw(c, lay)
+                continue
+            with seg.scope(c, clip=True) as cs:        # a region of several, side by side
+                lay = layer.columns(cs)
+                lay.geom.draw(cs, lay)
+
+
+def _draw_item(item: Any, ctx: Any) -> None:
+    if isinstance(item, list):                  # members of one call, in data order
+        from .layers.geoms import draw_in_order
+        if len(item) == 1 or not draw_in_order(ctx, item):
+            for c in item:
+                draw_layers(c, ctx)
+    elif hasattr(item, "layers") and hasattr(item, "series"):
+        draw_layers(item, ctx)
+    else:
+        item.draw(ctx)
+
+
+def _in_order(items: list[Any]) -> list[Any]:
+    """``items`` with the consecutive members of one call (``series._order_rows``: ``group=``
+    and level members) drawn alike (``z``, ``clip``, ``rasterize``) gathered in lists."""
+    out: list[Any] = []
+    last = None
+    for item in items:
+        s: Any = getattr(item, "series", None)
+        rows = None if s is None or not hasattr(item, "layers") else s.__dict__.get("_order_rows")
+        if s is None or rows is None:
+            out.append(item)
+            last = None
+            continue
+        key = (id(rows[0]), z_key(item),
+               *(s.resolve(k) if k in s.SETTINGS else None for k in ("clip", "rasterize")))
+        if key == last:
+            out[-1].append(item)
+        else:
+            out.append([item])
+            last = key
+    return out
+
+
+def _grid(canvas: Canvas, ctx: DrawContext, lines: Any) -> None:
+    from .lines import dash_of
+    x0, y0, x1, y1 = ctx.rect
+    for axis, prefix, horizontal, positions in lines:
+        width = axis.resolve(f"{prefix}_width")
+        with canvas.state():
+            canvas.stroke = resolve_color(axis.resolve(f"{prefix}_color"), ctx.cycle)
+            canvas.stroke_width = width
+            style = "solid" if prefix == "zero_line" else axis.resolve(f"{prefix}_style")
+            canvas.stroke_dasharray = dash_of(style, width)
+            path = vec_io.Path()
+            for p in positions:
+                if horizontal:
+                    path.move_to(x0, p).line_to(x1, p)
+                else:
+                    path.move_to(p, y0).line_to(p, y1)
+            canvas.draw_path(path, fill=None)
+
+
+def _spines(canvas: Canvas, spines: Any, cycle: Any) -> None:
+    with canvas.state():
+        canvas.stroke_linecap = "square"
+        for axis, (a, b, c, d) in spines:
+            lw = axis.resolve("line_width")
+            if not lw:
+                continue
+            canvas.stroke = resolve_color(axis.resolve("line_color"), cycle)
+            canvas.stroke_width = lw
+            canvas.draw_path(vec_io.Path().move_to(a, b).line_to(c, d), fill=None)
+
+
+def _axis(canvas: Canvas, state: Any, g: Any, cycle: Any) -> None:
+    if not g.shown:
+        return
+    axis = state.axis
+    for marks in g.marks:
+        with canvas.state():
+            canvas.stroke = resolve_color(axis.resolve("tick_color"), cycle)
+            canvas.stroke_width = axis.resolve("tick_width")
+            path = vec_io.Path()
+            for a, b, c, d in marks:
+                path.move_to(a, b).line_to(c, d)
+            canvas.draw_path(path, fill=None)
+    for r in g.labels:
+        draw_run(canvas, r)
+    draw_run(canvas, g.title)
+    draw_run(canvas, g.offset)
+
+
+def draw_plot(canvas: Canvas, g: Any) -> None:
+    """Draw a plot placed as ``g`` (:class:`~plot_io.geometry.PlotGeometry`)."""
+    ps = g.state
+    plot = ps.plot
+    x0, y0, x1, y1 = rect = g.rect
+    w, h = x1 - x0, y1 - y0
+    set_boxes(plot, axes_width=w, axes_height=h)
+    cycle = ps.cycle
+    ctx = DrawContext(canvas, plot, rect, ps.x, ps.y, cycle)
+    ctx.figure_size = g.figure_size
+    if g.legend is not None:                    # point labels keep clear of the legend
+        lx, ly, lw, lh = g.legend.box
+        ctx.avoid = [(lx, ly, lx + lw, ly + lh)]
+    bg = plot.resolve("background")
+    if bg is not None:
+        with canvas.state():
+            canvas.fill = resolve_color(bg, cycle)
+            canvas.draw_rect(x0, y0, w, h, stroke=None)
+    if ps.axes_on:
+        _grid(canvas, ctx, g.grid)
+    items = _in_order(sorted(list(ps.calls) + ps.decorations, key=z_key))
+    clipped = None
+    scope = contextlib.ExitStack()      # the clip of the calls drawn now
+    try:
+        for s in items:
+            obj = getattr(s[0] if isinstance(s, list) else s, "series", s)
+            own = obj.resolve("clip") if "clip" in obj.SETTINGS else True
+            want = bool(plot.resolve("clip")) and own is not False
+            if want != clipped:
+                scope.close()
+                scope.enter_context(canvas.state())
+                if want:
+                    canvas.clip(vec_io.Path().rect(x0, y0, w, h))
+                clipped = want
+            r = obj.resolve("rasterize") if "rasterize" in obj.SETTINGS else None
+            if r:
+                res = None if r is True else float(r)
+                with canvas.group(rasterize=True, dpi=res):
+                    _draw_item(s, ctx)
+            else:
+                _draw_item(s, ctx)
+    finally:
+        scope.close()
+    tctxs = []
+    for tg in g.twins:
+        t = tg.state
+        tctx = DrawContext(canvas, t.plot, rect, t.x, t.y, cycle)
+        tctx.figure_size = ctx.figure_size
+        tctxs.append((tg, tctx))
+        _grid(canvas, tctx, tg.grid)
+        with canvas.state():
+            if plot.resolve("clip"):
+                canvas.clip(vec_io.Path().rect(x0, y0, w, h))
+            for c in _in_order(list(t.calls)):
+                _draw_item(c, tctx)
+    for c in ps.calls:
+        draw_layers(c, ctx, overlay=True)
+    border = plot.resolve("border_color")
+    if border is not None and plot.resolve("border_width"):
+        with canvas.state():
+            canvas.stroke = resolve_color(border, cycle)
+            canvas.stroke_width = plot.resolve("border_width")
+            canvas.draw_path(vec_io.Path().rect(x0, y0, w, h), fill=None)
+    if ps.axes_on:
+        _spines(canvas, g.spines, cycle)
+        _axis(canvas, ps.x, g.x, cycle)
+        _axis(canvas, ps.y, g.y, cycle)
+    for tg, tctx in tctxs:
+        t = tg.state
+        _spines(canvas, tg.spines, t.cycle)
+        _axis(canvas, t.x, tg.x, cycle)
+        _axis(canvas, t.y, tg.y, cycle)
+        t.legend.draw(canvas, tctx, tg.legend)
+    for r in g.row_label:
+        draw_run(canvas, r)
+    for r in g.lane_names:
+        draw_run(canvas, r)
+    for r in (g.title if isinstance(g.title, tuple) else (g.title,)):
+        draw_run(canvas, r)
+    _rule(canvas, plot.title, g.title_rule)
+    for tg in g.titles:
+        _title(canvas, tg)
+    ps.legend.draw(canvas, ctx, g.legend)
+    for bg_ in g.bars:
+        bg_.state.draw(canvas, bg_)
+    for c in [ctx] + [t for _, t in tctxs]:
+        c.release()
+
+
+def _title(canvas: Canvas, tg: Any) -> None:
+    """A title placed as ``tg`` (:class:`~plot_io.geometry.TitleGeometry`): its runs or its
+    paragraph, then its rule."""
+    for r in tg.runs:
+        draw_run(canvas, r)
+    if tg.paragraph is not None:
+        x, y = tg.at
+        draw_paragraphs(canvas, tg.paragraph, x, y, tg.obj.resolve("color"))
+    _rule(canvas, tg.obj, tg.rule)
+
+
+def _rule(canvas: Canvas, title: Any, rect: Any) -> None:
+    """A title's rule (nothing for ``None``), in its ``rule_color``."""
+    if rect is None:
+        return
+    with canvas.state():
+        canvas.fill = resolve_color(title.resolve("rule_color"), ())
+        canvas.draw_rect(*rect, stroke=None)
+
+
+def draw_geometry(fig: Any, geom: Geometry, canvas: Canvas, fill: bool = True) -> None:
+    """Draw a laid-out figure (see :func:`plot_io.layout.layout`); ``fill``: its background
+    first."""
+    from .color.maps import cycle_of, map_of
+    from .lines import dash_of
+    bg = resolve_color(fig.resolve("background"), cycle_of(map_of(fig, "qualitative"))) \
+        if fill else None
+    if bg is not None:
+        with canvas.state():
+            canvas.fill = bg
+            canvas.draw_rect(0, 0, geom.width, geom.height, stroke=None)
+    f = geom.figure
+    for d, (x, y, w, h) in f.spans:
+        with canvas.state():
+            canvas.fill = resolve_color(d.resolve("color"), ())
+            canvas.opacity = d.resolve("opacity")
+            canvas.draw_rect(x, y, w, h, stroke=None)
+    for a in geom.areas:
+        if a.is_bar:
+            a.state.draw(canvas, a.geometry)
+        else:
+            draw_plot(canvas, a.geometry)
+    for d, (x0, y0, x1, y1) in f.lines:
+        w = d.resolve("line_width")
+        canvas.draw_lines([x0, x1], [y0, y1], stroke=resolve_color(d.resolve("color"), ()),
+                          stroke_width=w, stroke_dasharray=dash_of(d.resolve("line_style"), w),
+                          opacity=d.resolve("opacity"))
+    for r in f.groups:
+        draw_run(canvas, r)
+    for tg in f.titles:
+        _title(canvas, tg)
+    if f.legends:
+        contexts = {}
+        for a in geom.areas:
+            if not a.is_bar:
+                ps = a.state
+                c = DrawContext(canvas, ps.plot, a.axes, ps.x, ps.y, ps.cycle)
+                c.figure_size = (geom.width, geom.height)
+                contexts[id(ps.plot)] = c
+        for lg in f.legends:
+            lg.state.draw_figure(canvas, lg.legend, contexts)
+    for cg in f.colorbars:
+        cg.bar.state.draw(canvas, cg.bar)
+    _rule(canvas, fig.title, f.rule)
+    if f.title is not None:
+        draw_paragraphs(canvas, f.title, *f.title_at, fig.title.resolve("color"))
+
+
+def draw(fig: Any, canvas: Canvas, x: float = 0.0, y: float = 0.0,
+         only: Any = None) -> tuple[float, float]:
+    """Draw on a canvas (a vec_io page, a :class:`~plot_io.canvas.Recording`) at ``(x, y)``
+    (page units); returns the size in px.  Text is shaped with the fonts of the canvas'
+    document."""
+    with canvas.state():
+        scale = 0.75 / canvas.document.points_per_unit   # px → page units
+        canvas.translate(x, y)
+        if scale != 1.0:
+            canvas.scale(scale)
+        canvas.text_anchor = "start"
+        with rendering(fig):
+            geom = layout(fig, canvas.document.font_db, only)
+            draw_geometry(fig, geom, canvas)
+    return geom.width, geom.height
+
+
+#: Options of ``Document``: document-level choices.
+_DOC_KEYS = ("title", "author", "subject", "keywords", "creator", "base_dir", "creation_date")
+
+_IMAGES = ("png", "jpeg", "jxl", "avif")
+#: vec_io's view and page options, which plot_io does not take.
+_SIZE_KEYS = ("view", "pages")
+
+
+def output_kind(format: Any) -> str:
+    """The vec_io output kind of a format name or extension (``"jpg"`` is ``"jpeg"``)."""
+    kind = FORMATS.get(str(format).lower().lstrip("."))
+    if kind is None:
+        raise ValueError(f"unknown format {format!r}: use pdf, eps, svg, png, jpeg, jxl or "
+                         "avif")
+    return kind
+
+
+def fonts_of(fig: Any, value: Any = None) -> vec_io.Fonts:
+    """The fonts of an output: ``value`` (a vec_io ``Fonts`` or a dict of its fields), else
+    the figure's ``fonts``; a dict without ``system`` takes
+    :data:`plot_io.text.SYSTEM_FONTS`."""
+    if value is None:
+        value = fig.resolve("fonts")
+    if value is None or isinstance(value, dict):
+        value = {"system": _text.SYSTEM_FONTS, **(value or {})}
+    return vec_io.Fonts.of(value, "fonts")
+
+
+def font_db_of(fonts: vec_io.Fonts) -> Any:
+    """The font database of ``fonts``: its ``db``, else one shared between renders with
+    the same sources."""
+    if fonts.db is not None:
+        return fonts.db
+    return _text.document_db(fonts.dirs, fonts.system, fonts.downloads)
+
+
+def _page(fig: Any, only: Any, doc_opts: dict[str, Any], fill: bool = True,
+          fonts: Any = None, output: tuple[str, dict[str, Any]] | None = None) -> Any:
+    """A px document holding the figure on its one page (text shaped with ``fonts``, see
+    :func:`fonts_of`).  ``fill``: the figure's background drawn.  ``output``: ``(format,
+    write options)``, the output the page is recorded for (colours converted, text as
+    outlines with ``text="paths"``)."""
+    from vec_io.convert import recording_for
+
+    db = font_db_of(fonts_of(fig, fonts))
+    doc = vec_io.Document(unit="px", fonts=vec_io.Fonts(db=db), **doc_opts)
+    recording = contextlib.nullcontext() if output is None else recording_for(
+        doc, output[0], **output[1])
+    with rendering(fig), recording:
+        geom = layout(fig, doc.font_db, only)
+        page = doc.add_page(max(geom.width, 1.0), max(geom.height, 1.0))
+        draw_geometry(fig, geom, page, fill)
+    return page
+
+
+def size(fig: Any, only: Any = None) -> tuple[float, float]:
+    geom = layout(fig, font_db_of(fonts_of(fig)), only)
+    return geom.width, geom.height
+
+
+def quality_of(fig: Any, options: dict[str, Any]) -> Any:
+    """The ``quality`` option, else the figure's (an option of ``None`` is unset)."""
+    v = options.get("quality")
+    return fig.resolve("quality") if v is None else v
+
+
+@contextlib.contextmanager
+def _simplified(fig: Any, value: Any) -> Generator[None]:
+    """The figure's ``simplify`` taken as ``value`` while the body runs, in this thread
+    only (``None``: as it is); series with their own keep it."""
+    with overriding(fig, simplify=value):
+        yield
+
+
+def _with_quality(value: Any, cls: Any, what: str, quality: int | None) -> Any:
+    """Option ``value`` (an object, a dict of its fields or ``None``) with plot_io's
+    ``quality``: a dict or ``None`` takes it unless it sets its own; an object is used as
+    given."""
+    if value is not None and not isinstance(value, dict):
+        return cls.of(value, what)
+    fields = dict(value or {})
+    if quality is not None:
+        fields.setdefault("quality", quality)
+    return cls.of(fields, what) if fields else None
+
+
+def _flatten(value: Any) -> Any:
+    """``flatten``: a vec_io ``Flatten``, or a dict of its fields (``dpi`` as plot_io's
+    resolutions: ``"2x"`` is 192)."""
+    if isinstance(value, dict) and "dpi" in value:
+        value = {**value, "dpi": dpi(value["dpi"])}
+    return vec_io.Flatten.of(value, "flatten")
+
+
+def write(fig: Any, format: str = "pdf", only: Any = None, **options: Any) -> bytes:
+    """The figure (or the plot ``only``) as ``format`` bytes; ``options``: plot_io's
+    (``quality``, ``dpi``, ``default_dpi``, ``background``, ``simplify``, ``fonts``), the
+    ``Document``'s, and the rest :meth:`vec_io.Document.write`'s."""
+    kind = output_kind(format)
+    out = dict(options)
+    doc_opts = {k: out.pop(k) for k in _DOC_KEYS if k in out}
+    if "title" not in doc_opts:
+        doc_opts["title"] = document_title(fig, only)
+    elif not doc_opts["title"]:
+        doc_opts["title"] = None
+    fonts = out.pop("fonts", None)
+    for k in _SIZE_KEYS:
+        if k in out:
+            raise ValueError(f"{k} is not an output option of figures (their size and "
+                             "border are their width, height and margin settings)")
+    simplify = out.pop("simplify", None)
+    default_dpi = out.pop("default_dpi", None)
+    quality = output_quality(quality_of(fig, out), kind)
+    out.pop("quality", None)
+    if kind in _IMAGES:
+        cls = getattr(vec_io, kind.upper())
+        merged = _with_quality(out.get(kind), cls, kind, quality)
+        if merged is not None:
+            out[kind] = merged
+    else:
+        images = _with_quality(out.get("images"), vec_io.ImagePolicy, "images", quality)
+        if images is not None:
+            out["images"] = images
+    if simplify is not None:
+        simplify = out["simplify"] = simplify_value(simplify)
+    if out.get("dpi") is not None:
+        out["dpi"] = dpi(out["dpi"])
+    if out.get("flatten") is not None:
+        out["flatten"] = _flatten(out["flatten"])
+    fill = True
+    if kind in _IMAGES:
+        if out.get("dpi") is None:
+            out["dpi"] = dpi(default_dpi) if default_dpi is not None \
+                else fig.resolve("default_dpi")
+        from .color.maps import cycle_of, map_of
+        cycle = cycle_of(map_of(fig, "qualitative"))
+        if "background" in out:              # in place of the figure's
+            fill = False
+            out["background"] = resolve_color(out["background"], cycle)
+        else:
+            out["background"] = resolve_color(fig.resolve("background"), cycle)
+    with _simplified(fig, simplify):
+        page = _page(fig, only, doc_opts, fill, fonts, (kind, out))
+    return page.document.write(kind, **out)
+
+
+def save(fig: Any, file: Any, only: Any = None, format: str | None = None,
+         **options: Any) -> None:
+    """Write the figure to a path or a binary file object, in ``format`` (default: the
+    path's extension)."""
+    if format is None:
+        if hasattr(file, "write"):
+            raise ValueError("give the format of a figure written to a file object")
+        ext = os.path.splitext(os.fspath(file))[1].lower().lstrip(".")
+        if ext not in FORMATS:
+            raise ValueError(f"unknown format of {os.fspath(file)!r}: use .pdf, .eps, .svg, "
+                             ".png, .jpg, .jxl or .avif, or give format=")
+        format = ext
+    data = write(fig, format, only, **options)
+    if hasattr(file, "write"):
+        file.write(data)
+    else:
+        with open(file, "wb") as f:
+            f.write(data)
+
+
+def repr_svg(fig: Any, only: Any = None, include: Any = None,
+             exclude: Any = None) -> dict[str, str]:
+    """The notebook bundle: ``{"image/svg+xml": svg}`` (as ``write("svg")``), or ``{}`` when
+    ``include`` leaves the type out or ``exclude`` names it."""
+    kind = "image/svg+xml"
+    if (include is not None and kind not in include) or (exclude is not None and kind in exclude):
+        return {}
+    return {kind: write(fig, "svg", only).decode("utf-8")}