From 8d3b5cccf948b4489ccccc0c07fb2b181776692f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Murta?= Date: Sat, 14 Mar 2026 10:22:58 +0000 Subject: [PATCH] feat: 3D renderer of plantuml diagram Adds initial conversation with Claude along with the .html diagram renderer. --- conversation-summary.md | 118 ++++++++ plantuml-3d-renderer.html | 594 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 712 insertions(+) create mode 100644 conversation-summary.md create mode 100644 plantuml-3d-renderer.html diff --git a/conversation-summary.md b/conversation-summary.md new file mode 100644 index 0000000..2cf88bd --- /dev/null +++ b/conversation-summary.md @@ -0,0 +1,118 @@ +# Conversation summary — PlantUML isometric 3D renderer + +## Context + +This conversation explored generating interactive 3D/isometric renderings of embedded system architecture diagrams, with a specific focus on an automotive ECU use case. The team uses PlantUML and self-hosts the PlantUML server. + +--- + +## System being modelled + +Three top-level ECUs: **A**, **B**, and **C**. + +**ECU B** contains: +- A **Connector** and an **Adapter** for each of ECU A and ECU C (two parallel lanes) +- Both adapters feed into a single **Logic** component +- Inside Logic, a sequential sub-flow: **a → b → c** + +PlantUML source: + +```plantuml +@startuml +component "ECU A" as A +component "ECU C" as C + +component "ECU B" as B { + component "Connector A" as ConA + component "Adapter A" as AdpA + component "Connector C" as ConC + component "Adapter C" as AdpC + component "Logic" as L { + component "a" as La + component "b" as Lb + component "c" as Lc + La --> Lb + Lb --> Lc + } + ConA --> AdpA + ConC --> AdpC + AdpA --> L + AdpC --> L +} + +A --> ConA +C --> ConC +@enduml +``` + +--- + +## What was built + +An interactive isometric 3D renderer that: + +1. **Parses PlantUML component diagram syntax** client-side (no server required for the parser itself) +2. **Renders an isometric SVG** — each component is a 3-faced isometric block with color coding by component type +3. **Supports drill-down zoom** — clicking a component with nested children transitions to an internal view, with a breadcrumb trail for navigation +4. **Color scheme by component type:** + - Gray → ECU / top-level components + - Teal → Connectors + - Amber → Adapters + - Purple → Logic components + - Coral → Sequence steps (short labels like a, b, c) + +A standalone `plantuml-3d-renderer.html` file was produced — open it directly in any browser or VSCode Live Preview. + +--- + +## Architecture decisions + +### Parser approach +The client-side parser handles: +- `component "Label" as alias { ... }` — with or without braces +- `component alias { ... }` — unlabelled alias form +- `alias --> alias : optional label` — directed connections +- Arbitrary nesting depth + +**For production:** POST the `.puml` source to your self-hosted PlantUML server's `/json` endpoint and drive the renderer from the returned AST instead. This handles edge cases (stereotypes, notes, skinparam, grouped interfaces) that the lightweight client-side parser skips. + +### Rendering +- Pure SVG, no dependencies +- Isometric projection: each block has top/left/right faces using CSS custom properties for colors +- Dark mode automatic via `prefers-color-scheme` +- Zoom levels are discrete view transitions (not CSS transforms) — each level is a full redraw of the SVG for the selected node's children + +--- + +## DSL alternatives considered + +| Tool | License | Notes | +|---|---|---| +| **PlantUML** | GPL / LGPL (jar) | Team already uses it. Self-hosting fine for commercial internal use. Get a free Professional Edition key to suppress ads. | +| **Mermaid** | MIT | Simplest license, no restrictions. Less expressive for deep nesting. | +| **D2** | MPL 2.0 | Clean syntax, good nesting. TALA layout engine requires paid license for commercial use. | +| **Structurizr DSL** | Apache 2.0 | C4-model based. Server prebuilt binaries need a license; build from source is free. | +| **ArchiMate** | Non-commercial free / annual commercial license | The Archi tool (MIT), but the language spec requires a commercial license from The Open Group for commercial use. | +| **SysML** | Open source (OMG derived) | Semantically correct for ECU/embedded systems. Heavy tooling (Cameo, Papyrus). Eclipse SysON is open source. | +| **AADL** | SAE standard (spec costs money; OSATE tooling is open source) | Best fit for automotive embedded. Steep learning curve. | + +**Recommendation:** Stay on PlantUML. The team's existing knowledge compounds in value faster than any migration would justify — unless moving toward full MBSE (model-based systems engineering) with SysML or AADL. + +--- + +## Next steps / open threads + +- [ ] Wire the renderer to the self-hosted PlantUML `/json` endpoint instead of the client-side parser +- [ ] Add animated connection flows (data flowing between components) +- [ ] Support PlantUML stereotypes (`<>`, `<>`) as an explicit color override mechanism, removing the label-inference heuristic +- [ ] Consider a VSCode extension wrapper: watch `.puml` files, re-render on save, show isometric view in a side panel +- [ ] Explore Three.js for true 3D with orbit/zoom controls, for stakeholder presentation use cases + +--- + +## How to continue in VSCode + +1. Open `plantuml-3d-renderer.html` with Live Preview or any browser +2. Start a new Claude chat (Claude Code CLI or Copilot+Claude) and paste this summary +3. The renderer source is self-contained — all logic is in the single HTML file +4. Key function to extend: `parsePuml(src)` for parser changes, `drawLevel(node)` for rendering changes, `guessColor(node)` for color mapping changes diff --git a/plantuml-3d-renderer.html b/plantuml-3d-renderer.html new file mode 100644 index 0000000..878bd3d --- /dev/null +++ b/plantuml-3d-renderer.html @@ -0,0 +1,594 @@ + + + + + +PlantUML → Isometric 3D Renderer + + + + +

PlantUML → Isometric 3D Renderer

+

Paste a PlantUML component diagram and click Render to generate an interactive isometric view.

+ +
+
+
PlantUML source
+ + +
+ + +
+
+ +
+
+
ECU / top-level +
+
+
Connector +
+
+
Adapter +
+
+
Logic +
+
+
Sequence step +
+
+ +
+ Color is inferred from the component label.
+ Components with children are clickable — drill in to explore nested structure. +

+ To connect your self-hosted PlantUML server, POST the source to + /json and feed the response AST into the renderer instead of the client-side parser. +
+
+ +
+
+ +
+
+ +
+
+
+ + + +