VectorsGraphic#929

kushalkolar

closes #560

Uses instanced meshes to create the 3D vector representations and place them in 3D space.

VectorsGraphic graphic which is based on instanced meshes built by merging a cone and cylinder mesh.
- VectorDirections which manages the positions of the arrows through modifying the translation elements of the transform matrix of the instance buffer
- VectorDirections which manages the directions of the arrows through modifying the entire transform matrix of the instance buffer
- supports static immutable single colors for now
- auto-determines size of the arrows by estimating the density of vectors, or user can provide a specific size or specific shape for the arrows.

Can implement per-vector colors after pygfx/pygfx#1221 later in a future PR.

Can do some fun electromagnetism animations with this.

Very simple API:

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 indicate directions in x and y
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()])

vectors = figure[0, 0].add_vectors(
    positions=positions,
    directions=directions,
)

figure.show()

kushalkolar

few questions

kushalkolar

Interactions work well:

vectors-2025-10-28_01.52.43.mp4

figure = fpl.Figure(size=(700, 700))

start, stop, step = 0, 2 * np.pi, 0.4

# 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,
)

def update(change):
    val = change["new"]
    start, stop, step = 0, 2 * np.pi, 0.4
    start += val
    stop += val
    
    # 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)
    
    directions = np.column_stack([u.ravel(), v.ravel()])
    
    vector_field.directions = directions

slider = FloatSlider(value=0, min=-5, max=5, step=0.01)
slider.observe(update, "value")

VBox([figure.show(), slider])

Need to wait for pygfx/pylinalg#107
and pygfx/pygfx#1220

before merging into fastplotlib main

kushalkolar

The recursion error with the ome-zarr file makes no sense, going to get rid of it from tests and only show the code in the docs until they fix whatever is up.

github-actions

📚 Docs preview built and uploaded! https://www.fastplotlib.org/ver/vector-field

clewis7

Aside from that one example that won't run, everything LGTM

kushalkolar added 4 commits October 21, 2025 03:11

start vector fields

2828f48

basics of vector field works

c439fd9

add vector field to api docs

d10d08f

update event tables

6858fd6

kushalkolar requested a review from clewis7 as a code owner October 21, 2025 09:37

kushalkolar mentioned this pull request Oct 21, 2025

More features for instancing pygfx/pygfx#1221

Open

kushalkolar marked this pull request as draft October 21, 2025 09:38

add vector field to subsection_order

178ce12