Vectorfield Chart

The vectorfield function visualises vector field data using colour and arrow size to illustrate magnitude.

Syntax

vectorfield(X, Y, U, V)
vectorfield(X, Y, U, V, "Parent", fig)
vectorfield(X, Y, U, V, "BackgroundImageData", imgData)
vectorfield(X, Y, U, V, "BackgroundImageData", imgData, "BackgroundImageAlpha", 0.5)
vectorfield(X, Y, U, V, "ScaleFactor", sf)
vf = vectorfield(__)

Where X and Y are the start position of each vector and U and V are the horizontal and vertical components of the vector magnitude.

X, Y, U and V arrays must be the same size.

It is also possible to add a background image using the "BackgroundImageData" option and adjust the transparency using "BackgroundImageAlpha".

You can adjust the size of the arrows using the "ScaleFactor" option.

Use the "Parent" option to create the chart in an existing container. If you do not specify "Parent", vectorfield creates a uifigure.

Arrow colours are mapped from vector magnitude using the axes colormap and color limits.

The Autoscale option assumes the vectors lie on a regular or near-regular grid.

vf is a vectorfield object,use vf to modify properties of the plot after creating it.

Examples

Run provided examples here

Creating a vectorfield chart

% Create vector data
r = linspace(-pi, pi, 20);
[X, Y] = meshgrid(r, r);
U = sin(Y);
V = cos(X);

% Create vector field chart
v = vectorfield(X, Y, U, V);

Creating a vectorfield chart in an existing figure

fig = uifigure;
vf = vectorfield(X, Y, U, V, "Parent", fig);

Adding a background image

% Load image data
imgData = imread("peppers.png");

% Create vector data
numVectors = 20;
r = linspace(-pi, pi, numVectors);
[Xm, Ym] = meshgrid(r, r);
U = sin(Ym);
V = cos(Xm);

h = height(imgData);
w = width(imgData);
X = linspace(0, w, numVectors);
Y = linspace(0, h, numVectors);
[X,Y] = meshgrid(X, Y);

% visualise
vectorfield(X, Y, U, V, ...
    "BackgroundImageData", imgData, ...
    "BackgroundImageAlpha", 0.5);

Modify vector scale factor and colormap

vf = vectorfield(X, Y, U, V, ...
    "ScaleFactor", 2);

colormap(vf, "hot")

MathWorks® Products (https://www.mathworks.com)

Requires MATLAB® release R2025a or newer

The current implementation also uses functions from Image Processing Toolbox and Statistics and Machine Learning Toolbox.

Contact

Contact Andrew Redfearn for more information or to report issues: aredfear@mathworks.com

License

The license is available in the License.txt file in this GitHub repository.