From 36dbbebe76bef4b9e8ef32bc6f2b67e041f5f57a Mon Sep 17 00:00:00 2001 From: Ilya Ashikhmin Date: Thu, 2 Jul 2026 23:04:46 +0200 Subject: [PATCH] docs: add implementation plan for pipeline diagram editor Co-Authored-By: Claude Fable 5 --- docs/plan/plan.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 docs/plan/plan.md diff --git a/docs/plan/plan.md b/docs/plan/plan.md new file mode 100644 index 0000000..aef44ea --- /dev/null +++ b/docs/plan/plan.md @@ -0,0 +1,124 @@ +# Pipeline Network Diagram Editor — Implementation Plan + +A Qt 6 desktop editor for drawing pipeline networks (water, power, gas, …) with +grid-aligned routing, typed ports, grouped editable properties, styleable edges, +and a mock flow-calculation with animated flow. + +## Tool selection (research summary) + +Candidates evaluated (web research, July 2026): + +| Option | Verdict | +|---|---| +| **QtNodes / paceholder nodeeditor** | Mature model-view node editor, but built for *dataflow* graphs: connections are cubic curves only (no orthogonal/Manhattan routing), port placement limited to horizontal/vertical in/out layouts, no per-side port docking, no intersection decorations. Its node/port model would fight the pipeline-schematic requirements. | +| **QuickQanava (QML)** | Per-side port docks, but QML-centric; heavier stack, weaker fit for the widget-based property panel and offscreen unit testing. | +| **yFiles** | Real orthogonal routing, but commercial. | +| **Custom editor on QGraphicsView (Qt Widgets)** | Full control over orthogonal grid routing, arc jump-overs, SVG nodes with arbitrary port configs, relation-based connection rules. QGraphicsScene is battle-tested for exactly this (Elastic Nodes / Diagram Scene examples), integrates with QUndoStack, and tests run headless via the `offscreen` platform. | + +**Decision: custom QGraphicsView-based editor, C++20, Qt 6 Widgets + Qt SVG, CMake + Ninja, Qt Test.** + +Sources: +- https://github.com/paceholder/nodeeditor +- https://qtnodes.readthedocs.io/en/master/overview.html +- https://qtnodes.readthedocs.io/en/stable/features.html +- http://cneben.github.io/QuickQanava/nodes.html +- https://doc.qt.io/qt-6/qtwidgets-graphicsview-elasticnodes-example.html +- http://docs.yworks.com/yfiles/doc/developers-guide/orthogonal_edge_router.html + +## Architecture + +``` +src/ + core/ # Qt-Core-only, headless-testable + NodeType, PortSpec, Relation # node/port/relation definitions + Node, Edge, NetworkModel # document model, connection rules + Property, PropertySpec, Catalogue# typed grouped properties + EdgeStyle # line style + end decorations + Router # orthogonal routing + intersection arcs + FlowSolver # mock flow distribution + JsonIo # save/load + scene/ # QGraphicsScene layer + DiagramScene, NodeItem, PortItem, EdgeItem, GridView (bg grid, zoom/pan) + FlowAnimator # animated flow overlay + Commands # QUndoCommand set + app/ # widgets + MainWindow, NodePalette, PropertyPanel, SettingsDialog +resources/ # SVG node set, node-type & catalogue JSON +tests/ # Qt Test suites +``` + +Model layer is pure Qt Core (no scene), so connection rules, routing, solver and +serialization are unit-testable offscreen. Scene items observe the model; edits go +through QUndoCommands. + +## Checklist + +### 1. Foundation +- [ ] Install Qt 6 (base, svg), ninja; verify cmake configure +- [ ] Project scaffold: CMakeLists (app + tests), .gitignore, README +- [ ] This plan committed under docs/plan + +### 2. Core model +- [ ] Relations (water, gas, power, control, …) with per-scheme colors +- [ ] PortSpec: id, relation, direction (in/out/bidirectional), relative position on node +- [ ] NodeType: id, group, label, SVG path, port list, default size, property specs +- [ ] Node/Edge/NetworkModel: add/remove/move, connect with validation (relation match, direction, no self-port duplicates, occupancy) +- [ ] Signals for model→view sync + +### 3. Property system +- [ ] Property types: String, Int, Float, Enum, CatalogueItem, CatalogueItems, Color, ValueList +- [ ] PropertySpec with group ("General", "Presentation", "Physics"), unit, limits, read-only flag +- [ ] Catalogue store (e.g. pipe series DN/material) loaded from JSON +- [ ] Default specs: node (title, color, rotation…), edge (title, length, diameter, flow rate, flow type, style props) + +### 4. Routing +- [ ] Orthogonal (Manhattan) routing snapped to grid, port-direction-aware first segment +- [ ] Config: grid step, `arcOnIntersection` — arc jump-over where an edge crosses another +- [ ] Intersection computation between routed polylines +- [ ] Painter-path builder producing arcs over crossings + +### 5. Scene / items +- [ ] Grid background + snap-to-grid +- [ ] NodeItem: shared QSvgRenderer per type, selection highlight, drag with snapping +- [ ] PortItem: visible on node focus/hover, colored by relation, click-drag to start edge +- [ ] Interactive edge creation with live preview, drop on compatible port only (highlight legal targets) +- [ ] EdgeItem: styles — line (solid/dash/dot, width, color), head/tail decorations (none, arrow, circle, diamond, bar), title label +- [ ] Color schemes: light / dark / high-contrast; per-relation edge & port colors + +### 6. Application UI +- [ ] Node palette: grouped tree with SVG icons, drag & drop onto canvas (mime-encoded type id) +- [ ] Property panel: grouped editors per selected node/edge — line edit, spin boxes, combo (enum), catalogue pickers (single/multi), color button, string-list editor +- [ ] Settings dialog: grid size, snap, intersection arcs, color scheme +- [ ] Toolbar/menus, status bar with cursor position & zoom + +### 7. Editing UX (added features beyond the brief) +- [ ] Node dragging (multi-selection), rubber-band selection +- [ ] Zoom with Ctrl+wheel (cursor-anchored), fit-to-view, pan with middle mouse / space +- [ ] Undo/redo for all edits (add, delete, move, connect, property change) +- [ ] Copy/paste/duplicate with offset; Delete removes nodes + attached edges +- [ ] Context menus on canvas/node/edge +- [ ] Save/load document as JSON; window state persistence +- [ ] Keyboard shortcuts (standard set) + +### 8. Flow simulation mock +- [ ] FlowSolver: sources/sinks from node types, conservation-based distribution splitting flow by pipe conductance (diameter-driven), per-edge signed flow rate +- [ ] Animation: moving dashes along edge path; direction = flow sign, speed & density ∝ volume +- [ ] Run/stop simulation from toolbar; solver results shown in edge properties + +### 9. Assets +- [ ] SVG set: source, tank, pump, valve, consumer, junction, generator, transformer, switch +- [ ] Node-type JSON with port configs; sample catalogues (pipe series, materials) +- [ ] Sample document for demo + +### 10. Tests (Qt Test, offscreen) +- [ ] Model: create/connect validation matrix, port occupancy, delete cascades +- [ ] Properties: set/get, type safety, serialization round-trip +- [ ] Router: orthogonality, grid alignment, intersection arcs on/off +- [ ] Solver: conservation at junctions, distribution by diameter +- [ ] Undo/redo scenarios +- [ ] GUI: drop node from palette, drag node snapping, interactive connect, edge selection → property panel + +### 11. Delivery +- [ ] All tests green in CI-able script (`ctest`) +- [ ] README with build/run instructions and screenshots +- [ ] Conventional atomic commits per module