excalidraw-render 0.1.0__py3-none-any.whl

excalidraw_render/__init__.py

@@ -0,0 +1,5 @@
+"""excalidraw-render — clean, deterministic, browser-free renderer for .excalidraw files."""
+
+from excalidraw_render._version import __version__
+
+__all__ = ["__version__"]

excalidraw_render/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

excalidraw_render/cli.py

@@ -0,0 +1,143 @@
+"""Command-line entry point for excalidraw-render.
+
+Usage:
+    excalidraw-render FILE.excalidraw
+        → renders to FILE.png next to the source
+
+    excalidraw-render FILE.excalidraw -o out.svg --format svg
+        → renders to out.svg
+
+    excalidraw-render FILE.excalidraw --width 1200
+        → PNG at 1200px wide (height auto, aspect preserved)
+
+    excalidraw-render DIR/
+        → batch mode: every .excalidraw file in DIR rendered to <name>.png next to source
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from excalidraw_render._version import __version__
+from excalidraw_render.render import load_scene, render_png, render_svg
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="excalidraw-render",
+        description="Clean, browser-free renderer for .excalidraw files.",
+    )
+    parser.add_argument("input", help="path to a .excalidraw file or directory")
+    parser.add_argument(
+        "-o", "--output",
+        help="output file path (single-file mode) or output directory (batch mode). "
+             "default: same path as input with the format's extension",
+    )
+    parser.add_argument(
+        "-f", "--format",
+        choices=("png", "svg"),
+        default="png",
+        help="output format. default: png",
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        help="output width in pixels (PNG only; height computed from aspect ratio)",
+    )
+    parser.add_argument(
+        "--scale",
+        type=float,
+        default=1.0,
+        help="scale factor for PNG output when --width is not set. default: 1.0",
+    )
+    parser.add_argument(
+        "--no-background",
+        action="store_true",
+        help="render with a transparent background instead of white",
+    )
+    parser.add_argument(
+        "--padding",
+        type=float,
+        default=20.0,
+        help="padding around the scene's bounding box in SVG units. default: 20",
+    )
+    parser.add_argument(
+        "-V", "--version",
+        action="version",
+        version=f"excalidraw-render {__version__}",
+    )
+    return parser.parse_args(argv)
+
+
+def _output_path_for(source: Path, requested: str | None, fmt: str, *, batch_dir: Path | None) -> Path:
+    """Resolve the output path for a single source file."""
+    suffix = f".{fmt}"
+    if batch_dir is not None:
+        return batch_dir / (source.stem + suffix)
+    if requested:
+        out = Path(requested)
+        # If the requested path has no extension, append the format's extension.
+        if out.suffix == "":
+            out = out.with_suffix(suffix)
+        return out
+    return source.with_suffix(suffix)
+
+
+def _render_one(source: Path, output: Path, args: argparse.Namespace) -> None:
+    scene = load_scene(source)
+    background = None if args.no_background else "#ffffff"
+    if args.format == "svg":
+        svg = render_svg(scene, padding=args.padding, background=background)
+        output.write_text(svg)
+    else:
+        render_png(
+            scene,
+            output,
+            width=args.width,
+            scale=args.scale,
+            padding=args.padding,
+            background=background,
+        )
+    print(f"{source} -> {output}", file=sys.stderr)
+
+
+def _iter_excalidraw_files(directory: Path) -> list[Path]:
+    return sorted(p for p in directory.iterdir() if p.is_file() and p.suffix == ".excalidraw")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    input_path = Path(args.input)
+
+    if not input_path.exists():
+        print(f"excalidraw-render: not found: {input_path}", file=sys.stderr)
+        return 1
+
+    if input_path.is_dir():
+        sources = _iter_excalidraw_files(input_path)
+        if not sources:
+            print(f"excalidraw-render: no .excalidraw files in {input_path}", file=sys.stderr)
+            return 1
+        batch_dir = Path(args.output) if args.output else input_path
+        batch_dir.mkdir(parents=True, exist_ok=True)
+        for src in sources:
+            _render_one(src, _output_path_for(src, None, args.format, batch_dir=batch_dir), args)
+        return 0
+
+    if input_path.suffix != ".excalidraw":
+        print(
+            f"excalidraw-render: expected .excalidraw file, got {input_path.suffix or '(no extension)'}",
+            file=sys.stderr,
+        )
+        return 1
+
+    output = _output_path_for(input_path, args.output, args.format, batch_dir=None)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    _render_one(input_path, output, args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

excalidraw_render/element.py

@@ -0,0 +1,347 @@
+"""Typed dataclasses for Excalidraw elements + JSON loader.
+
+Schema reference:
+https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts
+
+We model only what the renderer needs. Fields we ignore (e.g., `versionNonce`,
+`seed`, `updated`, `frameId`, `boundElements` reverse-references handled at
+layout time) are dropped during parsing.
+
+Forward-compat: unknown fields are tolerated. Unknown element types are surfaced
+through `parse_scene()` so callers can decide whether to skip, warn, or fail.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+# ----------------------------------------------------------------------- enums
+
+StrokeStyle = Literal["solid", "dashed", "dotted"]
+FillStyle = Literal["solid", "hachure", "cross-hatch", "zigzag", "zigzag-line", "dots", "dashed"]
+TextAlign = Literal["left", "center", "right"]
+VerticalAlign = Literal["top", "middle", "bottom"]
+FontFamily = Literal[1, 2, 3, 4, 5, 6, 7, 8]  # Excalidraw uses ints for font families
+Arrowhead = Literal[
+    "arrow", "bar", "dot", "triangle", "triangle_outline",
+    "diamond", "diamond_outline",
+    "crowfoot_one", "crowfoot_many", "crowfoot_one_or_many",
+]
+LinearElementType = Literal["arrow", "line"]
+
+
+# --------------------------------------------------------------- common bases
+
+@dataclass(frozen=True, kw_only=True)
+class ExcalidrawElementBase:
+    """Fields shared by every Excalidraw element."""
+
+    id: str
+    type: str
+    x: float
+    y: float
+    width: float
+    height: float
+    angle: float = 0.0
+    stroke_color: str = "#1e1e1e"
+    background_color: str = "transparent"
+    fill_style: FillStyle = "solid"
+    stroke_width: float = 2.0
+    stroke_style: StrokeStyle = "solid"
+    roughness: int = 1
+    opacity: float = 100.0
+    group_ids: tuple[str, ...] = ()
+    frame_id: str | None = None
+    is_deleted: bool = False
+    link: str | None = None
+    locked: bool = False
+    # Per-element type-specific data goes in subclasses.
+
+
+# ----------------------------------------------------------- shape elements
+
+@dataclass(frozen=True, kw_only=True)
+class RectangleElement(ExcalidrawElementBase):
+    type: Literal["rectangle"] = "rectangle"
+    roundness: Roundness | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class EllipseElement(ExcalidrawElementBase):
+    type: Literal["ellipse"] = "ellipse"
+
+
+@dataclass(frozen=True, kw_only=True)
+class DiamondElement(ExcalidrawElementBase):
+    type: Literal["diamond"] = "diamond"
+    roundness: Roundness | None = None
+
+
+@dataclass(frozen=True)
+class Roundness:
+    """Excalidraw stores roundness as { type: int, value?: float }."""
+
+    type: int
+    value: float | None = None
+
+
+# ---------------------------------------------------- linear elements (arrow/line)
+
+@dataclass(frozen=True, kw_only=True)
+class LinearElement(ExcalidrawElementBase):
+    """Common base for arrow and line. Points are deltas from (x, y)."""
+
+    points: tuple[tuple[float, float], ...] = ()
+    start_arrowhead: Arrowhead | None = None
+    end_arrowhead: Arrowhead | None = None
+    start_binding: Binding | None = None
+    end_binding: Binding | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ArrowElement(LinearElement):
+    type: Literal["arrow"] = "arrow"
+
+
+@dataclass(frozen=True, kw_only=True)
+class LineElement(LinearElement):
+    type: Literal["line"] = "line"
+
+
+@dataclass(frozen=True)
+class Binding:
+    """Linear element bound to a shape (start/end). element_id is the target shape."""
+
+    element_id: str
+    focus: float = 0.0
+    gap: float = 0.0
+
+
+# ----------------------------------------------------------------- text
+
+@dataclass(frozen=True, kw_only=True)
+class TextElement(ExcalidrawElementBase):
+    type: Literal["text"] = "text"
+    text: str = ""
+    font_size: float = 20.0
+    font_family: FontFamily = 1
+    text_align: TextAlign = "left"
+    vertical_align: VerticalAlign = "top"
+    container_id: str | None = None
+    original_text: str | None = None
+    line_height: float = 1.25
+
+
+# ---------------------------------------------------------------- freedraw
+
+@dataclass(frozen=True, kw_only=True)
+class FreeDrawElement(ExcalidrawElementBase):
+    type: Literal["freedraw"] = "freedraw"
+    points: tuple[tuple[float, float], ...] = ()
+    pressures: tuple[float, ...] = ()
+    simulate_pressure: bool = True
+    last_committed_point: tuple[float, float] | None = None
+
+
+# ----------------------------------------------------------------- image
+
+@dataclass(frozen=True, kw_only=True)
+class ImageElement(ExcalidrawElementBase):
+    type: Literal["image"] = "image"
+    file_id: str | None = None
+    status: Literal["pending", "saved", "error"] = "saved"
+    scale: tuple[float, float] = (1.0, 1.0)
+
+
+# ----------------------------------------------------------------- frame
+
+@dataclass(frozen=True, kw_only=True)
+class FrameElement(ExcalidrawElementBase):
+    type: Literal["frame"] = "frame"
+    name: str | None = None
+
+
+# ---------------------------------------------------------- unknown element
+
+@dataclass(frozen=True, kw_only=True)
+class UnknownElement(ExcalidrawElementBase):
+    """Element with a type we don't recognize. Preserved so callers can decide."""
+
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+ExcalidrawElement = (
+    RectangleElement
+    | EllipseElement
+    | DiamondElement
+    | ArrowElement
+    | LineElement
+    | TextElement
+    | FreeDrawElement
+    | ImageElement
+    | FrameElement
+    | UnknownElement
+)
+
+
+# ----------------------------------------------------------------- files
+
+@dataclass(frozen=True)
+class EmbeddedFile:
+    """Image data referenced from ImageElement.file_id."""
+
+    id: str
+    mime_type: str
+    data_url: str  # e.g. "data:image/png;base64,..."
+    created: int = 0
+
+
+# ----------------------------------------------------------------- scene
+
+@dataclass(frozen=True)
+class Scene:
+    """A parsed .excalidraw document — elements + embedded files."""
+
+    elements: tuple[ExcalidrawElement, ...]
+    files: dict[str, EmbeddedFile] = field(default_factory=dict)
+    app_state: dict[str, Any] = field(default_factory=dict)
+    source: str = ""
+
+
+# ---------------------------------------------------------------- parsing
+
+def _common_fields(raw: dict[str, Any]) -> dict[str, Any]:
+    """Extract fields present on every element."""
+    return {
+        "id": raw["id"],
+        "type": raw["type"],
+        "x": float(raw.get("x", 0)),
+        "y": float(raw.get("y", 0)),
+        "width": float(raw.get("width", 0)),
+        "height": float(raw.get("height", 0)),
+        "angle": float(raw.get("angle", 0)),
+        "stroke_color": raw.get("strokeColor", "#1e1e1e"),
+        "background_color": raw.get("backgroundColor", "transparent"),
+        "fill_style": raw.get("fillStyle", "solid"),
+        "stroke_width": float(raw.get("strokeWidth", 2)),
+        "stroke_style": raw.get("strokeStyle", "solid"),
+        "roughness": int(raw.get("roughness", 1)),
+        "opacity": float(raw.get("opacity", 100)),
+        "group_ids": tuple(raw.get("groupIds", []) or []),
+        "frame_id": raw.get("frameId"),
+        "is_deleted": bool(raw.get("isDeleted", False)),
+        "link": raw.get("link"),
+        "locked": bool(raw.get("locked", False)),
+    }
+
+
+def _parse_roundness(raw: Any) -> Roundness | None:
+    if not isinstance(raw, dict):
+        return None
+    return Roundness(type=int(raw.get("type", 0)), value=raw.get("value"))
+
+
+def _parse_binding(raw: Any) -> Binding | None:
+    if not isinstance(raw, dict):
+        return None
+    return Binding(
+        element_id=raw.get("elementId", ""),
+        focus=float(raw.get("focus", 0)),
+        gap=float(raw.get("gap", 0)),
+    )
+
+
+def _parse_points(raw: Any) -> tuple[tuple[float, float], ...]:
+    if not raw:
+        return ()
+    return tuple((float(p[0]), float(p[1])) for p in raw if len(p) >= 2)
+
+
+def parse_element(raw: dict[str, Any]) -> ExcalidrawElement:
+    """Parse a single element dict into the matching typed dataclass."""
+    base = _common_fields(raw)
+    etype = raw.get("type")
+
+    if etype == "rectangle":
+        return RectangleElement(**base, roundness=_parse_roundness(raw.get("roundness")))
+    if etype == "ellipse":
+        return EllipseElement(**base)
+    if etype == "diamond":
+        return DiamondElement(**base, roundness=_parse_roundness(raw.get("roundness")))
+    if etype in ("arrow", "line"):
+        cls = ArrowElement if etype == "arrow" else LineElement
+        return cls(
+            **base,
+            points=_parse_points(raw.get("points")),
+            start_arrowhead=raw.get("startArrowhead"),
+            end_arrowhead=raw.get("endArrowhead"),
+            start_binding=_parse_binding(raw.get("startBinding")),
+            end_binding=_parse_binding(raw.get("endBinding")),
+        )
+    if etype == "text":
+        return TextElement(
+            **base,
+            text=raw.get("text", ""),
+            font_size=float(raw.get("fontSize", 20)),
+            font_family=raw.get("fontFamily", 1),
+            text_align=raw.get("textAlign", "left"),
+            vertical_align=raw.get("verticalAlign", "top"),
+            container_id=raw.get("containerId"),
+            original_text=raw.get("originalText"),
+            line_height=float(raw.get("lineHeight", 1.25)),
+        )
+    if etype == "freedraw":
+        lcp_raw = raw.get("lastCommittedPoint")
+        last_committed: tuple[float, float] | None = (
+            (float(lcp_raw[0]), float(lcp_raw[1]))
+            if lcp_raw is not None and len(lcp_raw) >= 2
+            else None
+        )
+        return FreeDrawElement(
+            **base,
+            points=_parse_points(raw.get("points")),
+            pressures=tuple(float(p) for p in raw.get("pressures", []) or []),
+            simulate_pressure=bool(raw.get("simulatePressure", True)),
+            last_committed_point=last_committed,
+        )
+    if etype == "image":
+        scale_raw = raw.get("scale", [1, 1])
+        scale: tuple[float, float] = (float(scale_raw[0]), float(scale_raw[1]))
+        return ImageElement(
+            **base,
+            file_id=raw.get("fileId"),
+            status=raw.get("status", "saved"),
+            scale=scale,
+        )
+    if etype == "frame":
+        return FrameElement(**base, name=raw.get("name"))
+
+    return UnknownElement(**base, raw=raw)
+
+
+def parse_files(raw: Any) -> dict[str, EmbeddedFile]:
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        fid: EmbeddedFile(
+            id=fid,
+            mime_type=meta.get("mimeType", "application/octet-stream"),
+            data_url=meta.get("dataURL", ""),
+            created=int(meta.get("created", 0)),
+        )
+        for fid, meta in raw.items()
+        if isinstance(meta, dict)
+    }
+
+
+def parse_scene(data: dict[str, Any], *, source: str = "") -> Scene:
+    """Parse a top-level .excalidraw JSON dict into a Scene."""
+    elements = tuple(
+        parse_element(el)
+        for el in data.get("elements", [])
+        if isinstance(el, dict) and not el.get("isDeleted", False)
+    )
+    files = parse_files(data.get("files"))
+    app_state = data.get("appState", {}) if isinstance(data.get("appState"), dict) else {}
+    return Scene(elements=elements, files=files, app_state=app_state, source=source)

excalidraw_render/render.py

@@ -0,0 +1,169 @@
+"""Scene → SVG, optionally → PNG. Top-level rendering entry points."""
+
+from __future__ import annotations
+
+import json
+import math
+from io import BytesIO
+from pathlib import Path
+from typing import IO, Any
+
+from excalidraw_render.element import (
+    ArrowElement,
+    DiamondElement,
+    EllipseElement,
+    ExcalidrawElement,
+    FrameElement,
+    FreeDrawElement,
+    ImageElement,
+    LineElement,
+    RectangleElement,
+    Scene,
+    TextElement,
+    UnknownElement,
+    parse_scene,
+)
+from excalidraw_render.renderers import (
+    render_arrow,
+    render_diamond,
+    render_ellipse,
+    render_frame,
+    render_freedraw,
+    render_image,
+    render_line,
+    render_rectangle,
+    render_text,
+)
+from excalidraw_render.renderers._util import fmt
+
+DEFAULT_PADDING = 20
+DEFAULT_BACKGROUND = "#ffffff"
+
+
+def _render_element(el: ExcalidrawElement, scene: Scene) -> str:
+    if isinstance(el, RectangleElement):
+        return render_rectangle(el)
+    if isinstance(el, EllipseElement):
+        return render_ellipse(el)
+    if isinstance(el, DiamondElement):
+        return render_diamond(el)
+    if isinstance(el, ArrowElement):
+        return render_arrow(el)
+    if isinstance(el, LineElement):
+        return render_line(el)
+    if isinstance(el, TextElement):
+        return render_text(el)
+    if isinstance(el, FreeDrawElement):
+        return render_freedraw(el)
+    if isinstance(el, ImageElement):
+        return render_image(el, scene.files)
+    if isinstance(el, FrameElement):
+        return render_frame(el)
+    if isinstance(el, UnknownElement):
+        return f'<!-- unhandled element type: {el.type} -->'
+    return ""
+
+
+def _scene_bbox(scene: Scene) -> tuple[float, float, float, float]:
+    """Compute the bounding box covering all rendered elements."""
+    if not scene.elements:
+        return (0.0, 0.0, 100.0, 100.0)
+
+    min_x = math.inf
+    min_y = math.inf
+    max_x = -math.inf
+    max_y = -math.inf
+
+    for el in scene.elements:
+        # Account for rotation when computing the bbox.
+        if el.angle:
+            cx = el.x + el.width / 2
+            cy = el.y + el.height / 2
+            corners = [
+                (el.x, el.y),
+                (el.x + el.width, el.y),
+                (el.x + el.width, el.y + el.height),
+                (el.x, el.y + el.height),
+            ]
+            cos_a = math.cos(el.angle)
+            sin_a = math.sin(el.angle)
+            for px, py in corners:
+                rx = cx + (px - cx) * cos_a - (py - cy) * sin_a
+                ry = cy + (px - cx) * sin_a + (py - cy) * cos_a
+                min_x = min(min_x, rx)
+                max_x = max(max_x, rx)
+                min_y = min(min_y, ry)
+                max_y = max(max_y, ry)
+        else:
+            min_x = min(min_x, el.x)
+            max_x = max(max_x, el.x + el.width)
+            min_y = min(min_y, el.y)
+            max_y = max(max_y, el.y + el.height)
+
+    if min_x == math.inf:
+        return (0.0, 0.0, 100.0, 100.0)
+    return (min_x, min_y, max_x, max_y)
+
+
+def render_svg(
+    scene: Scene,
+    *,
+    padding: float = DEFAULT_PADDING,
+    background: str | None = DEFAULT_BACKGROUND,
+) -> str:
+    """Render a Scene to a complete SVG document string."""
+    min_x, min_y, max_x, max_y = _scene_bbox(scene)
+    width = max_x - min_x + 2 * padding
+    height = max_y - min_y + 2 * padding
+    vx = min_x - padding
+    vy = min_y - padding
+
+    parts: list[str] = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{fmt(width)}" height="{fmt(height)}" '
+        f'viewBox="{fmt(vx)} {fmt(vy)} {fmt(width)} {fmt(height)}">'
+    ]
+    if background:
+        parts.append(
+            f'<rect x="{fmt(vx)}" y="{fmt(vy)}" '
+            f'width="{fmt(width)}" height="{fmt(height)}" fill="{background}"/>'
+        )
+    parts.extend(_render_element(el, scene) for el in scene.elements)
+    parts.append("</svg>")
+    return "\n".join(p for p in parts if p)
+
+
+def render_png(
+    scene: Scene,
+    out: IO[bytes] | Path | str,
+    *,
+    width: int | None = None,
+    scale: float = 1.0,
+    padding: float = DEFAULT_PADDING,
+    background: str | None = DEFAULT_BACKGROUND,
+) -> None:
+    """Render a Scene to a PNG. Writes to `out` (file path or binary file-like)."""
+    import cairosvg  # local import — cairosvg is heavy; let SVG-only use skip it.
+
+    svg = render_svg(scene, padding=padding, background=background)
+    target: str | IO[bytes] = str(out) if isinstance(out, (str, Path)) else out
+
+    kwargs: dict[str, Any] = {}
+    if width:
+        kwargs["output_width"] = width
+    else:
+        kwargs["scale"] = scale
+
+    if isinstance(target, str):
+        cairosvg.svg2png(bytestring=svg.encode("utf-8"), write_to=target, **kwargs)
+    else:
+        buf = BytesIO()
+        cairosvg.svg2png(bytestring=svg.encode("utf-8"), write_to=buf, **kwargs)
+        target.write(buf.getvalue())
+
+
+def load_scene(path: Path | str) -> Scene:
+    """Read a .excalidraw file from disk and parse to a Scene."""
+    p = Path(path)
+    data = json.loads(p.read_text())
+    return parse_scene(data, source=str(p))

excalidraw_render/renderers/__init__.py

@@ -0,0 +1,32 @@
+"""SVG renderers for each Excalidraw element type."""
+
+from excalidraw_render.renderers._util import (
+    fmt,
+    opacity_fraction,
+    stroke_dasharray,
+    text_escape,
+    transform_attr,
+)
+from excalidraw_render.renderers.frame import render_frame
+from excalidraw_render.renderers.freedraw import render_freedraw
+from excalidraw_render.renderers.image import render_image
+from excalidraw_render.renderers.linear import render_arrow, render_line
+from excalidraw_render.renderers.shapes import render_diamond, render_ellipse, render_rectangle
+from excalidraw_render.renderers.text import render_text
+
+__all__ = [
+    "fmt",
+    "opacity_fraction",
+    "render_arrow",
+    "render_diamond",
+    "render_ellipse",
+    "render_frame",
+    "render_freedraw",
+    "render_image",
+    "render_line",
+    "render_rectangle",
+    "render_text",
+    "stroke_dasharray",
+    "text_escape",
+    "transform_attr",
+]