imagespec 0.1.0__py3-none-any.whl

imagespec/__init__.py

@@ -0,0 +1,57 @@
+"""imagespec — render images from a declarative YAML/dict spec.
+
+Public API:
+
+    from imagespec import render, RenderContext
+
+    ctx = RenderContext(font_resolver=..., history_provider=...)
+    image = render(payload, width=296, height=128, rotate=0,
+                   background="white", context=ctx)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .colors import (
+    PALETTE_4,
+    PALETTE_7,
+    PALETTE_BW,
+    PALETTE_BWR,
+    PALETTES,
+    get_index_color,
+    get_palette,
+    quantize_color,
+)
+from .context import RenderContext
+from .core import ROTATE_MODE_CANVAS, ROTATE_MODE_IMAGE, render
+from .exceptions import RenderError
+from .registry import known_types
+from .resolvers import caching_resolver, chain_resolvers, directory_resolver
+
+__all__ = [
+    "render",
+    "RenderContext",
+    "RenderError",
+    "ROTATE_MODE_CANVAS",
+    "ROTATE_MODE_IMAGE",
+    "PALETTE_BW",
+    "PALETTE_BWR",
+    "PALETTE_4",
+    "PALETTE_7",
+    "PALETTES",
+    "get_palette",
+    "quantize_color",
+    "get_index_color",
+    "known_types",
+    "caching_resolver",
+    "chain_resolvers",
+    "directory_resolver",
+]
+
+# The version is defined statically in pyproject.toml.
+# We read it dynamically here via importlib.metadata.
+try:
+    __version__ = version("imagespec")
+except PackageNotFoundError:
+    __version__ = "unknown"

imagespec/colors.py

@@ -0,0 +1,157 @@
+"""Color handling for limited-palette displays.
+
+Different devices support different palettes — 2-color (black/white),
+4-color (+red/yellow), 7-color (ACeP), etc. The palette is therefore **not**
+hardcoded here: it lives on :class:`~imagespec.context.RenderContext` and is
+passed in per render. Any requested color (name or ``#RRGGBB``) is *quantized*
+to the nearest color the device can actually show.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+# ── Canonical named colors (RGBA) ──────────────────────────────────────────
+white = (255, 255, 255, 255)
+black = (0, 0, 0, 255)
+red = (255, 0, 0, 255)
+yellow = (255, 255, 0, 255)
+green = (0, 128, 0, 255)
+blue = (0, 0, 255, 255)
+orange = (255, 165, 0, 255)
+
+NAMED_COLORS = {
+    "white": white,
+    "w": white,
+    "black": black,
+    "b": black,
+    "red": red,
+    "r": red,
+    "yellow": yellow,
+    "y": yellow,
+    "green": green,
+    "g": green,
+    "blue": blue,
+    "orange": orange,
+    "o": orange,
+}
+
+# ── Device palettes (ordered subsets of the canonical colors) ──────────────
+PALETTE_BW = [black, white]  # 2-color
+PALETTE_BWR = [black, white, red]  # 3-color (BWR)
+PALETTE_BWY = [black, white, yellow]  # 3-color (BWY)
+PALETTE_4 = [black, white, red, yellow]  # 4-color
+PALETTE_7 = [black, white, red, green, blue, yellow, orange]  # 7-color (ACeP)
+
+# Optional shorthand aliases — never required; you can always pass an explicit
+# list of colors (see get_palette).
+PALETTES = {
+    "2": PALETTE_BW,
+    "bw": PALETTE_BW,
+    "mono": PALETTE_BW,
+    "3": PALETTE_BWR,
+    "bwr": PALETTE_BWR,
+    "bwy": PALETTE_BWY,
+    "4": PALETTE_4,
+    "7": PALETTE_7,
+    "acep": PALETTE_7,
+}
+
+DEFAULT_PALETTE = PALETTE_4
+
+
+def _normalize_color(c):
+    """Resolve one palette entry to an RGBA tuple.
+
+    Accepts a color name ("red"), a HEX string ("#ff0000"), or an
+    ``(r, g, b)`` / ``(r, g, b, a)`` tuple/list.
+    """
+    if isinstance(c, (tuple, list)):
+        if len(c) == 3:
+            return (int(c[0]), int(c[1]), int(c[2]), 255)
+        if len(c) == 4:
+            return (int(c[0]), int(c[1]), int(c[2]), int(c[3]))
+        raise ValueError(f"Invalid palette color {c!r}: expected 3 or 4 components")
+    s = str(c).strip().lower()
+    if s in NAMED_COLORS:
+        return NAMED_COLORS[s]
+    if s.startswith("#"):
+        h = s.lstrip("#")
+        if len(h) >= 6:
+            return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), 255)
+    raise ValueError(f"Unknown palette color {c!r} (not a known name or #RRGGBB)")
+
+
+def get_palette(spec):
+    """Resolve a palette specification to a list of RGBA tuples.
+
+    ``spec`` may be:
+
+    * a shorthand name/count string — ``"2"``/``"bw"``, ``"4"``, ``"7"``/``"acep"``, ...
+    * a list of colors, each a name (``"red"``), HEX (``"#ff0000"``), or
+      ``(r, g, b[, a])`` tuple — e.g. ``["black", "white", "red"]``.
+    """
+    if isinstance(spec, str):
+        key = spec.strip().lower()
+        if key not in PALETTES:
+            raise ValueError(f"Unknown palette '{spec}'. Use a list of colors, or one of: {sorted(PALETTES)}")
+        return PALETTES[key]
+    colors = [_normalize_color(c) for c in spec]
+    if not colors:
+        raise ValueError("palette must contain at least one color")
+    return colors
+
+
+def _requested_rgb(color):
+    """Resolve a color name or ``#RRGGBB`` to an RGBA tuple, or ``None``."""
+    if color is None:
+        return None
+    s = str(color).strip().lower()
+    if s in NAMED_COLORS:
+        return NAMED_COLORS[s]
+    if s.startswith("#"):
+        try:
+            h = s.lstrip("#")
+            if len(h) >= 6:
+                return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), 255)
+        except ValueError:
+            pass
+        return white
+    return white
+
+
+def nearest_in_palette(rgba, palette):
+    """Return the palette color closest to ``rgba`` (Euclidean in RGB)."""
+    best = palette[0]
+    best_dist = float("inf")
+    for c in palette:
+        dist = (rgba[0] - c[0]) ** 2 + (rgba[1] - c[1]) ** 2 + (rgba[2] - c[2]) ** 2
+        if dist < best_dist:
+            best_dist = dist
+            best = c
+    return best
+
+
+def quantize_color(color, palette):
+    """Map a requested color to the nearest color the device supports.
+
+    Returns ``None`` for a ``None`` input (meaning "no fill").
+    """
+    rgb = _requested_rgb(color)
+    if rgb is None:
+        return None
+    snapped = nearest_in_palette(rgb, palette)
+    if _LOGGER.isEnabledFor(logging.DEBUG) and tuple(rgb) != tuple(snapped):
+        _LOGGER.debug("color %s -> %s (palette size %d)", color, snapped, len(palette))
+    return snapped
+
+
+def get_index_color(color):
+    """Back-compat shim: quantize against the default 4-color palette.
+
+    Prefer ``RenderContext.color(...)`` inside handlers so the device's actual
+    palette is used.
+    """
+    return quantize_color(color, DEFAULT_PALETTE)

imagespec/context.py

@@ -0,0 +1,103 @@
+"""Render context: the seam where framework-specific behaviour is injected.
+
+The core renderer must not import Home Assistant. Anything it needs from the
+host application is provided through :class:`RenderContext`:
+
+* ``font_resolver`` — given a font name (as written in a payload), return an
+  absolute path to a ``.ttf``/``.otf`` file, or ``None`` to fall back to the
+  fonts bundled with this package. This is where an integration plugs in its
+  ``hass.config.path("www/fonts")`` lookup.
+* ``history_provider`` — given entity ids and a ``[start, end]`` window, return
+  historical states for the ``plot`` element. Only required if a payload uses
+  ``plot``; otherwise it can be left ``None``.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from PIL import ImageFont
+
+from .colors import DEFAULT_PALETTE, get_palette, quantize_color
+from .exceptions import RenderError
+
+FontResolver = Callable[[str], str | None]
+HistoryProvider = Callable[[Sequence[str], Any, Any], dict[str, Any]]
+
+_PKG_DIR = os.path.dirname(__file__)
+BUNDLED_FONTS_DIR = os.path.join(_PKG_DIR, "fonts")
+BUNDLED_ICONS_DIR = os.path.join(_PKG_DIR, "icons")
+
+
+def _bundled_font_path(name: str) -> str | None:
+    path = os.path.join(BUNDLED_FONTS_DIR, os.path.basename(name))
+    return path if os.path.exists(path) else None
+
+
+@dataclass
+class RenderContext:
+    """Host-supplied capabilities and defaults for a render call."""
+
+    font_resolver: FontResolver | None = None
+    history_provider: HistoryProvider | None = None
+    default_font: str = "NotoSansKR-Regular.ttf"
+    icons_dir: str = BUNDLED_ICONS_DIR
+    # Security: whether `dlimg` may open local/relative filesystem paths.
+    # Off by default — only http(s)/data URLs are allowed unless opted in.
+    allow_local_images: bool = False
+    # Device color palette. Accepts a list of RGBA tuples, or a name/count
+    # string ("2"/"bw", "4", "7"/"acep", ...). See colors.PALETTES.
+    palette: Any = field(default_factory=lambda: DEFAULT_PALETTE)
+    # Cache keyed by (resolved path, size) so repeated text elements are cheap.
+    _font_cache: dict[tuple[str, int], ImageFont.FreeTypeFont] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self):
+        # Allow palette to be given as a friendly name ("7", "bw", ...).
+        self.palette = get_palette(self.palette)
+
+    def color(self, value):
+        """Quantize a requested color to this device's palette (or ``None``)."""
+        return quantize_color(value, self.palette)
+
+    def resolve_font_path(self, name: str | None) -> str:
+        """Resolve a payload font name to an absolute file path.
+
+        Order: injected resolver → bundled font of the same basename →
+        bundled default font.
+        """
+        name = name or self.default_font
+        if self.font_resolver is not None:
+            p = self.font_resolver(name)
+            if p and os.path.exists(p):
+                return p
+        p = _bundled_font_path(name)
+        if p:
+            return p
+        p = _bundled_font_path(self.default_font)
+        if p:
+            return p
+        raise RenderError(
+            f"Font '{name}' could not be resolved and no bundled default ('{self.default_font}') is available."
+        )
+
+    def font(self, name: str | None, size) -> ImageFont.FreeTypeFont:
+        """Return a (cached) truetype font for ``name`` at ``size``."""
+        path = self.resolve_font_path(name)
+        key = (path, int(size))
+        cached = self._font_cache.get(key)
+        if cached is None:
+            cached = ImageFont.truetype(path, int(size))
+            self._font_cache[key] = cached
+        return cached
+
+    def history(self, entity_ids: Sequence[str], start, end) -> dict[str, Any]:
+        """Fetch historical states for the ``plot`` element."""
+        if self.history_provider is None:
+            raise RenderError(
+                "This payload uses 'plot', which needs historical data, but the "
+                "RenderContext has no history_provider configured."
+            )
+        return self.history_provider(entity_ids, start, end)

imagespec/core.py

@@ -0,0 +1,117 @@
+"""The render loop: turn a payload + size into a PIL image."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from PIL import Image
+
+# Importing the elements package registers all handlers via @element(...).
+from . import elements  # noqa: E402,F401  (side-effect import)
+from .context import RenderContext
+from .exceptions import RenderError
+from .registry import get_handler
+from .state import RenderState
+from .utils import should_show
+
+_LOGGER = logging.getLogger(__name__)
+
+# Rotation strategies — device-dependent (see docstring below).
+ROTATE_MODE_CANVAS = "canvas"  # gicisky / fixed-resolution e-ink panels
+ROTATE_MODE_IMAGE = "image"  # niimbot / variable-size label printers
+_ROTATE_MODES = (ROTATE_MODE_CANVAS, ROTATE_MODE_IMAGE)
+
+
+def render(
+    payload: Sequence[dict],
+    width: int,
+    height: int,
+    *,
+    rotate: int = 0,
+    rotate_mode: str = ROTATE_MODE_CANVAS,
+    background="white",
+    dither: bool = False,
+    context: RenderContext,
+) -> Image.Image:
+    """Render ``payload`` to an ``RGB`` :class:`PIL.Image.Image`.
+
+    Parameters
+    ----------
+    payload:
+        Sequence of element dicts (already parsed from YAML/JSON).
+    width, height:
+        Canvas dimensions you author against. ``RenderState.canvas_width`` /
+        ``canvas_height`` always reflect the actual surface being drawn on, so
+        element coordinates are written in this frame regardless of rotation.
+    rotate:
+        0/90/180/270 (always rotated back at the end via ``-rotate``).
+    rotate_mode:
+        How 90/270 rotation is handled — this differs by device:
+
+        * ``"canvas"`` (default, gicisky): the **background/canvas rotates**. The
+          working canvas is pre-swapped to ``(height, width)``, drawn on, then
+          rotated back, so the **output stays exactly ``width × height``** — the
+          right behaviour for a fixed-resolution e-ink panel.
+        * ``"image"`` (niimbot): the **drawing rotates**. The canvas is created
+          at ``width × height``, drawn on, then the whole image is rotated, so
+          the **output dimensions swap** — fine for a variable-size label printer.
+
+        For ``rotate`` of 0/180 the two modes are identical.
+    background:
+        Background color name or ``#RRGGBB`` (mapped via :func:`get_index_color`).
+    dither:
+        If True, Floyd–Steinberg dither the final image to ``context.palette``
+        (better for photos/logos on limited-color panels). Per-image dithering is
+        also available on the ``dlimg`` element.
+    context:
+        Host-supplied :class:`RenderContext` (fonts, history, ...).
+    """
+    rotate = int(rotate or 0)
+    if rotate not in (0, 90, 180, 270):
+        raise ValueError(f"rotate must be 0/90/180/270, got {rotate}")
+    if rotate_mode not in _ROTATE_MODES:
+        raise ValueError(f"rotate_mode must be one of {_ROTATE_MODES}, got {rotate_mode!r}")
+    if width <= 0 or height <= 0:
+        raise ValueError(f"width and height must be positive, got {width}x{height}")
+    bg = context.color(background)
+
+    if rotate in (90, 270) and rotate_mode == ROTATE_MODE_CANVAS:
+        img = Image.new("RGBA", (height, width), color=bg)
+    else:
+        img = Image.new("RGBA", (width, height), color=bg)
+
+    state = RenderState(
+        img=img,
+        canvas_width=img.width,
+        canvas_height=img.height,
+        context=context,
+    )
+
+    for idx, element in enumerate(payload or []):
+        if not isinstance(element, dict):
+            raise RenderError(f"each payload element must be a dict, got {type(element).__name__}")
+        etype = element.get("type", "")
+        _LOGGER.debug("type: %s", etype)
+        if not should_show(element):
+            continue
+        handler = get_handler(etype)
+        if handler is None:
+            _LOGGER.warning("Unknown element type '%s' — skipping.", etype)
+            continue
+        try:
+            handler(state, element)
+        except RenderError:
+            raise  # already descriptive (names the element type / missing arg)
+        except Exception as exc:  # noqa: BLE001 — add element context, then surface
+            raise RenderError(f"error rendering element #{idx} (type '{etype}'): {exc}") from exc
+
+    img = state.img
+    if rotate in (90, 180, 270):
+        img = img.rotate(-rotate, expand=True)
+    result = img.convert("RGB")
+    if dither:
+        from .dither import dither_to_palette
+
+        result = dither_to_palette(result, context.palette)
+    return result

imagespec/dither.py

@@ -0,0 +1,33 @@
+"""Floyd–Steinberg dithering to a device palette.
+
+Snapping each pixel to its nearest palette color (what `quantize_color` does for
+named element colors) looks bad for photos/logos on a 2–7 color panel. Dithering
+trades spatial resolution for perceived color depth and looks dramatically better.
+"""
+
+from __future__ import annotations
+
+from PIL import Image
+
+
+def _palette_image(palette) -> Image.Image:
+    """Build a 'P'-mode image whose palette is ``palette`` (list of RGBA)."""
+    rgbs = [tuple(c[:3]) for c in palette]
+    flat: list[int] = []
+    for c in rgbs:
+        flat.extend(c)
+    # Pad to 256 entries by repeating the first color (never introduce a new one).
+    pad = list(rgbs[0])
+    while len(flat) < 768:
+        flat.extend(pad)
+    pal_img = Image.new("P", (1, 1))
+    pal_img.putpalette(flat)
+    return pal_img
+
+
+def dither_to_palette(img: Image.Image, palette, *, dither: bool = True) -> Image.Image:
+    """Return ``img`` quantized to ``palette`` (RGB), optionally dithered."""
+    rgb = img.convert("RGB")
+    pal_img = _palette_image(palette)
+    mode = Image.Dither.FLOYDSTEINBERG if dither else Image.Dither.NONE
+    return rgb.quantize(palette=pal_img, dither=mode).convert("RGB")

imagespec/elements/__init__.py

@@ -0,0 +1,18 @@
+"""Element handlers.
+
+Importing this package imports each handler module for its registration
+side-effects (the ``@element(...)`` decorators populate the registry).
+
+When porting a new element category, add its module to the import list below.
+"""
+
+from __future__ import annotations
+
+from . import (
+    charts,  # noqa: F401
+    codes,  # noqa: F401
+    layout,  # noqa: F401
+    media,  # noqa: F401
+    shapes,  # noqa: F401
+    text,  # noqa: F401
+)