Main Content

streamparticles

Plot stream particles

collapse all in page

    Syntax

    streamparticles(verts)
    streamparticles(verts,n)
    streamparticles(___,Name,Value)
    streamparticles(target,___)
    lineobj = streamparticles(___)

    Description

    streamparticles(verts) plots stream particles at each vertex of the streamlines of a vector field. Stream particles can show the position and velocity of a streamline.

    example

    streamparticles(verts,n) uses n to determine how many stream particles to plot. n can represent the number of particles or a percentage of streamline vertices. You can use the ParticleAlignment name-value argument with this syntax to change how streamparticles uses n.

    example

    streamparticles(___,Name,Value) modifies stream particle animation and appearance by using one or more name-value arguments to set properties. For example, you can set the shape of the particles using the Marker property. Specify name-value arguments after all the arguments in any of the previous syntaxes. For a list of properties, see Line Properties.

    example

    streamparticles(target,___) uses the target object to create the stream particles plot. If the target object is an Axes object, then MATLAB® plots into the specified axes instead of the current axes (gca). If the target object is a Line object, then the line properties are updated to create the stream particles instead of creating a new Line object.

    lineobj = streamparticles(___) returns the Line object that contains all particle vertices.

    Examples

    collapse all

    Open Live Script

    Create vertices for two streamlines, specified as x- and y-coordinates in 15-by-2 matrices. Define the vertex input to streamparticles as a cell array, where each element represents one streamline.

    x = linspace(0,2*pi,15);
y1 = sin(x); 
y2 = sin(x) + 1;

s1 = [x;y1]';
s2 = [x;y2]';
verts = {s1,s2};

    Plot particles at each vertex of the streamlines.

    streamparticles(verts);

    Figure contains an axes object. The axes contains a line object which displays its values using only markers.

    Open Live Script

    Define a vector field using position and velocity matrices. Use streamslice to generate the vertices of the streamlines in the vector field, and store the vertices in verts.

    [x,y] = meshgrid(-10:10);
u = 2.*x.*y;
v = y.^2 - x.^2;
[verts,~] = streamslice(x,y,u,v);

    Plot the streamlines with streamline. Then, plot 100 particles with streamparticles. By default, the particles are spaced evenly over all the vertices.

    streamline(verts);
streamparticles(verts,100);

    Figure contains an axes object. The axes object contains 64 objects of type line. One or more of the lines displays its values using only markers

    For the same vector field, plot five particles evenly over the streamline with the most vertices by setting the ParticleAlignment property to "on". The streamparticles function uses that spacing to plot particles on the remaining streamlines.

    streamline(verts);
streamparticles(verts,5,"ParticleAlignment","on");

    Figure contains an axes object. The axes object contains 128 objects of type line.

    For the same vector field, plot 5% of the streamline vertices as particles.

    streamline(verts);
streamparticles(verts,0.05);

    Figure contains an axes object. The axes object contains 192 objects of type line.

    Open Live Script

    Create the vertices for a vector field, and plot its streamlines and stream particles. Animate the particles for five iterations at 30 frames per second by setting the Animate and FrameRate properties, respectively.

    [x,y] = meshgrid(-10:10);
u = 2.*x.*y;
v = y.^2 - x.^2;
[verts,~] = streamslice(x,y,u,v);

streamline(verts);
streamparticles(verts,100,"Animate",5,"FrameRate",30);

    Figure contains an axes object. The axes object contains 64 objects of type line. One or more of the lines displays its values using only markers

    Open Live Script

    Create the vertices for a vector field, and plot its streamlines and stream particles. Use green asterisk markers for the particles by setting the Marker and MarkerEdgeColor properties.

    [x,y] = meshgrid(-10:10); 
u = 2.*x.*y;
v = y.^2 - x.^2;
[verts,~] = streamslice(x,y,u,v);

streamline(verts);
streamparticles(verts,150,"Marker","*","MarkerEdgeColor",[0 0.5 0]);

    Figure contains an axes object. The axes object contains 64 objects of type line. One or more of the lines displays its values using only markers

    Input Arguments

    collapse all

    Streamline coordinate data, specified as a cell array (as returned by stream2, stream3, or streamslice). Each element of the cell array is a matrix of 2-D or 3-D vertices that defines one streamline, where each row represents the coordinates of one particle.

    Number of stream particles, specified as a positive value.

    • If n is greater than 1, streamparticles plots approximately n particles.

    • If n is less than or equal to 1, streamparticles plots a percentage of the vertices as particles. For example, if n is 0.2, streamparticles plots approximately 20% of the vertices.

    By default, streamparticles plots the number of particles determined by n evenly over all streamline vertices. However, if you set the ParticleAlignment property to "on", streamparticles plots the particles evenly over the streamline with the most vertices and then uses that particle spacing for the other streamlines.

    Target object, specified as an Axes or a Line object.

    • Axes object — streamparticles plots into the specified axes instead of the current axes.

    • Line object — The line properties are updated to create the stream particles instead of creating a new Line object.

    You can display a legend in a streamparticles plot by creating a Line object, calling legend, and then calling streamparticles with that line as the target object.

    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: streamparticles(verts,MarkerFaceColor="blue") specifies a blue marker for the stream particles.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: streamparticles(verts,"MarkerFaceColor","blue") specifies a blue marker for the stream particles.

    Note

    The line properties listed here are only a subset of properties that can change particle appearance. For a complete list, see Line Properties.

    Number of animation iterations, specified as a nonnegative integer. By default, the value of Animate is 0, which specifies no stream particle motion. If the value is Inf, the animation continues until you press Ctrl+C.

    Animation frames per second, specified as a nonnegative integer. By default, the value of FrameRate is Inf, which draws the animation as fast as possible given the limitations of the machine running streamparticles.

    Alignment of particles on streamlines, specified as "off" or "on".

    • If ParticleAlignment is "off", n determines the number of particles plotted, evenly spaced over all streamline vertices.

    • If ParticleAlignment is "on", n determines the number of particles plotted, evenly spaced over the streamline with the most vertices. The streamparticles function uses this spacing to plot particles on the remaining streamlines.

    Marker symbol, specified as one of the values listed in this table. By default, particles are displayed as circles. If the marker symbol does not have a face, for instance, "*", the marker edge color must be specified.

    MarkerDescriptionResulting Marker
    "o"Circle

    Sample of circle marker

    "+"Plus sign

    Sample of plus sign marker

    "*"Asterisk

    Sample of asterisk marker

    "."Point

    Sample of point marker

    "x"Cross

    Sample of cross marker

    "_"Horizontal line

    Sample of horizontal line marker

    "|"Vertical line

    Sample of vertical line marker

    "square"Square

    Sample of square marker

    "diamond"Diamond

    Sample of diamond marker

    "^"Upward-pointing triangle

    Sample of upward-pointing triangle marker

    "v"Downward-pointing triangle

    Sample of downward-pointing triangle marker

    ">"Right-pointing triangle

    Sample of right-pointing triangle marker

    "<"Left-pointing triangle

    Sample of left-pointing triangle marker

    "pentagram"Pentagram

    Sample of pentagram marker

    "hexagram"Hexagram

    Sample of hexagram marker

    "none"No markersNot applicable

    Marker outline color, specified as "none", an RGB triplet, a hexadecimal color code, a color name, or a short name. By default, there is no marker outline color.

    RGB triplets and hexadecimal color codes are useful for specifying custom colors.

    • 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 character vector or a string scalar 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. Thus, 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

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

    RGB TripletHexadecimal Color CodeAppearance
    [0 0.4470 0.7410]"#0072BD"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Marker fill color, specified as "red", "none", an RGB triplet, a hexadecimal color code, a color name, or a short name. By default, the marker fill color is red.

    RGB triplets and hexadecimal color codes are useful for specifying custom colors.

    • 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 character vector or a string scalar 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. Thus, 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

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

    RGB TripletHexadecimal Color CodeAppearance
    [0 0.4470 0.7410]"#0072BD"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Extended Capabilities

    Version History

    Introduced before R2006a

    See Also

    Functions

    Properties

    Topics