frameplot 0.1.0__py3-none-any.whl

frameplot/layout/scc.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from frameplot.layout.types import ValidatedPipeline
+
+
+@dataclass(slots=True)
+class SccResult:
+    components: tuple[tuple[str, ...], ...]
+    node_to_component: dict[str, int]
+
+
+def strongly_connected_components(validated: ValidatedPipeline) -> SccResult:
+    adjacency: dict[str, list[str]] = {node.id: [] for node in validated.nodes}
+    for edge in validated.edges:
+        adjacency[edge.source].append(edge.target)
+
+    for neighbors in adjacency.values():
+        neighbors.sort(key=validated.node_index.__getitem__)
+
+    index = 0
+    stack: list[str] = []
+    active: set[str] = set()
+    indices: dict[str, int] = {}
+    lowlinks: dict[str, int] = {}
+    components: list[list[str]] = []
+
+    def visit(node_id: str) -> None:
+        nonlocal index
+        indices[node_id] = index
+        lowlinks[node_id] = index
+        index += 1
+        stack.append(node_id)
+        active.add(node_id)
+
+        for neighbor in adjacency[node_id]:
+            if neighbor not in indices:
+                visit(neighbor)
+                lowlinks[node_id] = min(lowlinks[node_id], lowlinks[neighbor])
+            elif neighbor in active:
+                lowlinks[node_id] = min(lowlinks[node_id], indices[neighbor])
+
+        if lowlinks[node_id] == indices[node_id]:
+            component: list[str] = []
+            while True:
+                member = stack.pop()
+                active.remove(member)
+                component.append(member)
+                if member == node_id:
+                    break
+            component.sort(key=validated.node_index.__getitem__)
+            components.append(component)
+
+    for node in validated.nodes:
+        if node.id not in indices:
+            visit(node.id)
+
+    components.sort(key=lambda members: min(validated.node_index[node_id] for node_id in members))
+
+    node_to_component: dict[str, int] = {}
+    for component_id, component in enumerate(components):
+        for node_id in component:
+            node_to_component[node_id] = component_id
+
+    return SccResult(
+        components=tuple(tuple(component) for component in components),
+        node_to_component=node_to_component,
+    )

frameplot/layout/text.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import math
+import textwrap
+
+from frameplot.layout.types import MeasuredText, ValidatedPipeline
+
+
+TITLE_CHAR_WIDTH = 0.58
+SUBTITLE_CHAR_WIDTH = 0.54
+LINE_HEIGHT_RATIO = 1.25
+
+
+def measure_text(validated: ValidatedPipeline) -> dict[str, MeasuredText]:
+    theme = validated.theme
+    title_char_limit = max(10, int(theme.max_text_width / (theme.title_font_size * TITLE_CHAR_WIDTH)))
+    subtitle_char_limit = max(
+        10, int(theme.max_text_width / (theme.subtitle_font_size * SUBTITLE_CHAR_WIDTH))
+    )
+    measurements: dict[str, MeasuredText] = {}
+
+    for node in validated.nodes:
+        title_lines = tuple(_wrap(node.title, title_char_limit))
+        subtitle_lines = tuple(_wrap(node.subtitle, subtitle_char_limit)) if node.subtitle else ()
+
+        title_width = _max_line_width(title_lines, theme.title_font_size, TITLE_CHAR_WIDTH)
+        subtitle_width = _max_line_width(
+            subtitle_lines, theme.subtitle_font_size, SUBTITLE_CHAR_WIDTH
+        )
+        text_width = max(title_width, subtitle_width, theme.min_node_width - theme.node_padding_x * 2)
+
+        title_line_height = theme.title_font_size * LINE_HEIGHT_RATIO
+        subtitle_line_height = theme.subtitle_font_size * LINE_HEIGHT_RATIO
+
+        content_height = len(title_lines) * title_line_height
+        if subtitle_lines:
+            content_height += theme.inter_text_gap + len(subtitle_lines) * subtitle_line_height
+
+        auto_width = theme.node_padding_x * 2 + text_width
+        auto_height = theme.node_padding_y * 2 + content_height
+
+        width = max(node.width or 0.0, auto_width, theme.min_node_width)
+        height = max(node.height or 0.0, auto_height, theme.min_node_height)
+
+        measurements[node.id] = MeasuredText(
+            title_lines=title_lines,
+            subtitle_lines=subtitle_lines,
+            title_line_height=title_line_height,
+            subtitle_line_height=subtitle_line_height,
+            content_height=content_height,
+            width=round(width, 2),
+            height=round(height, 2),
+        )
+
+    return measurements
+
+
+def _wrap(value: str | None, width: int) -> list[str]:
+    if not value:
+        return []
+    wrapped = textwrap.wrap(
+        value,
+        width=width,
+        break_long_words=True,
+        break_on_hyphens=False,
+        drop_whitespace=True,
+    )
+    return wrapped or [value]
+
+
+def _max_line_width(lines: tuple[str, ...], font_size: float, ratio: float) -> float:
+    if not lines:
+        return 0.0
+    return math.ceil(max(len(line) for line in lines) * font_size * ratio)

frameplot/layout/types.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from frameplot.model import DetailPanel, Edge, Group, Node
+from frameplot.theme import Theme
+
+
+@dataclass(slots=True, frozen=True)
+class Point:
+    x: float
+    y: float
+
+
+@dataclass(slots=True, frozen=True)
+class Bounds:
+    x: float
+    y: float
+    width: float
+    height: float
+
+    @property
+    def right(self) -> float:
+        return self.x + self.width
+
+    @property
+    def bottom(self) -> float:
+        return self.y + self.height
+
+    def expand(self, padding: float) -> "Bounds":
+        return Bounds(
+            x=self.x - padding,
+            y=self.y - padding,
+            width=self.width + padding * 2,
+            height=self.height + padding * 2,
+        )
+
+
+def union_bounds(bounds: list[Bounds]) -> Bounds:
+    min_x = min(bound.x for bound in bounds)
+    min_y = min(bound.y for bound in bounds)
+    max_x = max(bound.right for bound in bounds)
+    max_y = max(bound.bottom for bound in bounds)
+    return Bounds(x=min_x, y=min_y, width=max_x - min_x, height=max_y - min_y)
+
+
+@dataclass(slots=True)
+class ValidatedPipeline:
+    nodes: tuple[Node, ...]
+    edges: tuple[Edge, ...]
+    groups: tuple[Group, ...]
+    node_lookup: dict[str, Node]
+    edge_lookup: dict[str, Edge]
+    node_index: dict[str, int]
+    edge_index: dict[str, int]
+    theme: Theme
+    detail_panel: "ValidatedDetailPanel | None" = None
+
+
+@dataclass(slots=True)
+class ValidatedDetailPanel:
+    panel: DetailPanel
+    nodes: tuple[Node, ...]
+    edges: tuple[Edge, ...]
+    groups: tuple[Group, ...]
+    node_lookup: dict[str, Node]
+    edge_lookup: dict[str, Edge]
+    node_index: dict[str, int]
+    edge_index: dict[str, int]
+    theme: Theme
+
+
+@dataclass(slots=True)
+class MeasuredText:
+    title_lines: tuple[str, ...]
+    subtitle_lines: tuple[str, ...]
+    title_line_height: float
+    subtitle_line_height: float
+    content_height: float
+    width: float
+    height: float
+
+
+@dataclass(slots=True)
+class LayoutNode:
+    node: Node
+    rank: int
+    order: int
+    component_id: int
+    width: float
+    height: float
+    x: float
+    y: float
+    title_lines: tuple[str, ...]
+    subtitle_lines: tuple[str, ...]
+    title_line_height: float
+    subtitle_line_height: float
+    content_height: float
+
+    @property
+    def bounds(self) -> Bounds:
+        return Bounds(self.x, self.y, self.width, self.height)
+
+    @property
+    def right(self) -> float:
+        return self.x + self.width
+
+    @property
+    def center_x(self) -> float:
+        return self.x + self.width / 2
+
+    @property
+    def center_y(self) -> float:
+        return self.y + self.height / 2
+
+
+@dataclass(slots=True)
+class RoutedEdge:
+    edge: Edge
+    points: tuple[Point, ...]
+    bounds: Bounds
+    stroke: str
+
+
+@dataclass(slots=True)
+class GroupOverlay:
+    group: Group
+    bounds: Bounds
+    stroke: str
+    fill: str
+
+
+@dataclass(slots=True)
+class GuideLine:
+    points: tuple[Point, ...]
+    bounds: Bounds
+    stroke: str
+
+
+@dataclass(slots=True)
+class GraphLayout:
+    nodes: dict[str, LayoutNode]
+    edges: tuple[RoutedEdge, ...]
+    groups: tuple[GroupOverlay, ...]
+    content_bounds: Bounds
+    width: float
+    height: float
+
+
+@dataclass(slots=True)
+class DetailPanelLayout:
+    panel: DetailPanel
+    graph: GraphLayout
+    bounds: Bounds
+    stroke: str
+    fill: str
+    guide_lines: tuple[GuideLine, ...]
+
+
+@dataclass(slots=True)
+class LayoutResult:
+    main: GraphLayout
+    detail_panel: DetailPanelLayout | None
+    width: float
+    height: float

frameplot/layout/validate.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from frameplot.layout.types import ValidatedDetailPanel, ValidatedPipeline
+
+
+def validate_pipeline(pipeline: "Pipeline") -> ValidatedPipeline:
+    from frameplot.api import Pipeline
+
+    if not isinstance(pipeline, Pipeline):
+        raise TypeError("pipeline must be a Pipeline instance.")
+
+    validated_graph = _validate_graph_parts(
+        nodes=tuple(pipeline.nodes),
+        edges=tuple(pipeline.edges),
+        groups=tuple(pipeline.groups),
+        owner_label="Pipeline",
+    )
+
+    detail_panel = None
+    if pipeline.detail_panel is not None:
+        if pipeline.detail_panel.focus_node_id not in validated_graph["node_lookup"]:
+            raise ValueError(
+                f"DetailPanel {pipeline.detail_panel.id} references missing focus node: "
+                f"{pipeline.detail_panel.focus_node_id}"
+            )
+        validated_panel = _validate_graph_parts(
+            nodes=tuple(pipeline.detail_panel.nodes),
+            edges=tuple(pipeline.detail_panel.edges),
+            groups=tuple(pipeline.detail_panel.groups),
+            owner_label=f"DetailPanel {pipeline.detail_panel.id}",
+        )
+        detail_panel = ValidatedDetailPanel(
+            panel=pipeline.detail_panel,
+            nodes=validated_panel["nodes"],
+            edges=validated_panel["edges"],
+            groups=validated_panel["groups"],
+            node_lookup=validated_panel["node_lookup"],
+            edge_lookup=validated_panel["edge_lookup"],
+            node_index=validated_panel["node_index"],
+            edge_index=validated_panel["edge_index"],
+            theme=pipeline.theme,
+        )
+
+    return ValidatedPipeline(
+        nodes=validated_graph["nodes"],
+        edges=validated_graph["edges"],
+        groups=validated_graph["groups"],
+        node_lookup=validated_graph["node_lookup"],
+        edge_lookup=validated_graph["edge_lookup"],
+        node_index=validated_graph["node_index"],
+        edge_index=validated_graph["edge_index"],
+        theme=pipeline.theme,
+        detail_panel=detail_panel,
+    )
+
+
+def _validate_graph_parts(
+    *,
+    nodes: tuple["Node", ...],
+    edges: tuple["Edge", ...],
+    groups: tuple["Group", ...],
+    owner_label: str,
+) -> dict[str, object]:
+    if not nodes:
+        raise ValueError(f"{owner_label} must contain at least one node.")
+
+    node_lookup: dict[str, object] = {}
+    edge_lookup: dict[str, object] = {}
+    node_index: dict[str, int] = {}
+    edge_index: dict[str, int] = {}
+
+    for index, node in enumerate(nodes):
+        if node.id in node_lookup:
+            raise ValueError(f"Duplicate node id: {node.id}")
+        node_lookup[node.id] = node
+        node_index[node.id] = index
+
+    for index, edge in enumerate(edges):
+        if edge.id in edge_lookup:
+            raise ValueError(f"Duplicate edge id: {edge.id}")
+        if edge.source not in node_lookup:
+            raise ValueError(f"Edge {edge.id} references missing source node: {edge.source}")
+        if edge.target not in node_lookup:
+            raise ValueError(f"Edge {edge.id} references missing target node: {edge.target}")
+        edge_lookup[edge.id] = edge
+        edge_index[edge.id] = index
+
+    for group in groups:
+        missing_nodes = [node_id for node_id in group.node_ids if node_id not in node_lookup]
+        missing_edges = [edge_id for edge_id in group.edge_ids if edge_id not in edge_lookup]
+        if missing_nodes:
+            raise ValueError(
+                f"Group {group.id} references missing node ids: {', '.join(sorted(missing_nodes))}"
+            )
+        if missing_edges:
+            raise ValueError(
+                f"Group {group.id} references missing edge ids: {', '.join(sorted(missing_edges))}"
+            )
+
+    return {
+        "nodes": nodes,
+        "edges": edges,
+        "groups": groups,
+        "node_lookup": node_lookup,
+        "edge_lookup": edge_lookup,
+        "node_index": node_index,
+        "edge_index": edge_index,
+    }

frameplot/model.py

@@ -0,0 +1,129 @@
+"""Public data models used to describe frameplot diagrams."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Node:
+    """Describe a rendered node in the main graph or a detail panel.
+
+    `id` and `title` are required. Optional colors override the active theme for
+    this node only, and `width` or `height` can pin the rendered box size.
+    Surrounding whitespace is stripped from text fields.
+    """
+
+    id: str
+    title: str
+    subtitle: str | None = None
+    fill: str | None = None
+    stroke: str | None = None
+    text_color: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    width: float | None = None
+    height: float | None = None
+
+    def __post_init__(self) -> None:
+        self.id = self.id.strip()
+        self.title = self.title.strip()
+        if self.subtitle is not None:
+            self.subtitle = self.subtitle.strip() or None
+        if not self.id:
+            raise ValueError("Node id must not be empty.")
+        if not self.title:
+            raise ValueError("Node title must not be empty.")
+        if self.width is not None and self.width <= 0:
+            raise ValueError("Node width must be positive.")
+        if self.height is not None and self.height <= 0:
+            raise ValueError("Node height must be positive.")
+
+
+@dataclass(slots=True)
+class Edge:
+    """Connect two nodes with a directional edge.
+
+    `source` and `target` must reference node identifiers in the same graph.
+    Set `dashed=True` to draw a secondary or conditional flow.
+    """
+
+    id: str
+    source: str
+    target: str
+    color: str | None = None
+    dashed: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.id = self.id.strip()
+        self.source = self.source.strip()
+        self.target = self.target.strip()
+        if not self.id:
+            raise ValueError("Edge id must not be empty.")
+        if not self.source or not self.target:
+            raise ValueError("Edge source and target must not be empty.")
+
+
+@dataclass(slots=True)
+class Group:
+    """Highlight related nodes or edges with a labeled overlay.
+
+    Groups are visual only. They do not constrain layout or change routing.
+    At least one node or edge reference is required.
+    """
+
+    id: str
+    label: str
+    node_ids: tuple[str, ...]
+    edge_ids: tuple[str, ...] = ()
+    stroke: str | None = None
+    fill: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.id = self.id.strip()
+        self.label = self.label.strip()
+        self.node_ids = tuple(node_id.strip() for node_id in self.node_ids if node_id.strip())
+        self.edge_ids = tuple(edge_id.strip() for edge_id in self.edge_ids if edge_id.strip())
+        if not self.id:
+            raise ValueError("Group id must not be empty.")
+        if not self.label:
+            raise ValueError("Group label must not be empty.")
+        if not self.node_ids and not self.edge_ids:
+            raise ValueError("Group must reference at least one node or edge.")
+
+
+@dataclass(slots=True)
+class DetailPanel:
+    """Expand a focus node into a lower inset with its own mini-graph.
+
+    The focus node must exist in the main pipeline graph, and the panel must
+    contain at least one node.
+    """
+
+    id: str
+    focus_node_id: str
+    label: str
+    nodes: tuple[Node, ...]
+    edges: tuple[Edge, ...]
+    groups: tuple[Group, ...] = ()
+    stroke: str | None = None
+    fill: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.id = self.id.strip()
+        self.focus_node_id = self.focus_node_id.strip()
+        self.label = self.label.strip()
+        self.nodes = tuple(self.nodes)
+        self.edges = tuple(self.edges)
+        self.groups = tuple(self.groups)
+        if not self.id:
+            raise ValueError("DetailPanel id must not be empty.")
+        if not self.focus_node_id:
+            raise ValueError("DetailPanel focus_node_id must not be empty.")
+        if not self.label:
+            raise ValueError("DetailPanel label must not be empty.")
+        if not self.nodes:
+            raise ValueError("DetailPanel must contain at least one node.")

frameplot/render/__init__.py

@@ -0,0 +1,4 @@
+from frameplot.render.png import save_png, svg_to_png_bytes
+from frameplot.render.svg import render_svg
+
+__all__ = ["render_svg", "save_png", "svg_to_png_bytes"]

frameplot/render/png.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def svg_to_png_bytes(svg: str) -> bytes:
+    """Convert an SVG string into PNG bytes with CairoSVG."""
+
+    try:
+        import cairosvg
+    except ImportError as exc:  # pragma: no cover - dependency issue
+        raise RuntimeError("CairoSVG is required for PNG export.") from exc
+    return cairosvg.svg2png(bytestring=svg.encode("utf-8"))
+
+
+def save_png(svg: str, path: str | Path) -> None:
+    """Write PNG bytes generated from `svg` to `path`."""
+
+    output = svg_to_png_bytes(svg)
+    Path(path).write_bytes(output)