bsplot 0.0.2__py3-none-any.whl

bsplot/graph/flowchart.py

@@ -0,0 +1,762 @@
+from __future__ import annotations
+
+from graphviz import Source
+import html
+import math
+import json
+from io import BytesIO
+from typing import Iterable, List, Sequence, Tuple, Optional, Dict
+
+# Optional at call sites only (so this module imports even outside notebooks)
+try:
+    from IPython.display import display, HTML  # noqa: F401
+except Exception:  # pragma: no cover
+    display = None
+    HTML = None
+
+
+Node = Tuple[str, str, str, str]  # (nid, icon, title, sub)
+Edge = Tuple[str, str, Optional[str]]  # (u, v, label)
+
+
+def build_dot(
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    same_rank_groups: Optional[Sequence[Sequence[str]]] = None,
+    node_width: float | str = "auto",
+    node_height: float | str = "auto",
+    nodesep: float = 1,
+    ranksep: float = 1,
+    fontsize: int = 10,
+    char_w: float = 0.08,
+    line_h: float = 0.28,
+    min_w: float = 0.5,
+    max_w: float = 2.0,
+    min_h: float = 0.5,
+    max_h: float = 0.8,
+    rankdir: str = "LR",
+    dpi: int = 144,
+    include_icon_row: bool = True,
+    icon_fontname: Optional[str] = None,   # use local Material Symbols ligature font if available
+    splines: str = "true",                 # control Graphviz splines mode
+    edge_label_mode: str = "auto",         # 'auto' | 'label' | 'xlabel'
+    icon_color: str = "#4a90e2",           # icon color (match HTML)
+    icon_scale: float = 2.4,               # icon size scale vs fontsize
+    icon_fontpath: Optional[str] = None,   # directory for the font, passed to Graphviz
+    # spacing controls
+    label_cellpadding: int = 0,
+    node_margin: float = 0.06,
+    compact_label: bool = False,
+    # NEW: tighten line spacing between title and subheading
+    label_lineheight: float = 2.0,
+    label_leading: float = 2.0,
+    # NEW: edge styling and label control
+    edge_color: str = "#999999",
+    edge_penwidth: float = 1.6,
+    edge_font_scale: float = 0.8,
+    show_edge_labels: bool = True,
+    # NEW: edge label background + padding
+    edge_label_bgcolor: str = "#ffffff",
+    edge_label_cellpadding: int = 2,
+) -> str:
+    """
+    Return a DOT string to compute node positions with Graphviz.
+
+    The label uses an HTML-like table with: optional icon row, title, sub.
+    Width/height are estimated if set to "auto", otherwise treated as fixed hints.
+    """
+
+    def n(nid: str, icon: str, title: str, sub: str) -> str:
+        w = (
+            max(min_w, min(max_w, (char_w * max(len(title), len(sub)) + min_w)))
+            if node_width == "auto" else float(node_width)
+        )
+        lines_title = max(1, math.ceil(len(title) / max(1, int((w - 0.6) / char_w))))
+        lines_sub = max(1, math.ceil(len(sub) / max(1, int((w - 0.6) / char_w))))
+        h_est = min_h + line_h * (lines_title - 1 + lines_sub - 1)
+        h = max(min_h, min(max_h, h_est)) if node_height == "auto" else float(node_height)
+
+        sub_fs = max(8, int(fontsize * 0.9))
+        icon_fs = max(fontsize, int(fontsize * icon_scale))
+
+        # Ensure no empty cells (Graphviz HTML labels reject empty FONT tags)
+        def _safe_cell_text(s: str) -> str:
+            return s if s and s.strip() else "\u00A0"
+
+        title_txt = _safe_cell_text(title)
+        sub_txt = _safe_cell_text(sub)
+
+        # Compact: single TD with <BR/> lines (minimizes inter-row spacing)
+        if compact_label:
+            icon_html = ""
+            if include_icon_row and icon:
+                if icon_fontname:
+                    icon_html = (
+                        f'<FONT FACE="{html.escape(icon_fontname)}" '
+                        f'POINT-SIZE="{icon_fs}" COLOR="{html.escape(icon_color)}">{html.escape(icon)}</FONT>'
+                    )
+                else:
+                    icon_html = (
+                        f'<FONT POINT-SIZE="{icon_fs}" COLOR="{html.escape(icon_color)}">{html.escape(icon)}</FONT>'
+                    )
+            parts = []
+            if icon_html:
+                parts.append(icon_html)
+            parts.append(f'<FONT POINT-SIZE="{fontsize}">{html.escape(title_txt)}</FONT>')
+            parts.append(f'<FONT POINT-SIZE="{sub_fs}" COLOR="#6b7280">{html.escape(sub_txt)}</FONT>')
+            return (
+                f'{nid}[label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="{label_cellpadding}" CELLSPACING="0">'
+                f'<TR><TD ALIGN="CENTER">' + "<BR/>".join(parts) + "</TD></TR></TABLE>>,"
+                f'width={w:.3f},height={h:.3f},fixedsize=false];'
+            )
+
+        # Default: separate rows
+        rows = []
+        if include_icon_row and icon:
+            if icon_fontname:
+                rows.append(
+                    f'<TR><TD ALIGN="CENTER"><FONT FACE="{html.escape(icon_fontname)}" '
+                    f'POINT-SIZE="{icon_fs}" COLOR="{html.escape(icon_color)}">{html.escape(icon)}</FONT></TD></TR>'
+                )
+            else:
+                rows.append(
+                    f'<TR><TD ALIGN="CENTER"><FONT POINT-SIZE="{icon_fs}" COLOR="{html.escape(icon_color)}">'
+                    f'{html.escape(icon)}</FONT></TD></TR>'
+                )
+        rows.append(f'<TR><TD ALIGN="CENTER"><FONT POINT-SIZE="{fontsize}">{html.escape(title_txt)}</FONT></TD></TR>')
+        rows.append(f'<TR><TD ALIGN="CENTER"><FONT POINT-SIZE="{sub_fs}" COLOR="#6b7280">{html.escape(sub_txt)}</FONT></TD></TR>')
+        return (
+            f'{nid}[label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="{label_cellpadding}" CELLSPACING="0">'
+            + "".join(rows)
+            + "</TABLE>>,"
+            f'width={w:.3f},height={h:.3f},fixedsize=false];'
+        )
+
+    rank_blocks = ""
+    if same_rank_groups:
+        rank_blocks = "".join("{rank=same; " + " ".join(group) + ";}" for group in same_rank_groups)
+
+    # Decide which edge label attribute to use
+    use_xlabel = (edge_label_mode == "xlabel") or (edge_label_mode == "auto" and splines.lower() == "curved")
+    label_attr = "xlabel" if use_xlabel else "label"
+
+    # Compute edge label font size once (used in HTML label)
+    edge_fontsize = max(7, int(fontsize * edge_font_scale))
+
+    def e(u: str, v: str, lbl: Optional[str]) -> str:
+        # Add a label only if enabled and provided
+        if show_edge_labels and lbl:
+            # HTML-like label with white background and small padding
+            html_lbl = (
+                f'<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="{edge_label_cellpadding}" '
+                f'BGCOLOR="{html.escape(edge_label_bgcolor)}"><TR><TD>'
+                f'<FONT POINT-SIZE="{edge_fontsize}" COLOR="#666666">{html.escape(lbl)}</FONT>'
+                f"</TD></TR></TABLE>>"
+            )
+            return f"{u}->{v} [{label_attr}={html_lbl}];"
+        return f"{u}->{v};"
+
+    # Build edges string robustly for (u,v) and (u,v,label)
+    edges_str_parts = []
+    for t in edges:
+        u, v = t[0], t[1]
+        lbl = t[2] if len(t) > 2 else None
+        if lbl is not None and not isinstance(lbl, str):
+            lbl = str(lbl)
+        edges_str_parts.append(e(u, v, lbl))
+    edges_str = "".join(edges_str_parts)
+
+    # Global defaults to better match HTML styling
+    node_font = "Segoe UI"
+    edge_font = "Segoe UI"
+    # edge_fontsize already computed above
+
+    # Graph attributes (allow passing a fontpath so dot can find local fonts)
+    graph_attrs = f'dpi={dpi},splines={splines}'
+    if icon_fontpath:
+        graph_attrs += f',fontpath="{icon_fontpath}"'
+
+    return (
+        "digraph G{"
+        f'graph[{graph_attrs}];'
+        f'rankdir={rankdir};nodesep={nodesep};ranksep={ranksep};'
+        f'node[fontname="{node_font}",fontsize={fontsize},shape=box,style="rounded,filled",'
+        f'fillcolor="#ffffff:#eef2f7",gradientangle=90,color="transparent",penwidth=0,margin="{node_margin}",'
+        f'lineheight={label_lineheight},leading={label_leading}];'
+        f'edge[fontname="{edge_font}",fontsize={edge_fontsize},color="{edge_color}",fontcolor="#666666",'
+        f'penwidth={edge_penwidth},arrowsize=0.7];'
+        + "".join(n(*x) for x in nodes)
+        + edges_str
+        + ("" if not same_rank_groups else "".join("{rank=same; " + " ".join(group) + ";}" for group in same_rank_groups))
+        + "}"
+    )
+
+
+def layout(dot: str) -> Tuple[float, float, Dict[str, Dict[str, float]]]:
+    """Run Graphviz 'plain' and return canvas size (W,H) in px and node box dict."""
+    S = 72.0  # pt->px
+    W = H = 0.0
+    pos: Dict[str, Dict[str, float]] = {}
+    for line in Source(dot).pipe(format="plain").decode().splitlines():
+        p = line.split()
+        if not p:
+            continue
+        if p[0] == "graph":
+            W, H = float(p[2]) * S, float(p[3]) * S
+        elif p[0] == "node":
+            _, name, x, y, w, h = p[:6]
+            pos[name] = {
+                "x": float(x) * S,
+                "y": float(y) * S,
+                "w": float(w) * S,
+                "h": float(h) * S,
+            }
+    return W, H, pos
+
+
+def _card_div(pos: Dict[str, Dict[str, float]], nid: str, icon: str, title: str, sub: str, H: float) -> str:
+    d = pos[nid]
+    left = d["x"] - d["w"] / 2
+    top = H - (d["y"] + d["h"] / 2)
+    return (
+        f'<div class="step" data-nid="{nid}" style="position:absolute;left:{left:.1f}px;top:{top:.1f}px;'
+        f'width:{d["w"]:.1f}px;"><div class="icon"><span class="material-symbols-outlined">'
+        f"{html.escape(icon)}</span></div><h4>{html.escape(title)}</h4><small>{html.escape(sub)}</small></div>"
+    )
+
+
+def render_html(
+    W: float,
+    H: float,
+    pos: Dict[str, Dict[str, float]],
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    ui_fontsize: int = 12,
+    rankdir: str = "LR",
+) -> str:
+    """Return standalone HTML for the diagram with cards that expand downward to fit text."""
+    cards = "".join(_card_div(pos, *n, H) for n in nodes)
+
+    # Scale-dependent sizes (px)
+    icon_px = int(ui_fontsize * 2.2)
+    title_px = int(ui_fontsize * 1.0)
+    small_px = int(ui_fontsize * 0.85)
+    pad_px = int(ui_fontsize * 0.6)
+
+    edges_pairs = [[u, v] for (u, v, *_lbl) in edges]
+    edges_js = json.dumps(edges_pairs)
+
+    css = f"""
+    .jp-RenderedHTMLCommon {{
+        font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif;
+        line-height:1.5;
+    }}
+    .jp-RenderedHTMLCommon h4 {{
+        font-weight:600;
+        color:rgba(0,0,0,.6);
+    }}
+    .jp-RenderedHTMLCommon small {{
+        color:rgba(0,0,0,.55);
+    }}
+    .workflow {{
+        position:relative;
+        width:{W:.1f}px;
+        height:{H:.1f}px;
+        margin:24px auto;
+        background:#ffffff;
+    }}
+    .step {{
+        background:#fff;
+        border-radius:1rem;
+        box-shadow:0 2px 6px rgba(0,0,0,.1);
+        box-sizing:border-box;
+        padding:{pad_px}px 10px;
+        display:grid;
+        grid-template-rows:{icon_px}px auto auto;
+        align-items:start;
+        justify-items:center;
+        gap:2px;
+        text-align:center;
+        overflow:visible;
+    }}
+    .icon {{
+        height:{icon_px}px;
+        width:100%;
+        display:flex;
+        align-items:center;
+        justify-content:center;
+    }}
+    .material-symbols-outlined {{
+        font-size:{icon_px}px;
+        color:#4a90e2;
+        line-height:1;
+    }}
+    h4 {{
+        margin:0;
+        font-family:sans-serif;
+        font-size:{title_px}px;
+        line-height:1.15;
+        max-width:100%;
+        overflow-wrap:anywhere;
+        word-break:normal;
+    }}
+    small {{
+        color:#555;
+        font-size:{small_px}px;
+        display:block;
+        max-width:100%;
+        overflow-wrap:anywhere;
+        word-break:normal;
+    }}
+    svg {{
+        position:absolute;
+        left:0;
+        top:0;
+        width:100%;
+        height:100%;
+        pointer-events:none;
+    }}
+    """
+
+    js = f"""
+    (function(){{
+      const rankdir = "{rankdir}";
+      const pad = 8;
+      const edges = {edges_js};
+      const container = document.querySelector('.workflow');
+      const svg = container.querySelector('svg');
+      function draw(){{
+        const g = svg.querySelector('#edges');
+        g.innerHTML = '';
+        let maxBottom = 0;
+        const rects = {{}};
+        Array.from(container.querySelectorAll('.step')).forEach(el => {{
+          rects[el.dataset.nid] = {{
+            left: el.offsetLeft,
+            top: el.offsetTop,
+            width: el.offsetWidth,
+            height: el.offsetHeight
+          }};
+          maxBottom = Math.max(maxBottom, el.offsetTop + el.offsetHeight);
+        }});
+        const Wpx = {W:.1f};
+        const Hpx = Math.ceil(maxBottom);
+        container.style.height = Hpx + 'px';
+        svg.setAttribute('viewBox', `0 0 ${'{'}Wpx{'}'} ${'{'}Hpx{'}'}`);
+        svg.setAttribute('height', Hpx);
+        function pathTD(u,v){{
+          const a = rects[u], b = rects[v];
+          if(!a||!b) return '';
+          const x1 = a.left + a.width/2;
+          const y1 = a.top + a.height + pad;
+          const x2 = b.left + b.width/2;
+          const y2 = b.top - pad;
+          const cy = (y1 + y2)/2;
+          return `M${'{'}x1{'}'},${'{'}y1{'}'} C${'{'}x1{'}'},${'{'}cy{'}'} ${'{'}x2{'}'},${'{'}cy{'}'} ${'{'}x2{'}'},${'{'}y2{'}'}`;
+        }}
+        function pathLR(u,v){{
+          const a = rects[u], b = rects[v];
+          if(!a||!b) return '';
+          const x1 = a.left + a.width + pad;
+          const y1 = a.top + a.height/2;
+          const x2 = b.left - pad;
+          const y2 = b.top + b.height/2;
+          const cx = (x1 + x2)/2;
+          return `M${'{'}x1{'}'},${'{'}y1{'}'} C${'{'}cx{'}'},${'{'}y1{'}'} ${'{'}cx{'}'},${'{'}y2{'}'} ${'{'}x2{'}'},${'{'}y2{'}'}`;
+        }}
+        edges.forEach(([u,v]) => {{
+          const d = (rankdir === 'TD' || rankdir === 'BT') ? pathTD(u,v) : pathLR(u,v);
+          if(!d) return;
+          const path = document.createElementNS('http://www.w3.org/2000/svg','path');
+          path.setAttribute('d', d);
+          path.setAttribute('fill','none');
+          path.setAttribute('stroke','#aaa');
+          path.setAttribute('stroke-width','1');
+          path.setAttribute('marker-end','url(#arrow)');
+          g.appendChild(path);
+        }});
+      }}
+      function layout(){{ requestAnimationFrame(draw); }}
+      window.addEventListener('load', layout);
+      window.addEventListener('resize', layout);
+      layout();
+    }})();
+    """
+
+    return (
+        f'<!doctype html><meta charset="utf-8" />'
+        f'<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet">'
+        f'<style>{css}</style>'
+        f'<div class="jp-RenderedHTMLCommon workflow">'
+        f'<svg viewBox="0 0 {W:.1f} {H:.1f}"><defs>'
+        f'<marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">'
+        f'<path d="M0,0 L10,5 L0,10 Z" fill="#aaa"/></marker></defs>'
+        f'<g id="edges"></g></svg>{cards}'
+        f'<script>{js}</script>'
+        f'</div>'
+    )
+
+
+def flowchart_html(
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    fontsize: int = 14,
+    rankdir: str = "TD",
+    nodesep: float = 1,
+    ranksep: float = 1,
+    same_rank_groups: Optional[Sequence[Sequence[str]]] = None,
+) -> str:
+    """Build DOT, compute layout, and return interactive HTML string."""
+    # Important: exclude the icon row from Graphviz labels.
+    # In HTML mode we render icons via the web font in CSS, so if Graphviz
+    # tries to render the icon ligature text (e.g., "radio_button_unchecked")
+    # it will greatly expand node width because the font is typically missing.
+    # By disabling the icon row for layout we keep widths driven by title/sub only.
+    dot = build_dot(  # type: ignore[arg-type]
+        nodes,
+        edges,
+        fontsize=fontsize,
+        ranksep=ranksep,
+        nodesep=nodesep,
+        rankdir=rankdir,
+        same_rank_groups=same_rank_groups,
+        include_icon_row=False,
+    )
+    W, H, pos = layout(dot)
+    return render_html(W, H, pos, nodes, edges, ui_fontsize=fontsize, rankdir=rankdir)
+
+
+def save_html(
+    path: str,
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    **kwargs,
+) -> None:
+    """Write interactive HTML to disk."""
+    html_out = flowchart_html(nodes, edges, **kwargs)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(html_out)
+
+
+def _dot_png(dot: str) -> bytes:
+    """Render DOT to PNG bytes via Graphviz."""
+    return Source(dot).pipe(format="png")
+
+
+def show_matplotlib(
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    fontsize: int = 12,
+    rankdir: str = "TD",
+    nodesep: float = 0.6,
+    ranksep: float = 0.6,
+    same_rank_groups: Optional[Sequence[Sequence[str]]] = None,
+    ax=None,
+    *,
+    icon_fontname: Optional[str] = "Material Symbols Outlined",
+    icon_fontpath: Optional[str] = None,
+    icon_color: str = "#4a90e2",
+    icon_scale: float = 2.4,
+    label_cellpadding: Optional[int] = None,
+    node_margin: Optional[float] = None,
+    # NEW: edge styling and label control
+    edge_color: str = "#999999",
+    edge_penwidth: float = 1.6,
+    edge_font_scale: float = 0.8,
+    show_edge_labels: bool = True,
+):
+    """
+    Draw a static PNG from Graphviz into a Matplotlib Axes.
+    To use local Material Symbols, install the font and optionally pass icon_fontpath
+    pointing to the directory containing the .ttf file.
+    """
+    # Prepare kwargs and forward optional spacing only when explicitly provided
+    _kwargs = dict(
+        fontsize=fontsize,
+        ranksep=ranksep,
+        nodesep=nodesep,
+        rankdir=rankdir,
+        include_icon_row=True,
+        icon_fontname=icon_fontname,
+        icon_fontpath=icon_fontpath,
+        splines="curved",           # wavy edges
+        edge_label_mode="auto",     # switch to xlabel for curved splines
+        icon_color=icon_color,      # blue icons
+        icon_scale=icon_scale,      # larger icons
+        compact_label=True,         # tighter vertical spacing using <BR/>
+        label_lineheight=0.85,
+        label_leading=0.0,
+        # edge styling
+        edge_color=edge_color,
+        edge_penwidth=edge_penwidth,
+        edge_font_scale=edge_font_scale,
+        show_edge_labels=show_edge_labels,
+    )
+    if label_cellpadding is not None:
+        _kwargs["label_cellpadding"] = label_cellpadding
+    if node_margin is not None:
+        _kwargs["node_margin"] = node_margin
+
+    dot = build_dot(
+        nodes,
+        edges,
+        **_kwargs,
+    )
+    png = _dot_png(dot)
+
+    # Lazy import to keep module light
+    import matplotlib.pyplot as plt  # type: ignore
+    from PIL import Image  # type: ignore
+
+    im = Image.open(BytesIO(png)).convert("RGBA")
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(im.width / 96, im.height / 96), dpi=300)
+        return_fig = True
+    else:
+        return_fig = False
+    ax.imshow(im)
+    ax.axis("off")
+
+    if return_fig:
+        plt.close()
+        return fig
+
+
+def prune_nodes_to_edges(nodes: Sequence[Node], edges: Sequence[Edge]) -> List[Node]:
+    """Keep only nodes referenced by edges."""
+    keep = {u for (u, *_r) in edges} | {v for (_u, v, *_r) in edges}
+    return [n for n in nodes if n[0] in keep]
+
+
+def show_matplotlib_bioicons(
+    nodes: Sequence[Node],
+    edges: Sequence[Edge],
+    fontsize: int = 12,
+    rankdir: str = "TD",
+    nodesep: float = 0.6,
+    ranksep: float = 0.6,
+    same_rank_groups: Optional[Sequence[Sequence[str]]] = None,
+    ax=None,
+    *,
+    icon_size: float = 0.08,
+    icon_zoom: float = 1.0,
+    local_icons_dir: Optional[str] = None,
+    # edge styling
+    edge_color: str = "#999999",
+    edge_penwidth: float = 1.6,
+    edge_font_scale: float = 0.8,
+    show_edge_labels: bool = True,
+    # node styling
+    node_facecolor: str = "#ffffff",
+    node_edgecolor: str = "#cccccc",
+    node_alpha: float = 0.95,
+    node_boxstyle: str = "round,pad=0.4",
+):
+    """
+    Draw a flowchart with bioicons in Matplotlib.
+    
+    This function uses Graphviz for layout but renders the result natively
+    in Matplotlib, allowing bioicons to be displayed as images.
+    
+    Parameters
+    ----------
+    nodes : Sequence[Node]
+        List of nodes as (nid, icon, title, sub) tuples.
+        The icon field should be a bioicon ID or path to an image file.
+    edges : Sequence[Edge]
+        List of edges as (u, v) or (u, v, label) tuples.
+    fontsize : int
+        Base font size for text.
+    rankdir : str
+        Graph direction: "TD" (top-down), "LR" (left-right), etc.
+    nodesep, ranksep : float
+        Node and rank separation in Graphviz units.
+    same_rank_groups : Sequence[Sequence[str]], optional
+        Groups of node IDs to place at the same rank.
+    ax : Axes, optional
+        Matplotlib axes. Creates new figure if None.
+    icon_size : float
+        Size of icons relative to node width.
+    icon_zoom : float
+        Additional zoom factor for icons.
+    local_icons_dir : str, optional
+        Directory containing local icon files.
+    edge_color : str
+        Color for edges.
+    edge_penwidth : float
+        Width of edge lines.
+    edge_font_scale : float
+        Scale factor for edge label font.
+    show_edge_labels : bool
+        Whether to show edge labels.
+    node_facecolor : str
+        Background color for nodes.
+    node_edgecolor : str
+        Border color for nodes.
+    node_alpha : float
+        Transparency of node boxes.
+    node_boxstyle : str
+        Matplotlib boxstyle string for node boxes.
+        
+    Returns
+    -------
+    fig : Figure or None
+        Returns figure if ax was None, otherwise None.
+    """
+    import matplotlib.pyplot as plt
+    import matplotlib.patches as mpatches
+    from matplotlib.patches import FancyBboxPatch, FancyArrowPatch
+    from matplotlib.path import Path as MplPath
+    import matplotlib.patheffects as path_effects
+
+    from ..bioicons import BioIcons
+
+    # Build DOT for layout only (no icons in labels to keep sizing accurate)
+    dot = build_dot(
+        nodes,
+        edges,
+        fontsize=fontsize,
+        ranksep=ranksep,
+        nodesep=nodesep,
+        rankdir=rankdir,
+        same_rank_groups=same_rank_groups,
+        include_icon_row=False,  # Icons rendered separately
+        splines="curved",
+        show_edge_labels=False,  # We'll handle labels ourselves
+    )
+
+    W, H, pos = layout(dot)
+
+    # Setup figure
+    return_fig = False
+    if ax is None:
+        fig_width = W / 72  # Convert points to inches
+        fig_height = H / 72
+        fig, ax = plt.subplots(figsize=(fig_width, fig_height), dpi=150)
+        return_fig = True
+    else:
+        fig = ax.get_figure()
+
+    ax.set_xlim(0, W)
+    ax.set_ylim(0, H)
+    ax.set_aspect("equal")
+    ax.axis("off")
+
+    # Initialize bioicons
+    icons = BioIcons(
+        local_icons_dir=local_icons_dir,
+    )
+
+    # Draw nodes
+    for nid, icon_id, title, sub in nodes:
+        if nid not in pos:
+            continue
+        d = pos[nid]
+        x, y, w, h = d["x"], d["y"], d["w"], d["h"]
+
+        # Draw node box
+        box = FancyBboxPatch(
+            (x - w/2, y - h/2),
+            w, h,
+            boxstyle=node_boxstyle,
+            facecolor=node_facecolor,
+            edgecolor=node_edgecolor,
+            alpha=node_alpha,
+            linewidth=1,
+            zorder=1,
+        )
+        ax.add_patch(box)
+
+        # Calculate positions for icon and text
+        icon_h = h * 0.35  # Icon takes top 35% of node
+        text_area_top = y + h/2 - icon_h - 2
+
+        # Draw icon at top of node
+        if icon_id:
+            icon_y = y + h/2 - icon_h/2 - 2
+            icons.plot(
+                icon_id,
+                ax=ax,
+                x=x,
+                y=icon_y,
+                size=icon_size * icon_zoom,
+                zorder=2,
+            )
+
+        # Draw title
+        title_y = text_area_top - 4
+        ax.text(
+            x, title_y,
+            title,
+            ha="center", va="top",
+            fontsize=fontsize,
+            fontweight="medium",
+            color="#333333",
+            zorder=3,
+        )
+
+        # Draw subtitle
+        sub_y = title_y - fontsize * 1.2
+        ax.text(
+            x, sub_y,
+            sub,
+            ha="center", va="top",
+            fontsize=int(fontsize * 0.85),
+            color="#666666",
+            zorder=3,
+        )
+
+    # Draw edges
+    edge_fontsize = int(fontsize * edge_font_scale)
+    for edge in edges:
+        u, v = edge[0], edge[1]
+        label = edge[2] if len(edge) > 2 else None
+
+        if u not in pos or v not in pos:
+            continue
+
+        src = pos[u]
+        dst = pos[v]
+
+        # Calculate edge start/end points based on rankdir
+        if rankdir in ("TD", "BT"):
+            x1, y1 = src["x"], src["y"] - src["h"]/2
+            x2, y2 = dst["x"], dst["y"] + dst["h"]/2
+        else:  # LR, RL
+            x1, y1 = src["x"] + src["w"]/2, src["y"]
+            x2, y2 = dst["x"] - dst["w"]/2, dst["y"]
+
+        # Draw curved arrow
+        arrow = FancyArrowPatch(
+            (x1, y1), (x2, y2),
+            connectionstyle="arc3,rad=0.1",
+            arrowstyle="->,head_width=4,head_length=6",
+            color=edge_color,
+            linewidth=edge_penwidth,
+            zorder=0,
+        )
+        ax.add_patch(arrow)
+
+        # Draw edge label if enabled
+        if show_edge_labels and label:
+            mid_x = (x1 + x2) / 2
+            mid_y = (y1 + y2) / 2
+            ax.text(
+                mid_x, mid_y,
+                str(label),
+                ha="center", va="center",
+                fontsize=edge_fontsize,
+                color="#666666",
+                bbox=dict(
+                    facecolor="white",
+                    edgecolor="none",
+                    alpha=0.8,
+                    pad=2,
+                ),
+                zorder=2,
+            )
+
+    if return_fig:
+        plt.tight_layout()
+        return fig
+    return None