Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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.

example

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.

example

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 (gca). The option ax can precede any of the input argument combinations in the previous syntaxes.

Examples

collapse all

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

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);

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

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 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

Control the animation speed by running 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

collapse all

Initial x values for the animated line, specified as a scalar or vector. The input x must be equal in size to y.

Example: 1:10

Data Types: double

Initial y values for the animated line, specified as a scalar or vector. The input y must be equal in size to x.

Example: 1:10

Data Types: double

Initial z values for the animated line, specified as a scalar or vector. The input z must be equal in size to x and y.

Example: 1:10

Data Types: double

Axes object. If you do not specify an axes object, then animatedline uses the current axes.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Color','red','Marker','o'

The animated line properties listed here are only a subset. For a complete list, see AnimatedLine Properties.

collapse all

Line color, specified as an RGB triplet or one of the color options listed in the table. The default value of [0 0 0] corresponds to black.

For a custom color, specify an RGB triplet. 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]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

OptionDescriptionEquivalent RGB Triplet
'red' or 'r'Red[1 0 0]
'green' or 'g'Green[0 1 0]
'blue' or 'b'Blue[0 0 1]
'yellow' or 'y'Yellow[1 1 0]
'magenta' or 'm'Magenta[1 0 1]
'cyan' or 'c'Cyan[0 1 1]
'white' or 'w'White[1 1 1]
'black' or 'k'Black[0 0 0]
'none'No colorNot applicable

Example: [0.4 0.6 0.7]

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

Line StyleDescriptionResulting Line
'-'Solid line

'--'Dashed line

':'Dotted line

'-.'Dash-dotted line

'none'No lineNo line

Line width, specified as a positive value in points. If the line has markers, then the line width also affects the marker edges.

Example: 0.75

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

ValueDescription
'o'Circle
'+'Plus sign
'*'Asterisk
'.'Point
'x'Cross
'square' or 's'Square
'diamond' or 'd'Diamond
'^'Upward-pointing triangle
'v'Downward-pointing triangle
'>'Right-pointing triangle
'<'Left-pointing triangle
'pentagram' or 'p'Five-pointed star (pentagram)
'hexagram' or 'h'Six-pointed star (hexagram)
'none'No markers

Marker size, specified as a positive value in points.

Example: 10

Marker outline color, specified as 'auto', an RGB triplet, or one of the color options listed in the table. The default value of 'auto' uses the same color as the Color property.

For a custom color, specify an RGB triplet. 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]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

OptionDescriptionEquivalent RGB Triplet
'red' or 'r'Red[1 0 0]
'green' or 'g'Green[0 1 0]
'blue' or 'b'Blue[0 0 1]
'yellow' or 'y'Yellow[1 1 0]
'magenta' or 'm'Magenta[1 0 1]
'cyan' or 'c'Cyan[0 1 1]
'white' or 'w'White[1 1 1]
'black' or 'k'Black[0 0 0]
'none'No colorNot applicable

Example: [0.5 0.5 0.5]

Example: 'blue'

Marker fill color, specified as 'auto', an RGB triplet, or one of the color options listed in the table. The 'auto' value uses the same color as the Color property for the axes.

For a custom color, specify an RGB triplet. 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]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

OptionDescriptionEquivalent RGB Triplet
'red' or 'r'Red[1 0 0]
'green' or 'g'Green[0 1 0]
'blue' or 'b'Blue[0 0 1]
'yellow' or 'y'Yellow[1 1 0]
'magenta' or 'm'Magenta[1 0 1]
'cyan' or 'c'Cyan[0 1 1]
'white' or 'w'White[1 1 1]
'black' or 'k'Black[0 0 0]
'none'No colorNot applicable

Example: [0.3 0.2 0.1]

Example: 'green'

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

collapse all

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.

Tips

  • Animated lines do not support data tips.

Introduced in R2014b

Was this topic helpful?