animatedline

Create animated line

Syntax

an = animatedline

an = animatedline(x,y)

an = animatedline(x,y,z)

an = animatedline(___,Name,Value)

an = animatedline(ax,___)

Description

an = animatedline creates an animated line that has no data and adds it to the current axes. Create an animation by adding points to the line in a loop using the addpoints function.

an = animatedline(x,y) creates an animated line with initial data points defined by x and y.

an = animatedline(x,y,z) creates an animated line with initial data points defined by x, y, and z.

an = animatedline(___,Name,Value) specifies animated line properties using one or more name-value pair arguments. For example, 'Color','r' sets the line color to red. Use this option after any of the input argument combinations in the previous syntaxes.

an = animatedline(ax,___) creates the line in the axes specified by ax instead of in the current axes. Specify ax before all other input arguments in any of the previous syntaxes.

Examples

Display Line Animation

Create the initial animated line object. Then, use a loop to add 1,000 points to the line. After adding each new point, use drawnow to display the new point on the screen.

h = animatedline;
axis([0,4*pi,-1,1])

x = linspace(0,4*pi,1000);
y = sin(x);
for k = 1:length(x)
    addpoints(h,x(k),y(k));
    drawnow
end

For faster rendering, add more than one point to the line each time through the loop or use drawnow limitrate.

Query the points of the line.

[xdata,ydata] = getpoints(h);

Clear the points from the line.

clearpoints(h)
drawnow

Specify Animated Line Color

Set the color of the animated line to red and set its line width to 3 points.

x = [1 2];
y = [1 2];
h = animatedline(x,y,'Color','r','LineWidth',3);

Specify Datetime and Duration Values

To plot nonnumeric points, such as datetime and duration values, start by initializing the animated line with values of the type you want to plot. You can specify either the first point in your plot or placeholder values such as NaT or NaN.

For example, plot datetime values on the x-axis and duration values (minutes) on the y-axis. Initialize the animated line with a NaT value and a minutes(NaN) value. Then create a datetime vector (x) and a duration vector (y) and add the points in those vectors to the animated line.

an = animatedline(NaT,minutes(NaN),"Marker","o");
x = datetime(2018,5,1:5);
y = minutes([1 7 3 11 4]);
addpoints(an,x,y)

Set Maximum Number of Points

Limit the number of points in the animated line to 100. Use a loop to add one point to the line at a time. When the line contains 100 points, adding a new point to the line deletes the oldest point.

h = animatedline('MaximumNumPoints',100);
axis([0,4*pi,-1,1])

x = linspace(0,4*pi,1000);
y = sin(x);
for k = 1:length(x)
    addpoints(h,x(k),y(k));
    drawnow
end

Add Points in Sets for Fast Animation

Use a loop to add 100,000 points to an animated line. Since the number of points is large, adding one point to the line each time through the loop might be slow. Instead, add 100 points to the line each time through the loop for a faster animation.

h = animatedline;
axis([0,4*pi,-1,1])

numpoints = 100000;
x = linspace(0,4*pi,numpoints);
y = sin(x);
for k = 1:100:numpoints-99
    xvec = x(k:k+99);
    yvec = y(k:k+99);
    addpoints(h,xvec,yvec)
    drawnow
end

Another technique for creating faster animations is to use drawnow limitrate instead of drawnow.

Use drawnow limitrate for Fast Animation

Use a loop to add 100,000 points to an animated line. Since the number of points is large, using drawnow to display the changes might be slow. Instead, use drawnow limitrate for a faster animation.

h = animatedline;
axis([0,4*pi,-1,1])

numpoints = 100000;
x = linspace(0,4*pi,numpoints);
y = sin(x);
for k = 1:numpoints
    addpoints(h,x(k),y(k))
    drawnow limitrate
end

Time Screen Updates for Efficiency

Run through several iterations of the animation loop before drawing the updates on the screen. Use this technique when drawnow is too slow and drawnow limitrate is too fast.

For example, update the screen every 1/30 seconds. Use the tic and toc commands to keep track of how much time passes between screen updates.

h = animatedline;
axis([0,4*pi,-1,1])
numpoints = 10000;
x = linspace(0,4*pi,numpoints);
y = sin(x);
a = tic; % start timer
for k = 1:numpoints
    addpoints(h,x(k),y(k))
    b = toc(a); % check timer
    if b > (1/30)
        drawnow % update screen every 1/30 seconds
        a = tic; % reset timer after updating
    end
end
drawnow % draw final frame

A smaller interval updates the screen more often and results in a slower animation. For example, use b > (1/1000) to slow down the animation.

Input Arguments

x — Starting x-coordinate

[] (default) | scalar or vector

Starting x-coordinate, specified as a scalar or vector the same size as y.

In polar coordinates, x corresponds to the starting theta value. In geographic coordinates, x corresponds to the starting latitude in degrees.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

y — Starting y-coordinate

[] (default) | scalar or vector

Starting y-coordinate, specified as a scalar or vector the same size as x.

In polar coordinates, y corresponds to the starting radius value. In geographic coordinates, y corresponds to the starting longitude in degrees.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

z — Starting z-coordinate

[] (default) | scalar or vector

Starting z-coordinate, specified as a scalar or vector.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

ax — Target axes

any type of axes | Group object | Transform object

Target axes, specified as any type of axes, a Group object, or a Transform object. If you do not specify this argument, then animatedline 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: animatedline(x,y,Color="red",Marker="o") creates an animated line with red circular markers.

Before R2021a: use commas to separate each name and value, and enclose Name in quotes. for example, animatedline(x,y,"Color","red","Marker","o") creates an animated line with red circular markers.

The animated line properties listed here are only a subset. For a complete list, see AnimatedLine 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.

Marker — Marker symbol

"none" (default) | "o" | "+" | "*" | "." | ...

Marker symbol, specified as one of the values listed in this table. By default, the object does not display markers. Specifying a marker symbol adds markers at each data point or vertex.

Marker	Description	Resulting Marker
"o"	Circle
"+"	Plus sign
"*"	Asterisk
"."	Point
"x"	Cross
"_"	Horizontal line
"|"	Vertical line
"square"	Square
"diamond"	Diamond
"^"	Upward-pointing triangle
"v"	Downward-pointing triangle
">"	Right-pointing triangle
"<"	Left-pointing triangle
"pentagram"	Pentagram
"hexagram"	Hexagram
"none"	No markers	Not applicable

MarkerSize — Marker size

6 (default) | positive value

Marker size, specified as a positive value in points, where 1 point = 1/72 of an inch.

MarkerEdgeColor — Marker outline color

'auto' (default) | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b'

Marker outline color, specified as "auto", an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of "auto" uses the same color as the Color property.

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"

MarkerFaceColor — Marker fill color

'none' (default) | 'auto' | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b'

Marker fill color, specified as "auto", an RGB triplet, a hexadecimal color code, a color name, or a short name. The "auto" option uses the same color as the Color property of the parent axes. If you specify "auto" and the axes plot box is invisible, the marker fill color is the color of the figure.

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"

MaximumNumPoints — Maximum number of points stored and displayed

1000000 (default) | positive value | Inf

Maximum number of points stored and displayed as part of the line, specified as a positive value or Inf. By default, the value is one million points. If the number of points exceeds the maximum value permitted, then the animated line keeps the most recently added points and drops points from the beginning of the line. These dropped points no longer display on the screen and are not returned when using getpoints.

Use this property to limit the number of points appearing on the screen at any given time or to limit the amount of memory used. If you specify the value as Inf, then the animated line does not drop any points, but the number of points stored is limited by the amount of memory available.

Example: 10

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

an — AnimatedLine object

AnimatedLine object

AnimatedLine object. Use an to modify the AnimatedLine object after its been created, such as changing property values or adding points to the line. For a list of properties, see AnimatedLine Properties.

Limitations

Animated lines do not support data tips.

Extended Capabilities

GPU Arrays

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

The animatedline 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 in R2014b

R2023a: Specify single, double, integer, datetime, or duration coordinates

Create animated lines using single, double, integer, datetime, or duration data for the x-, y-, and z-coordinates.