archgraph-layout 1.0.0__py3-none-any.whl

archgraph/__init__.py

@@ -0,0 +1,108 @@
+"""archgraph — hierarchical architecture diagrams with floorplanning layout and orthogonal routing.
+
+Typical use::
+
+    import archgraph
+    g = archgraph.build("system.xml")            # parse + layout + route
+    open("system.svg", "w").write(archgraph.to_svg(g))
+
+or from the command line::
+
+    archgraph render system.xml -o system.svg
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from .model import ArchGraphError, Graph
+from .parser import parse_file, parse_string
+# import subpackages eagerly so the public functions below are not shadowed by them
+from .placement import engine as _engine  # noqa: E402
+from . import routing as _routing  # noqa: E402
+
+__version__ = "1.0.0"
+__all__ = ["load", "loads", "layout", "route", "build", "to_svg", "to_html", "to_json", "to_png", "save",
+           "ArchGraphError", "Graph", "__version__"]
+
+
+def load(path: str) -> Graph:
+    """Parse an XML file into a :class:`Graph` (no layout yet)."""
+    return parse_file(path)
+
+
+def loads(text: str, base_dir: Optional[str] = None) -> Graph:
+    """Parse XML text into a :class:`Graph`."""
+    return parse_string(text, base_dir=base_dir)
+
+
+def layout(g: Graph) -> Graph:
+    """Place every block and subsystem (and assign ports)."""
+    _engine.layout(g)
+    return g
+
+
+def route(g: Graph) -> Graph:
+    """Route all connections and buses, nudge them apart and place labels."""
+    _routing.route(g)
+    from .geometry import Rect
+    rects = [e.rect for e in g.root.iter_descendants()]
+    g.bbox = Rect.bounding(rects)
+    return g
+
+
+def build(source: str, **overrides) -> Graph:
+    """Parse (file path or XML text), apply setting overrides, lay out and route."""
+    t0 = time.time()
+    if os.path.exists(source) or source.lower().endswith(".xml"):
+        g = parse_file(source)
+    else:
+        g = parse_string(source)
+    from .parser import apply_setting
+    errs = []
+    for k, v in overrides.items():
+        if v is not None:
+            apply_setting(g.settings, k, str(v), errs, "override")
+    if errs:
+        raise ArchGraphError(errs)
+    layout(g)
+    route(g)
+    if g.settings.routing == "orthogonal" and g.settings.num_spacing_passes() > 0:
+        _engine.expand_congested(g, route, g.settings.num_spacing_passes())
+    g.layout_stats["total_time"] = time.time() - t0
+    return g
+
+
+def to_svg(g: Graph) -> str:
+    from .render.svg import render_svg
+    return render_svg(g)
+
+
+def to_html(g: Graph) -> str:
+    from .render.html import render_html
+    return render_html(g, to_svg(g))
+
+
+def to_json(g: Graph) -> str:
+    from .render.jsonout import render_json
+    return render_json(g)
+
+
+def to_png(g: Graph, path: str, scale: float = 2.0) -> None:
+    from .render.png import render_png
+    render_png(to_svg(g), path, scale)
+
+
+def save(g: Graph, path: str, fmt: Optional[str] = None, scale: float = 2.0) -> str:
+    """Write the diagram; the format follows the extension unless ``fmt`` is given."""
+    fmt = (fmt or os.path.splitext(path)[1].lstrip(".") or "svg").lower()
+    if fmt == "png":
+        to_png(g, path, scale)
+        return path
+    text = {"svg": to_svg, "html": to_html, "htm": to_html, "json": to_json}.get(fmt)
+    if text is None:
+        raise ArchGraphError(f"unsupported output format '{fmt}' (svg, html, json, png)")
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(text(g))
+    return path

archgraph/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

archgraph/cli.py

@@ -0,0 +1,110 @@
+"""Command line interface: ``archgraph render|validate|stats|expand``."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import __version__
+from .model import ArchGraphError
+
+
+def _common(p):
+    p.add_argument("input", help="XML diagram description")
+    p.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                   help="override a setting, e.g. --set aspect=4:3 --set theme=dark (repeatable)")
+    p.add_argument("--quality", choices=["draft", "normal", "high", "max"], help="layout effort")
+    p.add_argument("--theme", help="light | dark | blueprint | mono | pastel")
+    p.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 1.5, square")
+    p.add_argument("--direction", help="default flow LR | RL | TB | BT")
+    p.add_argument("--seed", type=int, help="random seed (layouts are deterministic per seed)")
+
+
+def _overrides(args):
+    ov = {}
+    for item in args.set:
+        if "=" not in item:
+            raise ArchGraphError(f"--set expects KEY=VALUE, got '{item}'")
+        k, v = item.split("=", 1)
+        ov[k.strip()] = v.strip()
+    for k in ("quality", "theme", "aspect", "direction", "seed"):
+        v = getattr(args, k, None)
+        if v is not None:
+            ov[k] = v
+    return ov
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="archgraph", description="Hierarchical architecture diagrams from XML.")
+    ap.add_argument("--version", action="version", version=f"archgraph {__version__}")
+    sub = ap.add_subparsers(dest="cmd")
+    r = sub.add_parser("render", help="lay out, route and render a diagram")
+    _common(r)
+    r.add_argument("-o", "--output", action="append", default=[],
+                   help="output file(s); format from extension: .svg .html .json .png (repeatable)")
+    r.add_argument("--scale", type=float, default=2.0, help="PNG pixel scale")
+    r.add_argument("--stats", action="store_true", help="print layout quality metrics")
+    v = sub.add_parser("validate", help="check the XML and report errors/warnings")
+    v.add_argument("input")
+    s = sub.add_parser("stats", help="lay out and print quality metrics as JSON")
+    _common(s)
+    e = sub.add_parser("expand", help="print the XML after templates/repeats/includes are expanded")
+    e.add_argument("input")
+    args = ap.parse_args(argv)
+    if not args.cmd:
+        # shorthand: archgraph file.xml [-o out]
+        if argv is None:
+            argv = sys.argv[1:]
+        if argv and not argv[0].startswith("-"):
+            return main(["render"] + list(argv))
+        ap.print_help()
+        return 1
+    try:
+        if args.cmd == "validate":
+            from .parser import parse_file
+            g = parse_file(args.input)
+            n = len(g.nodes())
+            print(f"OK: {n} blocks, {len(g.subsystems())} subsystems, {len(g.edges)} connections, "
+                  f"{len(g.buses)} buses, {len(g.hints)} layout hints")
+            for w in g.warnings:
+                print("warning:", w)
+            return 0
+        if args.cmd == "expand":
+            import xml.etree.ElementTree as ET
+            from .parser import parse_file
+            g = parse_file(args.input)
+            root = g.extras["expanded_xml"]
+            for el in root.iter():
+                for k in [k for k in el.attrib if k.startswith("__")]:
+                    del el.attrib[k]
+            ET.indent(root)
+            print(ET.tostring(root, encoding="unicode"))
+            return 0
+        from . import build, save
+        from .quality import metrics
+        t0 = time.time()
+        g = build(args.input, **_overrides(args))
+        for w in g.warnings:
+            print("warning:", w, file=sys.stderr)
+        if args.cmd == "stats":
+            print(json.dumps(metrics(g), indent=1))
+            return 0
+        outs = args.output or [os.path.splitext(args.input)[0] + ".svg"]
+        for o in outs:
+            save(g, o, scale=args.scale)
+            print(f"wrote {o}")
+        if args.stats:
+            print(json.dumps(metrics(g), indent=1))
+        print(f"done in {time.time() - t0:.1f}s", file=sys.stderr)
+        return 0
+    except ArchGraphError as ex:
+        print("error:", file=sys.stderr)
+        for m in ex.messages:
+            print("  " + m, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

archgraph/geometry.py

@@ -0,0 +1,256 @@
+"""Small geometry toolkit used throughout archgraph.
+
+Coordinates follow SVG conventions: x grows to the right, y grows downward.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+Point = Tuple[float, float]
+
+EPS = 1e-6
+
+# Side constants (compass notation).  N is "up" (smaller y).
+N, E, S, W = "N", "E", "S", "W"
+SIDES = (N, E, S, W)
+SIDE_NORMALS = {N: (0.0, -1.0), E: (1.0, 0.0), S: (0.0, 1.0), W: (-1.0, 0.0)}
+OPPOSITE = {N: S, S: N, E: W, W: E}
+
+SIDE_ALIASES = {
+    "n": N, "north": N, "top": N, "up": N, "t": N,
+    "e": E, "east": E, "right": E, "r": E,
+    "s": S, "south": S, "bottom": S, "down": S, "b": S,
+    "w": W, "west": W, "left": W, "l": W,
+}
+
+
+def parse_side(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    v = str(value).strip().lower()
+    if v in ("", "auto", "any", "none"):
+        return None
+    if v not in SIDE_ALIASES:
+        raise ValueError(f"unknown side '{value}' (use north/east/south/west)")
+    return SIDE_ALIASES[v]
+
+
+@dataclass
+class Rect:
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+    @staticmethod
+    def from_center(cx: float, cy: float, w: float, h: float) -> "Rect":
+        return Rect(cx - w / 2.0, cy - h / 2.0, cx + w / 2.0, cy + h / 2.0)
+
+    @staticmethod
+    def bounding(rects: Iterable["Rect"]) -> Optional["Rect"]:
+        rs = list(rects)
+        if not rs:
+            return None
+        return Rect(min(r.x0 for r in rs), min(r.y0 for r in rs),
+                    max(r.x1 for r in rs), max(r.y1 for r in rs))
+
+    @staticmethod
+    def of_points(pts: Iterable[Point]) -> Optional["Rect"]:
+        pts = list(pts)
+        if not pts:
+            return None
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        return Rect(min(xs), min(ys), max(xs), max(ys))
+
+    @property
+    def w(self) -> float:
+        return self.x1 - self.x0
+
+    @property
+    def h(self) -> float:
+        return self.y1 - self.y0
+
+    @property
+    def cx(self) -> float:
+        return (self.x0 + self.x1) / 2.0
+
+    @property
+    def cy(self) -> float:
+        return (self.y0 + self.y1) / 2.0
+
+    @property
+    def area(self) -> float:
+        return max(0.0, self.w) * max(0.0, self.h)
+
+    def inflate(self, dx: float, dy: Optional[float] = None) -> "Rect":
+        if dy is None:
+            dy = dx
+        return Rect(self.x0 - dx, self.y0 - dy, self.x1 + dx, self.y1 + dy)
+
+    def translate(self, dx: float, dy: float) -> "Rect":
+        return Rect(self.x0 + dx, self.y0 + dy, self.x1 + dx, self.y1 + dy)
+
+    def contains_point(self, x: float, y: float, strict: bool = False) -> bool:
+        if strict:
+            return self.x0 + EPS < x < self.x1 - EPS and self.y0 + EPS < y < self.y1 - EPS
+        return self.x0 - EPS <= x <= self.x1 + EPS and self.y0 - EPS <= y <= self.y1 + EPS
+
+    def contains_rect(self, o: "Rect", tol: float = EPS) -> bool:
+        return (o.x0 >= self.x0 - tol and o.y0 >= self.y0 - tol and
+                o.x1 <= self.x1 + tol and o.y1 <= self.y1 + tol)
+
+    def overlaps(self, o: "Rect", tol: float = EPS) -> bool:
+        return (self.x0 < o.x1 - tol and o.x0 < self.x1 - tol and
+                self.y0 < o.y1 - tol and o.y0 < self.y1 - tol)
+
+    def overlap_area(self, o: "Rect") -> float:
+        dx = min(self.x1, o.x1) - max(self.x0, o.x0)
+        dy = min(self.y1, o.y1) - max(self.y0, o.y0)
+        if dx <= 0 or dy <= 0:
+            return 0.0
+        return dx * dy
+
+    def union(self, o: "Rect") -> "Rect":
+        return Rect(min(self.x0, o.x0), min(self.y0, o.y0), max(self.x1, o.x1), max(self.y1, o.y1))
+
+    def side_point(self, side: str, t: float = 0.5) -> Point:
+        """Point on a side; t in [0,1] runs left->right (N/S) or top->bottom (E/W)."""
+        if side == N:
+            return (self.x0 + t * self.w, self.y0)
+        if side == S:
+            return (self.x0 + t * self.w, self.y1)
+        if side == E:
+            return (self.x1, self.y0 + t * self.h)
+        return (self.x0, self.y0 + t * self.h)
+
+    def as_tuple(self) -> Tuple[float, float, float, float]:
+        return (self.x0, self.y0, self.x1, self.y1)
+
+
+def manhattan(a: Point, b: Point) -> float:
+    return abs(a[0] - b[0]) + abs(a[1] - b[1])
+
+
+def dist(a: Point, b: Point) -> float:
+    return math.hypot(a[0] - b[0], a[1] - b[1])
+
+
+def segment_intersects_rect(p: Point, q: Point, r: Rect, strict: bool = True) -> bool:
+    """Liang-Barsky clip test. ``strict`` ignores touching the boundary."""
+    x0, y0 = p
+    dx, dy = q[0] - p[0], q[1] - p[1]
+    shrink = EPS * 10 if strict else -EPS
+    rx0, ry0, rx1, ry1 = r.x0 + shrink, r.y0 + shrink, r.x1 - shrink, r.y1 - shrink
+    if rx0 >= rx1 or ry0 >= ry1:
+        return False
+    t0, t1 = 0.0, 1.0
+    for pp, qq in ((-dx, x0 - rx0), (dx, rx1 - x0), (-dy, y0 - ry0), (dy, ry1 - y0)):
+        if abs(pp) < 1e-12:
+            if qq < 0:
+                return False
+        else:
+            t = qq / pp
+            if pp < 0:
+                if t > t1:
+                    return False
+                t0 = max(t0, t)
+            else:
+                if t < t0:
+                    return False
+                t1 = min(t1, t)
+    return t0 <= t1
+
+
+def _orient(a: Point, b: Point, c: Point) -> float:
+    return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+
+
+def segments_cross(a: Point, b: Point, c: Point, d: Point) -> bool:
+    """True if open segments ab and cd properly cross (shared endpoints do not count)."""
+    o1 = _orient(a, b, c)
+    o2 = _orient(a, b, d)
+    o3 = _orient(c, d, a)
+    o4 = _orient(c, d, b)
+    return (o1 * o2 < -1e-9) and (o3 * o4 < -1e-9)
+
+
+def simplify_polyline(pts: Sequence[Point], tol: float = 1e-6) -> List[Point]:
+    """Remove duplicate and collinear interior points of an axis-parallel polyline."""
+    out: List[Point] = []
+    for p in pts:
+        p = (float(p[0]), float(p[1]))
+        if out and abs(out[-1][0] - p[0]) < tol and abs(out[-1][1] - p[1]) < tol:
+            continue
+        out.append(p)
+    changed = True
+    while changed and len(out) >= 3:
+        changed = False
+        res = [out[0]]
+        for i in range(1, len(out) - 1):
+            a, b, c = res[-1], out[i], out[i + 1]
+            if abs(_orient(a, b, c)) < tol * max(1.0, dist(a, c)):
+                # b is collinear; drop it only if it lies between a and c
+                if (min(a[0], c[0]) - tol <= b[0] <= max(a[0], c[0]) + tol and
+                        min(a[1], c[1]) - tol <= b[1] <= max(a[1], c[1]) + tol):
+                    changed = True
+                    continue
+            res.append(b)
+        res.append(out[-1])
+        out = res
+    return out
+
+
+def polyline_length(pts: Sequence[Point]) -> float:
+    return sum(dist(pts[i], pts[i + 1]) for i in range(len(pts) - 1))
+
+
+def polyline_point_at(pts: Sequence[Point], frac: float) -> Tuple[Point, int]:
+    """Point at fraction ``frac`` of the total length; also returns segment index."""
+    total = polyline_length(pts)
+    if total <= 0:
+        return pts[0], 0
+    target = frac * total
+    acc = 0.0
+    for i in range(len(pts) - 1):
+        seg = dist(pts[i], pts[i + 1])
+        if acc + seg >= target - 1e-9:
+            t = 0.0 if seg == 0 else (target - acc) / seg
+            p = (pts[i][0] + t * (pts[i + 1][0] - pts[i][0]), pts[i][1] + t * (pts[i + 1][1] - pts[i][1]))
+            return p, i
+        acc += seg
+    return pts[-1], len(pts) - 2
+
+
+def count_bends(pts: Sequence[Point]) -> int:
+    return max(0, len(simplify_polyline(pts)) - 2)
+
+
+def side_of_point(rect: Rect, x: float, y: float) -> str:
+    """Side of ``rect`` closest in direction to the point, normalised by rect size."""
+    dx = (x - rect.cx) / max(rect.w / 2.0, 1.0)
+    dy = (y - rect.cy) / max(rect.h / 2.0, 1.0)
+    if abs(dx) >= abs(dy):
+        return E if dx >= 0 else W
+    return S if dy >= 0 else N
+
+
+def parse_aspect(value) -> Optional[float]:
+    """Accepts '16:9', '1.6', 'square', 'wide', 'tall', 'auto'."""
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    v = str(value).strip().lower()
+    named = {"square": 1.0, "wide": 16 / 9, "widescreen": 16 / 9, "tall": 9 / 16, "portrait": 1 / math.sqrt(2),
+             "landscape": math.sqrt(2), "a4": math.sqrt(2), "letter": 11 / 8.5, "golden": 1.618, "auto": None,
+             "free": None, "none": None}
+    if v in named:
+        return named[v]
+    for sep in (":", "/", "x"):
+        if sep in v:
+            a, b = v.split(sep, 1)
+            return float(a) / float(b)
+    return float(v)