swmm2dmeshlayer.h

Go to the documentation of this file.

 
#ifndef OPENSWMMVIS_LAYERS_SWMM2DMESHLAYER_H
#define OPENSWMMVIS_LAYERS_SWMM2DMESHLAYER_H
 
#include "layers/meshspatialgrid.h"
#include "layers/openswmmvislayer.h"
#include "mesh/meshboundarygraph.h"
#include "mesh/meshresult.h"
#include "mesh/meshedgebc.h"
#include "render/isublayerhost.h"
 
#include <QByteArray>
#include <QColor>
#include <QLineF>
#include <QPair>
#include <QPointF>
#include <QPolygonF>
#include <QRectF>
#include <QSet>
#include <QString>
#include <QVector>
 
#include <ogr_spatialref.h>
 
#include <memory>
 
class QGraphicsScene;
class QGraphicsItem;
class SWMM2DMeshGraphicsItem;
 
namespace OpenSWMM::Render
{
class IFeatureRenderer;
class RuleList;   // Slice B.5b — see ruleList() override below.
class MeshFillSublayer;
class MeshEdgeSublayer;
class MeshNodeSublayer;
class ContourBandSublayer;
class IsolineSublayer;
class MeshBcSublayer;
class CoupledNodeSublayer;
}
 
class SWMM2DMeshLayer : public OpenSWMMVisLayer,
                        public OpenSWMM::Render::ISublayerHost
{
    Q_OBJECT
 
    // Source path + mesh-size metadata for the Properties window. The mesh
    // is immutable after construction so vertex / triangle counts are CONSTANT.
    Q_PROPERTY(QString sourcePath          READ sourcePath           CONSTANT)
    Q_PROPERTY(int    triangleCount        READ triangleCount        CONSTANT)
    Q_PROPERTY(int    vertexCount          READ vertexCount          CONSTANT)
 
    // Slice U-5 — Q_PROPERTYs for the unified LayerStyleDialog. Setters
    // already emit repaintRequested() which the dialog treats as NOTIFY.
    Q_PROPERTY(bool   showMeshNodes        READ showMeshNodes        WRITE setShowMeshNodes
               NOTIFY repaintRequested)
    Q_PROPERTY(bool   showEdges            READ showEdges            WRITE setShowEdges
               NOTIFY repaintRequested)
    Q_PROPERTY(double hillshadeAzimuth     READ hillshadeAzimuth     WRITE setHillshadeAzimuth
               NOTIFY repaintRequested)
    Q_PROPERTY(double hillshadeAltitude    READ hillshadeAltitude    WRITE setHillshadeAltitude
               NOTIFY repaintRequested)
    Q_PROPERTY(double hillshadeZExag       READ hillshadeZExag       WRITE setHillshadeZExag
               NOTIFY repaintRequested)
    Q_PROPERTY(double hillshadeMinLit      READ hillshadeMinLit      WRITE setHillshadeMinLit
               NOTIFY repaintRequested)
    Q_PROPERTY(bool   showContours         READ showContours         WRITE setShowContours
               NOTIFY repaintRequested)
    Q_PROPERTY(int    contourIntervalCount READ contourIntervalCount WRITE setContourIntervalCount
               NOTIFY repaintRequested)
    Q_PROPERTY(QColor contourColor         READ contourColor         WRITE setContourColor
               NOTIFY repaintRequested)
    Q_PROPERTY(double contourLineWidth     READ contourLineWidth     WRITE setContourLineWidth
               NOTIFY repaintRequested)
    Q_PROPERTY(bool   filledContours       READ filledContours       WRITE setFilledContours
               NOTIFY repaintRequested)
    Q_PROPERTY(double filledContoursOpacity READ filledContoursOpacity WRITE setFilledContoursOpacity
               NOTIFY repaintRequested)
 
    // Zoom at which the wireframe / vertex dots auto-appear, as the minimum
    // on-screen cell size (pixels across). Larger ⇒ must zoom in closer.
    Q_PROPERTY(double edgeZoomMinCellPx    READ edgeZoomMinCellPx    WRITE setEdgeZoomMinCellPx
               NOTIFY repaintRequested)
    Q_PROPERTY(double vertexZoomMinCellPx  READ vertexZoomMinCellPx  WRITE setVertexZoomMinCellPx
               NOTIFY repaintRequested)
 
    Q_CLASSINFO("group:sourcePath",           "Source")
    Q_CLASSINFO("group:triangleCount",        "Mesh")
    Q_CLASSINFO("group:vertexCount",          "Mesh")
    Q_CLASSINFO("group:showMeshNodes",        "Display")
    Q_CLASSINFO("group:showEdges",            "Display")
    Q_CLASSINFO("group:edgeZoomMinCellPx",    "Display")
    Q_CLASSINFO("group:vertexZoomMinCellPx",  "Display")
    Q_CLASSINFO("group:hillshadeAzimuth",     "Hillshade")
    Q_CLASSINFO("group:hillshadeAltitude",    "Hillshade")
    Q_CLASSINFO("group:hillshadeZExag",       "Hillshade")
    Q_CLASSINFO("group:hillshadeMinLit",      "Hillshade")
    Q_CLASSINFO("group:showContours",         "Contours")
    Q_CLASSINFO("group:contourIntervalCount", "Contours")
    Q_CLASSINFO("group:contourColor",         "Contours")
    Q_CLASSINFO("group:contourLineWidth",     "Contours")
    Q_CLASSINFO("group:filledContours",       "Contours")
    Q_CLASSINFO("group:filledContoursOpacity", "Contours")
 
public:
    explicit SWMM2DMeshLayer(mesh::MeshResult result,
                              const QString &sourcePath = {},
                              OpenSWMMVisWorkspace *parent = nullptr,
                              bool deferHeavyGeometry = false);
    ~SWMM2DMeshLayer() override;
 
    void finishSceneGeometryAsync();
 
    [[nodiscard]] bool sceneGeometryComplete() const { return m_sceneGeomComplete; }
 
    [[nodiscard]] QString sourcePath() const;
    void setSourcePath(const QString &path)  { m_sourcePath = path; }
 
    [[nodiscard]] bool isExternalMesh() const { return m_isExternal; }
    void setExternalMesh(bool external)      { m_isExternal = external; }
 
    [[nodiscard]] bool meshUnitsSI() const { return m_meshUnitsSI; }
    void setMeshUnitsSI(bool si)           { m_meshUnitsSI = si; }
 
    [[nodiscard]] int triangleCount() const { return int(m_mesh.triangles.size()); }
 
    [[nodiscard]] int quadCount() const { return m_mesh.quadCount(); }
 
    [[nodiscard]] int vertexCount()   const { return int(m_mesh.vertices.size()); }
 
    [[nodiscard]] int boundaryEdgeCount() const { return int(m_mesh.boundaryEdges.size()); }
 
    [[nodiscard]] int edgeCount() const {
        if (!m_sceneEdges.isEmpty()) return int(m_sceneEdges.size());
        return (3 * triangleCount() + quadCount() + boundaryEdgeCount()) / 2;
    }
 
    [[nodiscard]] double maxSlope() const { return double(m_maxSlope); }
 
    // ----- Self-description for the Layer Properties dialog ----------------
    [[nodiscard]] QString sourceDescription() const override;
    [[nodiscard]] QVector<QPair<QString, QString>> extendedMetadata() const override;
 
    [[nodiscard]] bool isActiveMesh() const { return m_active; }
    void setActiveMesh(bool active);
 
    // ----- QSG ownership (Mesh Tiled LOD plan P1.1) -------------------------
    [[nodiscard]] bool qsgOwnsRendering() const noexcept { return m_qsgOwnsRendering; }
    void setQsgOwnsRendering(bool own);
 
    // ----- Display toggles ------------------------------------------------
    // These remain on the layer so existing UI, JSON, and serialization
    // round-trip the way they always have, but they are now thin shims
    // that forward to the per-sublayer visibility flag.
    [[nodiscard]] bool showMeshNodes() const;
    void setShowMeshNodes(bool show);
 
    [[nodiscard]] bool showEdges() const;
    void setShowEdges(bool show);
 
    // ----- Zoom thresholds for edge / vertex auto-display -----------------
    // Both renderers suppress the wireframe / vertex-dot passes until the
    // mean on-screen cell size reaches these values (pixels across), so the
    // detail appears automatically as the user zooms in and never clutters
    // the far view. Configurable per layer; defaults reproduce the historic
    // LOD gates (√kEdgeMinCellAreaPx ≈ 5.66 px, √kMarkerMinCellAreaPx ≈
    // 14.14 px). 0 ⇒ always draw (when the sublayer is visible).
    [[nodiscard]] double edgeZoomMinCellPx()   const { return m_edgeMinCellPx; }
    void setEdgeZoomMinCellPx(double px);
    [[nodiscard]] double vertexZoomMinCellPx() const { return m_vertexMinCellPx; }
    void setVertexZoomMinCellPx(double px);
 
    [[nodiscard]] double edgeMinCellAreaPx()   const { return m_edgeMinCellPx * m_edgeMinCellPx; }
    [[nodiscard]] double vertexMinCellAreaPx() const { return m_vertexMinCellPx * m_vertexMinCellPx; }
 
    // ----- Hillshade ------------------------------------------------------
    // azimuth/altitude stay on the layer because they describe the light
    // source, which is layer-wide (not per-sublayer). zExag and minLit
    // map to the mesh-fill sublayer style's hillshadeStrength.
    [[nodiscard]] double hillshadeAzimuth()    const { return m_hillshadeAz; }
    [[nodiscard]] double hillshadeAltitude()   const { return m_hillshadeAlt; }
    [[nodiscard]] double hillshadeZExag()      const;
    [[nodiscard]] double hillshadeMinLit()     const;
    void setHillshadeAzimuth(double degrees);
    void setHillshadeAltitude(double degrees);
    void setHillshadeZExag(double factor);
    void setHillshadeMinLit(double minLit);
 
    // ----- Bed-elevation contours -----------------------------------------
    // Forward to the isoline + contour-band sublayers; the layer Q_PROPERTYs
    // exist for backwards compatibility with .oswp files written before the
    // sublayer refactor.
    [[nodiscard]] bool   showContours()         const;
    [[nodiscard]] int    contourIntervalCount() const;
    [[nodiscard]] QColor contourColor()         const;
    [[nodiscard]] double contourLineWidth()     const;
    void setShowContours(bool show);
    void setContourIntervalCount(int n);
    void setContourColor(const QColor &c);
    void setContourLineWidth(double widthPx);
 
    [[nodiscard]] bool   filledContours()        const;
    [[nodiscard]] double filledContoursOpacity() const;
    void setFilledContours(bool filled);
    void setFilledContoursOpacity(double a);
 
    [[nodiscard]] const mesh::MeshResult &mesh() const { return m_mesh; }
 
    [[nodiscard]] quint64 geomRevision() const { return m_geomRevision; }
 
    [[nodiscard]] bool hasUnsavedMeshEdits() const { return m_editsDirty; }
 
    void markMeshEdited() { m_editsDirty = true; }
 
    void setMeshEditsSaved() { m_editsDirty = false; }
 
    // ---------------------------------------------------------------------
    // Slice §V.VA — mesh-editing foundation: BC storage, picker / hover
    // helpers, write-path apply* family, attributeChanged signal.
    //
    // The layer is the model in the §V MVC; all views (Mesh Editing
    // toolbar, future Property Browser tab, Attribute Table, map renderer)
    // subscribe to attributeChanged and write through the apply* helpers.
    // ---------------------------------------------------------------------
 
    [[nodiscard]] const QVector<mesh::MeshEdgeBC> &edgeBCs() const { return m_bc; }
 
    QVector<mesh::MeshEdgeBC> &edgeBCsMutable() { ++m_bcRevision; return m_bc; }
 
    [[nodiscard]] int pickVertexAt(double sx, double sy,
                                    double tolPx, double pxPerSceneUnit) const;
 
    [[nodiscard]] int pickEdgeAt(double sx, double sy,
                                  double tolPx, double pxPerSceneUnit,
                                  bool boundaryOnly) const;
 
    [[nodiscard]] int locateTriangleAt(double sx, double sy) const;
 
    [[nodiscard]] int pickCellAt(const QPointF &scenePt) const;
 
    [[nodiscard]] QVector<int> pickCellsInRect(const QRectF &sceneRect) const;
 
    [[nodiscard]] QVector<int> pickCellsInPolygon(const QPolygonF &scenePoly) const;
 
    [[nodiscard]] double sampleZAt(double sx, double sy) const;
 
    [[nodiscard]] bool isBoundaryEdge(int triIdx, int edgeLocal) const;
 
    [[nodiscard]] const mesh::MeshBoundaryGraph &boundaryGraph();
 
    [[nodiscard]] QPair<int,int> findEdgeNeighbour(int triIdx, int edgeLocal) const;
 
    // ----- Write path (Slice §V.VA / §V.VB / §V.VC) ------------------------
    bool applyMeshVertexZ(int vertexIdx, double z);
 
    bool applyMeshEdgeBC(int triIdx, int edgeLocal, const mesh::MeshEdgeBC &bc);
 
    bool applyMeshEdgeConveyance(int triIdx, int edgeLocal, double conveyance);
 
    bool applyMeshVertexTag(int vertexIdx, const QString &tag);
 
    bool applyMeshVertexCoupledNode(int vertexIdx, const QString &node);
 
    bool applyMeshVertexCouplingCd(int vertexIdx, double cd);
 
    bool applyMeshVertexCouplingArea(int vertexIdx, double area);
 
    QVector<mesh::CellCoupling> applyCellCouplings(
        const QVector<mesh::CellCoupling> &rows);
 
    [[nodiscard]] const QVector<mesh::CellCoupling> &cellCouplings() const
    { return m_mesh.cellCouplings; }
 
    bool applyMeshTriangleMannings(int triIdx, double mannings);
 
    bool applyMeshTriangleInitDepth(int triIdx, double depth);
 
    bool applyMeshTriangleTag(int triIdx, const QString &tag);
 
    bool applyMeshTriangleInfil(int triIdx, const mesh::InfilRow &row);
 
    bool clearMeshTriangleInfil(int triIdx);
 
    bool applyMeshInfilDefault(const QString &tag, const mesh::InfilRow &row);
 
    bool clearMeshInfilDefault(const QString &tag);
 
    // ----- Selection highlighting (§V follow-up) ---------------------------
    [[nodiscard]] const QSet<int> &highlightedVertices() const { return m_selVertices; }
    void setHighlightedVertices(const QSet<int> &indices);
 
    [[nodiscard]] const QSet<int> &highlightedEdges()    const { return m_selEdges; }
    void setHighlightedEdges(const QSet<int> &flatIndices);
 
    [[nodiscard]] const QSet<int> &highlightedTriangles() const { return m_selTriangles; }
    void setHighlightedTriangles(const QSet<int> &indices);
 
signals:
    void attributeChanged(const QString &refName);
 
    void meshEditsChanged();
 
    void selectionInvalidated();
 
    void activeMeshChanged(bool isActive);
 
    void overviewBuildStarted(const QString &layerName);
    void overviewBuildFinished(bool ok);
 
    void sceneGeometryReady();
public:
 
    // ----- Renderer (Slice BI Phase 8.13.6.6) -----------------------------
    // API plumbing only — paint loop still uses the per-vertex hillshade
    // ramp directly.  Sub-phase 8.13.6.4 (deferred until Slice BB
    // ColorRamp lands) will refactor paint to consult m_renderer.
 
    [[nodiscard]] OpenSWMM::Render::IFeatureRenderer *renderer() const override;
 
    void setRenderer(std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> r) override;
 
    // ----- ISublayerHost interface -----------------------------------------
    [[nodiscard]] QList<OpenSWMM::Render::ISublayer *> sublayers() const override;
 
    bool moveSublayer(int from, int to) override;
 
    [[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::IsolineSublayer     *isolineSublayer()     const { return m_isolineSublayer; }
    [[nodiscard]] OpenSWMM::Render::MeshBcSublayer      *meshBcSublayer()      const { return m_meshBcSublayer; }
    [[nodiscard]] OpenSWMM::Render::CoupledNodeSublayer *coupledNodeSublayer() const { return m_coupledNodeSublayer; }
 
    void onSublayersJsonLoaded(const QJsonObject &sublayersJson) override;
 
    [[nodiscard]] double zMin() const { return m_zMin; }
    [[nodiscard]] double zMax() const { return m_zMax; }
 
    [[nodiscard]] QVector<double> elevationSamples(int maxSamples = 200000) const;
 
    // ----- Per-cell attribute colouring (MeshFillStyle::colorByAttribute) ---
    //
    // Values come from mesh::cellParamValue(), the single registry that also
    // drives the editing toolbar and the attribute table — never read
    // MeshTriangle::mannings directly, or the pending gw.* keys will not
    // light up for free when the engine grows them.
 
    [[nodiscard]] quint64 attrRevision() const { return m_attrRevision; }
 
    [[nodiscard]] quint64 bcRevision() const { return m_bcRevision; }
 
    [[nodiscard]] const QVector<qint32> &bcSceneEdges() const;
 
    [[nodiscard]] const QVector<float> &cellAttributeValues(const QByteArray &key) const;
 
    [[nodiscard]] QVector<double> cellAttributeSamples(const QByteArray &key,
                                                        int maxSamples = 200000) const;
 
    [[nodiscard]] bool cellAttributeRange(const QByteArray &key,
                                           double *vMin, double *vMax) 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;
 
    [[nodiscard]] std::vector<std::unique_ptr<openswmmvis::ui::ILayerStyleSubject>>
        styleSubjects() override;
 
    // ----- Rule Model (Slice B.5b, Phase B) -------------------------------
    //
    // 2D mesh layers carry decoration-style rendering (fill / edges /
    // nodes / hillshade / contours) rather than per-kind renderers, so
    // the seed RuleList holds one Rule per decoration archetype with a
    // SingleSymbolRenderer placeholder. The decoration specs from Z.6
    // (HillshadeSymbolLayerSpec / ContourSymbolLayerSpec / MeshEdge /
    // MeshNode) populate the SymbolStyle props inside each Rule. Paint
    // integration that consumes those specs is the named Z.6a slice.
    [[nodiscard]] OpenSWMM::Render::RuleList *ruleList() override;
    [[nodiscard]] const OpenSWMM::Render::RuleList *ruleList() const override;
 
    // ----- Scene-geometry structs (public for SWMM2DMeshQSGRenderer) ---------
 
    struct SceneTri
    {
        QPointF a, b, c;
        float   zAvg;       
        float   z0, z1, z2; 
        int     cell = -1;  
    };
 
    template <class Tris>
    static void appendVertexElevationSamples(const Tris &tris, QVector<double> &out)
    {
        out.reserve(out.size() + int(tris.size()) * 3);
        const SceneTri *prev = nullptr;
        for (const SceneTri &t : tris) {
            if (prev && t.cell >= 0 && t.cell == prev->cell) {
                const QPointF p[3] = { t.a, t.b, t.c };
                const float   z[3] = { t.z0, t.z1, t.z2 };
                for (int k = 0; k < 3; ++k)
                    if (p[k] != prev->a && p[k] != prev->b && p[k] != prev->c)
                        out.push_back(double(z[k]));
            } else {
                out.push_back(double(t.z0));
                out.push_back(double(t.z1));
                out.push_back(double(t.z2));
            }
            prev = &t;
        }
    }
 
    struct SceneEdge
    {
        QLineF  line;
        float   zAvg;
        float   slope;
    };
 
    struct SceneNode
    {
        QPointF pt;
        float   z;
        bool    tagged; 
    };
 
    // Scene-geometry caches — written by rebuildSceneGeometry(),
    // read by SWMM2DMeshQSGRenderer::updatePaintNode().
    QRectF             m_sceneBBox;
    QVector<SceneTri>  m_sceneTris;
    QVector<SceneEdge> m_sceneEdges;
    QVector<SceneNode> m_sceneNodes;
 
    QVector<qint32>    m_cellSceneStart;
 
    QVector<qint32>    m_sceneEdgeSlot;
    double             m_zMin     = 0.0;
    double             m_zMax     = 0.0;
    float              m_maxSlope = 0.0f;
 
    // ── Level-of-detail (LOD) overview for far-zoom rendering ──────────────
    // A coarse, fixed-resolution decimation of m_sceneTris built once by
    // rebuildOverview(): each occupied cell of a low-res aggregation grid
    // becomes a quad (two SceneTris) coloured by the mean elevation of the
    // triangles whose centroid falls in it, with corner heights averaged
    // from neighbouring cells so hillshade still reads. The painter draws
    // this instead of the full mesh when the native triangles project below
    // ~2 px (see SWMM2DMeshGraphicsItem::paint), turning a 5M-triangle fill
    // into a few-tens-of-thousands-triangle fill at full extent. Zoomed-in
    // views (native triangle ≥ threshold) keep the exact legacy path.
    QVector<SceneTri>  m_overviewTris;            
    double             m_nativeTriSpan = 0.0;     
 
    // Triangle indices into m_sceneTris sorted by descending scene-space area.
    // Drives adaptive far-zoom culling: at low zoom the painter walks this from
    // the front, drawing real cells while their projected area stays above a
    // pixel threshold and stopping as soon as it drops below — so large cells
    // render faithfully and tiny sub-pixel cells are skipped, in O(kept) rather
    // than O(all). Built alongside the overview for meshes past the threshold.
    QVector<int>       m_trisBySizeDesc;
 
    [[nodiscard]] bool hasOverview() const { return !m_overviewTris.isEmpty(); }
 
    void rebuildOverviewAsync();
 
    [[nodiscard]] bool overviewBuildRunning() const { return m_overviewBuildRunning; }
 
    // Uniform spatial grid over scene-space triangle / edge bboxes.
    // The full type lives in layers/meshspatialgrid.h (extracted so it
    // can be unit-tested without linking the rest of the layer); see
    // that header for storage layout and threading contract.
    MeshSpatialGrid    m_triGrid;
    MeshSpatialGrid    m_edgeGrid;
    QVector<QRectF>    m_triBBoxes;   
    QVector<QRectF>    m_edgeBBoxes;  
 
signals:
    void rendererChanged();
 
private:
    void rebuildSceneGeometry();
 
    [[nodiscard]] int locateSceneTriAt(double sx, double sy) const;
 
    void rebuildOverview();
    void buildRuleListLazy() const;   // Slice B.5b — lazy ruleList init.
 
    // Slice B.5b — Rule Model mirror over the mesh layer's decoration
    // state. Lazy-built on first ruleList() call.
    mutable std::unique_ptr<OpenSWMM::Render::RuleList> m_ruleList;
 
    // §V.VA — keep m_bc sized to mesh::edgeSlotCount(n_cells) in sync with the mesh,
    // and rebuild the vertex→triangles adjacency used by sampleZAt /
    // applyMeshVertexZ.
    void resizeBCsToMesh();
    void rebuildVertexAdjacency();
 
    void refreshSublayerLegendInputs();
 
    void scheduleLegendInputRefresh();
    bool m_legendRefreshQueued = false;
 
    void announceInfilDefaultsChanged();
 
    mesh::MeshResult             m_mesh;
    QString                      m_sourcePath;
    bool                         m_isExternal    = false;
    bool                         m_meshUnitsSI   = false;  
    bool                         m_active        = false;
 
    // Mesh Tiled LOD plan P1.1 — see qsgOwnsRendering().
    bool                         m_qsgOwnsRendering = false;
 
    // True while rebuildOverviewAsync() has a worker in flight.
    bool                         m_overviewBuildRunning = false;
 
    // Progressive load (deferHeavyGeometry ctor mode) — see
    // sceneGeometryComplete() / finishSceneGeometryAsync().
    bool                         m_sceneGeomComplete   = true;
    bool                         m_heavyBuildRunning   = false;
    QVector<QPointF>             m_pendingScenePts;   
 
    void rebuildSceneGeometryLight();
 
    // Hillshade state lives on the mesh-fill sublayer style; we keep a
    // pair of simple knobs the renderer reads from the layer (azimuth,
    // altitude) so the visual exactly reproduces the historic values
    // when the user has not edited anything. The Q_PROPERTY setters
    // forward through the sublayer styles where applicable.
    double                       m_hillshadeAz     = 225.0;   // compass deg
    double                       m_hillshadeAlt    =  35.264; // deg above horizon (asin(1/√3))
    double                       m_hillshadeMinLit =   0.15;  // shadow floor (0..1)
 
    // Zoom thresholds (min on-screen cell size, px) for edge / vertex passes.
    // Moderate defaults so the wireframe/vertices come in at a sensible zoom
    // (roughly a few px per cell) rather than only at extreme close-up.
    double                       m_edgeMinCellPx   =   3.0;
    double                       m_vertexMinCellPx =   6.0;
 
    quint64                      m_geomRevision  = 0;
    // See hasUnsavedMeshEdits(): conservative default, cleared only by an
    // explicit pristine attach or a confirmed successful save.
    bool                         m_editsDirty    = true;
    OGRCoordinateTransformation *m_transform     = nullptr;
    SWMM2DMeshGraphicsItem      *m_graphicsItem  = nullptr;
 
    // Per-cell attribute / BC revisions. Separate from m_geomRevision so an
    // attribute edit invalidates the renderer's fill-colour cache without
    // forcing a full geometry rebuild, and so the cached attribute vector
    // below knows when it went stale.
    quint64                      m_attrRevision  = 0;
    quint64                      m_bcRevision    = 0;
 
    // Cache for bcSceneEdges(); keyed on both revisions because a geometry
    // rebuild re-derives m_sceneEdgeSlot and a BC edit changes which slots
    // are non-Wall.
    mutable QVector<qint32>      m_bcSceneEdges;
    mutable quint64              m_bcSceneEdgesBcRev   = ~quint64(0);
    mutable quint64              m_bcSceneEdgesGeomRev = ~quint64(0);
 
    // Single-slot cache for cellAttributeValues() — the renderer asks for the
    // same key every frame, so one slot is enough and switching attributes is
    // a one-off recompute.
    mutable QByteArray           m_attrCacheKey;
    mutable quint64              m_attrCacheGeomRev = ~quint64(0);
    mutable quint64              m_attrCacheAttrRev = ~quint64(0);
    mutable QVector<float>       m_attrCacheVals;
    mutable double               m_attrCacheMin     = 0.0;
    mutable double               m_attrCacheMax     = 0.0;
    mutable bool                 m_attrCacheHasData = false;
 
    // Slice BI Phase 8.13.6.6 — renderer plumbing.  Initialised eagerly in
    // the ctor (default SingleSymbolRenderer) so renderer() never returns
    // null.  Paint refactor deferred until Slice BB ColorRamp ships.
    std::unique_ptr<OpenSWMM::Render::IFeatureRenderer> m_renderer;
 
    // §V.VA — per-edge BC storage, sized to mesh::edgeSlotCount(n_cells).
    // Flat indexed as `mesh::edgeSlot(cell, edgeLocal)`. Interior-edge
    // entries stay at the default Wall value; engine consults only boundary
    // slots.
    QVector<mesh::MeshEdgeBC>    m_bc;
 
    // §V.VA — per-vertex CSR adjacency for fast incident-triangle lookup
    // (used by sampleZAt / applyMeshVertexZ). Rebuilt by
    // rebuildVertexAdjacency() in the ctor and on geometry-changing
    // reloads (future).
    QVector<int>                 m_vertTriPtr;  // size = n_vertices + 1
    QVector<int>                 m_vertTriIdx;  // size = sum of incidences
 
    // §V.VA — precomputed boundary status per (cell, edgeLocal). Flat
    // indexed `mesh::edgeSlot(cell, eLocal)`. true = this edge slot is a
    // boundary edge in the loaded mesh. Rebuilt alongside m_bc / adjacency.
    QVector<bool>                m_isBoundary;
 
    // Lazily built from m_isBoundary by boundaryGraph(); invalidated
    // wherever m_isBoundary is rebuilt (resizeBCsToMesh / the deferred
    // finishSceneGeometryAsync completion).
    mesh::MeshBoundaryGraph      m_boundaryGraph;
    bool                         m_boundaryGraphValid = false;
 
    // §V follow-up — selection highlight state. Drives the renderer's
    // selection-overlay pass (cyan dots / cyan edges).
    QSet<int>                    m_selVertices;
    QSet<int>                    m_selEdges;
    QSet<int>                    m_selTriangles;
 
    // Sublayer host members. Each is QObject-parented to `this`, so the
    // ISublayerHost contract is satisfied without manual delete in the
    // dtor. The mesh layer surfaces these in sublayers() in paint order
    // (bottom-up): fill → contour bands → edges → isolines → vertex
    // markers.
    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::IsolineSublayer     *m_isolineSublayer     = nullptr;
    OpenSWMM::Render::MeshBcSublayer      *m_meshBcSublayer      = nullptr;
    OpenSWMM::Render::CoupledNodeSublayer *m_coupledNodeSublayer = nullptr;
 
    // User-customisable paint order (Slice GUI-2026-05-30 §2).
    mutable QList<OpenSWMM::Render::ISublayer *> m_sublayerOrder;
};
 
#endif // OPENSWMMVIS_LAYERS_SWMM2DMESHLAYER_H