swmmresultslayer.h

Go to the documentation of this file.

 
#ifndef SWMMRESULTSLAYER_H
#define SWMMRESULTSLAYER_H
 
#include "layers/openswmmvislayer.h"
#include "layers/speciesattributes.h"
#include "layers/gisrasterlayer.h"   // RasterColorRamp
#include "layers/swmmmodellayer.h"
 
#include <openswmm/engine/openswmm_output.h>
 
#include <QBrush>
#include <QColor>
#include <QDateTime>
#include <QHash>
#include <QPen>
#include <QSet>
#include <QString>
#include <QVariantMap>
#include <QVector>
 
#include <memory>
 
class OpenSWMMVisWorkspace;
class SpatialReferenceSystem;
class QGraphicsItem;   // Slice §Y.2 — m_itemByFeature stores QGraphicsItem*
class QGraphicsSimpleTextItem;   // L-1 — m_labelByFeature stores label items
 
// Slice U-0 — granular per-Category sublayer mix. The legacy four
// sublayers (NodeMarker / ConduitLine / ConduitArrow / SubcatchmentFill)
// are replaced by one FeatureSublayer instance per SWMMModelLayer::Category
// (11 in total). Each instance owns its own archetype-appropriate
// style bag so every visual object type can be styled independently.
#include "render/iattributeprovider.h"   // Slice DM.1
#include "render/isublayerhost.h"
#include "render/sublayers/feature/featuresublayer.h"
 
namespace OpenSWMM::Render {
class IFeatureRenderer;
class RuleList;   // Slice B.5 — see ruleList() override below.
enum class ClassEditKind;   // Gap B1 — legend facade (full def in ifeaturerenderer.h)
}
 
enum class SWMMResultVariable
{
    // Node results
    NodeDepth           = 0,
    NodeHead            = 1,
    NodeVolume          = 2,
    NodeInflow          = 3,
    NodeOverflow        = 4,
    NodeLateralInflow   = 5,
    // Link results
    LinkFlow            = 10,
    LinkDepth           = 11,
    LinkVelocity        = 12,
    LinkCapacity        = 13,
    // Subcatchment results
    SubcatchRunoff      = 20,
    SubcatchInfiltration = 21,
    SubcatchEvaporation = 22,
    SubcatchSnowDepth   = 23,
};
 
class SWMMResultsLayer : public OpenSWMMVisLayer,
                         public OpenSWMM::Render::ISublayerHost,
                         public OpenSWMM::Render::IAttributeProvider  // Slice DM.1
{
    Q_OBJECT
    Q_INTERFACES(OpenSWMM::Render::IAttributeProvider)  // Slice DM.1
 
    Q_PROPERTY(QString   resultsFilePath  READ resultsFilePath   NOTIFY resultsFilePathChanged)
    Q_PROPERTY(QString   scenarioName     READ scenarioName      WRITE setScenarioName
               NOTIFY scenarioNameChanged)
    Q_PROPERTY(QColor    profileLineColor READ profileLineColor  WRITE setProfileLineColor
               NOTIFY profileLineColorChanged)
    Q_PROPERTY(QPen      profileHglLinePen      READ profileHglLinePen
               WRITE setProfileHglLinePen        NOTIFY profileStyleChanged)
    Q_PROPERTY(QBrush    profileHglFillBrush    READ profileHglFillBrush
               WRITE setProfileHglFillBrush      NOTIFY profileStyleChanged)
    Q_PROPERTY(QPen      profileEglLinePen      READ profileEglLinePen
               WRITE setProfileEglLinePen        NOTIFY profileStyleChanged)
    // EGL renders as a line only (no physically-meaningful fill above HGL).
    Q_PROPERTY(QPen      profileMaxHglLinePen   READ profileMaxHglLinePen
               WRITE setProfileMaxHglLinePen     NOTIFY profileStyleChanged)
    Q_PROPERTY(QBrush    profileMaxHglFillBrush READ profileMaxHglFillBrush
               WRITE setProfileMaxHglFillBrush   NOTIFY profileStyleChanged)
    Q_PROPERTY(QPen      profileMaxEglLinePen   READ profileMaxEglLinePen
               WRITE setProfileMaxEglLinePen     NOTIFY profileStyleChanged)
    Q_PROPERTY(int       currentTimeStep  READ currentTimeStep   WRITE setCurrentTimeStep
               NOTIFY currentTimeStepChanged)
    Q_PROPERTY(QDateTime currentDateTime  READ currentDateTime   NOTIFY currentDateTimeChanged)
    Q_PROPERTY(int       totalTimeSteps   READ totalTimeSteps    NOTIFY totalTimeStepsChanged)
    Q_PROPERTY(SWMMResultVariable variable READ variable         WRITE setVariable
               NOTIFY variableChanged)
    Q_PROPERTY(bool      showLegend       READ showLegend        WRITE setShowLegend
               NOTIFY showLegendChanged)
 
public:
 
    explicit SWMMResultsLayer(const QString &resultsFilePath,
                              class SWMMModelLayer *modelLayer,
                              OpenSWMMVisWorkspace *parent = nullptr);
 
    ~SWMMResultsLayer() override;
 
    [[nodiscard]] class SWMMModelLayer *modelLayer() const { return m_modelLayer; }
 
    // ----- Results file ---------------------------------------------------
 
    [[nodiscard]] QString resultsFilePath() const;
 
    [[nodiscard]] QString reportFilePath() const;
    void setReportFilePath(const QString &path);
 
    // ----- Self-description for the Layer Properties dialog ----------------
    [[nodiscard]] QString sourceDescription() const override;
    [[nodiscard]] QVector<QPair<QString, QString>> extendedMetadata() const override;
 
    [[nodiscard]] QString scenarioName() const;
    void setScenarioName(const QString &name);
 
    [[nodiscard]] QColor profileLineColor() const;
    void setProfileLineColor(const QColor &color);
 
    // -------------------------------------------------------------------
    // Per-source styling for Slice BC's profile plot.
    //
    // Each result layer (think "model run" or "scenario") carries its own
    // pen+brush for the four overlay layers — Current HGL, Current EGL,
    // Max HGL, Max EGL — so two layers plotted side by side can be styled
    // independently (e.g. baseline solid blue vs. proposed dashed red).
    //
    // Defaults are derived from profileLineColor() at construction.
    // setProfileLineColor() does NOT re-derive them: once the user
    // customises a pen, it stays put across colour changes.  Each setter
    // emits the matching changed() signal; the dialog uses that to
    // refresh its preview swatch.
    // -------------------------------------------------------------------
    [[nodiscard]] QPen   profileHglLinePen()      const;
    [[nodiscard]] QBrush profileHglFillBrush()    const;
    [[nodiscard]] QPen   profileEglLinePen()      const;
    [[nodiscard]] QPen   profileMaxHglLinePen()   const;
    [[nodiscard]] QBrush profileMaxHglFillBrush() const;
    [[nodiscard]] QPen   profileMaxEglLinePen()   const;
 
    void setProfileHglLinePen     (const QPen &pen);
    void setProfileHglFillBrush   (const QBrush &brush);
    void setProfileEglLinePen     (const QPen &pen);
    void setProfileMaxHglLinePen  (const QPen &pen);
    void setProfileMaxHglFillBrush(const QBrush &brush);
    void setProfileMaxEglLinePen  (const QPen &pen);
 
    void writeProfileStyle(class QSettings &settings) const;
 
    void readProfileStyle(class QSettings &settings);
 
    bool openResults(QList<QString> &warnings, QList<QString> &errors);
 
    void openResultsAsync();
 
    bool openResultsLive(QList<QString> &errors);
 
    int refreshLive();
 
    [[nodiscard]] bool isLive() const noexcept { return m_live; }
 
    void closeResults();
 
    // ----- Per-output node summary statistics (Slice QA.3 + QA-01) -------
    //
    // These four accessors return the same statistics the editing-engine
    // exposes via `swmm_node_get_stat_*`, but sourced from THIS output
    // file rather than the editing engine's ambient state. The node
    // attribute panel (Slice QA.2) dispatches to one of these when the
    // user picks a non-null "Stats source" from the combo, so multiple
    // loaded SWMMResultsLayers can be compared in the same panel.
    //
    // Backed by engine API QA-01 (`swmm_output_get_node_stat_*` in
    // openswmm_output.h), which aggregates the four flooding stats
    // on-demand from the .out file's per-period node results. The
    // aggregation runs at REPORT-step resolution — see the QA-01
    // header doc for the precision caveat when the routing step is
    // much finer than the report step.
    //
    // \p nodeName is the SWMM model-side identifier (e.g. "J1"); the
    // implementation resolves it to the output-side index via the
    // already-built nodeOutputIndex() map. Returns 0.0 for unknown
    // names or when the underlying file is closed.
    //
    // Each aggregator is one O(n_periods) walk of the .out file, so all
    // four are memoised per node index (see m_nodeStats / nodeStatsFor,
    // cleared by closeResults()) — same reason and same shape as the
    // link / subcatchment caches below.
    [[nodiscard]] double nodeStatMaxDepth(const QString &nodeName) const;
    [[nodiscard]] double nodeStatMaxOverflow(const QString &nodeName) const;
    [[nodiscard]] double nodeStatVolFlooded(const QString &nodeName) const;
    [[nodiscard]] double nodeStatTimeFlooded(const QString &nodeName) const;
 
    // ----- Per-output link / subcatchment summary statistics -------------
    //
    // Peers of the four node accessors above, for the dynamics columns the
    // Attribute Table shows for links and subcatchments. Unlike the node
    // stats there is no `swmm_output_get_*_stat_*` engine API for these, so
    // they are aggregated HERE by walking the .out file's per-period series
    // once per object. The result is cached per output index (see
    // m_linkStats / m_subcatchStats, cleared by closeResults()), as are the
    // node stats above.
    //
    // PRECISION CAVEAT — identical in kind to the QA-01 node aggregators:
    // the walk sees REPORT steps, not routing steps. Maxima are therefore
    // the largest REPORTED value (a peak between two report times is
    // missed), and the volume / duration integrals use the report step as
    // dt. Expect small disagreement with the .rpt summary tables when
    // REPORT_STEP is much coarser than ROUTING_STEP; they converge as the
    // two approach each other.
    //
    // Units match the editing-engine getters they stand in for: flow and
    // velocity in project flow / velocity units, filling dimensionless,
    // volumes in project volume units, durations in hours. Volume is the
    // one that needs work — the .out file stores a RATE in the file's own
    // flow units, so the integral goes through Qcf/Ucf (see the .cpp).
    //
    // The three pump statistics reconstruct too, from a combination that is
    // not obvious: the engine's on/off test is `setting > 0 && flow > 0`, and
    // the .out file carries BOTH — flow directly, and `setting` as the
    // CAPACITY variable, which for every non-conduit link is the pump speed /
    // regulator opening rather than a fill ratio (legacy link.c). See the
    // extra accuracy note on linkStatPumpCycles.
    [[nodiscard]] double linkStatMaxFlow(const QString &linkName) const;
    [[nodiscard]] double linkStatMaxVelocity(const QString &linkName) const;
    [[nodiscard]] double linkStatMaxFilling(const QString &linkName) const;
    [[nodiscard]] double linkStatVolFlow(const QString &linkName) const;
    [[nodiscard]] double linkStatSurchargeTime(const QString &linkName) const;
 
    [[nodiscard]] double linkStatPumpCycles(const QString &linkName) const;
    [[nodiscard]] double linkStatPumpOnTime(const QString &linkName) const;
    [[nodiscard]] double linkStatPumpVolume(const QString &linkName) const;
 
    [[nodiscard]] double subcatchStatPrecip(const QString &subName) const;
    [[nodiscard]] double subcatchStatRunoffVol(const QString &subName) const;
    [[nodiscard]] double subcatchStatMaxRunoff(const QString &subName) const;
 
    // ----- Animation ------------------------------------------------------
 
    [[nodiscard]] int       currentTimeStep()  const;
    [[nodiscard]] QDateTime currentDateTime()  const;
    [[nodiscard]] int       totalTimeSteps()   const;
    [[nodiscard]] QDateTime startDateTime()    const;
    [[nodiscard]] QDateTime endDateTime()      const;
    // 2026-07-19 — reported data origin (slider range fix). startDateTime()
    // is the SIMULATION start (`swmm_output_get_start_date`), but the first
    // data frame lives at period 0's report time = reportStart + reportStep.
    // Anchoring the animation range / period grid on the simulation start
    // produced a dead zone at the left of the global slider whenever
    // REPORT_START != START_DATE (and an off-by-one in
    // periodIndexForDateTime). Falls back to startDateTime() when period 0's
    // time is unavailable.
    [[nodiscard]] QDateTime reportedStartDateTime() const;
    [[nodiscard]] int       reportStepSeconds() const;
 
    void setCurrentTimeStep(int step);
 
    [[nodiscard]] int periodIndexForDateTime(const QDateTime &dt) const;
 
    [[nodiscard]] int periodIndexForDateTimeAsOf(const QDateTime &dt) const;
 
    void stepForward(bool loop = false);
 
    void stepBackward(bool loop = false);
 
    // ----- Variable & colour mapping --------------------------------------
 
    [[nodiscard]] SWMMResultVariable variable() const;
    void setVariable(SWMMResultVariable var);
 
    [[nodiscard]] RasterColorRamp colorRamp() const;
    void setColorRamp(const RasterColorRamp &ramp);
 
    void autoStretchColorRamp();
 
    // ----- Renderer (Slice BI Phase 8.13.6.3) -----------------------------
    // The renderer is the §J.2 seam every future paint path will go through.
    // In sub-phase 8.13.6.3 this is API plumbing only — the existing paint
    // loop still reads m_colorRamp / m_variable directly. Sub-phase 8.13.6.4
    // will swap the paint loop to consult m_renderer instead, after which
    // m_colorRamp / m_variable become private implementation details of the
    // default GraduatedRenderer.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *renderer() const;
 
    void setRenderer(std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r);
 
    // ----- Per-kind renderers (Slice OUT.1) -------------------------------
    // Mirrors SWMMModelLayer's per-kind renderer slots so the user can
    // style Junctions vs Outfalls (etc.) independently for the same
    // NodeDepth/LinkFlow variable. The layer-level renderer() above stays
    // as the fallback when no kind-renderer is installed.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *kindRenderer(
        SWMMModelLayer::Category c) const;
 
    void setKindRenderer(SWMMModelLayer::Category c,
                         std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r);
 
    void resetKindRendererToDefaults(SWMMModelLayer::Category c);
 
    [[nodiscard]] bool kindRendererIsDefault(SWMMModelLayer::Category c) const;
 
    void refreshRuleMirror(SWMMModelLayer::Category c);
 
    // ----- Gap B1 — legend-as-editor facade (mirrors SWMMModelLayer) -----
    //
    // The legend views read rows through legendSymbolItems() and route
    // per-class edits through the facade below. Class keys are
    // kind-qualified ("<kindKey>\x1F<innerKey>") so edits land on the
    // right kind renderer even when two kinds share inner keys.
 
    [[nodiscard]] QList<OpenSWMM::Render::LegendSymbolItem> legendSymbolItems();
    [[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;
 
    // ----- Rule Model (Slice B.5, Phase B) --------------------------------
    //
    // Mirrors SWMMModelLayer::ruleList() — 11 kindRenderer slots → 11
    // Rules, lazy-built on first access. Each Rule owns a clone of the
    // matching kindRenderer; Rule-side swaps propagate back via
    // setKindRenderer. Same one-way sync caveat as B.4 — external
    // setKindRenderer calls don't refresh the in-memory RuleList.
    [[nodiscard]] OpenSWMM::Render::RuleList *ruleList() override;
    [[nodiscard]] const OpenSWMM::Render::RuleList *ruleList() const override;
 
    // ----- IAttributeProvider (Slice DM.1) --------------------------------
    //
    // Returns the engine output codes available for the given category.
    // All entries are isDynamic=true (per-frame values). 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;
 
    [[nodiscard]] QStringList speciesNames() const;
 
    // ----- Legend ---------------------------------------------------------
 
    [[nodiscard]] bool showLegend() const;
    void setShowLegend(bool show);
 
    // ----- Bulk output access (Slice BC) ----------------------------------
 
    [[nodiscard]] SWMM_Output outputHandle() const;
 
    [[nodiscard]] int nodeOutputIndex(const QString &name) const;
 
    [[nodiscard]] int linkOutputIndex(const QString &name) const;
 
    [[nodiscard]] int subcatchOutputIndex(const QString &name) const;
 
    [[nodiscard]] int flowUnits() const;
 
    // ----- OpenSWMMVisLayer interface -----------------------------------------
 
    void populateScene(QGraphicsScene *scene,
                       const MapExtent &canvasExtent,
                       const SpatialReferenceSystem *canvasSRS) override;
 
    void depopulateScene(QGraphicsScene *scene) override;
 
    void setLabelConfig(const OpenSWMM::Render::LabelConfig &cfg) override;
 
    void onCanvasCRSChanged(const SpatialReferenceSystem *newCanvasSRS) override;
 
    // ----- ISublayerHost interface (Slice U-0) ------------------------------
    //
    // Returns the granular per-Category sublayer mix (paint order = list
    // order, bottom-up). Order matches SWMMModelLayer::Category but groups
    // by archetype so polygon fills paint first, then lines, then point
    // markers, then rain gages on top:
    //
    //   [0]  Subcatchments        (FillKind,    polygon archetype, dynamic)
    //   [1]  Conduits             (LineKind,    line archetype,    dynamic)
    //   [2]  Pumps                (LineKind,    line archetype,    dynamic)
    //   [3]  Orifices             (LineKind,    line archetype,    dynamic)
    //   [4]  Weirs                (LineKind,    line archetype,    dynamic)
    //   [5]  Outlets              (LineKind,    line archetype,    dynamic)
    //   [6]  Junctions            (MarkerKind,  point archetype,   dynamic)
    //   [7]  Outfalls             (MarkerKind,  point archetype,   dynamic)
    //   [8]  Storage              (MarkerKind,  point archetype,   dynamic)
    //   [9]  Dividers             (MarkerKind,  point archetype,   dynamic)
    //   [10] RainGages            (MarkerKind,  point archetype,   static)
    //
    // The sublayer instances are owned by this layer via QObject parent-
    // child.
    [[nodiscard]] QList<OpenSWMM::Render::ISublayer *> sublayers() const override;
 
    // 2026-07-19 — animation-tick fast path (slider scrub perf). The base
    // ISublayerHost::dispatchAnimationTick() invalidates every dynamic
    // sublayer; in this layer each ISublayer::invalidated fires the
    // wireRefresh lambda, which re-runs fetchResultsForStep() PER SUBLAYER
    // and escalates SceneDirty::Structural — turning the intended cheap
    // Values-only restyle into ~8 redundant .out fetches plus a full
    // populateScene rebuild on every tick. Animation ticks change only
    // per-feature values, never the item set, so this override routes
    // through setCurrentTimeStep()'s Values path and never touches the
    // sublayer-invalidation (Structural) machinery. wireRefresh keeps its
    // Structural escalation for its real purpose: visibility / style /
    // attribute edits.
    void dispatchAnimationTick(int period) override;
 
    bool moveSublayer(int from, int to) override;
 
    [[nodiscard]] OpenSWMM::Render::FeatureSublayer *
        featureSublayer(SWMMModelLayer::Category c) const;
 
    [[nodiscard]] QList<OpenSWMM::Render::LegendSymbolItem>
        sublayerLegendItems();
 
    [[nodiscard]] std::vector<std::unique_ptr<openswmmvis::ui::ILayerStyleSubject>>
        styleSubjects() override;
 
signals:
    void resultsFilePathChanged(const QString &path);
    void scenarioNameChanged(const QString &name);
    void profileLineColorChanged(const QColor &color);
    void profileStyleChanged();   
    void currentTimeStepChanged(int step);
    void currentDateTimeChanged(const QDateTime &dt);
    void totalTimeStepsChanged(int count);
    void periodsAppended(int firstNew, int count);
    void resultsFinalized();
    void variableChanged(SWMMResultVariable var);
    void showLegendChanged(bool show);
    void resultsOpened();
    void resultsError(const QString &message);
    void resultsOpenFinished(bool ok);
    void rendererChanged();
 
public:
    void refreshScene(QGraphicsScene *scene,
                      const MapExtent &canvasExtent,
                      const SpatialReferenceSystem *canvasSRS) override;
 
private:
    OpenSWMMVis::Species::SpeciesMissWarner m_speciesMissWarner;
 
    bool finishOpen(qint64 msOpen, QList<QString> &warnings, QList<QString> &errors);
 
    void fetchResultsForStep(int step);
    void buildOutputIdMaps();
 
    void restyleScene(QGraphicsScene *scene);
 
    void refreshLabels(QGraphicsScene *scene);
    void clearLabels();
 
    bool requiresStructuralRebuildForRestyle() const;
 
    // Phase 7 (2026-05-25) — lazy attribute-range samplers. Walk every
    // period of (kind, outCode) once; cache the (min, max) result. Cleared
    // on closeResults. Used by populateScene to build a local
    // RasterColorRamp whose range is data-derived rather than the
    // hardcoded [0, 1] of the layer's m_colorRamp. Returns {0,1} on
    // sampling failure so paint still has a defined ramp.
    QPair<double, double> ensureNodeAttributeRange(int outCode);
    QPair<double, double> ensureLinkAttributeRange(int outCode);
    QPair<double, double> ensureSubcatchAttributeRange(int outCode);
 
    // Engine output handle ------------------------------------------------
    SWMM_Output          m_handle         = nullptr;
 
    // File & scenario metadata --------------------------------------------
    QString              m_resultsFilePath;
    QString              m_reportFilePath;   
    QString              m_scenarioName;
    QColor               m_profileLineColor;
    int                  m_reportStepSec  = 0;
 
    // Per-source profile styling -----------------------------------------
    // Initialised from m_profileLineColor at construction; independently
    // editable thereafter (color changes do NOT clobber them).
    QPen                 m_profileHglLinePen;
    QBrush               m_profileHglFillBrush;
    QPen                 m_profileEglLinePen;
    QPen                 m_profileMaxHglLinePen;
    QBrush               m_profileMaxHglFillBrush;
    QPen                 m_profileMaxEglLinePen;
 
    // Model layer (non-owning) --------------------------------------------
    class SWMMModelLayer *m_modelLayer    = nullptr;
 
    // Animation state -----------------------------------------------------
    int                  m_currentStep    = 0;
    int                  m_totalSteps     = 0;
    bool                 m_live           = false;   
    QDateTime            m_startDateTime;
    QDateTime            m_endDateTime;
    // 2026-07-19 — period 0's report time; see reportedStartDateTime().
    QDateTime            m_reportedStartDateTime;
 
    // Variable & colour mapping -------------------------------------------
    SWMMResultVariable   m_variable       = SWMMResultVariable::NodeDepth;
    RasterColorRamp      m_colorRamp;
    bool                 m_showLegend     = true;
 
    // Slice BI Phase 8.13.6.3 — renderer plumbing. Initialised eagerly in
    // the ctor (default GraduatedRenderer) so renderer() never returns null.
    // The existing paint loop still reads m_colorRamp / m_variable; 8.13.6.4
    // refactors that to consult m_renderer instead.
    std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> m_renderer;
 
    // Slice OUT.1 — per-kind renderer slots. Indexed by
    // SWMMModelLayer::Category ordinal; slots default to nullptr (no
    // override) so paint can fall back to m_renderer. Slice OUT.2 hooks
    // the per-feature override cache into these and refactors the paint
    // loop in populateScene() to consult them.
    std::vector<std::unique_ptr<OpenSWMM::Render::IFeatureRenderer>> m_kindRenderers;
 
    // Slice B.5 — RuleList mirroring m_kindRenderers (lazy-built).
    mutable std::unique_ptr<OpenSWMM::Render::RuleList> m_ruleList;
    bool m_ruleKindSyncGuard = false;
    void buildRuleListLazy() const;
 
    // Slice Z.7a — per-frame rebinning for Rules with rebinPerFrame=true.
    // Connected to currentTimeStepChanged in buildRuleListLazy.
    void rebinDynamicRulesIfNeeded();
 
    // Slice OUT.2 — per-feature override cache. Sized to category row
    // count at rebuild time. Read by populateScene's paint loop in
    // preference to m_colorRamp.colorForValue(). Rebuilt whenever
    // result values change (setVariable / setCurrentTimeStep /
    // animation tick) OR when setKindRenderer() swaps a slot.
    QVector<QColor>  m_kindFeatureColors[SWMMModelLayer::NumCategories];
    QVector<double>  m_kindFeatureSizes [SWMMModelLayer::NumCategories]; 
    QVector<double>  m_kindFeatureWidths[SWMMModelLayer::NumCategories]; 
    QVector<int>     m_kindFeatureShapes[SWMMModelLayer::NumCategories]; 
    QVector<int>     m_kindFeatureDashes[SWMMModelLayer::NumCategories]; 
    bool             m_kindUsesOverrides[SWMMModelLayer::NumCategories] = {};
 
    // Slice X.21 — categorized-renderer string-attribute cache.  Keyed
    // by "<categoryOrdinal>/<classifyAttribute>" → per-row string
    // value pulled from m_modelLayer->identifyByName(...).  Identity-
    // by-name is a hot lookup that touches every cached node / link /
    // subcatch entry, so re-fetching it every animation tick is
    // wasteful — the source data is topology-invariant.  Flat string
    // key avoids the QHash<QPair<int,QString>, …> requirement of an
    // explicit qHash overload.
    mutable QHash<QString, QVector<QString>> m_categoricalAttrCache;
 
    void rebuildKindFeatureOverrides(SWMMModelLayer::Category c);
 
    void rebuildAllActiveKindFeatureOverrides();
 
    void reclassifyKindsForResolvedRange(int scope, int outCode);
 
    // Per-step result caches (fetched from .out each time step changes) ----
    QVector<float>       m_nodeResults;     
    QVector<float>       m_linkResults;     
    QVector<float>       m_subcatchResults; 
    // Phase 2 (2026-05-25) — concurrent multi-attribute paint. Each visible
    // sublayer carries its own `style.attribute` Q_PROPERTY; per period,
    // fetchResultsForStep populates a vector per (kind, varCode) pair that
    // any visible sublayer needs. populateScene reads from these maps using
    // the sublayer's attribute. The legacy m_nodeResults/m_linkResults/
    // m_subcatchResults remain populated (for the active m_variable) so
    // existing callers continue to work unchanged.
    QHash<int, QVector<float>>  m_nodeResultsByVar;
    QHash<int, QVector<float>>  m_linkResultsByVar;
    QHash<int, QVector<float>>  m_subcatchResultsByVar;
 
    // Phase 7 (2026-05-25) — per-attribute observed range, computed by
    // sampling EVERY period of a variable when first needed. Replaces the
    // hardcoded [0, 1] m_colorRamp range so values aren't clamped at one
    // end of the ramp. Cleared on closeResults / openResults; lazily
    // populated by ensure*AttributeRange() helpers in the cpp.
    QHash<int, QPair<double, double>>  m_nodeAttributeRange;
    QHash<int, QPair<double, double>>  m_linkAttributeRange;
    QHash<int, QPair<double, double>>  m_subcatchAttributeRange;
 
    // Per-attribute scan in-flight markers. A request from the paint path
    // (ensure*AttributeRange) returns a placeholder range immediately,
    // queues a background QtConcurrent scan of every period, and on
    // completion the result is inserted into the matching cache and a
    // repaintRequested() is emitted from the layer thread.
    QSet<int>  m_nodeRangePending;
    QSet<int>  m_linkRangePending;
    QSet<int>  m_subcatchRangePending;
 
    // Name → output-file index maps (built once on openResults) -----------
    QHash<QString, int>  m_nodeOutputIdx;
    QHash<QString, int>  m_linkOutputIdx;
    QHash<QString, int>  m_subcatchOutputIdx;
 
    // Aggregated per-object summary statistics, keyed by OUTPUT index and
    // filled lazily by linkStatsFor() / subcatchStatsFor(). Each miss costs
    // one series read per contributing variable over the whole run, so the
    // cache is what keeps an Attribute Table scroll from re-walking the
    // .out file for every painted cell. Mutable so the const accessors can
    // populate it; cleared by closeResults().
    struct LinkStats {
        double maxFlow = 0.0, maxVelocity = 0.0, maxFilling = 0.0;
        double volFlow = 0.0, surchargeTimeHr = 0.0;
        // Pumps only; left at zero for every other link type.
        double pumpCycles = 0.0, pumpOnTimeHr = 0.0, pumpVolume = 0.0;
    };
    struct SubcatchStats {
        double precipVol = 0.0, runoffVol = 0.0, maxRunoff = 0.0;
    };
    // Nodes get the same treatment. Their four values come from engine
    // aggregators rather than being computed here, but each of those is
    // still one O(n_periods) walk of the .out file — a seek plus a 4-byte
    // read per period — so uncached they cost four whole-file walks per
    // painted row, per repaint.
    struct NodeStats {
        double maxDepth = 0.0, maxOverflow = 0.0;
        double volFlooded = 0.0;
        double timeFloodedHr = 0.0;
    };
    mutable QHash<int, LinkStats>     m_linkStats;
    mutable QHash<int, SubcatchStats> m_subcatchStats;
    mutable QHash<int, NodeStats>     m_nodeStats;
 
    [[nodiscard]] LinkStats     linkStatsFor(int outIdx) const;
    [[nodiscard]] SubcatchStats subcatchStatsFor(int outIdx) const;
    [[nodiscard]] NodeStats     nodeStatsFor(int outIdx) const;
 
    // GDAL coordinate transform -------------------------------------------
    class OGRCoordinateTransformation *m_transform = nullptr;
 
    // Granular per-Category sublayer storage (Slice U-0) -------------------
    // One FeatureSublayer per SWMMModelLayer::Category. Indexed by the
    // category ordinal; size = SWMMModelLayer::NumCategories. Constructed
    // in the ctor with `this` as QObject parent (no manual delete). The
    // sublayers() return-list orders them by archetype (polygon → line →
    // point) so paint order looks correct out of the box.
    OpenSWMM::Render::FeatureSublayer *m_featureSublayers[SWMMModelLayer::NumCategories] = {};
 
    // User-customisable sublayer paint order (Slice GUI-2026-05-30 §2).
    // Populated lazily on first sublayers() / moveSublayer() call from the
    // archetype-default sequence (polygon → line → marker).  Reordered via
    // moveSublayer(); persisted by ISublayerHost::saveSublayersToJson and
    // restored by loadSublayersFromJson on .oswp load.
    mutable QList<OpenSWMM::Render::ISublayer *> m_sublayerOrder;
 
    // Slice §Y.2 — incremental scene refresh state.
    //
    // m_sceneDirty drives refreshScene's branch.  Structural forces the
    // legacy depopulate + populate path (every QGraphicsItem destroyed and
    // re-allocated).  Values reuses the cached items and only mutates
    // brush / pen.  Clean returns immediately.  The default is Structural
    // so the first paint after construction (or after a results file
    // open) still produces a full scene.
    enum class SceneDirty : int { Clean = 0, Values = 1, Structural = 2 };
    SceneDirty m_sceneDirty { SceneDirty::Structural };
 
    // Per-Category item cache.  populateScene records the primary
    // QGraphicsItem for every feature row into the matching slot; null
    // entries are valid (NaN values / missing geometry / filtered rows).
    // restyleScene walks the slots and applies setBrush / setPen in place.
    // depopulateScene clears the slots.  Sizing tracks the model's
    // categoryCount at population time; restyleScene falls back to
    // structural when the size mismatches the current count (mid-session
    // topology edit).
    QVector<QGraphicsItem *> m_itemByFeature[SWMMModelLayer::NumCategories];
 
    // L-1 — parallel per-feature label items ("name: value"). Same sizing /
    // lifecycle contract as m_itemByFeature: built/refreshed by refreshLabels,
    // cleared by depopulateScene (base destroys the tagged scene items).
    QVector<QGraphicsSimpleTextItem *> m_labelByFeature[SWMMModelLayer::NumCategories];
 
    void escalateSceneDirty(SceneDirty next);
};
 
Q_DECLARE_METATYPE(SWMMResultsLayer *)
Q_DECLARE_METATYPE(SWMMResultVariable)
 
#endif // SWMMRESULTSLAYER_H