125 lines
6.8 KiB
Markdown
125 lines
6.8 KiB
Markdown
# 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
|
|
- [x] Install Qt 6 (base, svg), ninja; verify cmake configure
|
|
- [x] Project scaffold: CMakeLists (app + tests), .gitignore, README
|
|
- [x] This plan committed under docs/plan
|
|
|
|
### 2. Core model
|
|
- [x] Relations (water, gas, power, control, …) with per-scheme colors
|
|
- [x] PortSpec: id, relation, direction (in/out/bidirectional), relative position on node
|
|
- [x] NodeType: id, group, label, SVG path, port list, default size, property specs
|
|
- [x] Node/Edge/NetworkModel: add/remove/move, connect with validation (relation match, direction, no self-port duplicates, occupancy)
|
|
- [x] Signals for model→view sync
|
|
|
|
### 3. Property system
|
|
- [x] Property types: String, Int, Float, Enum, CatalogueItem, CatalogueItems, Color, ValueList
|
|
- [x] PropertySpec with group ("General", "Presentation", "Physics"), unit, limits, read-only flag
|
|
- [x] Catalogue store (e.g. pipe series DN/material) loaded from JSON
|
|
- [x] Default specs: node (title, color, rotation…), edge (title, length, diameter, flow rate, flow type, style props)
|
|
|
|
### 4. Routing
|
|
- [x] Orthogonal (Manhattan) routing snapped to grid, port-direction-aware first segment
|
|
- [x] Config: grid step, `arcOnIntersection` — arc jump-over where an edge crosses another
|
|
- [x] Intersection computation between routed polylines
|
|
- [x] Painter-path builder producing arcs over crossings
|
|
|
|
### 5. Scene / items
|
|
- [x] Grid background + snap-to-grid
|
|
- [x] NodeItem: shared QSvgRenderer per type, selection highlight, drag with snapping
|
|
- [x] PortItem: visible on node focus/hover, colored by relation, click-drag to start edge
|
|
- [x] Interactive edge creation with live preview, drop on compatible port only (highlight legal targets)
|
|
- [x] EdgeItem: styles — line (solid/dash/dot, width, color), head/tail decorations (none, arrow, circle, diamond, bar), title label
|
|
- [x] Color schemes: light / dark / high-contrast; per-relation edge & port colors
|
|
|
|
### 6. Application UI
|
|
- [x] Node palette: grouped tree with SVG icons, drag & drop onto canvas (mime-encoded type id)
|
|
- [x] Property panel: grouped editors per selected node/edge — line edit, spin boxes, combo (enum), catalogue pickers (single/multi), color button, string-list editor
|
|
- [x] Settings dialog: grid size, snap, intersection arcs, color scheme
|
|
- [x] Toolbar/menus, status bar with cursor position & zoom
|
|
|
|
### 7. Editing UX (added features beyond the brief)
|
|
- [x] Node dragging (multi-selection), rubber-band selection
|
|
- [x] Zoom with Ctrl+wheel (cursor-anchored), fit-to-view, pan with middle mouse
|
|
- [x] Undo/redo for all edits (add, delete, move, connect, property change)
|
|
- [x] Copy/paste/duplicate with offset; Delete removes nodes + attached edges
|
|
- [x] Context menus on canvas/node/edge
|
|
- [x] Save/load document as JSON; window state persistence
|
|
- [x] Keyboard shortcuts (standard set)
|
|
|
|
### 8. Flow simulation mock
|
|
- [x] FlowSolver: sources/sinks from node types, conservation-based distribution splitting flow by pipe conductance (diameter-driven), per-edge signed flow rate
|
|
- [x] Animation: moving dashes along edge path; direction = flow sign, speed & density ∝ volume
|
|
- [x] Run/stop simulation from toolbar; solver results shown in edge properties
|
|
|
|
### 9. Assets
|
|
- [x] SVG set: source, tank, pump, valve, consumer, junction, generator, transformer, switch
|
|
- [x] Node-type JSON with port configs; sample catalogues (pipe series, materials)
|
|
- [x] Sample document for demo
|
|
|
|
### 10. Tests (Qt Test, offscreen)
|
|
- [x] Model: create/connect validation matrix, port occupancy, delete cascades
|
|
- [x] Properties: set/get, type safety, serialization round-trip
|
|
- [x] Router: orthogonality, grid alignment, intersection arcs on/off
|
|
- [x] Solver: conservation at junctions, distribution by diameter
|
|
- [x] Undo/redo scenarios
|
|
- [x] GUI: drop node from palette, drag node snapping, interactive connect, edge selection → property panel
|
|
|
|
### 11. Delivery
|
|
- [x] All tests green in CI-able script (`ctest`)
|
|
- [x] README with build/run instructions and screenshots
|
|
- [x] Conventional atomic commits per module
|