Add QuiverItem for 2D vector field plots (closes #54)

New plot item displaying arrows at grid positions, similar to
Matplotlib's quiver:

- QuiverItem class (plotpy/items/quiver.py) with configurable
  arrow scale, head size, color, and auto-meshgrid from 1D inputs
- Builder method make.quiver() and interactive plt.quiver()
- Integrated with plot autoscale (initial zoom + middle-click reset)
- Item icon for the item list widget
- Test and release notes for v2.9.0

Author: PierreRaybaut

doc/features/items/overview.rst

@@ -41,6 +41,13 @@ The following image items are available:
 * :py:func:`.get_plot_qrect`
 * :py:func:`.get_image_from_plot`
 
+Flow fields
+^^^^^^^^^^^
+
+The following flow field items are available:
+
+* :py:class:`.QuiverItem`: a flow field item with arrows
+
 Grid
 ^^^^
 

doc/features/items/reference.rst

@@ -71,6 +71,12 @@ Histograms
 .. autoclass:: plotpy.items.Histogram2DItem
     :members:
 
+Flow fields
+^^^^^^^^^^^
+
+.. autoclass:: plotpy.items.QuiverItem
+   :members:
+
 Grid
 ^^^^
 

doc/release_notes/release_2.09.md

@@ -0,0 +1,16 @@
+# Version 2.9 #
+
+## PlotPy Version 2.9.0 ##
+
+💥 New features:
+
+* Added `QuiverItem` for displaying 2D vector fields (quiver plots), similar to
+  Matplotlib's `quiver`. This closes
+  [Issue #54](https://github.com/PlotPyStack/PlotPy/issues/54):
+  * New `QuiverItem` plot item class supporting X, Y, U, V arrays (1D or 2D)
+  * Auto-meshgrid expansion when X, Y are 1D and U, V are 2D
+  * Configurable arrow scale, head size, and color
+  * New `make.quiver()` builder method for easy item creation
+  * New `quiver()` function in the interactive plotting interface (`plotpy.pyplot`)
+  * Integrated with plot autoscale (initial zoom and middle-click reset)
+  * Item icon displayed in the item list widget

plotpy/__init__.py

@@ -20,7 +20,7 @@
 .. _GitHub: https://github.com/PierreRaybaut/plotpy
 """
 
-__version__ = "2.8.4"
+__version__ = "2.9.0"
 __VERSION__ = tuple([int(number) for number in __version__.split(".")])
 
 # --- Important note: DATAPATH and LOCALEPATH are used by guidata.configtools

plotpy/builder/curvemarker.py

@@ -6,11 +6,11 @@
 # pylint: disable=C0103
 
 """
-Curve/cursor/marker Item builder
---------------------------------
+Curve/cursor/marker/... Item builder
+------------------------------------
 
 This module provides a set of factory functions to simplify the creation of
-curve, cursor and marker items.
+curve, cursor, marker, histogram and flow field items.
 """
 
 # Note: when adding method to builder classes, please do not forget to update the
@@ -32,6 +32,7 @@
     ErrorBarCurveItem,
     HistogramItem,
     Marker,
+    QuiverItem,
     XRangeSelection,
     YRangeSelection,
 )
@@ -1023,3 +1024,70 @@ def marker(
             marker.set_movable(False)
             marker.set_resizable(False)
         return marker
+
+    def quiver(
+        self,
+        x: numpy.ndarray,
+        y: numpy.ndarray,
+        u: numpy.ndarray,
+        v: numpy.ndarray,
+        title: str = "",
+        color: str | None = None,
+        arrow_scale: float = 30.0,
+        arrow_head_size: float = 6.0,
+        headwidth: float = 0.7,
+        xaxis: str = "bottom",
+        yaxis: str = "left",
+    ) -> QuiverItem:
+        """Make a quiver (vector field) `plot item`
+
+        Displays arrows at grid positions (x, y) with direction and magnitude
+        defined by (u, v) components, similar to Matplotlib's ``quiver``.
+
+        Args:
+            x: 1D or 2D array of arrow X positions
+            y: 1D or 2D array of arrow Y positions
+            u: 1D or 2D array of arrow X components
+            v: 1D or 2D array of arrow Y components
+            title: plot item title. Default is ''
+            color: arrow color name. Default is None (black)
+            arrow_scale: scale factor for arrow length in pixels.
+             Default is 30.0. Larger values produce longer arrows.
+            arrow_head_size: size of arrow heads in pixels.
+             Default is 6.0
+            headwidth: arrow head width as multiple of head size.
+             Default is 0.7
+            xaxis: x axis name. Default is 'bottom'
+            yaxis: y axis name. Default is 'left'
+
+        Returns:
+            :py:class:`.QuiverItem` object
+
+        Example::
+
+            import numpy as np
+            x = np.linspace(-2, 2, 10)
+            y = np.linspace(-2, 2, 10)
+            X, Y = np.meshgrid(x, y)
+            U, V = -Y, X  # Rotational field
+            quiver(X, Y, U, V, title="Rotation", color="blue")
+        """
+        if color is None:
+            color = "black"
+        item = QuiverItem(
+            x,
+            y,
+            u,
+            v,
+            color=color,
+            arrow_scale=arrow_scale,
+            arrow_head_size=arrow_head_size,
+            headwidth=headwidth,
+        )
+        if title:
+            item.setTitle(title)
+        else:
+            item.setTitle(_("Quiver"))
+        item.setXAxis(BasePlot.AXIS_NAMES[xaxis])
+        item.setYAxis(BasePlot.AXIS_NAMES[yaxis])
+        return item

plotpy/data/icons/items/quiver.png

@@ -594,6 +594,7 @@ def register_serializable_items(modname, classnames):
     "plotpy.items",
     [
         "CurveItem",
+        "QuiverItem",
         "PolygonMapItem",
         "ErrorBarCurveItem",
         "RawImageItem",

plotpy/io.py

@@ -55,6 +55,7 @@
     SelectedLegendBoxItem,
 )
 from .polygonmap import PolygonMapItem
+from .quiver import QuiverItem
 from .shape import (
     AbstractShape,
     Axes,