Skip to main content

Quiver plot

A quiver plot draws a 2D vector field as a grid of arrows. Each arrow has a tail at (x, y) and a vector (u, v) giving its direction and length. It is the canonical way to show fluid flow, a force field, a gradient, wind or current patterns — anywhere each location carries a direction and a magnitude.

WITH g AS (SELECT ((i * 10.0 / 9.0) - 5.0)::DOUBLE AS v FROM (SELECT unnest(range(0, 10)) AS i))
SELECT kuva_render(to_json({
'title': 'Rotational field',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': (SELECT list({'x': x.v, 'y': y.v, 'u': -y.v * 0.3, 'v': x.v * 0.3}) FROM g x, g y),
'color': 'steelblue'
}]
})) AS chart;

That is a rotational field (u, v) = (−y, x) · 0.3 sampled on a 10×10 grid. Real data usually comes from a table instead — one row per arrow with x, y, u, v columns:

SELECT kuva_render(to_json({
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': list({'x': x, 'y': y, 'u': u, 'v': v}),
'color': 'steelblue'
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/quiver.tsv');

Scaling​

By default the multiplier is auto-computed so that the longest arrow is roughly one grid cell long. That keeps arrows from piling on top of each other whatever units (u, v) are in.

Two fields override it:

FieldEffect
scalePin the multiplier. Arrow length in data coordinates is (u, v) · scale.
auto_scale_fractionKeep auto-scaling but change its target (default 0.9). Near 1.0 packs the arrows tip-to-tail; smaller values leave more air.
SELECT kuva_render(to_json({
'title': 'Pinned scale',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': list({'x': x, 'y': y, 'u': u, 'v': v}),
'color': 'steelblue',
'scale': 0.5
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/quiver.tsv');

Pivot​

pivot says where (x, y) sits on its arrow:

pivotMeaning
"tail"(x, y) is the tail; the arrow points away from it (default)
"middle"The arrow is centred on (x, y)
"tip"(x, y) is the tip; the arrow comes into it

For a sampled field, "middle" reads more naturally as "what the field is doing at this location".

SELECT kuva_render(to_json({
'title': 'Pivot at the middle',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': list({'x': x, 'y': y, 'u': u, 'v': v}),
'color': 'steelblue',
'pivot': 'middle'
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/quiver.tsv');

Colouring by magnitude​

color_map colours each arrow by its magnitude √(u² + v²) and draws a colour bar automatically, titled with color_legend_label.

SELECT kuva_render(to_json({
'title': 'Coloured by magnitude',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': list({'x': x, 'y': y, 'u': u, 'v': v}),
'color_map': 'viridis',
'color_legend_label': 'magnitude'
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/quiver.tsv');

Priority: a per-arrow color beats color_map, which beats the series color.

Arrow styling​

FieldDefaultWhat it sets
shaft_width1.2Stroke width of the shaft, in pixels
head_ratio0.28Head length as a fraction of the shaft
head_length / head_widthproportionalPin the head to fixed pixel dimensions
head_min_px / head_max_px4 / 14Clamp a proportional head, so tiny arrows still show one

By default heads stay proportional, so every arrow looks like an arrow whatever its magnitude. Pinning head_length / head_width gives identical glyphs across a mixed-magnitude field.

SELECT kuva_render(to_json({
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'quiver',
'arrows': list({'x': x, 'y': y, 'u': u, 'v': v}),
'color': 'steelblue',
'shaft_width': 1,
'head_ratio': 0.35
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/quiver.tsv');

Fields​

FieldTypeWhat it sets
arrowsarrow[]Required. One entry per arrow: {x, y, u, v, color?}.
colorstringArrow colour.
scalenumberMultiplier for (u, v); without it the arrows are auto-scaled.
auto_scale_fractionnumberTarget fraction of the plot the arrows span when auto-scaling.
shaft_widthnumberShaft width, in pixels.
head_lengthnumberArrowhead length, in pixels.
head_widthnumberArrowhead half-width, in pixels.
head_rationumberArrowhead length / shaft length.
head_aspectnumberArrowhead half-width / length.
head_min_px / head_max_pxnumberBounds on the arrowhead length, in pixels.
color_mapstringA colormap by magnitude; overrides color.
color_range[number, number]The magnitude range the colormap spans.
color_legend_labelstringThe colour bar's title.
legendstringThe legend entry.
tight_boundsbooleanFit the axes to the arrow tails only, ignoring the tips.
clip_to_plot_areabooleanClip arrows to the plot area (false lets them overflow).
pivotstringWhere the arrow is anchored: "tail" (default) · "middle" · "tip".

Notes​

  • arrows must not be empty, and every x, y, u, v must be finite — a non-finite component is an error rather than a silently dropped arrow.
  • color_map colours by arrow magnitude; a per-arrow color covers the arrows without one.
  • tight_bounds is worth turning on when the arrows near the edge would otherwise stretch the axes.

See also​