swmm2dresultslayer.h

Go to the documentation of this file.

 
#ifndef OPENSWMMVIS_LAYERS_SWMM2DRESULTSLAYER_H
#define OPENSWMMVIS_LAYERS_SWMM2DRESULTSLAYER_H
 
#include "io/mesh2dh5reader.h"       // openswmmvis::io::CoordinateReference
#include "layers/openswmmvislayer.h"
#include "layers/meshspatialgrid.h"
#include "layers/vertexdepthreconstruct.h"   // VertexDepthReconstruct::CellSplit
#include "map/mapextent.h"
 
#include <ogr_spatialref.h>          // OGRCoordinateTransformation (issue #155)
 
#include <QDateTime>
#include <QLineF>
#include <QPointF>
#include <QPolygonF>
#include <QRectF>
#include <QSet>
#include <QTimer>
#include <QString>
#include <QVector>
 
#include <array>
#include <memory>
#include <vector>
 
class QGraphicsScene;
class QGraphicsItem;
class SWMM2DResultsGraphicsItem;
class SWMM2DVelocityArrowsItem;
 
namespace openswmmvis::io { class Mesh2DH5Reader; }
namespace OpenSWMM::Render {
class IFeatureRenderer;
class RuleList;   // Slice B.5b — see ruleList() override below.
}
 
// Slice S5.6 (RENDERING_OUTPUT_SUBLAYERS_PLAN.md) — 2D sublayer foundation.
#include "render/iattributeprovider.h"   // Slice DM.3
#include "render/isublayerhost.h"
#include "render/legendsymbolitem.h"
#include "render/sublayers/contourbandsublayer.h"
#include "render/sublayers/isolinesublayer.h"
#include "render/sublayers/meshedgesublayer.h"
#include "render/sublayers/meshfillsublayer.h"
#include "render/sublayers/meshnodesublayer.h"
#include "render/sublayers/scalarfillsublayer.h"
#include "render/sublayers/velocityvectorsublayer.h"
 
// ---------------------------------------------------------------------------
// IMesh2DSource — data-source abstraction shared by live + replay modes
// ---------------------------------------------------------------------------
 
class IMesh2DSource
{
public:
    virtual ~IMesh2DSource() = default;
 
    virtual int vertexCount()   const = 0;
    virtual int triangleCount() const = 0;
 
    virtual int timeCount() const = 0;
 
    virtual bool isLive() const { return false; }
 
    virtual bool readMeshGeometry(std::vector<double>& vx,
                                   std::vector<double>& vy,
                                   std::vector<double>& vz,
                                   std::vector<std::array<int, 3>>& tris) = 0;
 
    virtual bool readCells(std::vector<double>& vx,
                           std::vector<double>& vy,
                           std::vector<double>& vz,
                           std::vector<std::array<int, 4>>& cells)
    {
        std::vector<std::array<int, 3>> tris;
        if (!readMeshGeometry(vx, vy, vz, tris)) return false;
        cells.resize(tris.size());
        for (size_t i = 0; i < tris.size(); ++i)
            cells[i] = { tris[i][0], tris[i][1], tris[i][2], -1 };
        return true;
    }
 
    virtual openswmmvis::io::CoordinateReference coordinateReference() const
    {
        return {};
    }
 
    virtual bool readDepthsAt(int timeIdx, std::vector<float>& depths) = 0;
 
    virtual bool readDepthAt(int timeIdx, int cell, float& out)
    {
        std::vector<float> row;
        if (!readDepthsAt(timeIdx, row) || cell < 0 || cell >= static_cast<int>(row.size()))
            return false;
        out = row[static_cast<size_t>(cell)];
        return true;
    }
 
    virtual int historyGeneration() const { return 0; }
 
    virtual QDateTime simTimeAt(int timeIdx) const { (void)timeIdx; return {}; }
 
    virtual bool readEdgeFluxAt(int timeIdx, std::vector<float>& flux)
    {
        (void)timeIdx; (void)flux;
        return false;
    }
 
    virtual bool readEdgeGeometry(std::vector<float>& length,
                                  std::vector<float>& nx,
                                  std::vector<float>& ny)
    {
        (void)length; (void)nx; (void)ny;
        return false;
    }
 
    virtual bool readVertexDepthsAt(int timeIdx, std::vector<float>& vdepths)
    {
        (void)timeIdx; (void)vdepths;
        return false;
    }
 
    virtual bool hasFaceField(const char* dataset) const
    {
        (void)dataset;
        return false;
    }
 
    virtual bool readFaceFieldAt(const char* dataset, int timeIdx,
                                 std::vector<float>& values)
    {
        (void)dataset; (void)timeIdx; (void)values;
        return false;
    }
 
    virtual bool readFaceEnvelope(const char* dataset, std::vector<float>& values)
    {
        (void)dataset; (void)values;
        return false;
    }
};
 
// ---------------------------------------------------------------------------
// EngineMesh2DSource — live source driven by SimulationRunner ticks
// ---------------------------------------------------------------------------
 
class EngineMesh2DSource : public IMesh2DSource
{
public:
    EngineMesh2DSource(std::vector<double>            vx,
                       std::vector<double>            vy,
                       std::vector<double>            vz,
                       std::vector<std::array<int,3>> tris);
 
    EngineMesh2DSource(std::vector<double>            vx,
                       std::vector<double>            vy,
                       std::vector<double>            vz,
                       std::vector<std::array<int,4>> cells);
 
    void pushDepths(std::vector<float> depths,
                    QDateTime simTime,
                    double elapsedSec);
 
    void pushFlux(std::vector<float> flux,
                  QDateTime simTime,
                  double elapsedSec);
 
    void pushVertexSignedDepths(std::vector<double> depths,
                                QDateTime simTime,
                                double elapsedSec);
 
    void pushRainfall(std::vector<float> rainfall,
                      std::vector<float> rainCum,
                      QDateTime simTime,
                      double elapsedSec);
 
    void pushHeads(std::vector<float> heads,
                   QDateTime simTime,
                   double elapsedSec);
 
    void setEnvelopes(std::vector<float> maxDepth, std::vector<float> maxVel);
 
    void   setDryDepth(double m) { dry_depth_ = m; }
    double dryDepth() const noexcept { return dry_depth_; }
 
    void setHistoryPinned(bool pinned);
    bool historyPinned() const noexcept { return pinned_; }
 
    void setEdgeGeometry(std::vector<float> length,
                         std::vector<float> nx,
                         std::vector<float> ny);
 
    // IMesh2DSource
    int  vertexCount()   const override { return static_cast<int>(vx_.size()); }
    int  triangleCount() const override { return static_cast<int>(cells_.size()); }
    int  timeCount()     const override { return static_cast<int>(history_.size()); }
    bool isLive()        const override { return !finished_; } // streaming from the running sim
 
    void markFinished() { finished_ = true; }
    bool readDepthAt(int timeIdx, int cell, float& out) override;
    int  historyGeneration() const override { return generation_; }
 
    void setMaxFrames(int n) { max_frames_ = n; enforceCap_(); }
    int  maxFrames() const noexcept { return max_frames_; }
 
    void   setMaxBytes(size_t bytes) { max_bytes_ = bytes; enforceCap_(); }
    size_t maxBytes() const noexcept { return max_bytes_; }
    size_t historyBytes() const;
    bool readMeshGeometry(std::vector<double>& vx,
                          std::vector<double>& vy,
                          std::vector<double>& vz,
                          std::vector<std::array<int, 3>>& tris) override;
    bool readCells(std::vector<double>& vx,
                   std::vector<double>& vy,
                   std::vector<double>& vz,
                   std::vector<std::array<int, 4>>& cells) override;
    bool readDepthsAt(int timeIdx, std::vector<float>& depths) override;
    QDateTime simTimeAt(int timeIdx) const override;
 
    bool readEdgeFluxAt(int timeIdx, std::vector<float>& flux) override;
    bool readEdgeGeometry(std::vector<float>& length,
                          std::vector<float>& nx,
                          std::vector<float>& ny) override;
    bool readVertexDepthsAt(int timeIdx, std::vector<float>& vdepths) override;
    bool hasFaceField(const char* dataset) const override;
    bool readFaceFieldAt(const char* dataset, int timeIdx,
                         std::vector<float>& values) override;
    bool readFaceEnvelope(const char* dataset, std::vector<float>& values) override;
 
private:
    std::vector<float> toEdgeSlots_(std::vector<float> a) const;
 
    std::vector<double>              vx_, vy_, vz_;
    std::vector<std::array<int,4>>   cells_;   
 
    struct Tick {
        std::vector<float> depths;
        std::vector<float> flux;       
        std::vector<float> vertex_depths; 
        std::vector<float> rainfall;   
        std::vector<float> rain_cum;   
        std::vector<float> heads;      
        QDateTime          sim_time;
        double             elapsed_sec = 0.0;
    };
    std::vector<Tick> history_;
    bool              has_rainfall_ = false;   
    bool              has_heads_    = false;   
    bool              has_flux_     = false;   
    std::vector<float> env_max_depth_;         
    std::vector<float> env_max_vel_;
    double            dry_depth_    = 1e-4;    
    int               max_frames_   = 2000;    
    size_t            max_bytes_    = 0;       
    int               generation_   = 0;       
    bool              finished_     = false;   
    bool              pinned_       = false;   
    void enforceCap_();
    bool reconstructVelocity_(int timeIdx, std::vector<float>& vx,
                              std::vector<float>& vy) const;
 
    // Time-invariant edge geometry; populated once at twoDInitialized via
    // setEdgeGeometry. Empty when the engine lacks the bulk geometry API.
    std::vector<float> edge_length_;
    std::vector<float> edge_nx_;
    std::vector<float> edge_ny_;
};
 
// ---------------------------------------------------------------------------
// HDF5Mesh2DSource — post-run source backed by Mesh2DH5Reader
// ---------------------------------------------------------------------------
 
class HDF5Mesh2DSource : public IMesh2DSource
{
public:
    HDF5Mesh2DSource();
    ~HDF5Mesh2DSource() override;
 
    bool open(const QString& path);
    const QString& path() const noexcept { return path_; }
 
    // IMesh2DSource
    int  vertexCount()   const override;
    int  triangleCount() const override;
    int  timeCount()     const override;
    bool readMeshGeometry(std::vector<double>& vx,
                          std::vector<double>& vy,
                          std::vector<double>& vz,
                          std::vector<std::array<int, 3>>& tris) override;
    bool readCells(std::vector<double>& vx,
                   std::vector<double>& vy,
                   std::vector<double>& vz,
                   std::vector<std::array<int, 4>>& cells) override;
    bool readDepthsAt(int timeIdx, std::vector<float>& depths) override;
    QDateTime simTimeAt(int timeIdx) const override;
 
    bool readEdgeFluxAt(int timeIdx, std::vector<float>& flux) override;
    bool readEdgeGeometry(std::vector<float>& length,
                          std::vector<float>& nx,
                          std::vector<float>& ny) override;
    bool readVertexDepthsAt(int timeIdx, std::vector<float>& vdepths) override;
    bool hasFaceField(const char* dataset) const override;
    bool readFaceFieldAt(const char* dataset, int timeIdx,
                         std::vector<float>& values) override;
    bool readFaceEnvelope(const char* dataset, std::vector<float>& values) override;
    openswmmvis::io::CoordinateReference coordinateReference() const override;
 
    void setSimulationStart(QDateTime t) { sim_start_ = t; }
 
private:
    QString                                            path_;
    std::unique_ptr<openswmmvis::io::Mesh2DH5Reader>   reader_;
    QDateTime                                          sim_start_;
    std::vector<float>                                 depth_buf_;     
};
 
// ---------------------------------------------------------------------------
// SWMM2DResultsLayer
// ---------------------------------------------------------------------------
 
class SWMM2DResultsLayer : public OpenSWMMVisLayer,
                            public OpenSWMM::Render::ISublayerHost,
                            public OpenSWMM::Render::IAttributeProvider  // Slice DM.3
{
    Q_OBJECT
    Q_INTERFACES(OpenSWMM::Render::IAttributeProvider)  // Slice DM.3
public:
    // Slice DM.3 — exposes depth / head / velocity-magnitude / velocity-
    // x / velocity-y so renderer panels can theme the heatmap and
    // contour rules by the right variable. All entries are dynamic.
    // 2D results have no SWMM category concept; we ignore the cat
    // argument and always return the mesh-scope field set.
    [[nodiscard]] QVector<OpenSWMM::Render::AttributeField>
        availableAttributes(OpenSWMMVis::SwmmCategory cat) const override;
    explicit SWMM2DResultsLayer(const QString& name = QStringLiteral("2D Results"),
                                 OpenSWMMVisWorkspace* parent = nullptr);
    ~SWMM2DResultsLayer() override;
 
    void setSource(std::unique_ptr<IMesh2DSource> source);
 
    IMesh2DSource* source() noexcept { return source_.get(); }
    const IMesh2DSource* source() const noexcept { return source_.get(); }
 
    void setFallbackCoordinateScale(double metresPerModelUnit);
 
    int currentTimeIndex() const noexcept { return current_time_idx_; }
    void setCurrentTimeIndex(int t);
 
    void refreshCurrentFrame();
 
    void refreshTimeRange();
 
    void setFollowLive(bool on) noexcept { follow_live_ = on; }
    [[nodiscard]] bool followLive() const noexcept { return follow_live_; }
 
    void setLiveRenderEnabled(bool on);
    [[nodiscard]] bool liveRenderEnabled() const noexcept { return live_render_enabled_; }
 
    void closeSource();
 
    double dryDepth() const noexcept { return dry_depth_; }
    void   setDryDepth(double d);
 
    // ----- Self-description for the Layer Properties dialog ----------------
    [[nodiscard]] QString sourceDescription() const override;
    [[nodiscard]] QVector<QPair<QString, QString>> extendedMetadata() const override;
 
    // ----- VS.8 — QSG (GPU) rendering ownership ------------------------------
    //
    // When MapCanvas hosts this layer in SWMM2DResultsQSGRenderer, it sets
    // this flag and the QGraphicsItem QPainter passes return early (same
    // per-kind bypass pattern as SWMMLayerItem §QSG-1). The CPU path stays
    // intact as the fallback (mask clip active, QSG init failure).
    [[nodiscard]] bool qsgOwnsRendering() const noexcept { return m_qsgOwnsRendering; }
    void setQsgOwnsRendering(bool own);
 
    double maxDepth() const noexcept { return max_depth_; }
    void   setMaxDepth(double d);
 
    // ----- Velocity vector overlay (CF.2) -----------------------------------
    //
    // Gap A3.1 — these knobs (and the band / isoline ones below) are now
    // facades over the sublayer model (visibility + style bags), which is
    // the single source of truth the paint passes consult. The legacy
    // fields survive only as fallbacks for the (never-hit) no-sublayer
    // case. Both the dialog (legacy setters) and the layer tree (sublayer
    // toggles) therefore drive — and report — the same state.
 
    bool   velocityVectorsVisible() const;
    void   setVelocityVectorsVisible(bool v);
 
    qreal  velocityOpacity() const;
    void   setVelocityOpacity(qreal alpha);
 
    double velocityArrowScale() const;
    void   setVelocityArrowScale(double scale);
 
    double maxVelocity() const noexcept { return max_velocity_; }
    void   setMaxVelocity(double v);
 
    bool   hasVelocityData() const noexcept { return have_velocity_; }
 
    bool   hasEdgeFluxData() const;
 
    // ----- Color-ramp + contour styling (Slice CF.MVP-fix.3) ----------------
 
    enum class ColorRampStyle { Smooth, Graduated };
    [[nodiscard]] ColorRampStyle colorRampStyle() const noexcept { return color_ramp_style_; }
    void                          setColorRampStyle(ColorRampStyle s);
 
    [[nodiscard]] int  colorClasses() const noexcept { return color_classes_; }
    void               setColorClasses(int n);
 
    [[nodiscard]] bool   filledContours()        const;
    void                 setFilledContours(bool on);
    [[nodiscard]] double filledContoursOpacity() const;
    void                 setFilledContoursOpacity(double a);
    [[nodiscard]] int    filledContoursLevels()  const;
    void                 setFilledContoursLevels(int n);
 
    [[nodiscard]] bool   isolines()        const;
    void                 setIsolines(bool on);
    [[nodiscard]] int    isolinesLevels()  const;
    void                 setIsolinesLevels(int n);
    [[nodiscard]] QColor isolinesColor()   const;
    void                 setIsolinesColor(QColor c);
    [[nodiscard]] double isolinesWidth()   const;
    void                 setIsolinesWidth(double px);
 
    // ----- Renderer (Slice BI Phase 8.13.6.6) -----------------------------
    // API plumbing only — the existing paint path still uses dry_depth_ /
    // max_depth_ directly.  Sub-phase 8.13.6.4 (deferred until Slice BB
    // ColorRamp lands) will swap the paint loop to consult m_renderer.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *renderer() const;
 
    void setRenderer(std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r);
 
    std::pair<float, int> currentPeak() const;
 
    void setCurrentSimTime(QDateTime t);
 
    void setCurrentSimTimeAsOf(QDateTime cursor);
 
    // ----- Cell selection / picking (CF.3) ----------------------------------
 
    [[nodiscard]] QVector<int> pickCellsInRect(const QRectF& sceneRect) const;
 
    [[nodiscard]] QVector<int> pickCellsInPolygon(const QPolygonF& scenePoly) const;
 
    [[nodiscard]] int pickCellAt(const QPointF& scenePt) const;
 
    [[nodiscard]] float depthAtSceneNow(const QPointF& scenePt) const;
 
    [[nodiscard]] double depthToMeshUnits() const { return resolveCoordinateScale_(); }
 
    [[nodiscard]] float depthAtSceneInterp(const QPointF& scenePt) const;
 
    [[nodiscard]] float depthAtCellInterp(int triIdx, const QPointF& scenePt) const;
 
    [[nodiscard]] bool cellHasSurface(int triIdx) const;
 
    [[nodiscard]] bool velocityAtScene(const QPointF& scenePt,
                                       float& outVx, float& outVy) const;
 
    [[nodiscard]] QVector<float> maxDepthPerVertex() const;
 
    [[nodiscard]] float maxDepthAtSceneInterp(const QPointF& scenePt,
                                              const QVector<float>& vertMax) const;
 
    void highlightCells(const QSet<int>& triIdxSet);
 
    void clearHighlights();
 
    [[nodiscard]] const QSet<int>& highlightedCells() const noexcept { return m_highlighted; }
 
    // ----- 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;
 
    // ----- Scene caches (public for the graphics item) -----------------------
 
    struct SceneTri {
        QPointF a, b, c;
        QPointF centroid;       
        float   depth = 0.0f;   
        // Per-corner SIGNED depths η−z (m), used by the marching-triangles
        // contour passes. Recomputed each tick in applyCurrentDepths_() from
        // the wet-masked vertex free-surface field, so the contour passes see
        // a continuous scalar across cell boundaries. Without this the
        // algorithm degenerates (v0==v1==v2 → vMax > vMin is false) and the
        // contour passes silently skip every triangle.
        //
        // Exactly 0 is the NO-DATA sentinel (no wet incident cell) — EXCEPT in
        // a cell that has at least one wet corner, where the dry corners carry
        // the extrapolated pooling surface maxEta − z_k (negative where the bed
        // stands above the pool). That keeps the field LINEAR on the triangle,
        // which is what the marching passes assume, so they cut the shoreline
        // on the true sub-cell bed intercept. Per-corner, so these are NOT
        // interchangeable across the cells sharing a vertex.
        // (workplans/2D_MAP_POOLING_EXTRAPOLATION_PLAN_2026-08-04.md)
        float   dv0   = 0.0f;
        float   dv1   = 0.0f;
        float   dv2   = 0.0f;
        float   vx    = 0.0f;   
        float   vy    = 0.0f;   
        float   vmag  = 0.0f;   
    };
 
    QRectF             m_sceneBBox;
    QVector<SceneTri>  m_sceneTris;
    MeshSpatialGrid    m_triGrid;
 
    struct SceneEdge {
        QPointF a, b;
        float   slope = 0.0f;
    };
    QVector<SceneEdge> m_sceneEdges;
 
    QVector<QPointF>   m_sceneVerts;
 
    [[nodiscard]] const std::vector<std::array<int, 3>> &triVertexIndices() const noexcept
    { return tris_; }
 
    [[nodiscard]] const std::vector<std::array<int, 4>> &cellVertexIndices() const noexcept
    { return cells_; }
 
    [[nodiscard]] const std::vector<int> &triCellMap() const noexcept { return triCell_; }
 
    [[nodiscard]] const std::vector<int> &cellTriRange() const noexcept { return cellTri0_; }
 
    [[nodiscard]] int cellCount() const noexcept { return static_cast<int>(cells_.size()); }
 
    [[nodiscard]] quint64 geomRevision() const noexcept { return m_geomRevision; }
 
signals:
    void timeRangeChanged(int lo, int hi);
 
    void currentTimeChanged(int t);
 
    void currentDateTimeChanged(const QDateTime &dt);
 
    void cellHovered(int triIdx);
 
    void highlightedCellsChanged();
 
    void rendererChanged();
 
private:
    bool loadFrame_(int t);          
    void rebuildSceneGeometry_();   
    void applyCurrentDepths_();     
    void applyCurrentFlux_();       
 
    [[nodiscard]] double resolveCoordinateScale_() const;
 
    quint64 m_geomRevision = 0;
 
    OGRCoordinateTransformation *m_transform = nullptr;
 
    mutable bool m_warnedUndeclaredCrs = false;
 
    double m_fallbackMetresPerModelUnit = 1.0;
 
    [[nodiscard]] int pickDisplayTriAt_(const QPointF& scenePt) const;
    [[nodiscard]] float depthAtDisplayTriInterp_(int triIdx, const QPointF& scenePt) const;
 
    std::unique_ptr<IMesh2DSource> source_;
    std::vector<double>            vx_, vy_, vz_;
    // Mixed-mesh split (workplans/TRI_QUAD_MESHING_PLAN_2026-09-06.md): the
    // CELLS carry the per-face values; the display FAN (one sub-triangle per
    // triangle cell, two per quad on the engine's VFR diagonal) is what the
    // scene, hit-testing, contours and interpolation run on. Every per-face
    // lookup for a display triangle goes through triCell_.
    std::vector<std::array<int,4>> cells_;      
    std::vector<std::array<int,3>> tris_;       
    std::vector<int>               triCell_;    
    std::vector<int>               cellTri0_;   
    std::vector<VertexDepthReconstruct::CellSplit> cellSplit_;  
    std::vector<QPointF>           cellCentroidScene_;          
    std::vector<float>             current_depths_;             
 
    // Sub-cell free-surface reconstruction for partial wet/dry rendering. The
    // engine reports a per-cell mean depth h = V/A under a flat-cell closure;
    // its free surface is η = z_centroid + h (horizontal at equilibrium). We
    // reconstruct that η at vertices and carry a SIGNED per-vertex depth so the
    // wet/dry shoreline cuts through cells instead of snapping to cell edges.
    // cellZc_ is each cell's centroid bed elevation (static; built once in
    // rebuildSceneGeometry_); the eta_* vectors are per-frame scratch reused by
    // applyCurrentDepths_ to avoid per-frame allocation.
    std::vector<float>             cellZc_;       
    std::vector<float>             eta_vsum_;     
    std::vector<float>             eta_wsum_;     
    std::vector<float>             vdepth_;       
 
    // V1 (Issue 5) — per-vertex velocity field, reconstructed each frame in
    // applyCurrentFlux_ as the depth-weighted average of incident cell vectors.
    // A continuous (C0) field so glyphs sampled across cell boundaries vary
    // smoothly instead of stepping at each cell; the peer of vdepth_ for flow.
    std::vector<float>             vvx_;          
    std::vector<float>             vvy_;          
 
    // CF.2 — per-tick flux + time-invariant edge geometry pulled once from the source.
    std::vector<float>             current_flux_;     
    std::vector<float>             edge_length_;      
    std::vector<float>             edge_nx_;          
    std::vector<float>             edge_ny_;          
    bool                           have_edge_geom_   = false;
    bool                           have_velocity_    = false;
    mutable int                    edge_flux_probe_  = 0;
 
    int                            current_time_idx_ = -1;
    bool                           follow_live_      = true;  // live source: auto-advance to newest frame until the user scrubs
    bool                           live_render_enabled_ = true; // live source: master gate for streaming/render work (Issue 2 toggle)
 
    // Live-tick coalescing. A tick arrives as up to four queued pushes
    // (depths, flux, vertex depths, rainfall), each followed by a refresh
    // request; the requests are folded into ONE range emission + ONE frame
    // load per event-loop turn (scheduleLiveSync_ / liveSync_).
    bool                           live_sync_pending_ = false;
    bool                           live_range_dirty_  = false;
    bool                           live_frame_dirty_  = false;
    int                            last_range_hi_     = -1;   
    void scheduleLiveSync_();
    void liveSync_();
 
    // Incremental per-vertex max-depth envelope (maxDepthPerVertex): frames
    // already folded in are not re-read on the next call. Keyed on the source
    // and its history generation; the newest frame is always re-folded.
    mutable std::vector<float>     vertMaxCache_;
    mutable std::vector<uint8_t>   vertWetCache_;
    mutable int                    vertMaxFramesDone_ = 0;
    mutable const IMesh2DSource*   vertMaxSource_     = nullptr;
    mutable int                    vertMaxGeneration_ = -1;
    double                         dry_depth_        = 1e-4;  // 0.1 mm — auto-tuned per project
    double                         max_depth_        = 0.01;  // 10 mm — auto-grows from data each tick
    bool                           max_depth_user_set_ = false;
 
    // Velocity overlay state.
    // CF.2 transitional default: arrows ON so the overlay is eyeball-able
    // before the layer-panel UI lands. Flip back to false once a UI toggle
    // exists.
    bool                           velocity_visible_     = true;
    qreal                          velocity_opacity_     = 0.9;
    double                         velocity_arrow_scale_ = 30.0;   // px per log1p(vmag/vRef)
    double                         max_velocity_         = 1.0;    // m/s, auto-grown
    bool                           max_velocity_user_set_ = false;
 
    SWMM2DResultsGraphicsItem*     graphics_item_    = nullptr;
    SWMM2DVelocityArrowsItem*      arrows_item_      = nullptr;
 
    // VS.8 — true while SWMM2DResultsQSGRenderer owns the on-screen pixels.
    bool                           m_qsgOwnsRendering = false;
 
    // CF.3 — selection / highlight state.
    QSet<int>                      m_highlighted;
 
    // Slice BI Phase 8.13.6.6 — renderer plumbing.  Initialised eagerly in
    // the ctor (default GraduatedRenderer) so renderer() never returns
    // null.  Paint refactor deferred until Slice BB ColorRamp ships.
    std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> m_renderer;
 
    // Slice CF.MVP-fix.3 — graduated colour + contour styling. All default
    // values preserve the pre-fix.3 paint output byte-identically.
    ColorRampStyle color_ramp_style_         = ColorRampStyle::Smooth;
    int            color_classes_            = 5;
    bool           filled_contours_          = false;
    double         filled_contours_opacity_  = 0.60;
    int            filled_contours_levels_   = 8;
    bool           isolines_                 = false;
    int            isolines_levels_          = 5;
    QColor         isolines_color_           = QColor(20, 20, 20, 230);
    double         isolines_width_           = 1.0;  // pixels
 
    // Slice S5.6 — sublayer foundation (dormant pointers, populated in
    // ctor). The existing paint pipeline does not yet consume these; the
    // final paint-replacement slice will replace the current SceneTri
    // pipeline with sublayer-driven QSG geometry.
    OpenSWMM::Render::MeshFillSublayer        *m_meshFillSublayer       = nullptr;
    OpenSWMM::Render::MeshEdgeSublayer        *m_meshEdgeSublayer       = nullptr;
    OpenSWMM::Render::MeshNodeSublayer        *m_meshNodeSublayer       = nullptr;
    OpenSWMM::Render::ContourBandSublayer     *m_contourBandSublayer    = nullptr;
    OpenSWMM::Render::CellDepthFillSublayer   *m_cellDepthFillSublayer  = nullptr;
    OpenSWMM::Render::SmoothDepthFillSublayer *m_smoothDepthFillSublayer = nullptr;
    OpenSWMM::Render::IsolineSublayer         *m_isolineSublayer        = nullptr;
    OpenSWMM::Render::VelocityVectorSublayer  *m_velocityVectorSublayer = nullptr;
 
    // User-customisable paint order (Slice GUI-2026-05-30 §2).  Lazy-seeded
    // from the default order in sublayers(); reordered via moveSublayer();
    // round-tripped through ISublayerHost::save/loadSublayersFromJson.
    mutable QList<OpenSWMM::Render::ISublayer *> m_sublayerOrder;
 
public:
    // ----- ISublayerHost interface (Slice S5.6) -----------------------------
    //
    // Default sublayer mix (2026-06-21; depth color ramp + flow arrows removed):
    //   [0] MeshFillSublayer         (static — terrain hillshade base)
    //   [1] ContourBandSublayer      (dynamic — filled bands; the depth fill, default on)
    //   [2] MeshEdgeSublayer         (static — wireframe over results)
    //   [3] IsolineSublayer          (dynamic — marching-squares isolines; default off)
    //   [4] MeshNodeSublayer         (static — coupled-vertex markers)
    //   [5] VelocityVectorSublayer   (dynamic — RT0 arrow glyphs; also show direction)
    [[nodiscard]] QList<OpenSWMM::Render::ISublayer *> sublayers() const override;
 
    bool moveSublayer(int from, int to) override;
 
    [[nodiscard]] QList<OpenSWMM::Render::LegendSymbolItem>
        sublayerLegendItems() const;
 
    [[nodiscard]] OpenSWMM::Render::MeshFillSublayer *
        meshFillSublayer() const { return m_meshFillSublayer; }
    [[nodiscard]] OpenSWMM::Render::MeshEdgeSublayer *
        meshEdgeSublayer() const { return m_meshEdgeSublayer; }
    [[nodiscard]] OpenSWMM::Render::MeshNodeSublayer *
        meshNodeSublayer() const { return m_meshNodeSublayer; }
    [[nodiscard]] OpenSWMM::Render::ContourBandSublayer *
        contourBandSublayer() const { return m_contourBandSublayer; }
    [[nodiscard]] OpenSWMM::Render::CellDepthFillSublayer *
        cellDepthFillSublayer() const { return m_cellDepthFillSublayer; }
    [[nodiscard]] OpenSWMM::Render::SmoothDepthFillSublayer *
        smoothDepthFillSublayer() const { return m_smoothDepthFillSublayer; }
    [[nodiscard]] OpenSWMM::Render::IsolineSublayer *
        isolineSublayer() const { return m_isolineSublayer; }
    [[nodiscard]] OpenSWMM::Render::VelocityVectorSublayer *
        velocityVectorSublayer() const { return m_velocityVectorSublayer; }
 
    [[nodiscard]] std::vector<std::unique_ptr<openswmmvis::ui::ILayerStyleSubject>>
        styleSubjects() override;
 
    // ----- Rule Model (Slice B.5b, Phase B) -------------------------------
    //
    // Five seed Rules covering the result-layer decoration archetypes
    // (Depth color ramp / Velocity vectors / Contour / Mesh edges /
    // Mesh nodes). Same lazy-build pattern as SWMM2DMeshLayer.
    [[nodiscard]] OpenSWMM::Render::RuleList *ruleList() override;
    [[nodiscard]] const OpenSWMM::Render::RuleList *ruleList() const override;
 
private:
    void buildRuleListLazy() const;
    mutable std::unique_ptr<OpenSWMM::Render::RuleList> m_ruleList;
};
 
#endif // OPENSWMMVIS_LAYERS_SWMM2DRESULTSLAYER_H