fastplotlib · kushalkolar · Nov 4, 2025 · Oct 21, 2025 · Oct 21, 2025 · Oct 21, 2025
@@ -0,0 +1,35 @@
+.. _api.VectorDirections:
+
+VectorDirections
+****************
+
+================
+VectorDirections
+================
+.. currentmodule:: fastplotlib.graphics.features
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorDirections_api
+
+    VectorDirections
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorDirections_api
+
+    VectorDirections.value
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: VectorDirections_api
+
+    VectorDirections.add_event_handler
+    VectorDirections.block_events
+    VectorDirections.clear_event_handlers
+    VectorDirections.remove_event_handler
+    VectorDirections.set_value
+
@@ -0,0 +1,35 @@
+.. _api.VectorPositions:
+
+VectorPositions
+***************
+
+===============
+VectorPositions
+===============
+.. currentmodule:: fastplotlib.graphics.features
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorPositions_api
+
+    VectorPositions
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorPositions_api
+
+    VectorPositions.value
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: VectorPositions_api
+
+    VectorPositions.add_event_handler
+    VectorPositions.block_events
+    VectorPositions.clear_event_handlers
+    VectorPositions.remove_event_handler
+    VectorPositions.set_value
+
@@ -26,6 +26,8 @@ Graphic Features
     VolumeIsoEmissive
     VolumeIsoShininess
     VolumeSlicePlane
+    VectorPositions
+    VectorDirections
     TextData
     FontSize
     TextFaceColor

diff --git a/docs/source/api/graphics/VectorField.rst b/docs/source/api/graphics/VectorField.rst
@@ -0,0 +1,49 @@
+.. _api.VectorField:
+
+VectorField
+***********
+
+===========
+VectorField
+===========
+.. currentmodule:: fastplotlib
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorField_api
+
+    VectorField
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: VectorField_api
+
+    VectorField.alpha
+    VectorField.alpha_mode
+    VectorField.axes
+    VectorField.block_events
+    VectorField.deleted
+    VectorField.directions
+    VectorField.event_handlers
+    VectorField.name
+    VectorField.offset
+    VectorField.positions
+    VectorField.right_click_menu
+    VectorField.rotation
+    VectorField.supported_events
+    VectorField.visible
+    VectorField.world_object
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: VectorField_api
+
+    VectorField.add_axes
+    VectorField.add_event_handler
+    VectorField.clear_event_handlers
+    VectorField.remove_event_handler
+    VectorField.rotate
+
@@ -9,6 +9,7 @@ Graphics
     ScatterGraphic
     ImageGraphic
     ImageVolumeGraphic
+    VectorField
     TextGraphic
     LineCollection
     LineStack
@@ -53,6 +53,7 @@ Methods
     Subplot.add_line_stack
     Subplot.add_scatter
     Subplot.add_text
+    Subplot.add_vector_field
     Subplot.auto_scale
     Subplot.center_graphic
     Subplot.center_scene

@@ -66,6 +66,7 @@
             "../../examples/line",
             "../../examples/line_collection",
             "../../examples/scatter",
+            "../../examples/vector_field",
             "../../examples/text",
             "../../examples/events",
             "../../examples/selection_tools",

@@ -697,6 +697,108 @@ deleted
 | value    | bool | True when graphic was deleted |
 +----------+------+-------------------------------+
 
+VectorField
+-----------
+
+positions
+^^^^^^^^^
+
+**event info dict**
+
++----------+------------+----------------------+
+| dict key | type       | description          |
++==========+============+======================+
+| value    | np.ndarray | new vector positions |
++----------+------------+----------------------+
+
+directions
+^^^^^^^^^^
+
+**event info dict**
+
++----------+------------+-----------------------+
+| dict key | type       | description           |
++==========+============+=======================+
+| value    | np.ndarray | new vector directions |
++----------+------------+-----------------------+
+
+name
+^^^^
+
+**event info dict**
+
++----------+------+--------------------+
+| dict key | type | description        |
++==========+======+====================+
+| value    | str  | user provided name |
++----------+------+--------------------+
+
+offset
+^^^^^^
+
+**event info dict**
+
++----------+---------------------------------+----------------------+
+| dict key | type                            | description          |
++==========+=================================+======================+
+| value    | np.ndarray[float, float, float] | new offset (x, y, z) |
++----------+---------------------------------+----------------------+
+
+rotation
+^^^^^^^^
+
+**event info dict**
+
++----------+----------------------------------------+-------------------------+
+| dict key | type                                   | description             |
++==========+========================================+=========================+
+| value    | np.ndarray[float, float, float, float] | new rotation quaternion |
++----------+----------------------------------------+-------------------------+
+
+alpha
+^^^^^
+
+**event info dict**
+
++----------+-------+-----------------+
+| dict key | type  | description     |
++==========+=======+=================+
+| value    | float | new alpha value |
++----------+-------+-----------------+
+
+alpha_mode
+^^^^^^^^^^
+
+**event info dict**
+
++----------+------+----------------+
+| dict key | type | description    |
++==========+======+================+
+| value    | str  | new alpha mode |
++----------+------+----------------+
+
+visible
+^^^^^^^
+
+**event info dict**
+
++----------+------+---------------------+
+| dict key | type | description         |
++==========+======+=====================+
+| value    | bool | new visibility bool |
++----------+------+---------------------+
+
+deleted
+^^^^^^^
+
+**event info dict**
+
++----------+------+-------------------------------+
+| dict key | type | description                   |
++==========+======+===============================+
+| value    | bool | True when graphic was deleted |
++----------+------+-------------------------------+
+
 TextGraphic
 -----------
 

diff --git a/examples/vector_field/README.rst b/examples/vector_field/README.rst
@@ -0,0 +1,2 @@
+Vector Field Examples
+=====================
diff --git a/examples/vector_field/vector_field_simple.py b/examples/vector_field/vector_field_simple.py
@@ -0,0 +1,45 @@
+"""
+Simple Vector Field
+===================
+
+Simple vector field example. Similar to matplotlib quiver.
+
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import fastplotlib as fpl
+
+figure = fpl.Figure(size=(700, 700))
+
+start, stop, step = 0, 2 * np.pi, 0.2
+
+# get uniform x, y positions
+x, y = np.meshgrid(np.arange(start, stop, step), np.arange(start, stop, step))
+
+# vectors, u and v are x and y components indication directions
+u = np.cos(x)
+v = np.sin(y)
+
+# positions of each vector as [n_points, 2] array
+positions = np.column_stack([x.ravel(), y.ravel()])
+# directions of each vector as a [n_points, 2] array
+directions = np.column_stack([u.ravel(), v.ravel()])
+
+
+vector_field = figure[0, 0].add_vector_field(
+    positions=positions,
+    directions=directions,
+    spacing=step,
+    size_scaling_factor=5.0,
+)
+
+figure.show()
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
diff --git a/examples/vector_field/vector_field_swirl.py b/examples/vector_field/vector_field_swirl.py
@@ -0,0 +1,49 @@
+"""
+Swirling vector field
+=====================
+
+Example showing a swirling vector field. Similar to matplotlib quiver.
+
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import fastplotlib as fpl
+
+figure = fpl.Figure(cameras="3d", controller_types="orbit", size=(700, 700))
+
+start, stop, step = -1, 1, 0.3
+
+# Make the grid
+x, y, z = np.meshgrid(
+    np.arange(start, stop, step),
+    np.arange(start, stop, step),
+    np.arange(start, stop, step),
+)
+
+# Make the direction data for the arrows
+u = np.sin(np.pi * x) * np.cos(np.pi * y) * np.cos(np.pi * z)
+v = -np.cos(np.pi * x) * np.sin(np.pi * y) * np.cos(np.pi * z)
+w = np.sqrt(2.0 / 3.0) * np.cos(np.pi * x) * np.cos(np.pi * y) * np.sin(np.pi * z)
+
+positions = np.column_stack([x.ravel(), y.ravel(), z.ravel()])
+directions = np.column_stack([u.ravel(), v.ravel(), w.ravel()])
+
+
+vector_field = figure[0, 0].add_vector_field(
+    positions=positions,
+    directions=directions,
+    spacing=step,
+    size_scaling_factor=2.0,
+)
+
+figure.show()
+
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
@@ -3,6 +3,7 @@
 from .scatter import ScatterGraphic
 from .image import ImageGraphic
 from .image_volume import ImageVolumeGraphic
+from .vector_field import VectorField
 from .text import TextGraphic
 from .line_collection import LineCollection, LineStack
 
@@ -13,6 +14,7 @@
     "ScatterGraphic",
     "ImageGraphic",
     "ImageVolumeGraphic",
+    "VectorField",
     "TextGraphic",
     "LineCollection",
     "LineStack",