docs: add implementation plan for pipeline diagram editor
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ilya Ashikhmin
commit
36dbbebe76
124
docs/plan/plan.md
Normal file
124
docs/plan/plan.md
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user