streamline

Plot streamlines from 2-D or 3-D vector data

• 

Syntax

streamline(X,Y,Z,U,V,W,startX,startY,startZ)

streamline(U,V,W,startX,startY,startZ)

streamline(X,Y,U,V,startX,startY)

streamline(U,V,startX,startY)

streamline(verts)

streamline(___,options)

streamline(___,Name=Value)

streamline(ax,___)

lineobj = streamline(___)

Description

streamline(X,Y,Z,U,V,W,startX,startY,startZ) returns plotted streamlines for 3-D vector data. The inputs X, Y, and Z are vector data coordinates, U, V, and W are vector data, and startX, startY, and startZ are the starting positions of the streamlines.

streamline(U,V,W,startX,startY,startZ) uses the default coordinate data for U, V, and W. The (x,y,z) location for each element in U, V, and W is based on the column, row, and page index, respectively.

streamline(X,Y,U,V,startX,startY) returns plotted streamlines for 2-D vector data. The inputs X and Y are vector data coordinates, U and V are vector data, and startX and startY are the starting positions of the streamlines.

streamline(U,V,startX,startY) uses the default coordinate data for  U and V. The (x,y) location for each element in U and V is based on the column and row index, respectively.

streamline(verts) plots streamlines from vertices, specified as a cell array of vertex arrays (as returned by stream2, stream3, or streamslice).

streamline(___,options) plots streamlines using the specified options, defined as a one- or two-element vector with the form step or [step maxvert], where step is the step size in data units for interpolating the vector data and maxvert is the maximum number of vertices in a streamline. Use this argument with any of the input argument combinations from the previous syntaxes.

streamline(___,Name=Value) sets properties of the streamline plot using one or more name-value arguments. For example, you can specify the color and thickness of the streamlines. For a list of properties, see Line Properties. (since R2024b)

streamline(ax,___) plots streamlines into the specified axes, instead of into the current axes object (gca).

lineobj = streamline(___) returns a vector of one or more Line objects. Use lineobj to modify properties of the streamlines after creating them. For a list of properties, see Line Properties.

Examples

Compute 3-D Streamlines

Load the wind data set which contains measurements of air current over regions of North America.

• 3-D arrays x, y, and z represent the locations of air current measurements.

• 3-D arrays u, v, and w represent the velocity of the air current in 3-D vector fields.

Define the starting position of 16 hypothetical particles. In this case, the particles all start at x = 80 and have starting y positions ranging from 20 to 50 and starting z positions ranging from 0 to 15.

load wind
[startX,startY,startZ] = meshgrid(80,20:10:50,0:5:15);

Compute the 3-D streamline vertex data for a hypothetical particle placed into the air current at the collection of starting positions in startX, startY, and startZ.

verts = stream3(x,y,z,u,v,w,startX,startY,startZ);

Visualize the 3-D volume of vector fields with streamline. Return the line objects in the variable lineobj, so you can change their properties later.

lineobj = streamline(verts);
view(3)

To change aspects of a particular line, set properties on one of the returned line objects. For example, change the color of the tenth line to green and change its thickness to 3.

lineobj(10).Color = "g";
lineobj(10).LineWidth = 3;

Compute 2-D Streamlines

Load the wind data set, which contains measurements of air current over regions of North America.

• 3-D arrays x and y represent the locations of air current measurements.

• 3-D arrays u and v represent the velocity of the air current in 3-D vector fields.

Use the fifth page of the arrays. Define the starting position of four hypothetical particles. In this case, the four starting locations are (80, 20), (80, 30), (80, 40), and (80, 50).

load wind
x5 = x(:,:,5);
y5 = y(:,:,5);
u5 = u(:,:,5);
v5 = v(:,:,5);
[startX,startY] = meshgrid(80,20:10:50);

Compute the 2-D streamline vertex data for a hypothetical particle placed into the air current with stream2.

verts = stream2(x5,y5,u5,v5,startX,startY);

Visualize the 2-D matrix of vector fields by calling streamline. Return the line objects in the variable lineobj, so you can change their properties later.

lineobj = streamline(verts);

To change aspects of a particular line, set properties on one of the returned line objects. For example, change the color of the second line to magenta and change its style to dashed.

lineobj(2).Color = "m";
lineobj(2).LineStyle = "--";

Plot Streamlines from Vertices

Load the wind dataset and compute the vertices of streamlines that start at evenly spaced points on the plane x = 80. Then, plot the streamlines from the vertex data.

load wind
[startX,startY,startZ] = meshgrid(80,20:10:50,0:5:15);
verts = stream3(x,y,z,u,v,w,startX,startY,startZ);
streamline(verts)
axis tight
view(3);

Input Arguments

X — x-coordinates of vector data

2-D array | 3-D array

x-axis coordinates of vector data, specified as a 2-D or 3-D array that can be combined with Y (and optionally Z) to form a grid of coordinates. You can use the meshgrid function to create the arrays.

X must be the same size as Y, Z, U, V, and W.

Y — y-coordinates of vector data

2-D array | 3-D array

y-axis coordinates of vector data, specified as a 2-D or 3-D array that can be combined with X (and optionally Z) to form a grid of coordinates. You can use the meshgrid function to create the arrays.

Y must be the same size as X, Z, U, V, and W.

Z — z-coordinates of vector data

3-D array

z-axis coordinates of vector data, specified as a 3-D array that can be combined with X and Y to form a grid of coordinates. You can use the meshgrid function to create the arrays.

Z must be the same size as X, Y, U, V, and W.

U — x-components

2-D array | 3-D array

x-components of vector data, specified as a 2-D or 3-D array. U must be the same size as X, Y, Z, V, and W.

V — y-components

2-D array | 3-D array

y-components of vector data, specified as a 2-D or 3-D array. V must be the same size as X, Y, Z, U, and W.

W — z-components

3-D array

z-components of vector data, specified as a 3-D array. W must be the same size as X, Y, Z, U, and V.

startX — x-axis streamline starting positions

scalar | vector | matrix

x-axis streamline starting positions, specified as a vector or matrix. startX must be a scalar or be the same size as startY and startZ.

startY — y-axis streamline starting positions

scalar | vector | matrix

y-axis streamline starting positions, specified as a vector or matrix. startY must be a scalar or be the same size as startX and startZ.

startZ — z-axis streamline starting positions

scalar | vector | matrix

z-axis streamline starting positions, specified as a vector or matrix. startZ must be a scalar or be the same size as startX and startY.

verts — Streamline vertices

cell array

Streamline vertices, specified as a cell array (as returned by stream2, stream3, or streamslice). Each element of the cell array is a matrix of vertices for one line.

options — Streamline options

[0.1, 10000] (default) | one-element vector | two-element vector

Streamline options, specified as a one- or two-element vector with one of the following forms:

• step

• [step,maxvert]

step is the step size used to adjust the streamline resolution and determine the vertex locations for which streamline velocity is interpolated. maxvert is the maximum number of vertices calculated for a streamline before computation is complete.

The default step-size is 0.1, and the default maximum number of vertices is 10,000.

ax — Target axes

Axes object

Target axes, specified as an Axes object. If you do not specify the axes, then the streamline function uses the current axes.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: streamline(verts,LineWidth=2) plots streamlines with a two-point line thickness.

Note

The properties listed here are only a subset. For a full list, see Line Properties.

Color — Line color

[0 0 0] (default) | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Line color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of [0 0 0] corresponds to black.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

LineStyle — Line style

"-" (default) | "--" | ":" | "-." | "none"

Line style, specified as one of the options listed in this table.

Line Style	Description	Resulting Line
"-"	Solid line
"--"	Dashed line
":"	Dotted line
"-."	Dash-dotted line
"none"	No line	No line

LineWidth — Line width

0.5 (default) | positive value

Line width, specified as a positive value in points, where 1 point = 1/72 of an inch. If the line has markers, then the line width also affects the marker edges.

The line width cannot be thinner than the width of a pixel. If you set the line width to a value that is less than the width of a pixel on your system, the line displays as one pixel wide.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The streamline function supports GPU array input with these usage notes and limitations:

• This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• This function operates on distributed arrays, but executes in the client MATLAB.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2024b: Control appearance and behavior with name-value arguments

Control the appearance and behavior of streamline plots by specifying name-value arguments. Previously, streamline did not support name-value arguments.

R2023b: Default line color is has changed

When you create a streamline plot, MATLAB automatically assigns colors and line styles the same way as for most other plots. For example, the first set of lines created with streamline are now a soft blue color.

To preserve the appearance from previous releases, use the set function to set the Color property to [0 0 1].

lineobj = streamline(verts);
set(lineobj,Color=[0 0 1])