feat: add lifecycle handles for field plots

Author: chdinh

CHANGELOG.md

@@ -19,6 +19,9 @@ All notable changes to SkigenPlot will be documented in this file.
   operations.
 - Composite stem plots return one stable handle for updating, styling, hiding,
   or removing their stems and markers together.
+- Heatmap, contour, filled-contour, and hexbin plots return independent stable
+  handles for styling, visibility, and removal, allowing field plots to compose
+  without replacing earlier field geometry.
 - Theme-aware legends for labelled 2D series with automatic or fixed-corner
   placement.
 - Independent x/y axis limits with getters, autoscale reset, validation, and

README.md

@@ -43,10 +43,13 @@ int main(int argc, char* argv[]) {
 ```
 
 `plot()`, `scatter()`, `hist()`, `bar()`, `barh()`, `fillBetween()`, `step()`,
-`errorbar()`, `stem()`, `boxplot()`, `violinplot()`, `quiver()`, and `pie()`
-return stable `SeriesHandle` values.
+`errorbar()`, `stem()`, `boxplot()`, `violinplot()`, `quiver()`, `pie()`,
+`imshow()`, `contour()`, `contourf()`, and `hexbin()` return stable
+`SeriesHandle` values.
 Use `updateSeriesData()`, `setSeriesStyle()`, `setSeriesVisible()`, and
 `removeSeries()` to modify one series without clearing the rest of the view.
+Field-plot data is immutable in v1, so `updateSeriesData()` returns `false`
+for those handles; style, visibility, and removal remain supported.
 Visible labelled series can be shown in a theme-aware legend with automatic
 or explicit corner placement.
 

doc/dev-notes/v1.0.0_requirements.md

@@ -104,7 +104,7 @@ because they affect ordinary scientific workflows or public API stability.
 
 | Capability | Status | v1.0 requirement | Matplotlib analogue |
 |---|---|---|---|
-| Series lifecycle | **Partial** | Plot-creation methods return a stable `SeriesHandle`; data, style, visibility, and removal can be updated without clearing unrelated series. Invalidated handles fail predictably. | `Artist`, `Line2D.set_data`, `Artist.remove` |
+| Series lifecycle | **Implemented** | Plot-creation methods return a stable `SeriesHandle`; supported data/style updates, visibility, and removal do not clear unrelated series. Field data updates are unsupported in v1 and return `false`. Invalidated handles fail predictably. | `Artist`, `Line2D.set_data`, `Artist.remove` |
 | Legend | **Implemented** | Render labels from `PlotStyle::label`; support show/hide, automatic placement, and four corner placements. Unlabelled and hidden series are omitted. | `legend` |
 | Axis limits | **Implemented** | Get/set/reset x and y limits independently. Explicit limits disable autoscaling for that axis until reset. Reversed limits intentionally invert an axis. Non-finite and equal endpoints are rejected. | `xlim`, `ylim`, `autoscale`, axis inversion |
 | Axis scales | **Implemented** | Independent linear and base-10 logarithmic x/y scales. Limits remain in data units, reversed positive limits preserve inversion, pan/zoom operate in transformed space, and non-positive samples are omitted from logarithmic bounds and rendering. | `xscale`, `yscale`, `semilogx`, `semilogy`, `loglog` |
@@ -248,7 +248,7 @@ not block v1.0.0.
   or gallery coverage.
 - [x] Scrolling telemetry uses fixed-capacity circular sample storage and the
   existing dynamic line-rendering pipeline.
-- [ ] The essential v1.0 usability surface above is implemented and documented:
+- [x] The essential v1.0 usability surface above is implemented and documented:
   series handles, legends, axis limits, linear/log scales, line styles,
   markers, and deterministic input validation.
 - [x] Multiple line/scatter/fill series compose in one view without changing

doc/website/docs/api/plotview.mdx

@@ -86,10 +86,13 @@ public:
 `PlotView` is the central class of SkigenPlot. It accepts Eigen matrix expressions directly — no manual data conversion needed. Data is interleaved into GPU vertex buffers and rendered using Qt's RHI abstraction layer.
 
 Line, scatter, histogram, bar, horizontal-bar, filled-area, step, error-bar,
-stem, box, violin, quiver, and pie creation returns an opaque `SeriesHandle`.
+stem, box, violin, quiver, pie, heatmap, contour, filled-contour, and hexbin
+creation returns an opaque `SeriesHandle`.
 Handles remain stable when other series are removed. Mutating or removing an
 invalid, stale, or foreign handle returns `false` and leaves the view unchanged.
 Creation with insufficient input returns an invalid handle.
+Field geometry is immutable in v1, so `updateSeriesData()` returns `false` for
+field handles; style, visibility, containment, and removal are supported.
 
 X and y axes independently support `AxisScale::Linear` and
 `AxisScale::Log10`. Public limits remain in data units and may be reversed.

include/skigen/plot/plotview.h

@@ -249,14 +249,14 @@ class SKIGENPLOT_EXPORT PlotView : public QRhiWidget {
     ///   to [min, max] across finite cells unless @p vmin < @p vmax is given.
     ///   Non-finite cells are omitted; all-invalid input leaves the view unchanged.
     template <typename Derived>
-    void imshow(const Eigen::MatrixBase<Derived>& m,
+    auto imshow(const Eigen::MatrixBase<Derived>& m,
                 Colormap cmap = Colormap::Viridis,
-                float vmin = 0.0f, float vmax = 0.0f)
+                float vmin = 0.0f, float vmax = 0.0f) -> SeriesHandle
     {
         Eigen::MatrixXf mf = m.derived().template cast<float>().eval();
-        imshowImpl({mf.data(), static_cast<std::size_t>(mf.size())},
-                   static_cast<int>(mf.rows()), static_cast<int>(mf.cols()),
-                   cmap, vmin, vmax);
+        return imshowImpl({mf.data(), static_cast<std::size_t>(mf.size())},
+                          static_cast<int>(mf.rows()), static_cast<int>(mf.cols()),
+                          cmap, vmin, vmax);
     }
 
     // ── 2D contour lines / filled contour ───────────────────────────
@@ -266,26 +266,26 @@ class SKIGENPLOT_EXPORT PlotView : public QRhiWidget {
     ///   maps to grid coordinate (c, rows-1-r), matching imshow(). Cells with
     ///   non-finite corners are omitted. Values of @p levels below 1 use 1.
     template <typename Derived>
-    void contour(const Eigen::MatrixBase<Derived>& z, int levels = 8,
-                 const PlotStyle& style = {})
+    auto contour(const Eigen::MatrixBase<Derived>& z, int levels = 8,
+                 const PlotStyle& style = {}) -> SeriesHandle
     {
         Eigen::MatrixXf zf = z.derived().template cast<float>().eval();
-        contourImpl({zf.data(), static_cast<std::size_t>(zf.size())},
-                    static_cast<int>(zf.rows()), static_cast<int>(zf.cols()),
-                    levels, style);
+        return contourImpl({zf.data(), static_cast<std::size_t>(zf.size())},
+                           static_cast<int>(zf.rows()), static_cast<int>(zf.cols()),
+                           levels, style);
     }
 
     /// @brief Filled contour: colour each finite cell by its value band using
     ///   @p cmap (cell-level quantisation). Companion to contour(). Values of
     ///   @p levels below 2 use 2.
     template <typename Derived>
-    void contourf(const Eigen::MatrixBase<Derived>& z, int levels = 10,
-                  Colormap cmap = Colormap::Viridis)
+    auto contourf(const Eigen::MatrixBase<Derived>& z, int levels = 10,
+                  Colormap cmap = Colormap::Viridis) -> SeriesHandle
     {
         Eigen::MatrixXf zf = z.derived().template cast<float>().eval();
-        contourfImpl({zf.data(), static_cast<std::size_t>(zf.size())},
-                     static_cast<int>(zf.rows()), static_cast<int>(zf.cols()),
-                     levels, cmap);
+        return contourfImpl({zf.data(), static_cast<std::size_t>(zf.size())},
+                            static_cast<int>(zf.rows()), static_cast<int>(zf.cols()),
+                            levels, cmap);
     }
 
     // ── 2D violin plot (KDE density per group) ──────────────────────
@@ -324,14 +324,15 @@ class SKIGENPLOT_EXPORT PlotView : public QRhiWidget {
     ///   are omitted; all-invalid input leaves the view unchanged. Values of
     ///   @p gridsize below 2 use 2.
     template <typename DX, typename DY>
-    void hexbin(const Eigen::MatrixBase<DX>& x, const Eigen::MatrixBase<DY>& y,
+    auto hexbin(const Eigen::MatrixBase<DX>& x, const Eigen::MatrixBase<DY>& y,
                 int gridsize = 20, Colormap cmap = Colormap::Viridis)
+        -> SeriesHandle
     {
         Eigen::VectorXf xf = x.derived().template cast<float>().eval();
         Eigen::VectorXf yf = y.derived().template cast<float>().eval();
-        hexbinImpl({xf.data(), static_cast<std::size_t>(xf.size())},
-                   {yf.data(), static_cast<std::size_t>(yf.size())},
-                   gridsize, cmap);
+        return hexbinImpl({xf.data(), static_cast<std::size_t>(xf.size())},
+                          {yf.data(), static_cast<std::size_t>(yf.size())},
+                          gridsize, cmap);
     }
 
     // ── 2D pie chart ────────────────────────────────────────────────
@@ -494,6 +495,13 @@ class SKIGENPLOT_EXPORT PlotView : public QRhiWidget {
                        const PlotStyle& style,
                        SeriesHandle groupHandle = {},
                        bool supportsDataUpdate = false) -> SeriesHandle;
+    auto addFieldSeries(std::vector<float> vertices, bool coloredTriangles,
+                        const BoundingBox2D& bounds,
+                        const PlotStyle& style = {},
+                        std::optional<Colormap> colormap = std::nullopt,
+                        float vmin = 0.0f, float vmax = 1.0f)
+        -> SeriesHandle;
+    void refreshColorbar();
 
     auto histImpl(std::span<const float> values, int bins, bool density,
                   const PlotStyle& style) -> SeriesHandle;
@@ -510,17 +518,17 @@ class SKIGENPLOT_EXPORT PlotView : public QRhiWidget {
     auto errorbarImpl(std::span<const float> x, std::span<const float> y,
                       std::span<const float> yerr, const PlotStyle& style)
         -> SeriesHandle;
-    void imshowImpl(std::span<const float> data, int rows, int cols,
-                    Colormap cmap, float vmin, float vmax);
-    void contourImpl(std::span<const float> data, int rows, int cols,
-                     int levels, const PlotStyle& style);
-    void contourfImpl(std::span<const float> data, int rows, int cols,
-                      int levels, Colormap cmap);
+    auto imshowImpl(std::span<const float> data, int rows, int cols,
+                    Colormap cmap, float vmin, float vmax) -> SeriesHandle;
+    auto contourImpl(std::span<const float> data, int rows, int cols,
+                     int levels, const PlotStyle& style) -> SeriesHandle;
+    auto contourfImpl(std::span<const float> data, int rows, int cols,
+                      int levels, Colormap cmap) -> SeriesHandle;
     auto quiverImpl(std::span<const float> x, std::span<const float> y,
                     std::span<const float> u, std::span<const float> v,
                     const PlotStyle& style) -> SeriesHandle;
-    void hexbinImpl(std::span<const float> x, std::span<const float> y,
-                    int gridsize, Colormap cmap);
+    auto hexbinImpl(std::span<const float> x, std::span<const float> y,
+                    int gridsize, Colormap cmap) -> SeriesHandle;
     auto pieImpl(std::span<const float> values) -> SeriesHandle;
 
     void setPointCloudData(std::span<const float> data, int vertexCount,