swmmmodellayer.h

Go to the documentation of this file.

 
#ifndef SWMMMODELLAYER_H
#define SWMMMODELLAYER_H
 
#include "layers/openswmmvislayer.h"
#include "layers/swmm_category.h"
#include "core/preferencesmanager.h"     // NewProjectSpec defaults structs
#include "render/labelconfig.h"
#include "render/iattributeprovider.h"   // Slice DM.3
#include "render/markershape.h"
#include "render/legendsymbolitem.h"     // X4 — legend-as-editor facade
 
#include <cstdint>
#include <memory>
#include <optional>
#include <vector>
 
// Forward declaration — nanoflann types are confined to swmmmodellayer.cpp
// so the header stays free of the nanoflann.hpp template machinery.
struct SWMMKdTrees;
 
#include <QColor>
#include <QDateTime>
 
#include <openswmm/engine/openswmm_callbacks.h>  // SWMM_Engine typedef
#include <openswmm/engine/openswmm_infrastructure.h>  // SWMM_InletUsage (by value)
#include <QFont>
#include <QMap>
#include <QPen>
#include <QBrush>
#include <QPointer>
#include <QPolygonF>
#include <QSet>
#include <QVariantMap>
 
class OpenSWMMVisWorkspace;
class SpatialReferenceSystem;
class MapCanvas;   // setEditCanvas() — undo-stack host for mediated edits
 
namespace OpenSWMM::Render {
class IFeatureRenderer;
class GraduatedRenderer;   // classifyGraduatedIfNeeded — data-derived breaks.
class RuleList;   // Slice B.4 — see ruleList() override below.
enum class ClassEditKind;   // X4 — legend-as-editor facade (full def in ifeaturerenderer.h)
}
 
// Slice BS Phase 6.9.2 — hydrograph MVC layer. Forward-declared so the
// header doesn't drag in <QAbstractItemModel>; accessors return pointers
// that consumers can wire to QTableView / QListView. See
// include/layers/hydrographmodels.h.
class HydrographGroupListModel;
class HydrographRtkTableModel;
class HydrographIaTableModel;
class HydrographDecayTableModel;
 
namespace openswmmvis::ui {
class UserFlagsModel;   // [USER_FLAGS] / [USER_FLAG_VALUES] store — see ensureUserFlagsModel().
}
 
// Persistent per-kind symbol adapter set — see elementSymbolAdapter().
class SwmmElementSymbolAdapter;
 
struct SWMMElementSymbol
{
    QColor  fillColor    = Qt::blue;
    QColor  outlineColor = Qt::darkBlue;
    double  outlineWidth = 1.0;
    double  size         = 8.0;    
    OpenSWMM::Render::MarkerShape markerShape
                         = OpenSWMM::Render::MarkerShape::Circle;
    bool    showLabel    = false;
    QFont   labelFont;
    QColor  labelColor   = Qt::black;
 
    // Slice BI Phase 8.13.8-mini (2026-05-24) — flow-direction arrows
    // for link kinds (Conduits / Pumps / Orifices / Weirs / Outlets).
    // Ignored for point / polygon kinds. The arrow points from the
    // link's upstream node to its downstream node — i.e. follows the
    // polyline tangent at the midpoint of the visible polyline.
    bool    showArrows           = false;
    double  arrowSize            = 16.0;           
    double  arrowWidth           = 8.0;
    QColor  arrowColor           = QColor(34, 34, 34);  
    // Slice FX.1 — was `true` by default, but that gates arrows on a
    // bound `.out` (every link has flow=0 pre-simulation). Users who
    // toggle "Show flow arrows" expect arrows to appear immediately,
    // independent of whether a sim has run. The flow-positive filter
    // remains opt-in via the Arrows tab → "Only when flow > 0".
    bool    arrowOnlyWhenFlowPos = false;
};
 
class SWMMModelLayer : public OpenSWMMVisLayer,
                       public OpenSWMM::Render::IAttributeProvider  // Slice DM.3
{
    Q_OBJECT
    Q_INTERFACES(OpenSWMM::Render::IAttributeProvider)  // Slice DM.3
 
    // The batched scene-item renderer reads the SoA + GDAL transform
    // directly so paint() is a single tight pass over the cached data.
    friend class SWMMLayerItem;
    // Phase B.RHI — the QSG renderer reads the same flat buffers to
    // populate its QSGGeometryNode vertex data on geometry change.
    friend class SWMMLayerQSGRenderer;
 
public:
    using Category = OpenSWMMVis::SwmmCategory;
    static constexpr Category CatJunctions     = OpenSWMMVis::CatJunctions;
    static constexpr Category CatOutfalls      = OpenSWMMVis::CatOutfalls;
    static constexpr Category CatStorage       = OpenSWMMVis::CatStorage;
    static constexpr Category CatDividers      = OpenSWMMVis::CatDividers;
    static constexpr Category CatConduits      = OpenSWMMVis::CatConduits;
    static constexpr Category CatPumps         = OpenSWMMVis::CatPumps;
    static constexpr Category CatOrifices      = OpenSWMMVis::CatOrifices;
    static constexpr Category CatWeirs         = OpenSWMMVis::CatWeirs;
    static constexpr Category CatOutlets       = OpenSWMMVis::CatOutlets;
    static constexpr Category CatSubcatchments = OpenSWMMVis::CatSubcatchments;
    static constexpr Category CatRainGages     = OpenSWMMVis::CatRainGages;
    static constexpr Category NumCategories    = OpenSWMMVis::NumCategories;
 
    enum DataCategory {
        DataCurves        = 0,
        DataTimeSeries,
        DataPatterns,
        DataLIDControls,
        DataPollutants,
        DataLandUses,
        DataAquifers,
        DataSnowpacks,
        DataControls,
        DataTransects,
        DataHydrographs,
        DataStreets,
        DataInlets,
        NumDataCategories
    };
 
    Q_PROPERTY(QString modelFilePath  READ modelFilePath  NOTIFY modelFilePathChanged)
    Q_PROPERTY(bool    showNodes      READ showNodes      WRITE setShowNodes
               NOTIFY showNodesChanged)
    Q_PROPERTY(bool    showLinks      READ showLinks      WRITE setShowLinks
               NOTIFY showLinksChanged)
    Q_PROPERTY(bool    showSubcatchments READ showSubcatchments
               WRITE setShowSubcatchments NOTIFY showSubcatchmentsChanged)
    Q_PROPERTY(bool    showRainGages  READ showRainGages  WRITE setShowRainGages
               NOTIFY showRainGagesChanged)
    Q_PROPERTY(bool    showLabels     READ showLabels     WRITE setShowLabels
               NOTIFY showLabelsChanged)
 
public:
 
    explicit SWMMModelLayer(const QString &modelFilePath,
                            OpenSWMMVisWorkspace *parent = nullptr);
 
    ~SWMMModelLayer() override;
 
    // ----- Model file -----------------------------------------------------
 
    [[nodiscard]] QString modelFilePath() const;
    void setModelFilePath(const QString &path);
 
    // ----- Self-description for the Layer Properties dialog ----------------
    [[nodiscard]] QString sourceDescription() const override;
    [[nodiscard]] QVector<QPair<QString, QString>> extendedMetadata() const override;
 
    [[nodiscard]] SWMM_Engine engine() const;
 
    [[nodiscard]] bool crsAssigned() const noexcept { return m_crsAssigned; }
 
    bool loadModel(QList<QString> &warnings, QList<QString> &errors);
 
    static SWMM_Engine openEngineForPath(const QString &path,
                                         QString *errorDetail,
                                         qint64 *openMs = nullptr);
 
    void buildFromEngine(SWMM_Engine engine,
                         qint64 *soaMsOut = nullptr, qint64 *geomMsOut = nullptr);
 
    bool adoptOpenEngine(SWMM_Engine engine,
                         QList<QString> &warnings, QList<QString> &errors,
                         qint64 openMs = -1, qint64 soaMs = 0, qint64 geomMs = 0);
 
    void closeEngine();
 
    // ----- In-memory new project (File → New) -----------------------------
 
    struct NewProjectSpec {
        QString   name;                      
        QDateTime startDateTime;
        QDateTime endDateTime;
        bool      forNewEngine = true;       
        PreferencesManager::SimulationDefaults sim;   
        PreferencesManager::TwoDDefaults       twoD;  
    };
 
    static SWMM_Engine createBlankEngine(const NewProjectSpec &spec,
                                         QString *errorDetail);
 
    bool adoptNewEngine(const NewProjectSpec &spec,
                        QList<QString> &warnings, QList<QString> &errors);
 
    // ----- Element visibility toggles -------------------------------------
 
    [[nodiscard]] bool showNodes()        const;
    void setShowNodes(bool show);
 
    [[nodiscard]] bool showLinks()        const;
    void setShowLinks(bool show);
 
    [[nodiscard]] bool showSubcatchments() const;
    void setShowSubcatchments(bool show);
 
    [[nodiscard]] bool showRainGages()    const;
    void setShowRainGages(bool show);
 
    [[nodiscard]] bool showLabels()       const;
    void setShowLabels(bool show);
 
    // VS.10 — labelConfig() inherited from OpenSWMMVisLayer; only the setter
    // is overridden to keep the legacy m_showLabels flag in sync.
    void setLabelConfig(const OpenSWMM::Render::LabelConfig &cfg) override;
 
    enum QsgKind : quint8 {
        QsgNone     = 0x00,
        QsgNodes    = 0x01,  
        QsgLinks    = 0x02,  
        QsgCatch    = 0x04,  
        QsgGages    = 0x08,  
    };
    Q_DECLARE_FLAGS(QsgKinds, QsgKind)
 
    [[nodiscard]] QsgKinds qsgRenderKinds() const noexcept { return m_qsgKinds; }
    void setQsgRenderKinds(QsgKinds kinds);
 
    [[nodiscard]] bool qsgOwnsKind(QsgKind k) const noexcept
        { return m_qsgKinds.testFlag(k); }
 
    [[nodiscard]] bool glRenderingEnabled() const noexcept
        { return m_qsgKinds != QsgNone; }
    void setGlRenderingEnabled(bool on)
        { setQsgRenderKinds(on ? QsgKinds(QsgNodes | QsgLinks | QsgCatch | QsgGages)
                               : QsgKinds(QsgNone)); }
 
    // ----- Per-object visibility (Slice O) --------------------------------
 
    [[nodiscard]] bool isObjectVisible(const QString &name) const;
 
    [[nodiscard]] bool isObjectVisible(const QString &name, Category c) const;
    void setObjectVisible(const QString &name, bool visible);
 
    void setObjectsVisible(const QList<QString> &names, bool visible);
 
    [[nodiscard]] QSet<QString> hiddenObjects() const { return m_hiddenObjects; }
 
    [[nodiscard]] double maxMarkerHalfBoundPx() const;
 
    // ----- Category-aware API (consumed by SWMMObjectTreeModel) -----------
 
    [[nodiscard]] int categoryCount(Category c) const;
 
    [[nodiscard]] QString objectNameAt(Category c, int row) const;
 
    [[nodiscard]] int soaIndexAt(Category c, int row) const;
 
    [[nodiscard]] int dataObjectCount(DataCategory c) const;
 
    [[nodiscard]] QString dataObjectNameAt(DataCategory c, int row) const;
 
    [[nodiscard]] QString suggestUniqueDataObjectName(DataCategory c) const;
 
    [[nodiscard]] QStringList tableIdsOfType(int tableType) const;
 
    [[nodiscard]] bool createDataObject(DataCategory c,
                                          const QString &name,
                                          const QVariantMap &options,
                                          QString *outError = nullptr);
 
    [[nodiscard]] Qt::CheckState categoryCheckState(Category c) const;
 
    void setObjectVisibleAt(Category c, int row, bool visible);
 
    void setCategoryVisible(Category c, bool visible);
 
    [[nodiscard]] qreal categoryOpacity(Category c) const;
    void setCategoryOpacity(Category c, qreal opacity);
 
    bool findObjectLocation(const QString &name,
                            Category *cat, int *row) const;
 
    // ----- Category ordering (Slice T.2) ----------------------------------
 
    [[nodiscard]] QVector<Category> categoryOrder() const;
 
    void setCategoryOrder(const QVector<Category> &order);
 
    // ----- Intra-category object ordering (Slice T.3) ---------------------
 
    void setObjectOrder(Category cat, const QVector<int> &soaIndices);
 
    void clearObjectOrder(Category cat);
 
    [[nodiscard]] QVector<int> objectOrder(Category cat) const;
 
    [[nodiscard]] QVector<int> defaultObjectOrder(Category cat) const;
 
    // ----- Symbology ------------------------------------------------------
 
    [[nodiscard]] SWMMElementSymbol junctionSymbol()   const;
    void setJunctionSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol outfallSymbol()    const;
    void setOutfallSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol storageSymbol()    const;
    void setStorageSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol dividerSymbol()    const;
    void setDividerSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol virtualJunctionSymbol() const;
    void setVirtualJunctionSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol inletJunctionSymbol() const;
    void setInletJunctionSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol inletConnectorSymbol() const;
    void setInletConnectorSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol conduitSymbol()    const;
    void setConduitSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol pumpSymbol()       const;
    void setPumpSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol orificeSymbol()    const;
    void setOrificeSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol weirSymbol()       const;
    void setWeirSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol outletSymbol()     const;
    void setOutletSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol subcatchmentSymbol() const;
    void setSubcatchmentSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] SWMMElementSymbol rainGageSymbol()   const;
    void setRainGageSymbol(const SWMMElementSymbol &s);
 
    [[nodiscard]] std::vector<std::unique_ptr<openswmmvis::ui::ILayerStyleSubject>>
        styleSubjects() override;
 
    [[nodiscard]] SwmmElementSymbolAdapter *
        elementSymbolAdapter(const QString &routingId);
 
    [[nodiscard]] quint64 editRevision() const { return m_editRevision; }
 
    // ----- Renderer (Slice BI Phase 8.13.6.5) -----------------------------
    // The renderer is the §J.2 seam every future paint path will go through.
    // Sub-phase 8.13.6.5 is API plumbing only — the existing paint loop in
    // SWMMLayerItem still reads the per-kind SWMMElementSymbol members
    // (m_junctionSym, m_conduitSym, …) directly. The paint refactor lands
    // later (after Slice BB Phase 8.6.1 provides a proper ColorRamp type),
    // at which point the default renderer will be swapped from this
    // placeholder SingleSymbolRenderer to a MultiKindRenderer adapter that
    // delegates to the 11 per-category symbols.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *renderer() const override;
 
    void setRenderer(std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r) override;
 
    // ----- Per-kind renderer (Slice BI-MK.1 / BI-MK.LT, 2026-05-24) --------
    //
    // Stores 11 per-kind IFeatureRenderer entries, indexed by Category, so
    // SymbologyDialog's left-pane kind picker and LayerTreePanel's sub-row
    // right-click menu can drive per-kind styling independently. Single-
    // symbol renderers double-bind to the legacy `m_*Sym` SWMMElementSymbol
    // fields (write-through both ways) so the current bucketed paint code
    // in SWMMLayerItem keeps working without a full per-feature symbolFor()
    // refactor. Graduated/Categorized renderers are stored + drive legends
    // / persistence; canvas painting from them is deferred to the full
    // Phase 8.13.6.4 paint-loop refactor.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *kindRenderer(Category c) const;
 
    void setKindRenderer(Category c,
                          std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r);
 
    void resetKindRendererToDefaults(Category c);
 
    [[nodiscard]] static QString kindKey(Category c);
 
    // ----- X4: legend-as-editor facade ------------------------------------
    // The model layer is multi-kind, so it has no single IFeatureRenderer for
    // the legend dock to drive. These mirror the IFeatureRenderer class-edit
    // contract but aggregate across the 11 per-kind renderers: legend rows
    // carry a kind-qualified classKey ("Junctions␟<inner>"), and the
    // colour/size accessors decode the kind and delegate to the matching
    // kindRenderer() — i.e. edits land on the very objects the painter reads
    // (single source of truth). Mutating setters rebuild that kind's
    // per-feature override cache and request a repaint.
    [[nodiscard]] QList<OpenSWMM::Render::LegendSymbolItem> legendSymbolItems() const;
    [[nodiscard]] bool   supportsClassEdit(OpenSWMM::Render::ClassEditKind kind) const;
    [[nodiscard]] QColor colorForClass(const QString &classKey) const;
    void                 setColorForClass(const QString &classKey, const QColor &color);
    [[nodiscard]] qreal  sizeForClass(const QString &classKey) const;
    void                 setSizeForClass(const QString &classKey, qreal size);
 
    // ----- Rule Model (Slice B.4, Phase B) --------------------------------
    //
    // 11 kindRenderer slots → 11 Rules, one per Category. The RuleList
    // is lazy-built on first access; each Rule holds a CLONE of the
    // matching kindRenderer at construction time. Rule-side renderer
    // swaps (via Z.3b's setRendererById) propagate back to the layer
    // via setKindRenderer, which keeps the legacy paint-time + override
    // cache code paths intact.
    //
    // Limitation: external calls to setKindRenderer (e.g. from undo
    // commands) don't re-sync the RuleList. The user must reopen the
    // Layer Style dialog to see fresh state — acceptable for B.4; full
    // bidirectional sync lands in a follow-up if it surfaces a real
    // problem.
    [[nodiscard]] OpenSWMM::Render::RuleList *ruleList() override;
    [[nodiscard]] const OpenSWMM::Render::RuleList *ruleList() const override;
 
    // ----- IAttributeProvider (Slice DM.3) --------------------------------
    //
    // Returns the per-kind static engine fields a user can theme by
    // (length, slope, diameter, invertElev, area, impervPct, …). All
    // entries are isDynamic=false (statics don't change per animation
    // frame). Drives the attribute combo in the Graduated / Categorized
    // renderer panels — see RENDERING_DIALOG_DEMO_PLAN.md §2.
    [[nodiscard]] QVector<OpenSWMM::Render::AttributeField>
        availableAttributes(OpenSWMMVis::SwmmCategory cat) const override;
 
    // ----- Flow-direction arrows (Slice BI Phase 8.13.8-mini, 2026-05-24) -
    //
    // Per-link-kind toggle for arrowheads drawn at the polyline midpoint
    // pointing upstream → downstream. Wraps the showArrows / arrowSize /
    // arrowColor / arrowOnlyWhenFlowPos fields on the corresponding
    // SWMMElementSymbol so the painter can drive arrows from a single
    // place. `c` must be a link kind (Conduits / Pumps / Orifices /
    // Weirs / Outlets); other categories silently no-op the setter and
    // return false from the getter.
 
    [[nodiscard]] bool linkArrowsEnabled(Category c) const;
 
    void setLinkArrowsEnabled(Category c, bool enabled);
 
    // Slice FX.1 — per-kind arrow size / colour / flow-positive filter.
    // Mirror the linkArrowsEnabled getter+setter shape; setters emit
    // repaintRequested when the underlying field actually changes.
    [[nodiscard]] double linkArrowSize(Category c) const;
    void setLinkArrowSize(Category c, double pixels);
    [[nodiscard]] double linkArrowWidth(Category c) const;
    void setLinkArrowWidth(Category c, double pixels);
    [[nodiscard]] QColor linkArrowColor(Category c) const;
    void setLinkArrowColor(Category c, const QColor &col);
    [[nodiscard]] bool   linkArrowOnlyWhenFlowPos(Category c) const;
    void setLinkArrowOnlyWhenFlowPos(Category c, bool onlyPos);
 
    [[nodiscard]] double linkFlow(int linkIdx) const;
 
    [[nodiscard]] bool kindUsesOverrides(Category c) const;
 
    [[nodiscard]] QColor featureColor(Category c, int idx) const;
 
    [[nodiscard]] double featureSize(Category c, int idx) const;
 
    [[nodiscard]] int featureShape(Category c, int idx) const;
 
    [[nodiscard]] double featureOffset(Category c, int idx) const;
 
    [[nodiscard]] bool kindHasAnyOffset(Category c) const;
 
    void rebuildKindFeatureColors(Category c);
 
    void classifyGraduatedIfNeeded(Category c,
                                   OpenSWMM::Render::GraduatedRenderer *g);
 
    // ----- Selection ------------------------------------------------------
 
    static constexpr quint8 kKindNode  = 0x01;
    static constexpr quint8 kKindLink  = 0x02;
    static constexpr quint8 kKindCatch = 0x04;
    static constexpr quint8 kKindGage  = 0x08;
    static constexpr quint8 kKindAll   = 0x0F;
 
    [[nodiscard]] static quint8 kindBitForCategory(Category c) noexcept;
 
    struct SelectedElement {
        QString name;
        quint8  kinds = 0;
        bool operator==(const SelectedElement &o) const
            { return kinds == o.kinds && name == o.name; }
    };
 
    [[nodiscard]] QStringList selectedElementNames() const;
 
    [[nodiscard]] const QVector<SelectedElement> &selectedElements() const
        { return m_selectedElements; }
 
    void setSelectedElements(const QVector<SelectedElement> &sel);
 
    void setSelectedElementNames(const QStringList &names);
 
    void clearSelection();
 
    // ----- Identify -------------------------------------------------------
 
    [[nodiscard]] QVariantMap identifyAt(double mapX, double mapY,
                                         const SpatialReferenceSystem *canvasSRS,
                                         double tolerance = 1e-6) const;
 
    [[nodiscard]] QVariantMap identifyAt(double mapX, double mapY,
                                         double tolerance = 1e-6) const;
 
    [[nodiscard]] QVariantMap identifyByName(const QString &name,
                                             quint8 kindMask = kKindAll) const;
 
    [[nodiscard]] class MapExtent objectExtent(const QString &name) const;
 
    // ----- Spatial-index queries (O(log N + k), backed by nanoflann KD-tree) ---
 
    [[nodiscard]] QStringList nodesInRect(double canvasMinX, double canvasMinY,
                                          double canvasMaxX, double canvasMaxY) const;
 
    [[nodiscard]] bool snapNearestPoint(double mapX, double mapY, double mapRadius,
                                        QPointF &outPt,
                                        std::optional<QPointF> excludePos = std::nullopt) const;
 
    [[nodiscard]] QStringList gagesInRect(double canvasMinX, double canvasMinY,
                                          double canvasMaxX, double canvasMaxY) const;
 
    [[nodiscard]] QStringList linksInRect(double canvasMinX, double canvasMinY,
                                          double canvasMaxX, double canvasMaxY) const;
 
    [[nodiscard]] QStringList subcatchmentsInRect(double canvasMinX, double canvasMinY,
                                                  double canvasMaxX, double canvasMaxY) const;
 
    // ----- Polygon (lasso) queries ----------------------------------------
    // Same contract as the *InRect queries above, but the test region is an
    // arbitrary polygon given in canvas CRS. Candidates are first gathered
    // with the polygon's bounding box (reusing the accelerated *InRect path),
    // then refined with an exact point-in-polygon test performed in layer CRS
    // (nodes/gages at their coordinate; links/subcatchments at their bbox
    // centre). Hidden objects are excluded. \p canvasPoly needs >= 3 vertices.
 
    [[nodiscard]] QStringList nodesInPolygon(const QPolygonF &canvasPoly) const;
    [[nodiscard]] QStringList gagesInPolygon(const QPolygonF &canvasPoly) const;
    [[nodiscard]] QStringList linksInPolygon(const QPolygonF &canvasPoly) const;
    [[nodiscard]] QStringList subcatchmentsInPolygon(const QPolygonF &canvasPoly) const;
 
    // ----- OpenSWMMVisLayer interface -----------------------------------------
 
    void populateScene(QGraphicsScene *scene,
                       const MapExtent &canvasExtent,
                       const SpatialReferenceSystem *canvasSRS) override;
 
    void depopulateScene(QGraphicsScene *scene) override;
 
    void refreshScene(QGraphicsScene *scene,
                      const MapExtent &canvasExtent,
                      const SpatialReferenceSystem *canvasSRS) override;
 
    void onCanvasCRSChanged(const SpatialReferenceSystem *newCanvasSRS) override;
 
    void reloadGeometry();
 
    bool transformCanvasToLayer(double cx, double cy,
                                double &lx, double &ly) const;
 
    [[nodiscard]] QPolygonF polygonCanvasToLayer(const QPolygonF &poly) const;
 
    bool transformLayerToCanvas(double lx, double ly,
                                double &cx, double &cy) const;
 
    [[nodiscard]] int objectTypeFor(const QString &name) const;
 
    // ----- Geometry editing API (Phase 2) --------------------------------
 
    [[nodiscard]] int nodeIndex(const QString &name) const;
 
    [[nodiscard]] int linkIndex(const QString &name) const;
 
    bool cachedNodeCoord(int idx, double *x, double *y) const;
 
    bool elementPosition(const QString &name, double *x, double *y) const;
 
    [[nodiscard]] QVector<QPointF> cachedLinkPolyline(int idx) const;
 
    [[nodiscard]] QVector<QPointF> cachedLinkInteriorVertices(int idx) const;
 
    [[nodiscard]] int renderLinkCount() const
    { return int(m_linkVertexCount.size()); }
 
    [[nodiscard]] bool renderLinkHidden(int idx) const
    {
        return idx >= 0 && size_t(idx) < m_linkHiddenFlag.size()
            && m_linkHiddenFlag[size_t(idx)] != 0;
    }
 
    [[nodiscard]] QVector<QPointF> cachedSubcatchVertices(int idx) const;
 
    [[nodiscard]] int cachedSubcatchCount() const;
 
    [[nodiscard]] int cachedNodeCount() const;
    [[nodiscard]] int cachedLinkCount() const;
    [[nodiscard]] int cachedGageCount() const;
 
    [[nodiscard]] bool cachedGageCoord(int idx, double *x, double *y) const;
 
    [[nodiscard]] quint64 geomRevision() const { return m_geomRevision; }
 
    // ----- Simulation-options pass-through (Slice U) ----------------------
 
    [[nodiscard]] QString getOption(const QByteArray &key,
                                    const QString    &fallback = {}) const;
 
    bool setOption(const QByteArray &key, const QString &value);
 
    int  setOptions(const QMap<QByteArray, QString> &values);
 
    [[nodiscard]] double engineLinkLength(int linkIdx) const;
 
    [[nodiscard]] double polylineLengthInModelUnits(
        const QVector<QPointF> &vertices) const;
 
    [[nodiscard]] bool isConduit(int linkIdx) const;
 
    // ----- Tool-facing hit-test (Slice R Phase 3) -------------------------
 
    struct PickResult {
        bool     valid    = false;
        Category cat      = NumCategories;
        int      soaIndex = -1;
        QString  name;
    };
 
    [[nodiscard]] PickResult pickAt(double sceneX, double sceneY,
                                    double tolerance) const;
 
    bool previewNodeMove(int idx, double newX, double newY);
 
    bool previewGageMove(int idx, double newX, double newY);
 
    [[nodiscard]] QVector<int> linksAttachedToNode(int nodeIdx) const;
 
    [[nodiscard]] int linkEndForNode(int linkIdx, int nodeIdx) const;
 
    [[nodiscard]] int linkFromNodeIdx(int linkIdx) const;
 
    [[nodiscard]] int linkToNodeIdx(int linkIdx) const;
 
    bool applyNodeMove(int idx, double newX, double newY);
 
    bool applyLinkLength(int linkIdx, double length);
 
    void convertLinkOffsets(bool toElevation, bool convertValues);
 
    bool applyLinkXsect(int linkIdx, int shape,
                          double g1, double g2, double g3, double g4);
 
    bool applyLinkBarrels(int linkIdx, int barrels);
 
    bool applyLinkCulvertCode(int linkIdx, int code);
 
    bool applyNodeConvert(const QString &name, int newNodeType,
                          QStringList *outCleared  = nullptr,
                          QStringList *outWarnings = nullptr,
                          QString *outError = nullptr);
 
    bool applyLinkConvert(const QString &name, int newLinkType,
                          QStringList *outCleared  = nullptr,
                          QStringList *outWarnings = nullptr,
                          QString *outError = nullptr);
 
    bool applyLinkFlip(int linkIdx);
 
    // ===== Virtual junctions ==============================================
    // Engine-side split/fuse semantics (swmm_conduit_split /
    // swmm_virtual_junction_fuse / swmm_node_set_virtual) so CLI, Python,
    // MCP and GUI share one implementation. See
    // workplans/VIRTUAL_JUNCTION_GUI_PLAN_2026-08-01.md.
 
    bool nodeIsVirtual(int soaIdx) const {
        return soaIdx >= 0 && soaIdx < m_nodes.size() &&
               m_nodes[soaIdx].isVirtual != 0;
    }
 
    bool applySetVirtual(const QString &name, bool makeVirtual,
                         QString *outError = nullptr);
 
    bool applyInsertVirtualJunction(const QString &linkName, double t,
                                    const QString &newNodeName,
                                    const QString &newLinkName,
                                    int *outNodeIdx = nullptr,
                                    int *outLinkIdx = nullptr,
                                    QString *outError = nullptr);
 
    bool applyFuseVirtualJunction(const QString &nodeName,
                                  QString *outError = nullptr);
 
    bool applyInsertJunctionSplit(const QString &linkName, double t,
                                  const QString &newNodeName,
                                  const QString &newLinkName,
                                  int *outNodeIdx = nullptr,
                                  int *outLinkIdx = nullptr,
                                  QString *outError = nullptr);
 
    bool applyFuseJunctionSplit(const QString &nodeName,
                                QString *outError = nullptr);
 
    static QString virtualJunctionRuleText(int engineErrorCode);
 
    // ===== Inlet junctions and inlet usage ================================
    // Engine surface: swmm_node_is_inlet / _inlet_eligible / _set_inlet
    // (openswmm_nodes.h), swmm_inlet_usage_* (openswmm_infrastructure.h),
    // swmm_conduit_split_inlet / swmm_inlet_junction_fuse (openswmm_edit.h).
    // See workplans/INLET_EDITOR_AND_INLET_JUNCTION_GUI_PLAN_2026-09-05.md.
 
    [[nodiscard]] bool nodeIsInlet(int soaIdx) const {
        return soaIdx >= 0 && soaIdx < m_nodes.size() &&
               m_nodes[soaIdx].isInlet != 0;
    }
 
    [[nodiscard]] bool engineSupportsInletJunctions() const;
 
    [[nodiscard]] bool inletUsageFor(int hostKind, int hostIdx,
                                     SWMM_InletUsage *out) const;
 
    bool applySetInletUsage(const SWMM_InletUsage &usage,
                            QString *outError = nullptr);
 
    bool applyRemoveInletUsage(int hostKind, int hostIdx,
                               QString *outError = nullptr);
 
    bool applySetInlet(const QString &name, bool makeInlet,
                       QString *outError = nullptr);
 
    bool applyInsertInletJunction(const QString &linkName, double t,
                                  const QString &newNodeName,
                                  const QString &newLinkName,
                                  const QString &inletId,
                                  const QString &captureNode,
                                  int *outNodeIdx = nullptr,
                                  int *outLinkIdx = nullptr,
                                  QString *outError = nullptr);
 
    bool applyFuseInletJunction(const QString &nodeName,
                                QString *outError = nullptr);
 
    struct InletConnector {
        QPointF host;      
        QPointF capture;   
    };
 
    [[nodiscard]] const QVector<InletConnector> &inletConnectors() const;
 
    void setEditCanvas(MapCanvas *canvas);
    [[nodiscard]] MapCanvas *editCanvas() const;
 
    bool pushInletUsageEdit(const SWMM_InletUsage &usage);
    bool pushInletUsageRemoval(int hostKind, int hostIdx);
 
    bool applyLinkInteriorVertices(int linkIdx, const QVector<QPointF> &interior);
 
    bool applySubcatchVertices(int idx, const QVector<QPointF> &vertices);
    bool applySubcatchArea(int idx, double areaInModelUnits);
 
    bool applySubcatchSetGage(int idx, const QString &gageName);
 
    bool applyNodeAdd(const QString &name, int nodeType,
                      double x, double y,
                      int *outIdx = nullptr);
 
    bool rollbackTailNodeAdd(const QString &name);
 
    bool applyLinkAdd(const QString &name, int linkType,
                      const QString &fromNodeName, const QString &toNodeName,
                      const QVector<QPointF> &interiorVertices,
                      int *outIdx = nullptr);
 
    bool rollbackTailLinkAdd(const QString &name);
 
    bool applyGageMove(int idx, double newX, double newY);
 
    bool applyGageAdd(const QString &name, double x, double y,
                      int *outIdx = nullptr);
 
    bool rollbackTailGageAdd(const QString &name);
 
    bool applySubcatchAdd(const QString &name,
                          const QVector<QPointF> &polygon,
                          int *outIdx = nullptr);
 
    bool rollbackTailSubcatchAdd(const QString &name);
 
    bool applyRename(const QString &oldName, const QString &newName,
                     quint8 kindHint = kKindAll);
 
    // ===== Bulk edit — coalesce the per-object cache-rebuild storm =======
    //
    // Every applyXxxAdd / applyXxxDelete rebuilds the whole derived cache
    // (category index, model extent, link spatial grid) and then emits
    // repaintRequested() + geometryChanged(), whose listeners each do
    // O(model) work of their own. That is affordable for one object and
    // quadratic for a selection: deleting 100 junctions from a 104k-node
    // model costs ~21 s, of which only ~4.6 s is the engine.
    //
    // Inside a bulk edit the engine call and the SoA removal/append still
    // happen IMMEDIATELY — only the derived work is deferred. That is
    // deliberate: it keeps the "SoA index == engine index" invariant true
    // at every instant, which the rest of this class relies on.
    //
    // Always use the RAII BulkEdit guard; never call beginBulkEdit() /
    // endBulkEdit() by hand. A batch that begins and never ends would
    // leave the layer permanently signal-blocked with stale caches.
    class BulkEdit
    {
    public:
        explicit BulkEdit(SWMMModelLayer *layer) : m_layer(layer)
        {
            if (m_layer) m_layer->beginBulkEdit();
        }
        ~BulkEdit()
        {
            if (m_layer) m_layer->endBulkEdit();
        }
        BulkEdit(const BulkEdit &)            = delete;
        BulkEdit &operator=(const BulkEdit &) = delete;
 
    private:
        QPointer<SWMMModelLayer> m_layer;
    };
 
    void beginBulkEdit();
 
    void endBulkEdit();
 
    [[nodiscard]] bool bulkEditActive() const { return m_bulkDepth > 0; }
 
    bool applyNodeDelete(const QString &name,
                         QStringList *cascadeLinkNames = nullptr);
 
    bool applyLinkDelete(const QString &name);
 
    bool applyGageDelete(const QString &name);
 
    bool applySubcatchDelete(const QString &name);
 
    bool applyDeleteMany(const QStringList &nodeNames,
                         const QStringList &linkNames,
                         const QStringList &subcatchNames,
                         const QStringList &gageNames,
                         QStringList *cascadeLinkNames = nullptr);
 
    // ===== Slice BS Phase 6.9.2 — hydrograph + RDII decay MVC layer ======
    //
    // Every mutation to [HYDROGRAPHS] / [RDII_DECAY] data routes through one
    // of the helpers below — never call `swmm_hydrograph_*` /
    // `swmm_rdii_decay_*` directly from a dialog. On success each helper
    // emits hydrographChanged(uhName) so all subscribed Qt models refresh in
    // lock-step. The model layer is the single Qt-side mediator over the
    // engine's BS-02 C API.
    //
    // See: docs/GUI_IMPLEMENTATION_PLAN.md Slice BS Phase 6.9.2.
 
    bool applyHydrographAddGroup(const QString &name,
                                  const QString &gageName,
                                  int initialResponse);
 
    bool applyHydrographRemoveGroup(const QString &name);
 
    bool applyHydrographRenameGroup(const QString &oldName, const QString &newName);
 
    bool applyHydrographSetGage(const QString &name, const QString &gageName);
 
    bool applyHydrographSetRtk(const QString &name, int month, int response,
                                double r, double t, double k);
 
    bool applyHydrographSetIa(const QString &name, int month, int response,
                               double dmax, double drecov, double dinit);
 
    bool applyHydrographRemoveEntry(const QString &name, int month, int response);
 
    bool applyHydrographClearMonths(const QString &name);
 
    bool applyRdiiDecaySet(const QString &name, int response,
                            double k_dep, double k_0, double k_T,
                            double T_ref, double theta_rec, double T_freeze,
                            bool snowOn = false, double snow_T = 1.0,
                            double snow_ddf = 0.0);
 
    bool applyRdiiDecayRemove(const QString &name, int response);
 
    HydrographGroupListModel  *hydrographGroupListModel();
 
    HydrographRtkTableModel   *hydrographRtkModel();
 
    HydrographIaTableModel    *hydrographIaModel();
 
    HydrographDecayTableModel *hydrographDecayModel();
 
    QObject *ensureTimeseriesRegistry();
 
    QObject *ensurePatternRegistry();
 
    QObject *ensureCurveRegistry();
 
    // ===== Slice BR Phase 6.8.1 — control-rule MVC layer ====================
    //
    // Mirrors the hydrograph pattern at Phase 6.9.2 (`applyHydrograph*` +
    // `hydrographChanged`) and the curve/pattern/timeseries `ensureXRegistry`
    // accessors above. The four `applyControlRule*` helpers are the **only**
    // place engine `swmm_control_*` mutation calls live; all UI surfaces
    // (RulesEditorDialog, SWMMControlRulePropertyAdapter, Object Browser)
    // route through them and re-render off the `controlRulesChanged(name)`
    // signal.
    //
    // The engine has no per-rule mutator (DA-ENG-11), so each apply helper
    // snapshots every rule, modifies the target slot in the snapshot, calls
    // `swmm_control_clear_rules`, and re-`swmm_control_add_rule`s the
    // snapshot. This matches today's `SWMMControlRulePropertyAdapter
    // ::setRuleText` round-trip.
 
    bool applyControlRuleAdd(const QString &name, const QString &body,
                               QString *outError = nullptr);
 
    bool applyControlRuleReplace(const QString &name, const QString &newBody,
                                   QString *outError = nullptr);
 
    bool applyControlRuleRename(const QString &oldName, const QString &newName,
                                  QString *outError = nullptr);
 
    bool applyControlRuleRemove(const QString &name,
                                  QString *outError = nullptr);
 
    QObject *ensureControlRuleRegistry();
 
    // ===== Slice BQ Phase 6.7.4 — transect MVC layer =========================
    //
    // Mirrors the curve / pattern / control-rule pattern. The applyTransect*
    // helpers are the only place engine `swmm_transect_*` mutation calls
    // live; all UI surfaces (TransectEditorDialog, SWMMTransectPropertyAdapter,
    // Object Browser) route through them and re-render off
    // `transectChanged(name)`.
 
    bool applyTransectAdd(const QString &name, QString *outError = nullptr);
 
    bool applyTransectRename(const QString &oldName, const QString &newName,
                              QString *outError = nullptr);
 
    bool applyTransectRemove(const QString &name, QString *outError = nullptr);
 
    bool applyTransectSetComments(const QString &name, const QString &comments);
    bool applyTransectSetRoughness(const QString &name,
                                    double nLeft, double nRight, double nChannel);
    bool applyTransectSetBankStations(const QString &name, double xLeft, double xRight);
    bool applyTransectSetEncroachmentStations(const QString &name,
                                               double xLeft, double xRight);
    bool applyTransectSetModifiers(const QString &name,
                                    double stationMul, double elevOffset, double meander);
    bool applyTransectSetStations(const QString &name,
                                   const QVector<QPair<double,double>> &stations);
 
    QObject *ensureTransectRegistry();
 
    QObject *ensureStreetRegistry();
 
    QObject *ensurePollutantRegistry();
 
    QObject *ensureLandUseRegistry();
 
    QObject *ensureAquiferRegistry();
 
    QObject *ensureSnowpackRegistry();
 
    QObject *ensureInletRegistry();
 
    QObject *ensureLidControlRegistry();
 
    // ===== User flags ([USER_FLAGS] / [USER_FLAG_VALUES]) ==================
    //
    // Phase 1 of docs/USER_FLAGS_UI_PLAN_2026-06-03.md. Same lazy-init /
    // engine-handle-guard pattern as the registries above. All engine
    // user-flag mutation calls live in UserFlagsModel; UI surfaces (User
    // Flags Manager dialog, Attribute Table flag columns, Attribute Panel
    // rows) share this instance and re-render off its defsChanged() /
    // valueChanged() signals.
 
    openswmmvis::ui::UserFlagsModel *ensureUserFlagsModel();
 
public slots:
    void markEdited() { emit modelEdited(); }
 
signals:
    void modelFilePathChanged(const QString &path);
    void showNodesChanged(bool show);
    void showLinksChanged(bool show);
    void showSubcatchmentsChanged(bool show);
    void showRainGagesChanged(bool show);
    void showLabelsChanged(bool show);
 
    // VS.10 — labelConfigChanged() is inherited from OpenSWMMVisLayer.
 
    void selectionChanged(const QStringList &selectedNames);
    void modelLoaded();
    void modelLoadError(const QString &errorMessage);
    void rendererChanged();
 
    void optionsChanged(const QStringList &keys);
 
    void categoryOrderChanged();
 
    void geometryChanged();
 
    void attributeChanged(const QString &objectName);
 
    void qsgRenderKindsChanged(QsgKinds kinds);
 
    void hydrographChanged(const QString &uhName);
 
    void controlRulesChanged(const QString &ruleName);
 
    void transectChanged(const QString &transectName);
 
    void dataObjectsChanged();
 
    void modelEdited();
 
private:
    // X4 — decode a kind-qualified legend class key ("<kindKey><sep><inner>")
    // back to its Category + inner class key. Returns false when the key
    // isn't kind-qualified or the kind is unknown.
    bool decodeLegendClassKey(const QString &key, Category *catOut,
                              QString *innerOut) const;
 
    struct NodeGeom    { double x, y; int objectType; int nodeType;
                         int isVirtual = 0;
                         int isInlet = 0;
                         QString name; };
    struct LinkGeom {
        QVector<QPointF> vertices;   // interior bend points only (no node endpoints)
        int              linkType    = -1;
        int              fromNodeIdx = -1;
        int              toNodeIdx   = -1;
        QString          name;
    };
    struct CatchGeom   { QVector<QPointF> vertices; QString name; };
 
    struct OutletLine  { QLineF line; int catchIdx; };
 
    void buildGeometryCache();
    void rebuildTransform(const SpatialReferenceSystem *canvasSRS);
    void rebuildKdTrees() const;  
    void ensureKdTrees()  const;  
 
    void rebuildSceneCoords();
    void refreshSceneCoordsForNode(int nodeIdx);
    void refreshSceneCoordsForLink(int linkIdx);
    void refreshSceneCoordsForSubcatch(int catchIdx);
    void refreshCatchOutletLinesForNode(int nodeIdx);
 
    // Incremental scene/cache mutations — O(1) per element plus an
    // O(L) spatial-grid touch where unavoidable. These let single
    // add / rename / delete operations skip the full O(N·V) OGR
    // re-transform that rebuildSceneCoords() does on every feature.
    void appendNodeSceneEntry();     
    void appendLinkSceneEntry();     
    void appendCatchSceneEntry();    
    void appendGageSceneEntry();     
    void compactNodeSceneEntry(int nodeIdx);
    void compactLinkSceneEntry(int linkIdx);
    void compactCatchSceneEntry(int catchIdx);
    void compactGageSceneEntry(int gageIdx);
 
    void syncLinkEndpointIndicesFromEngine();
 
    void renameInIndices(const QString &oldName, const QString &newName,
                         quint8 renamedKind);
 
    void recomputeExtentFromCaches();
 
    // Incremented at the end of every rebuildSceneCoords() call.
    // SWMMLayerQSGRenderer uses this to invalidate its subcatchment
    // triangulation cache without needing a signal or pointer comparison.
    quint64 m_geomRevision = 0;
 
    // Bulk-edit scope depth, and whether anything inside it actually
    // mutated. m_bulkDirty gates the batch-end rebuild so an all-failed
    // batch costs nothing — and so a batch of pure no-ops does not emit a
    // spurious geometryChanged().
    int  m_bulkDepth = 0;
    bool m_bulkDirty = false;
 
    // See crsAssigned(). Set by srsChanged after load; the load path resets
    // it to whether the .inp itself carried a CRS.
    bool m_crsAssigned = false;
 
    struct LinkSpatialGrid
    {
        QRectF       extent;         
        double       cellW = 0.0;
        double       cellH = 0.0;
        int          cols  = 0;
        int          rows  = 0;
        QVector<QVector<int>> cells; 
 
        void clear() { extent = {}; cellW = cellH = 0.0; cols = rows = 0; cells.clear(); }
        [[nodiscard]] bool isEmpty() const { return cells.isEmpty(); }
 
        void rebuild(const QVector<QRectF> &linkBBoxes);
 
        [[nodiscard]] QVector<int> query(const QRectF &rect) const;
    };
    LinkSpatialGrid              m_linkGrid;
 
    void rebuildCategoryIndex();
 
    SWMM_Engine                  m_engine          = nullptr;
 
    QString                      m_modelFilePath;
    bool                         m_showNodes       = true;
    bool                         m_showLinks       = true;
    bool                         m_showSubcatchments = true;
    bool                         m_showRainGages   = true;
    bool                         m_showLabels      = false;
    // VS.10 — m_labelConfig moved to OpenSWMMVisLayer (base owns it now).
    // Per-kind QSG scope (see QsgKind / qsgRenderKinds() above).
    // Default empty means the QSG overlay never runs and every kind is
    // drawn by the CPU SWMMLayerItem path — matches pre-§QSG-1 behaviour
    // and is what the Preferences toggle inverts when the user enables
    // the experimental GPU path.
    QsgKinds                     m_qsgKinds = QsgNone;
 
    // Slice O — per-object hidden set. Names listed here are skipped by
    // populateScene. NOTE: SWMM names are per-type namespaces — real
    // models routinely pair every subcatchment with a same-named rain
    // gage, and links may share names with nodes — so membership alone
    // cannot say WHICH kind the user hid. m_hiddenKindMask below carries
    // that type information; this set stays the name-keyed canonical
    // membership for the legacy API and .oswp persistence.
    QSet<QString>                m_hiddenObjects;
 
    // Per-name bitmask of hidden kinds. Invariant: a name is in
    // m_hiddenObjects iff its mask entry exists and is non-zero. Names
    // hidden through the legacy name-only API carry kKindAll.
    QHash<QString, quint8>       m_hiddenKindMask;
 
    // Per-name bitmask of SELECTED kinds — canonical typed selection.
    // m_selectedNames mirrors the keys for legacy name-based readers.
    // Names selected through the legacy name-only API carry kKindAll.
    QHash<QString, quint8>       m_selectedKindMask;
 
    QVector<NodeGeom>            m_nodes;
    QVector<LinkGeom>            m_links;
    QVector<CatchGeom>           m_catchments;
    QVector<NodeGeom>            m_gages;
 
    // Per-feature bbox caches, parallel to m_links / m_catchments.
    // Computed once in buildGeometryCache() and refreshed on edits
    // that touch coords (applyNodeMove / applyLinkInteriorVertices /
    // applyNodeAdd). linksInRect / subcatchmentsInRect iterate these
    // arrays directly — no per-call name lookup, no per-call vertex
    // loop. Big-model rubber-band selects went from O(N²) (linkIndex
    // linear scan + per-link vertex bbox) to O(N) with constant work
    // per item.
    QVector<MapExtent>           m_linkBboxes;
    QVector<MapExtent>           m_catchBboxes;
 
    // Scene-space coordinate cache, parallel to the SoAs above. Computed
    // once in rebuildSceneCoords() (on geometry change or CRS change) and
    // refreshed incrementally by edit paths. SWMMLayerItem::paint reads
    // from these directly — no per-vertex Transform()/toScene() call on
    // the paint hot path. Per-feature scene-space bounding rects support
    // viewport cull without a per-paint per-link bbox compute.
    QVector<QPointF>             m_nodeScenePts;
    QVector<QRectF>              m_linkSceneBBoxes;
    QVector<QVector<QPointF>>    m_catchScenePts;
    QVector<QRectF>              m_catchSceneBBoxes;
    QVector<QPointF>             m_gageScenePts;
    QVector<OutletLine>          m_catchOutletLines;  
 
    // Phase A.3 — flat-array link scene-coords. Replaces the previous
    // per-link QVector<QPointF> with one big std::vector<double> of
    // interleaved (x, y) pairs, plus per-link (offset, count). At 5M
    // links this saves ~120 MB of QVector overhead and gives the GL
    // pipeline (Phase B) a buffer it can stream into a VBO.
    //
    //   m_linkSceneFlat[(m_linkVertexOffset[i] + v) * 2 + 0]  =  x
    //   m_linkSceneFlat[(m_linkVertexOffset[i] + v) * 2 + 1]  =  y   (Y-flipped)
    //   v in [0, m_linkVertexCount[i])
    //
    // Doubles, not floats: SWMM models in projected CRS (state plane
    // feet, UTM meters) routinely have 6-7 digit coordinates, where
    // float's ~7 significant digits leaves ~0.5-1 m of quantisation
    // error. That shows up at high zoom as a visible gap between a
    // node glyph (drawn from the double m_nodeScenePts) and the link
    // endpoint that should be coincident with it. Y is pre-flipped so
    // paint feeds straight into QPainter::drawLines without per-vertex
    // math. GPU renderers that need single-precision VBOs subtract a
    // local origin and downcast on upload. Any vertex-count change
    // (rare; only when an editor adds/removes a vertex) triggers a
    // full rebuildSceneCoords; in-place node moves only rewrite the
    // affected link's slice of m_linkSceneFlat.
    std::vector<double>          m_linkSceneFlat;
    std::vector<uint32_t>        m_linkVertexOffset;   // size == m_links.size()
    std::vector<uint32_t>        m_linkVertexCount;    // size == m_links.size()
 
    // Phase A.2 of the 5M-rendering plan: selection / hidden state as
    // dense byte arrays parallel to the SoAs. SWMMLayerItem::paint reads
    // these directly instead of hashing each name into a QSet<QString>
    // every frame. Maintained alongside m_selectedNames / m_hiddenObjects
    // — those QString-keyed members remain the canonical state (used by
    // identify, attribute panel, persistence) but the flag arrays are
    // the fast path on the paint loop. Kept coherent by
    // setSelectedElementNames / setObjectVisible* / rebuildCategoryIndex.
    std::vector<uint8_t>         m_nodeSelectedFlag;   // 1 if m_nodes[i] selected
    std::vector<uint8_t>         m_linkSelectedFlag;
    std::vector<uint8_t>         m_catchSelectedFlag;
    std::vector<uint8_t>         m_gageSelectedFlag;
    std::vector<uint8_t>         m_nodeHiddenFlag;
    std::vector<uint8_t>         m_linkHiddenFlag;
    std::vector<uint8_t>         m_catchHiddenFlag;
    std::vector<uint8_t>         m_gageHiddenFlag;
 
    // Per-category row → SoA-index buckets. Built in buildGeometryCache,
    // cleared in closeEngine. Used by the virtualised Object Browser tree
    // model to resolve QModelIndex (category, row) → backing name in O(1)
    // without scanning the whole SoA on every data() call.
    QVector<int>                 m_nodesByType[4];   // junction/outfall/storage/divider
    QVector<int>                 m_linksByType[5];   // conduit/pump/orifice/weir/outlet
 
    // Per-category count of hidden members. Kept in sync by
    // setObjectVisible, setObjectVisibleAt, setCategoryVisible so
    // categoryCheckState() is O(1). Seeded to 0 at cache rebuild.
    int                          m_hiddenCountByCategory[NumCategories] = {};
 
    // Per-kind (sub-layer) opacity in [0,1], default 1.0. Multiplies each
    // feature's alpha in both paint paths; edited via the layer-tree Opacity
    // column on kind rows. NumCategories entries, brace-init below leaves
    // them 0 — the ctor fills 1.0 (see swmmmodellayer.cpp).
    qreal                        m_categoryOpacity[NumCategories];
 
    // User-controlled display order for the Object Browser (Slice T.2).
    // Seeded to the enum sequence in rebuildCategoryIndex() so a fresh
    // model starts with the default order.
    QVector<Category>            m_categoryOrder;
 
    // Per-category object order overrides (Slice T.3). Absent key =
    // category uses its default bucket order; present key = visible
    // row r maps to `m_objectOrderOverrides[c][r]`, which is the SoA
    // index for nodes (m_nodes) / links (m_links) / catch (m_catchments)
    // / gages (m_gages). Sparse by design: only categories the user
    // actually reordered carry memory. Cleared on geometry rebuild so
    // stale indices can't survive an add/remove.
    QHash<Category, QVector<int>> m_objectOrderOverrides;
 
    // name → (category, row) lookup seeded at cache time. Serves the
    // legacy name-based setObjectVisible(name, bool) entry point and
    // the SelectionManager → model-index mapping in the Object Browser
    // without a full O(N) scan of m_nodes / m_links per call.
    QHash<QString, QPair<Category, int>> m_objectLocation;
 
    // Phase A.2 — name → (kind, SoA index) for the flag-array paint
    // path. `kind` selects which array (m_nodes / m_links /
    // m_catchments / m_gages) the SoA index addresses. Built alongside
    // m_objectLocation in rebuildCategoryIndex and kept coherent on
    // edits. Distinct from m_objectLocation because that one stores
    // *display* row inside per-category buckets, whereas paint needs
    // the raw SoA index — different translation, different consumers.
    enum class SoaKind : int8_t { Node = 0, Link = 1, Catch = 2, Gage = 3 };
    struct SoaLocation { SoaKind kind; int soaIdx; };
    QHash<QString, SoaLocation>  m_nameToSoa;
 
    // Per-kind name → SoA index. Deliberately SEPARATE from m_nameToSoa,
    // which cannot serve these lookups: it is single-keyed, and while nodes
    // beat links there (links insert only when absent), catchments and gages
    // insert UNCONDITIONALLY and therefore overwrite a colliding node or
    // link. identifyByName / nodeIndex / linkIndex must instead resolve
    // node → link → catchment → gage, which is what the linear scans they
    // replace did. SWMM keeps a separate namespace per kind, so such
    // collisions are legal and do occur in real models.
    //
    // Within a kind, first definition wins — matching the scans' behaviour
    // of returning the lowest index. Maintained in lockstep with
    // m_nameToSoa: rebuilt in rebuildCategoryIndex(), swapped in
    // renameObject(), extended in appendNodeSceneEntry() /
    // appendLinkSceneEntry(). Deletions always go through
    // rebuildCategoryIndex(), so no incremental erase path is needed.
    QHash<QString, int>          m_nodeByName;
    QHash<QString, int>          m_linkByName;
    QHash<QString, int>          m_catchByName;
    QHash<QString, int>          m_gageByName;
 
    void rebuildFlagArrays();
 
    void forgetStaleObjectState(const QString &name, quint8 kindBit);
 
    SWMMElementSymbol            m_junctionSym;
    SWMMElementSymbol            m_virtualJunctionSym;
    SWMMElementSymbol            m_inletJunctionSym;
    SWMMElementSymbol            m_inletConnectorSym;
 
    mutable QVector<InletConnector> m_inletConnectors;
    mutable bool                    m_inletConnectorsDirty = true;
    mutable int                     m_inletJunctionSupport = -1;
    QPointer<MapCanvas>             m_editCanvas;
    void rebuildInletConnectors() const;
 
    void syncSplitCaches(int li, int newNode, int newLink,
                         const QString &newNodeName,
                         const QString &newLinkName,
                         const QString &origLinkName,
                         int isVirtual, int isInlet);
 
    void syncFuseCaches(int ni, int dn, int surviving);
    SWMMElementSymbol            m_outfallSym;
    SWMMElementSymbol            m_storageSym;
    SWMMElementSymbol            m_dividerSym;
    SWMMElementSymbol            m_conduitSym;
    SWMMElementSymbol            m_pumpSym;
    SWMMElementSymbol            m_orificeSym;
    SWMMElementSymbol            m_weirSym;
    SWMMElementSymbol            m_outletSym;   // Slice FX.1 — Outlets honor showArrows independently of Conduits.
    SWMMElementSymbol            m_subcatchSym;
    SWMMElementSymbol            m_gageSym;
 
    // Persistent per-kind symbol adapters keyed by subject routing id
    // ("model.junctions" …). Lazily built by elementSymbolAdapter(); owned
    // via QObject parenting. set*Symbol keeps their cached structs truthful
    // through resyncSymbolAdapter().
    QHash<QString, SwmmElementSymbolAdapter *> m_symbolAdapters;
    void resyncSymbolAdapter(const QString &routingId,
                             const SWMMElementSymbol &s);
 
    // Data-edit epoch for derived style/label caches. Bumped whenever
    // modelEdited or attributeChanged fires (self-connections in the ctor)
    // so consumers (SWMMLayerItem's label cache) can detect staleness
    // without wiring their own signal plumbing. Distinct from
    // m_geomRevision, which tracks scene-coordinate rebuilds only.
    quint64 m_editRevision = 0;
    bool m_derivedStyleCachesPending = false;
    void invalidateDerivedStyleCaches();
 
    // Slice BI Phase 8.13.6.5 — renderer plumbing. Eagerly initialised in
    // the ctor (default placeholder: SingleSymbolRenderer) so renderer()
    // never returns null. The existing paint loop still reads the per-kind
    // m_*Sym members; the paint refactor sub-phase swaps in a
    // MultiKindRenderer adapter and flips the paint path.
    std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> m_renderer;
 
    // Slice BI-MK.1 / BI-MK.LT (2026-05-24) — per-kind renderer storage.
    // Indexed by Category ordinal; size == NumCategories. SymbologyDialog's
    // left-pane picker and the layer-tree sub-row right-click menu drive
    // edits here. Single-symbol entries are kept in sync with the legacy
    // m_*Sym fields (write-through both directions) so the existing paint
    // loop reflects user edits without a per-feature symbolFor() refactor.
    std::vector<std::unique_ptr<OpenSWMM::Render::IFeatureRenderer>> m_kindRenderers;
 
    // Slice B.4 — RuleList mirroring the per-kind renderers. Lazy-built
    // on first ruleList() call (cloned from m_kindRenderers). mutable
    // so the const override can populate on first read.
    mutable std::unique_ptr<OpenSWMM::Render::RuleList> m_ruleList;
    void buildRuleListLazy() const;
    // M1 — set when a kind renderer changes after the RuleList was built, so
    // the next ruleList() rebuilds from the live per-kind renderers instead
    // of handing back a stale mirror (the "dialog doesn't match what's drawn
    // on open" bug). Rebuild happens only at read time (dialog open), never
    // mid-session, so an open dialog's rule pointers stay valid.
    mutable bool m_ruleListDirty = false;
 
    // M2 — keep the per-kind renderer (the single source of truth)
    // consistent when a legacy struct setter is called directly (e.g.
    // preferences / project load). Updates only SingleSymbol renderers (in
    // place — no signal, no recursion); classified renderers are left intact
    // since the struct is the single-symbol fallback. Marks the RuleList
    // dirty so the next dialog open reflects the change.
    void syncSingleRendererFromStruct(Category c, const SWMMElementSymbol &s);
 
    // Slice BI Phase 8.13.6.4 (2026-05-24) — per-feature colour-override
    // cache populated when a kind's renderer is Graduated / Categorized /
    // RuleBased. Indexed by Category × SoA index. The painter checks
    // m_kindUsesOverrides[c] to switch between the legacy bucketed fast
    // path and the per-feature override path.
    QVector<QColor>  m_kindFeatureColors[NumCategories];
    QVector<double>  m_kindFeatureSizes[NumCategories];   
    QVector<double>  m_kindFeatureOffsets[NumCategories]; 
    QVector<int>     m_kindFeatureShapes[NumCategories];  
    bool             m_kindHasAnyOffset[NumCategories]  = {}; 
    bool             m_kindUsesOverrides[NumCategories] = {};
 
    QStringList                  m_selectedNames;
    // Canonical typed selection (ordered). m_selectedNames and
    // m_selectedKindMask are derived mirrors, rebuilt atomically in
    // setSelectedElements().
    QVector<SelectedElement>     m_selectedElements;
 
    // Engine-table partition cache (curves vs. timeseries). The engine
    // stores both in the same unified table list keyed by type; without
    // this cache, the Object Browser data-category views and pickers
    // re-walked the entire table list on every row count / name lookup —
    // O(N) per call × N rows = O(N²) per refresh.  Filled lazily in
    // ensureTablePartition(); invalidated when a curve or timeseries is
    // added / removed / renamed, and on every modelLoaded().
    mutable QVector<int> m_curveTableIdx;
    mutable QVector<int> m_tsTableIdx;
    mutable bool         m_tablePartitionDirty = true;
    void ensureTablePartition() const;
 
public:
    void invalidateDataObjectCache() { m_tablePartitionDirty = true; }
 
private:
 
    // GDAL transform (layer CRS → canvas CRS)
    class OGRCoordinateTransformation *m_transform = nullptr;
 
    // Cached inverse (canvas CRS → layer CRS); built lazily on first
    // transformCanvasToLayer() call and invalidated whenever m_transform is
    // rebuilt or destroyed. Mutable so the public const accessor can populate.
    mutable class OGRCoordinateTransformation *m_inverseTransform = nullptr;
 
    // The (layer CRS, canvas CRS) pair m_transform was last built from, so
    // rebuildTransform() can no-op when nothing about the projection
    // changed. One srsChanged emission reaches this layer through two
    // independent listeners (see rebuildTransform), and each arrival
    // otherwise redoes rebuildSceneCoords over every node, link and
    // subcatchment vertex. WKT rather than the authority string because a
    // Local CRS has no authority code — precisely the case on the models
    // where the redundant rebuild costs the most.
    QString m_transformLayerWkt;
    QString m_transformCanvasWkt;
    bool    m_transformValid = false;
 
    // Dirty flag — skip scene rebuild when only the view extent changed
    bool                         m_needsRebuild = true;
 
    // KD-tree spatial index for point-feature queries (nodes + gages).
    // Mutable so const query methods (identifyAt, nodesInRect, …) can
    // trigger a lazy rebuild without breaking const-correctness.
    mutable bool                                 m_kdDirty = true;
    mutable std::unique_ptr<SWMMKdTrees>         m_kdTrees;
 
    // Batched scene renderer (created in populateScene). Edit paths that
    // mutate SoA coordinates call refreshBoundingRect() on it so the
    // scene's BSP index stays aligned after moves beyond the prior
    // extent. Cleared in depopulateScene.
    class SWMMLayerItem         *m_batchedItem = nullptr;
 
    // Slice BS Phase 6.9.2 — hydrograph MVC models, lazily constructed on
    // first accessor call. Owned by the layer (parented through the
    // QObject tree, destroyed with it). Shared across all consumer UIs.
    HydrographGroupListModel    *m_uhGroupListModel  = nullptr;
    HydrographRtkTableModel     *m_uhRtkModel        = nullptr;
    HydrographIaTableModel      *m_uhIaModel         = nullptr;
    HydrographDecayTableModel   *m_uhDecayModel      = nullptr;
 
    // Lazy-loaded data-object registries scoped to the current engine
    // handle. Forward-declared as `QObject*` to keep this header free of
    // the registry includes; the .cpp downcasts to the concrete type.
    // Shared across every UI that mutates these data objects so all
    // views see the same provider instances.
    QObject                     *m_tsRegistry                   = nullptr;
    void                        *m_tsRegistryEngineHandle       = nullptr;
    QObject                     *m_patternRegistry              = nullptr;
    void                        *m_patternRegistryEngineHandle  = nullptr;
    QObject                     *m_curveRegistry                = nullptr;
    void                        *m_curveRegistryEngineHandle    = nullptr;
 
    // Slice BR Phase 6.8.1 — control-rule registry mirror.
    QObject                     *m_controlRuleRegistry              = nullptr;
    void                        *m_controlRuleRegistryEngineHandle  = nullptr;
 
    // Slice BQ Phase 6.7.4 — transect registry mirror.
    QObject                     *m_transectRegistry                 = nullptr;
    void                        *m_transectRegistryEngineHandle     = nullptr;
 
    // Street registry mirror (parametric [STREETS] cross-sections).
    QObject                     *m_streetRegistry                   = nullptr;
    void                        *m_streetRegistryEngineHandle       = nullptr;
 
    // Pollutant registry mirror ([POLLUTANTS]).
    QObject                     *m_pollutantRegistry                = nullptr;
    void                        *m_pollutantRegistryEngineHandle    = nullptr;
 
    // Land-use registry mirror ([LANDUSES]).
    QObject                     *m_landUseRegistry                  = nullptr;
    void                        *m_landUseRegistryEngineHandle      = nullptr;
 
    // Aquifer registry mirror ([AQUIFERS]).
    QObject                     *m_aquiferRegistry                  = nullptr;
    void                        *m_aquiferRegistryEngineHandle      = nullptr;
 
    // Snowpack registry mirror ([SNOWPACKS]).
    QObject                     *m_snowpackRegistry                 = nullptr;
    void                        *m_snowpackRegistryEngineHandle     = nullptr;
 
    // Inlet registry mirror ([INLETS]).
    QObject                     *m_inletRegistry                    = nullptr;
    void                        *m_inletRegistryEngineHandle        = nullptr;
 
    // LID-control registry mirror ([LID_CONTROLS]).
    QObject                     *m_lidControlRegistry               = nullptr;
    void                        *m_lidControlRegistryEngineHandle   = nullptr;
 
    // User-flags store — see ensureUserFlagsModel().
    openswmmvis::ui::UserFlagsModel *m_userFlagsModel               = nullptr;
    void                        *m_userFlagsModelEngineHandle       = nullptr;
};
 
Q_DECLARE_METATYPE(SWMMModelLayer *)
Q_DECLARE_METATYPE(SWMMElementSymbol)
Q_DECLARE_OPERATORS_FOR_FLAGS(SWMMModelLayer::QsgKinds)
 
#endif // SWMMMODELLAYER_H