119 lines
4.9 KiB
Markdown
119 lines
4.9 KiB
Markdown
# 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 (`<<ECU>>`, `<<connector>>`) 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
|