sysml2tikz 0.0.1__py3-none-any.whl

sysml2tikz/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jon R. Fox and Hermes Agent
+"""sysml2tikz — SysML v2 notation for LaTeX/TikZ.
+
+Two halves, usable separately:
+
+* ``sysml2tikz.sty`` (shipped inside this distribution) is the LaTeX notation
+  layer, licensed MPL-2.0 OR LPPL-1.3c. Use it directly with
+  ``\\usepackage{sysml2tikz}`` if you only want figures in a paper.
+* this Python package turns a SysML v2 model (or a notation IR) into a ``.tex``
+  file: ``project`` (sysmlpy -> IR), ``emit`` (IR -> .tex), ``layout``
+  (TeX-measured sizes -> routed coordinates).
+
+Nothing here is required to use the ``.sty``, and the ``.sty`` is not required
+to emit IR.
+"""
+from importlib.resources import files
+
+__version__ = "0.0.1"
+
+def sty_path() -> str:
+    """Absolute path of the bundled ``sysml2tikz.sty`` (for TEXINPUTS)."""
+    return str(files(__name__).joinpath("sysml2tikz.sty"))
+
+__all__ = ["__version__", "sty_path"]

sysml2tikz/cli.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jon R. Fox and Hermes Agent
+"""Command line entry points.
+
+    sysml2tikz emit     model.json out.tex     IR -> .tex
+    sysml2tikz layout   model.json out.tex     IR -> measured + routed .tex
+    sysml2tikz project  model.sysml out.json   SysML v2 text -> IR
+    sysml2tikz sty                             print the bundled .sty path
+    sysml2tikz version
+"""
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+
+
+def _usage() -> int:
+    print(__doc__.strip())
+    return 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        return _usage()
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "version":
+        print(__version__)
+        return 0
+    if cmd == "sty":
+        from . import sty_path
+        print(sty_path())
+        return 0
+    if cmd == "emit":
+        from .emit import main as run
+        return run(["emit"] + rest)
+    if cmd == "layout":
+        from .layout import main as run
+        return run(["layout"] + rest)
+    if cmd == "project":
+        from .project import main as run
+        return run(["project"] + rest)
+    if cmd in ("-h", "--help", "help"):
+        return _usage()
+    print("unknown subcommand: %s\n" % cmd, file=sys.stderr)
+    return _usage()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sysml2tikz/emit.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jon R. Fox and Hermes Agent
+r"""emit_tex.py — reference implementation of stage 4 of the sysml2tikz pipeline.
+
+Reads a small notation IR (JSON) and writes a TikZ .tex file that uses
+sysml2tikz.sty. Deliberately dumb: no parsing, no layout engine, no model
+semantics — those are stages 1-3. This exists to pin down the emitter
+contract (row mini-syntax, escaping, deterministic ordering) and to prove the
+IR is expressive enough for definition/usage figures.
+
+Row mini-syntax (one string per compartment row):
+    "*perform* providePower"   -> keyword in bold:  \kw{perform} providePower
+    ":>>Vehicle::mass"         -> redefinition row: \redefines{:>>Vehicle::mass}
+    "mass :> mass"             -> plain text, ':>' kept literally
+    "text = \"1800 kg\""       -> plain text, '=' kept literally
+
+Usage:
+    python3 emit_tex.py model.json out.tex
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+# LaTeX specials that must not reach the output raw. Order matters: backslash
+# first, then the rest. ':' '>' '=' '<' '"' are left alone on purpose — they
+# are SysML notation, and the font encoding handles them.
+_ESCAPE = {
+    "\\": r"\textbackslash{}",
+    "_": r"\_",
+    "&": r"\&",
+    "%": r"\%",
+    "#": r"\#",
+    "$": r"\$",
+    "~": r"\textasciitilde{}",
+    "^": r"\textasciicircum{}",
+}
+
+
+def esc(text: str) -> str:
+    out = []
+    for ch in text:
+        out.append(_ESCAPE.get(ch, ch))
+    return "".join(out)
+
+
+def render_row(row: str) -> str:
+    """Turn one IR row string into LaTeX source (no trailing line break)."""
+    row = row.strip()
+    if row.startswith(":>>"):
+        # '>>' is a ligature in T1/TU fonts and prints as »; break it explicitly
+        return r"\redefines{:\textgreater{}\textgreater{}%s}" % esc(row[3:])
+    # *keyword* anywhere in the row becomes \kw{keyword}
+    parts = re.split(r"\*([^*]+)\*", row)
+    out = []
+    for i, part in enumerate(parts):
+        out.append((r"\kw{%s}" % esc(part)) if i % 2 else esc(part))
+    return "".join(out)
+
+
+def render_compartments(compartments) -> str:
+    bits = []
+    for comp in compartments:
+        bits.append(r"\sysmlcomp{%s}" % esc(comp["label"]))
+        for row in comp["rows"]:
+            bits.append(render_row(row) + r"\\")
+    # the final row keeps its \\ so the tabular closes cleanly
+    return "".join(bits)
+
+
+def emit_node(node: dict) -> str:
+    kind = node["kind"]
+    place = node.get("place")  # e.g. "at={(0,0)}" or "below=of veh"
+    opt = f"[{place}]" if place else "[at={(0,0)}]"
+    body = render_compartments(node.get("compartments", []))
+    if kind.endswith(" def"):
+        return (
+            "  \\sysmldefnode%s{%s}{%s}{%s}{%%\n    %s\n  }\n"
+            % (opt, node["id"], esc(kind), esc(node["name"]), body)
+        )
+    # a usage: header carries "name : Type"
+    return (
+        "  \\sysmlusagenode%s{%s}{%s}{%s}{%s}{%%\n    %s\n  }\n"
+        % (opt, node["id"], esc(kind), esc(node["name"]), esc(node.get("type", "")), body)
+    )
+
+
+def emit_port(port: dict) -> str:
+    return "  \\sysmlport{%s}{%s}{%s}{%s}\n" % (
+        port["node"],
+        port["side"],
+        esc(port["name"]),
+        port.get("label_side", "above"),
+    )
+
+
+def emit_edge(edge: dict) -> str:
+    style = edge.get("style", "reference")
+    src = edge["src"] if "src_port" not in edge else "%s-p-%s" % (edge["src"], edge["src_port"])
+    dst = edge["dst"] if "dst_port" not in edge else "%s-p-%s" % (edge["dst"], edge["dst_port"])
+    bits = [r"  \draw[sysml %s] (%s)" % (style, src)]
+    route = edge.get("route")
+    if route == "arc-right":
+        bits.append(r" to[out=0, in=0, looseness=1.15]")
+    elif route == "arc-left":
+        bits.append(r" to[out=180, in=180, looseness=1.15]")
+    if route and route.startswith("bend-"):
+        bits.append(r" to[bend %s]" % route.split("-", 1)[1])
+    if not route:
+        bits.append(r" --")
+    label = edge.get("label")
+    if label:
+        bits.append(r" node[%s, font=\scriptsize, pos=0.5]{%s}"
+                    % (edge.get("label_side", "right"), esc(label)))
+    bits.append(" (%s);\n" % dst)
+    return "".join(bits)
+
+
+def emit(model: dict) -> str:
+    head = [
+        r"\documentclass[tikz,border=10pt]{standalone}",
+        r"\usepackage{sysml2tikz}",
+        r"\begin{document}",
+        r"\begin{tikzpicture}[node distance=%s]" % model.get("node_distance", "12mm"),
+        "",
+    ]
+    body = []
+    for node in model.get("nodes", []):
+        body.append(emit_node(node))
+    body.append("")
+    for port in model.get("ports", []):
+        body.append(emit_port(port))
+    body.append("")
+    for edge in model.get("edges", []):
+        body.append(emit_edge(edge))
+    tail = [r"\end{tikzpicture}", r"\end{document}", ""]
+    return "\n".join(head + body + tail)
+
+
+def copy_sty(dest_dir: str) -> str:
+    """Drop the bundled .sty next to the output so any TeX engine finds it.
+
+    tectonic resolves packages from its bundle, not from TEXINPUTS, and a plain
+    TeX Live only finds sysml2tikz once CTAN has shipped it — so the reliable
+    move for a pip-only install is to put the file in the document's directory.
+    """
+    from importlib.resources import files
+    import shutil
+
+    src = files("sysml2tikz").joinpath("sysml2tikz.sty")
+    dest = os.path.join(dest_dir, "sysml2tikz.sty")
+    with open(dest, "wb") as fh:
+        fh.write(src.read_bytes())
+    return dest
+
+
+def main(argv: list[str]) -> int:
+    argv = [a for a in argv if a != "--copy-sty"]
+    want_sty = "--copy-sty" in sys.argv
+    if len(argv) != 3:
+        print(__doc__)
+        return 2
+    with open(argv[1], encoding="utf-8") as fh:
+        model = json.load(fh)
+    tex = emit(model)
+    with open(argv[2], "w", encoding="utf-8") as fh:
+        fh.write(tex)
+    if want_sty:
+        print("copied", copy_sty(os.path.dirname(os.path.abspath(argv[2]))))
+    print("wrote", argv[2], "(%d bytes, %d nodes, %d edges)"
+          % (len(tex), len(model.get("nodes", [])), len(model.get("edges", []))))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

sysml2tikz/layout.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jon R. Fox and Hermes Agent
+"""layout_adapter.py — stage 3 of the sysml2tikz pipeline.
+
+TikZ does not lay out graphs, and diagramboxes does not know how wide a TikZ
+tabular will be. So: measure in TeX, lay out in diagramboxes, emit absolute
+coordinates.
+
+    1. measure   emit a throwaway .tex that places every block, then prints
+                 width()/height() for each via \\typeout; compile with tectonic
+                 --keep-logs and parse the log.
+    2. layout    build a diagramboxes Diagram with those exact sizes (the
+                 per-node `_calc_size` is neutered so the real size survives),
+                 run its orthogonal router, read node origins and edge
+                 waypoints.
+    3. emit      write the real .tex with at={(x,y)} per node and one
+                 \\draw ... -- (x,y) -- ... polyline per edge.
+
+Usage:
+    python3 layout_adapter.py model.json out.tex [--scale 4.0]
+
+`--scale` is points per diagramboxes unit. Sizes are divided by it going in
+and multiplied coming out, so the router's gaps mean "scale points".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+
+# ---------------------------------------------------------------- emit helpers
+_ESCAPE = {
+    "\\": r"\textbackslash{}", "&": r"\&", "%": r"\%", "#": r"\#",
+    "$": r"\$", "~": r"\textasciitilde{}", "^": r"\textasciicircum{}",
+    "_": r"\_",
+}
+
+
+def esc(text: str) -> str:
+    return "".join(_ESCAPE.get(c, c) for c in text)
+
+
+def render_row(row: str) -> str:
+    row = row.strip()
+    if row.startswith(":>>"):
+        # '>>' is a ligature in T1/TU fonts and prints as »; break it explicitly
+        return r"\redefines{:\textgreater{}\textgreater{}%s}" % esc(row[3:])
+    parts = re.split(r"\*([^*]+)\*", row)
+    out = []
+    for i, part in enumerate(parts):
+        out.append((r"\kw{%s}" % esc(part)) if i % 2 else esc(part))
+    return "".join(out)
+
+
+def node_body(node: dict) -> str:
+    bits = []
+    for comp in node.get("compartments", []):
+        bits.append(r"\sysmlcomp{%s}" % esc(comp["label"]))
+        for row in comp["rows"]:
+            bits.append(render_row(row) + r"\\")
+    return "".join(bits)
+
+
+def node_call(node: dict, opt: str) -> str:
+    kind = node["kind"]
+    body = node_body(node)
+    if kind.endswith(" def"):
+        return ("  \\sysmldefnode%s{%s}{%s}{%s}{%%\n    %s\n  }\n"
+                % (opt, node["id"], esc(kind), esc(node["name"]), body))
+    return ("  \\sysmlusagenode%s{%s}{%s}{%s}{%s}{%%\n    %s\n  }\n"
+            % (opt, node["id"], esc(kind), esc(node["name"]),
+               esc(node.get("type", "")), body))
+
+
+# ------------------------------------------------------------------- 1 measure
+def measure(model: dict, workdir: str, tectonic: str) -> dict[str, tuple[float, float]]:
+    """Return {node id: (width_pt, height_pt)} measured by TeX itself."""
+    nodes = model.get("nodes", [])
+    # spread them out so nothing overlaps while measuring
+    lines = [r"\documentclass[tikz,border=2pt,multi=false]{standalone}",
+             r"\usepackage{sysml2tikz}",
+             r"\begin{document}",
+             r"\begin{tikzpicture}[x=200cm,y=1cm]"]
+    for i, node in enumerate(nodes):
+        lines.append(node_call(node, "[at={(%.3fcm,0)}]" % i))
+    for node in nodes:
+        # measure by anchor difference: width("name") is fragile with quoting
+        lines.append(r"  \newdimen\sysmlw\newdimen\sysmlh")
+        lines.append(r"  \pgfextractx{\sysmlw}{\pgfpointdiff{\pgfpointanchor{%s}{west}}"
+                     r"{\pgfpointanchor{%s}{east}}}" % (node["id"], node["id"]))
+        lines.append(r"  \pgfextracty{\sysmlh}{\pgfpointdiff{\pgfpointanchor{%s}{south}}"
+                     r"{\pgfpointanchor{%s}{north}}}" % (node["id"], node["id"]))
+        lines.append(r"  \typeout{SYSMLSZ %s \the\sysmlw}" % node["id"])
+        lines.append(r"  \typeout{SYSMLSH %s \the\sysmlh}" % node["id"])
+    lines += [r"\end{tikzpicture}", r"\end{document}", ""]
+    tex = os.path.join(workdir, "measure.tex")
+    with open(tex, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+    subprocess.run([tectonic, "--keep-logs", tex], cwd=workdir,
+                   check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    log = os.path.join(workdir, "measure.log")
+    sizes: dict[str, dict[str, float]] = {}
+    with open(log, encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            m = re.search(r"SYSMLSZ (\S+) ([\d.]+)", line)
+            if m:
+                sizes.setdefault(m.group(1), {})["w"] = float(m.group(2))
+            m = re.search(r"SYSMLSH (\S+) ([\d.]+)", line)
+            if m:
+                sizes.setdefault(m.group(1), {})["h"] = float(m.group(2))
+    missing = [n["id"] for n in nodes if n["id"] not in sizes]
+    if missing:
+        raise SystemExit("measure failed for: %s" % ", ".join(missing))
+    return {k: (v["w"], v["h"]) for k, v in sizes.items()}
+
+
+# -------------------------------------------------------------------- 2 layout
+def layout(model: dict, sizes: dict[str, tuple[float, float]], scale: float,
+           layer_gap: int, node_gap: int):
+    try:
+        from diagramboxes.layout import Diagram
+    except ImportError:                    # dev checkout without an install
+        sys.path.insert(0, os.path.expanduser("~/proj/diagramboxes"))
+        try:
+            from diagramboxes.layout import Diagram
+        except ImportError as exc:
+            raise SystemExit(
+                "layout needs diagramboxes (pip install 'sysml2tikz[layout]'): %s" % exc)
+
+    d = Diagram()
+    by_id = {}
+    for node in model.get("nodes", []):
+        n = d.add_node(node["id"])
+        n._calc_size = lambda: None          # keep the TeX size, do not re-derive
+        w, h = sizes[node["id"]]
+        # diagramboxes' router works in integer pixel units
+        n.w, n.h = max(1, int(round(w / scale))), max(1, int(round(h / scale)))
+        by_id[node["id"]] = n
+    # ports: IR side names -> diagramboxes sides; the router docks on them
+    side_map = {"east": "right", "west": "left", "north": "top", "south": "bottom"}
+    ports: dict[tuple[str, str], object] = {}
+    for port in model.get("ports", []):
+        node = by_id[port["node"]]
+        db_side = side_map[port["side"]]
+        ports[(port["node"], port["side"])] = node.add_port(
+            port["name"], side=db_side, offset=0.5,
+            direction=port.get("direction"))
+    for edge in model.get("edges", []):
+        kw = {}
+        if edge.get("src_port"):
+            kw["source_port"] = ports[(edge["src"], edge["src_port"])]
+        if edge.get("dst_port"):
+            kw["target_port"] = ports[(edge["dst"], edge["dst_port"])]
+        d.add_edge(by_id[edge["src"]], by_id[edge["dst"]], **kw)
+    d.layout(routing="orthogonal", layer_gap=layer_gap, node_gap=node_gap)
+    return d, by_id, ports
+
+
+# ---------------------------------------------------------------------- 3 emit
+def label_at(points: list[tuple[float, float]]) -> tuple[float, float, float]:
+    """Label position + the angle of the segment carrying it (longest segment)."""
+    best, best_len = None, -1.0
+    for (x1, y1), (x2, y2) in zip(points, points[1:]):
+        length = ((x2 - x1) ** 2 + (y2 - y1) ** 2) ** 0.5
+        if length > best_len:
+            best, best_len = ((x1 + x2) / 2.0, (y1 + y2) / 2.0), length
+    return best[0], best[1], best_len
+
+
+def emit(model: dict, d, by_id, ports, scale: float, out_path: str) -> None:
+    geometry = {"nodes": {}, "ports": {}}
+    lines = [r"\documentclass[tikz,border=10pt]{standalone}",
+             r"\usepackage{sysml2tikz}",
+             r"\begin{document}",
+             r"\begin{tikzpicture}"]
+    for node in model.get("nodes", []):
+        n = by_id[node["id"]]
+        cx = (n.x + n.w / 2.0) * scale
+        cy = -(n.y + n.h / 2.0) * scale
+        lines.append(node_call(node, "[at={(%.1fpt,%.1fpt)}]" % (cx, cy)))
+        geometry["nodes"][node["id"]] = {
+            "cx": cx, "cy": cy,
+            "w": by_id[node["id"]].w * scale, "h": by_id[node["id"]].h * scale}
+    for i, edge in enumerate(model.get("edges", [])):
+        db_edge = d.edges[i]
+        pts = [((x) * scale, -(y) * scale) for x, y in db_edge.waypoints]
+        if not pts:
+            continue
+        style = edge.get("style", "reference")
+        coords = " -- ".join("(%.1fpt,%.1fpt)" % p for p in pts)
+        label = edge.get("label")
+        if label:
+            lx, ly, _ = label_at(db_edge.waypoints)
+            lines.append(r"  \draw[sysml %s] %s;"
+                         % (style, coords.replace(
+                             " -- ", " -- ", 1)))
+            lines.append(r"  \node[font=\scriptsize, right] at (%.1fpt,%.1fpt) {%s};"
+                         % (lx * scale, -ly * scale, esc(label)))
+        else:
+            lines.append(r"  \draw[sysml %s] %s;" % (style, coords))
+    # diagramboxes parks a port just OUTSIDE the node wall (x = px + pw); the
+    # corpus draws the square centred ON the wall. Slide the glyph back by half
+    # the router's own port box, so glyph centre == wall and the routed flow
+    # still terminates on the glyph's outer face.
+    for port in model.get("ports", []):
+        db_port = ports[(port["node"], port["side"])]
+        px = (db_port.x + db_port.w / 2.0) * scale
+        py = -(db_port.y + db_port.h / 2.0) * scale
+        side = port["side"]
+        if side == "east":
+            px -= (db_port.w / 2.0) * scale
+        elif side == "west":
+            px += (db_port.w / 2.0) * scale
+        elif side == "north":
+            py -= (db_port.h / 2.0) * scale
+        elif side == "south":
+            py += (db_port.h / 2.0) * scale
+        lines.append("  \\sysmlportat{%s-p-%s}{(%.1fpt,%.1fpt)}{%s}{%s}"
+                     % (port["node"], port["side"], px, py, esc(port["name"]),
+                        port.get("label_side", "above right")))
+        geometry["ports"]["%s.%s" % (port["node"], port["side"])] = {
+            "x": px, "y": py, "side": port["side"]}
+    lines += [r"\end{tikzpicture}", r"\end{document}", ""]
+    with open(out_path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+    stem = os.path.splitext(os.path.basename(out_path))[0]
+    sidecar = os.path.join(os.path.dirname(os.path.abspath(out_path)),
+                           "geometry-%s.json" % stem)
+    with open(sidecar, "w", encoding="utf-8") as fh:
+        json.dump(geometry, fh, indent=2, sort_keys=True)
+    print("wrote", out_path, "and", sidecar)
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        print(__doc__)
+        return 2
+    want_sty = "--copy-sty" in sys.argv
+    argv = [a for a in argv if a != "--copy-sty"]
+    model_path, out_path = argv[1], argv[2]
+    scale = 4.0
+    layer_gap, node_gap = 14, 8
+    for i, arg in enumerate(argv[3:]):
+        if arg == "--scale":
+            scale = float(argv[3 + i + 1])
+    with open(model_path, encoding="utf-8") as fh:
+        model = json.load(fh)
+    workdir = os.path.dirname(os.path.abspath(out_path))
+    tectonic = os.path.expanduser("~/.local/bin/tectonic")
+    sizes = measure(model, workdir, tectonic)
+    print("measured:", {k: (round(v[0], 1), round(v[1], 1)) for k, v in sizes.items()})
+    d, by_id, ports = layout(model, sizes, scale, layer_gap, node_gap)
+    emit(model, d, by_id, ports, scale, out_path)
+    if want_sty:
+        from .emit import copy_sty
+        print("copied", copy_sty(os.path.dirname(os.path.abspath(out_path))))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

sysml2tikz/project.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jon R. Fox and Hermes Agent
+"""from_sysml.py — stage 1+2 of the sysml2tikz pipeline.
+
+sysmlpy model -> notation IR (the JSON the emitter consumes).
+
+Scope of this first cut, stated plainly:
+  * top-level definitions and usages (package children, one level deep) become
+    BOXES; their members become compartment ROWS, not separate boxes.
+  * a row is the member's own SysML text (`dump()`), which already carries the
+    notation the corpus prints: `:>` subsetting, `:>>Owner::x` redefinition,
+    `= value`, `[mult]`.
+  * keyword = the element's SysML kind + " def" for definitions
+    (`part def` / `part`, `attribute def` / `attribute`, ...).
+  * compartment label follows the corpus: bare noun on definitions
+    (`attributes`, `ports`), verb + noun on usages (`perform actions`,
+    `exhibit states`).
+  * one composition edge is emitted for a top-level usage whose type resolves
+    to another top-level definition.
+
+Not handled yet (deliberate): nested part trees as nodes, ports as routing
+anchors taken from the model, requirement satisfy edges from the model,
+view/viewpoint frames.
+
+Usage:
+    PYTHONPATH=~/proj/sysmlpy/src python3 from_sysml.py model.sysml out.json
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+
+
+KIND = {
+    "Part": "part", "Attribute": "attribute", "Port": "port", "Item": "item",
+    "Action": "action", "State": "state", "Requirement": "requirement",
+    "Calculation": "calc", "Constraint": "constraint", "Allocation": "allocation",
+    "Interface": "interface", "Enumeration": "enum", "Connection": "connection",
+}
+
+# class -> compartment label for a DEFINITION, and for a USAGE
+COMPARTMENT = {
+    "Attribute": ("attributes", "attributes"),
+    "Part": ("parts", "parts"),
+    "Port": ("ports", "ports"),
+    "Item": ("items", "items"),
+    "Action": ("actions", "perform actions"),
+    "State": ("states", "exhibit states"),
+    "Requirement": ("requirements", "require requirements"),
+    "Calculation": ("calculations", "perform calculations"),
+    "Constraint": ("constraints", "assert constraints"),
+    "Connection": ("connections", "connections"),
+}
+
+HEADER_RE = re.compile(
+    r"^\s*(?:\w+\s+(?:def\s+)?)?"   # keyword, optionally 'def'
+    r"(?P<name>[A-Za-z_][\w]*(?:::[A-Za-z_][\w]*)?)"   # name or qualified name
+    r"\s*(?::\s*(?P<type>[A-Za-z_][\w:]*(?:\[[^\]]*\])?))?"  # optional : Type
+)
+
+
+def first_line(text: str) -> str:
+    return text.strip().splitlines()[0] if text.strip() else ""
+
+
+ROW_KEYWORD_RE = re.compile(
+    r"^(?:abstract\s+)?(?:part|attribute|port|item|action|state|requirement|"
+    r"calc|constraint|allocation|interface|connection|enum|ref)\s+(?:def\s+)?")
+
+
+def dump_row(elem) -> str:
+    """A member's SysML text as one notation row.
+
+    The corpus prints compartment rows WITHOUT the member's own keyword
+    ("power : PowerValue", not "attribute power : PowerValue"), so the leading
+    keyword is stripped — the compartment label already carries it.
+    """
+    text = elem.dump().strip()
+    text = " ".join(line.strip() for line in text.splitlines())
+    text = text.rstrip(";").split("{")[0].strip()
+    return ROW_KEYWORD_RE.sub("", text)
+
+
+def classify(elem):
+    cls = type(elem).__name__
+    return KIND.get(cls), COMPARTMENT.get(cls)
+
+
+skipped: list[str] = []
+
+
+def project_element(elem) -> dict | None:
+    kind, compartments = classify(elem)
+    if kind is None:
+        return None
+    is_def = bool(getattr(elem, "is_definition", False))
+    header = first_line(elem.dump())
+    m = HEADER_RE.match(header)
+    if not m or not m.group("name"):
+        return None
+    node = {
+        "id": re.sub(r"\W+", "_", m.group("name")),
+        "kind": kind + (" def" if is_def else ""),
+        "name": m.group("name"),
+    }
+    type_field = m.group("type")
+    if type_field and not is_def:
+        node["type"] = type_field
+    # members -> rows, grouped into corpus-ordered compartments
+    order = ["attributes", "parts", "ports", "actions", "states",
+             "requirements", "items", "connections", "calculations", "constraints"]
+    buckets: dict[str, list[str]] = {}
+    for child in getattr(elem, "children", []) or []:
+        ckind, ccomp = classify(child)
+        if ckind is None or ccomp is None:
+            continue
+        label = ccomp[0] if is_def else ccomp[1]
+        row = dump_row(child)
+        if row.strip() in ("action", "perform", "perform action"):
+            # sysmlpy keeps no name for `perform x;` (dump() -> "perform action ;")
+            skipped.append("%s: %s" % (type(child).__name__, elem.dump().split()[0]))
+            continue
+        if is_def and type(child).__name__ == "Action" and row:
+            row = "*perform* " + row
+        if not row:
+            continue
+        buckets.setdefault(label, []).append(row)
+    node["compartments"] = [
+        {"label": label, "rows": buckets[label]}
+        for label in sorted(buckets, key=lambda l: order.index(l) if l in order else 99)
+    ]
+    return node
+
+
+def project(model) -> dict:
+    nodes: list[dict] = []
+    types: dict[str, str] = {}          # definition name -> node id
+    usages: list[tuple[str, str, str | None]] = []   # (node id, type name, mult)
+
+    for pkg in getattr(model, "children", []) or []:
+        for elem in getattr(pkg, "children", []) or []:
+            node = project_element(elem)
+            if node is None:
+                continue
+            nodes.append(node)
+            if node["kind"].endswith(" def"):
+                types[node["name"]] = node["id"]
+            elif node.get("type"):
+                mult = re.search(r"\[([^\]]+)\]", node["type"])
+                base = re.sub(r"\s*\[[^\]]*\]", "", node["type"]).strip()
+                usages.append((node["id"], base, mult.group(1) if mult else None))
+
+    edges = []
+    for node_id, type_name, mult in usages:
+        target = types.get(type_name.split("::")[-1])
+        if target:
+            edge = {"src": node_id, "dst": target, "style": "composition"}
+            if mult:
+                edge["label"] = mult
+            edges.append(edge)
+
+    # keep definitions above their usages
+    out_nodes = sorted(nodes, key=lambda n: (not n["kind"].endswith(" def"), n["id"]))
+    ir = {"node_distance": "14mm", "nodes": out_nodes, "ports": [], "edges": edges}
+    if skipped:
+        ir["projection_notes"] = {
+            "skipped_members": sorted(set(skipped)),
+            "why": "sysmlpy does not retain a name for these members (e.g. a bare "
+                   "`perform x;` parses to 'perform action ;'), so there is no row to print",
+        }
+    return ir
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        print(__doc__)
+        return 2
+    try:
+        import sysmlpy
+    except ImportError:                    # dev checkout without an install
+        sys.path.insert(0, os.path.expanduser("~/proj/sysmlpy/src"))
+        try:
+            import sysmlpy
+        except ImportError as exc:
+            raise SystemExit(
+                "project needs sysmlpy (pip install 'sysml2tikz[parse]'): %s" % exc)
+
+    with open(argv[1], encoding="utf-8") as fh:
+        model = sysmlpy.loads(fh.read())
+    ir = project(model)
+    with open(argv[2], "w", encoding="utf-8") as fh:
+        json.dump(ir, fh, indent=2)
+    print("projected %d node(s), %d edge(s) -> %s"
+          % (len(ir["nodes"]), len(ir["edges"]), argv[2]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

sysml2tikz/sysml2tikz.sty

@@ -0,0 +1,115 @@
+% SPDX-License-Identifier: MPL-2.0 OR LPPL-1.3c
+% Copyright (c) 2026 Jon R. Fox and Hermes Agent
+%
+% This file may be used under either of two licences, at your option:
+%   * the LaTeX Project Public License, version 1.3c or later (LICENSES/LPPL-1.3c.txt)
+%     — the branch under which the package can live on CTAN and in TeX Live;
+%   * the Mozilla Public License, version 2.0 (LICENSES/MPL-2.0.txt).
+%
+% sysml2tikz.sty — a SysML v2 notation layer on plain TikZ.
+%
+% Grounded in the OMG SysML v2.1 reference-implementation figures
+% (SysML-v2-Release/doc/images/sysml/): fig-57 "Part Definition for Vehicle"
+% (square-cornered definition, keyword + name header, italic centred
+% compartment labels) and fig-61 "Part Usage for vehicle_b" (ROUNDED corners,
+% "name: Type" header, ':>>' redefinition rows, 'default' / '=' value rows,
+% verb-prefixed compartment labels such as "perform actions").
+%
+% Distinctions this file encodes:
+%   definition : square corners, header = keyword + name, compartments are
+%                bare nouns (attributes, ports, actions, states)
+%   usage      : rounded corners, header = keyword + "name: Type", compartment
+%                labels keep the verb (perform actions, exhibit states) and
+%                rows may carry ':>>Owner::feature', 'default', '=' bindings
+%
+% Author: Jon R. Fox + Hermes Agent. Licence: MPL-2.0.
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{sysml2tikz}[2026/11/11 v0.1 SysML v2 notation for TikZ]
+
+\RequirePackage{tikz}
+\usetikzlibrary{arrows.meta,positioning,calc,fit,shapes.geometric}
+
+% ---------------------------------------------------------------- dimensions
+\newlength{\sysmlrowsep}
+\setlength{\sysmlrowsep}{2pt}
+\newlength{\sysmlradius}
+\setlength{\sysmlradius}{4.5pt}
+
+% ------------------------------------------------------------------- styles
+\tikzset{
+  % a definition: square corners (corpus fig-57)
+  sysml def box/.style={
+    draw, thick, fill=white, rectangle, rounded corners=0pt,
+    inner sep=2.6pt, align=left, font=\footnotesize\sffamily
+  },
+  % a usage: rounded corners (corpus fig-61)
+  sysml usage box/.style={
+    draw, thick, fill=white, rectangle, rounded corners=\sysmlradius,
+    inner sep=2.6pt, align=left, font=\footnotesize\sffamily
+  },
+  sysml frame/.style={
+    draw, thick, fill=white, rectangle, inner sep=10pt, font=\footnotesize\sffamily
+  },
+  sysml port/.style={
+    draw, fill=white, thick, rectangle, minimum size=2.4mm, inner sep=0pt
+  },
+  sysml edge/.style={thick, draw=black},
+  % composition (whole end carries the filled diamond)
+  sysml composition/.style={sysml edge, -{Diamond[length=3.2mm,width=2.4mm,fill=black]}},
+  % directed reference / item flow
+  sysml reference/.style={sysml edge, -{Stealth[length=2.6mm]}},
+  sysml itemflow/.style={sysml edge, dashed, -{Stealth[length=2.4mm]}},
+  % satisfy / dependency
+  sysml satisfy/.style={sysml edge, densely dotted, -{Stealth[length=2.4mm]}},
+  sysml gen/.style={sysml edge, -{Triangle[length=3mm,width=3mm,open,fill=white]}},
+}
+
+% ------------------------------------------------------------- header pieces
+% «keyword» — italic inside guillemets, as printed in the corpus
+\newcommand{\sysmlkw}[1]{\textit{«#1»}}
+% definition header: keyword line, then centred name, then a rule
+\newcommand{\sysmlhead}[2]{%
+  \multicolumn{1}{c}{\sysmlkw{#1}}\\[-\sysmlrowsep]
+  \multicolumn{1}{c}{\large\sffamily #2}\\[1.5pt]}
+% usage header: keyword line, then centred "name : Type", then a rule
+\newcommand{\sysmlheadusage}[2]{%
+  \multicolumn{1}{c}{\sysmlkw{#1}}\\[-\sysmlrowsep]
+  \multicolumn{1}{c}{\large\sffamily #2}\\[1.5pt]}
+% compartment label: rule + centred italic label
+\newcommand{\sysmlcomp}[1]{\hline\multicolumn{1}{c}{\itshape #1}\\[-\sysmlrowsep]}
+% member keyword (perform, exhibit, default, allocate ...) — bold in corpus
+\newcommand{\kw}[1]{\textbf{#1}}
+% a redefinition row, printed italic in the corpus: ':>>Vehicle::mass'
+\newcommand{\redefines}[1]{\textit{#1}}
+
+% --------------------------------------------------------------- block nodes
+% \sysmldefnode[<tikz placement opts>]{<node id>}{<kind>}{<name>}{<body>}
+\newcommand{\sysmldefnode}[5][]{%
+  \node[sysml def box, #1] (#2) {\begin{tabular}{@{}l@{}}%
+    \sysmlhead{#3}{#4}#5%
+  \end{tabular}};}
+
+% \sysmlusagenode[<tikz placement opts>]{<id>}{<kind>}{<name>}{<type>}{<body>}
+\newcommand{\sysmlusagenode}[6][]{%
+  \node[sysml usage box, #1] (#2) {\begin{tabular}{@{}l@{}}%
+    \sysmlheadusage{#3}{#4\,:\,#5}#6%
+  \end{tabular}};}
+
+% ---------------------------------------------------------------- ports
+% \sysmlport{<node>}{<anchor or angle>}{<label>}{<label side>}
+\newcommand{\sysmlport}[4]{%
+  \node[sysml port, label={[font=\scriptsize\sffamily, inner sep=1pt]#4:#3}]
+    (#1-p-#2) at (#1.#2) {};}
+
+% \sysmlportat{<node id>}{(x,y)}{<label>}{<label anchor>} — used by the layout
+% adapter, which knows the routed dock coordinates instead of a bare side.
+\newcommand{\sysmlportat}[4]{%
+  \node[sysml port, label={[font=\scriptsize\sffamily, inner sep=1pt]#4:#3}]
+    (#1) at #2 {};}
+
+% ---------------------------------------------------------------- framing
+% \sysmlframe{<id>}{<title>}{<fit targets>}
+\newcommand{\sysmlframenode}[3]{%
+  \node[sysml frame, fit=#3, label={[font=\scriptsize\sffamily,anchor=north]north:{#2}}] (#1) {};}
+
+\endinput

sysml2tikz-0.0.1.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: sysml2tikz
+Version: 0.0.1
+Summary: SysML v2 notation for LaTeX/TikZ: a .sty notation layer plus a model-to-figure pipeline
+Project-URL: Homepage, https://github.com/mycr0ft/sysml2tikz
+Project-URL: Issues, https://github.com/mycr0ft/sysml2tikz/issues
+Author: Jon R. Fox
+License: MPL-2.0 OR LPPL-1.3c
+Keywords: diagram,latex,mbse,sysml,sysml-v2,tikz,uml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.10
+Provides-Extra: layout
+Requires-Dist: diagramboxes; extra == 'layout'
+Provides-Extra: parse
+Requires-Dist: sysmlpy; extra == 'parse'
+Description-Content-Type: text/markdown
+
+# tikz-sysml — SysML v2 notation in TikZ
+
+Two things live here:
+
+1. `sysml2tikz.sty` — a notation layer over plain TikZ. It encodes the
+   definition/usage distinction the way the OMG SysML v2 reference figures draw
+   it, and gives you compartments, ports, item flows and the relationship
+   arrowheads without hand-drawing any of it.
+2. `gen/` — the pipeline: `from_sysml.py` (sysmlpy → IR), `emit_tex.py` (IR →
+   .tex), `layout_adapter.py` (TeX-measured sizes → diagramboxes' orthogonal
+   router → absolute coordinates), `tools/verify.py` (golden diff, compile,
+   geometry gates). See `PIPELINE.md`.
+
+## Install
+
+Two independent doors:
+
+```bash
+# LaTeX only — drop the .sty in your document's directory (or install it from CTAN
+# once the package is accepted), then:
+\usepackage{sysml2tikz}
+
+# Python — the generator; the wheel carries the same .sty
+pip install sysml2tikz
+sysml2tikz emit model.json out.tex --copy-sty   # --copy-sty puts the .sty beside the output
+tectonic out.tex
+```
+
+`--copy-sty` exists because tectonic resolves packages from its own bundle rather
+than from `TEXINPUTS`, and a plain TeX Live only finds `sysml2tikz.sty` after CTAN
+ships it. For a repo checkout the `gen/*.py` scripts are thin shims over
+`src/sysml2tikz/*`, so the commands in `PIPELINE.md` keep working with no install.
+
+Optional extras: `pip install "sysml2tikz[parse]"` (sysmlpy, for SysML text input)
+and `pip install "sysml2tikz[layout]"` (diagramboxes, for routed layout).
+
+## Build
+
+```bash
+tectonic demo.tex                 # hand-authored API demo
+cd gen && python3 emit_tex.py model.json out.tex && tectonic out.tex
+pdftoppm -r 190 -png -singlefile out.pdf out      # review raster
+```
+
+No system TeX required: `tectonic` fetches only what a document uses.
+
+## Figures
+
+All four are produced by this repo; the PNGs are 200 dpi rasters of the compiled PDFs.
+
+Hand-authored macros — the definition/usage distinction in one picture
+(`demo.tex`): square «part def», rounded «part», compartments, ports, composition,
+«satisfy».
+
+![definition and usage](docs/figures/fig-definition-and-usage.png)
+
+Same figure generated from a JSON notation IR (`gen/model.json` → `gen/emit_tex.py`) —
+nothing typed by hand:
+
+![generated from IR](docs/figures/fig-generated-from-ir.png)
+
+Laid out automatically: TeX-measured box sizes → diagramboxes' orthogonal router →
+absolute coordinates and polyline edges (`gen/laid_out.tex`):
+
+![routed layout](docs/figures/fig-routed-layout.png)
+
+End to end from SysML v2 text — `examples/vehicle.sysml` parsed by sysmlpy, projected,
+routed and rendered:
+
+![from sysml model](docs/figures/fig-from-sysml-model.png)
+
+## The distinction this package exists for
+
+The corpus draws the two sides differently and the difference is semantic, not
+decoration:
+
+| | definition | usage |
+|---|---|---|
+| keyword | `«part def»` | `«part»` |
+| box | square corners | rounded corners |
+| header | name only | `name : Type` |
+| compartment labels | bare noun (`attributes`, `ports`, `actions`, `states`) | verb + noun (`perform actions`, `exhibit states`) |
+| rows | `max :> temperature` | `cargoMass default 0 [kg]`, `:>>Vehicle::cargoMass`, `dryMass=sum(partMasses)` |
+
+Grounded in `fig-57-Part-Definition-for-Vehicle.svg` and
+`fig-61-Part-Usage-for-vehicle_b.svg` under
+`~/proj/third_party/SysML-v2-Release/doc/images/sysml/` — every other kind pair
+(`attribute`, `port`, `item`, `requirement`, `action`, `state`, `calc`,
+`constraint`, `allocation`, `interface`, `view`, `viewpoint`) has its own
+`fig-NN-<Kind>-Definition-and-Usage.svg` in that directory and is the
+acceptance criterion for extending the table.
+
+## API
+
+```tex
+\sysmldefnode[at={(0,0)}]{veh}{part def}{Vehicle}{%
+  \sysmlcomp{attributes}
+  brakePedalDepressed: Boolean\\
+  \sysmlcomp{actions}
+  \kw{perform} providePower\\
+}
+\sysmlusagenode[below=of veh]{vehb}{part}{vehicle\_b}{Vehicle}{%
+  \sysmlcomp{attributes}
+  cargoMass \kw{default} 0 [kg]\\
+  \redefines{:>>Vehicle::cargoMass}\\
+}
+\sysmlport{veh}{east}{fuelIn}{above right}
+\draw[sysml composition] (vehb) -- node[right, font=\scriptsize, pos=.5]{1} (veh);
+\draw[sysml satisfy]     (vehb) -- node[right, font=\scriptsize, pos=.5]{«satisfy»} (req);
+\draw[sysml itemflow]    (veh-p-east) to[out=0,in=0,looseness=1.15] (vehb-p-east);
+```
+
+Edge styles: `sysml composition` (filled diamond), `sysml reference`,
+`sysml itemflow`, `sysml satisfy`, `sysml gen` (hollow triangle).
+
+## Licence
+
+`sysml2tikz.sty` is **MPL-2.0 OR LPPL-1.3c** (dual, your choice — LPPL is the branch
+CTAN/TeX Live can carry). The Python under `gen/` and `tools/` is **MPL-2.0**.
+SPDX identifiers are in every file; full texts and the reasoning are in `LICENSES/`.

sysml2tikz-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sysml2tikz/__init__.py,sha256=i8kICbcuWK5RxvgbmILyApa0vR3_EECFk-sCZw-Vfa4,927
+sysml2tikz/cli.py,sha256=BhHVp9Pe9nW3x2YzhHFBhV8mUi-W9QhKpKHFx0Z3hA8,1406
+sysml2tikz/emit.py,sha256=0Hz7iiVq4xBO_JfSL1jBw4DeBiUK4xz2wPny6Ae_VVI,6159
+sysml2tikz/layout.py,sha256=hGwc_pa6amDe60j-gtqZQlE0RXEJU4to2uwC97WxZc0,11642
+sysml2tikz/project.py,sha256=LsjIHAipcrttoNuTBL7uSJ8zlpFcoO8Ug516H4sZbd8,7535
+sysml2tikz/sysml2tikz.sty,sha256=x3N5OIzWJSOyvdxeYtXbUJA7AofQFQzaZ0kH5GM4VVk,5298
+sysml2tikz-0.0.1.dist-info/METADATA,sha256=RmaCb2kQEWzgFLgFhSF7hmhA5ld3TeZziVSNj5Yo264,5570
+sysml2tikz-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+sysml2tikz-0.0.1.dist-info/entry_points.txt,sha256=MJxcnvuUjzRFxFXsWJnaCtzLgPBokqdIV9c85xNd0hI,51
+sysml2tikz-0.0.1.dist-info/RECORD,,

sysml2tikz-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sysml2tikz-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sysml2tikz = sysml2tikz.cli:main