Add curved_quiver — Curved Vector Field Arrows for 2D Plots

[cvanelteren]

This PR introduces a new plotting feature: curved_quiver, a method for drawing curved vector field arrows (streamlines with arrows) for 2D vector fields. This method provides a visually intuitive way to represent vector fields, combining the clarity of streamlines with the directionality of arrows.

Motivation

• Enhanced Visualization: Traditional quiver plots use straight arrows, which can be misleading for complex flows. curved_quiver uses streamlines with arrows, making vector field direction and magnitude easier to interpret.
• User Request: This feature was suggested by user @Yefee, who advocated for a more declarative and modular approach to vector field visualization.
• Consistency: The implementation aligns with the project’s style, using clear, single-responsibility helper functions for maintainability and extensibility.

Attribution

• The core logic of curved_quiver is adapted from the Deltares dfm_tools repository.

Features

• Draws curved arrows along streamlines for 2D vector fields.
• Supports customization of color, linewidth, colormap, arrow size/style, density, and more.
• Accepts user-defined starting points for streamlines.
• Returns a container object (CurvedQuiverSet) with both the line and arrow collections for further manipulation or legend creation.
• Modular implementation: major steps are handled by private, well-documented helper functions.

Usage Example

fig, ax = uplt.subplots()
x = np.linspace(-4, 4, 20)
y = np.linspace(-3, 3, 20)
X, Y = np.meshgrid(x, y)
U = -Y
V = X
speed = np.sqrt(U**2 + V**2)
cq = ax.curved_quiver(X, Y, U, V, color=speed, arrow_at_end=True, scale=2.0, grains=10)
fig.colorbar(cq.lines, ax=ax, label="speed")

Acknowledgement

This feature was suggested by user @Yefee, who requested a declarative, helper-driven approach for curved vector field arrows.

Impact

• Adds a new, powerful visualization tool for vector fields.
• No breaking changes; fully additive.
• Comprehensive tests included for all helper functions and main plotting logic.

[codecov]

Codecov Report

❌ Patch coverage is 80.84112% with 82 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ultraplot/axes/plot_types/curved_quiver.py	78.53%	38 Missing and 9 partials ⚠️
ultraplot/axes/plot.py	72.65%	17 Missing and 18 partials ⚠️

📢 Thoughts on this report? Let us know!

[cvanelteren]

• Proof of principle is implemented. Need to refactor now before asking for review.

[cvanelteren]

Pinging @veenstrajelmer. I wrote a wrapper around the code that was introduced in dfm_tools but we have a licensing issue. That repository uses GPL3.0 and we use MIT. I am not too sure if under the current wrapper it satisfies GPL3.0. Could you chip in on this?

[veenstrajelmer]

I wrote a wrapper around the code that was introduced in dfm_tools but we have a licensing issue. That repository uses GPL3.0 and we use MIT. I am not too sure if under the current wrapper it satisfies GPL3.0. Could you chip in on this?

That should be no issue I think, feel free to take it and adapt it as you wish. As written in the docstring of modplot.py, the code in that file is an improved version of https://github.com/kieranmrhunt/curved-quivers/blob/master/modplot.py (which has no licence), this again was based largely on matplotlibs streamplot functionality. I made the code in dfm_tools such that the diff was minimal with the matplotlib.streamplot code (at the time). I also hoped matplotlib would adopt it for that reason, as you probably read in the discussion in matplotlib/matplotlib#20038. So please ignore the dfm_tools license for this script, and feel free to use and adopt it as you please.

[beckermr]

A bit more stuff on the class names. Looking good!

[cvanelteren]

@beckermr done merge away when ready.