Main Content

getframe

Capture axes or figure as movie frame

Description

example

F= getframecaptures the current axes as it appears on the screen as a movie frame.Fis a structure containing the image data.getframecaptures the axes at the same size that it appears on the screen. It does not capture tick labels or other content outside the axes outline.

example

F= getframe(ax)captures the axes identified byaxinstead of the current axes.

example

F= getframe(无花果)captures the figure identified by无花果. Specify a figure if you want to capture the entire interior of the figure window, including the axes title, labels, and tick marks. The captured movie frame does not include the figure menu and tool bars.

F= getframe(___,rect)captures the area within the rectangle defined byrect. Specifyrectas a four-element vector of the form[left bottom width height]. Use this option with either theaxor无花果input arguments in the previous syntaxes.

Examples

collapse all

Create a plot of random data. Capture the axes and return the image data.getframecaptures the interior of the axes and the axes outline. It does not capture content that extends beyond the axes outline.

plot(rand(5)) F = getframe;

Fis a structure with the fieldcdatathat contains the captured image data.

Display the captured image data usingimshow.

无花果ure imshow(F.cdata)

Create a surface plot. Capture the interior of the figure window, excluding the menu and tool bars.

surf(peaks) F = getframe(gcf);

Fis a structure with the fieldcdatathat contains the captured image data.

Display the captured image data in a figure with a darker background usingimshow, so you can see captured area.

无花果ure('Color',[0.5 0.5 0.5]) imshow(F.cdata)

Capture the interior of an axes plus a margin of 30 pixels in each direction. The added margin is necessary to include the tick labels in the capture frame. Depending on the size of the tick labels, the margin might need to be adjusted.

Create a plot of random data.

plot(rand(5))

Change the axes units to pixels and return the current axes position. The third and fourth elements of the position vector specify the axes width and height in pixels.

drawnow ax = gca; ax.Units ='pixels'; pos = ax.Position
pos = 73.8000 47.2000 434.0000 342.3000

Create a four-element vector,rect, that defines a rectangular area covering the axes plus the desired margin. The first two elements ofrectspecify the lower left corner of the rectangle relative to the lower left corner of the axes. The last two elements ofrectspecify the width and height of the rectangle. Reset the axes units to the default value of'normalized'.

marg = 30; rect = [-marg, -marg, pos(3)+2*marg, pos(4)+2*marg]; F = getframe(gca,rect); ax.Units ='normalized';

Display the captured image data in a figure with a darker background usingimshow, so you can see captured area.

无花果ure('Color',[0.5 0.5 0.5]) imshow(F.cdata)

Calculate a margin around the axes so that the captured image data includes the title, axis labels, and tick labels.

Create a plot with a title and anx-axis label.

情节(兰德(5))包含('x values') title('Plot of Random Data')

Change the axes units to pixels and store thePositionandTightInsetproperty values for the axes. TheTighInsetproperty is a four-element vector of the form[left bottom right top]. The values are the margins used around the axes for the tick values and text labels.

drawnow ax = gca; ax.Units ='pixels'; pos = ax.Position; ti = ax.TightInset;

Create a four-element vector,rect, that defines a rectangular area covering the axes plus the automatically calculated margin. The first two elements ofrectspecify the lower left corner of the rectangle relative to the lower left corner of the axes. The last two elements ofrectspecify the width and height of the rectangle.

rect = [-ti(1), -ti(2), pos(3)+ti(1)+ti(3), pos(4)+ti(2)+ti(4)]; F = getframe(ax,rect);

Display the captured image data in a figure with a darker background usingimshow, so you can see captured area.

无花果ure('Color',[0.5 0.5 0.5]) imshow(F.cdata)

Starting in R2019b, you can display a tiling of plots using thetiledlayoutandnexttilefunctions. Call thetiledlayoutfunction to create a 2-by-1 tiled chart layout. Call thenexttilefunction to create the axes objectsax1andax2. Plot a line in each axes.

tiledlayout(2,1) ax1 = nexttile; plot(1:10,'b') ax2 = nexttile; plot(1:10,'r')

Capture the contents of the lower axes.getframecaptures the interior and border of the plot. It does not capture tick values or labels that extend beyond the outline of the plot.

F = getframe(ax2);

Display the captured image data usingimshow.

无花果ure imshow(F.cdata)

Record frames of thepeaksfunction vibrating by usinggetframein a loop. Preallocate an array to store the movie frames.

Z = peaks; surf(Z) axistightmanualax = gca; ax.NextPlot ='replaceChildren'; loops = 40; F(loops) = struct('cdata',[],'colormap',[]);forj = 1:loops X = sin(j*pi/10)*Z; surf(X,Z) drawnow F(j) = getframe(gcf);end

Playback the movie two times.

无花果= figure; movie(fig,F,2)

Input Arguments

collapse all

Axes to capture, specified as anAxesobject or aGeographicAxesobject. Use this option if you want to capture an axes that is not the current axes.

getframecaptures the content within the smallest rectangle that encloses the axes outline. If you want to capture all the tick values and labels, then use the无花果input argument instead.

Example:F = getframe(ax);

Figure to capture, specified as aFigureobject.

Rectangular area to capture, specified as a four-element vector of the form[left bottom width height]inpixels. Theleftandbottomelements define the position of the lower left corner of the rectangle. The position is relative to the figure or axes that is specified as the first input argument togetframe. Thewidthandheightelements define the dimensions of the rectangle.

Specify a rectangle that is fully contained within the figure window.

Output Arguments

collapse all

Movie frame, returned as a structure with two fields:

  • cdata— The image data stored as an array ofuint8values. The size of the image data array depends on your screen resolution.

  • colormap— The colormap. On true color systems, this field is empty.

Note

These are some important considerations about the size ofcdata:

  • If you query the size of the region thatgetframecaptures (either the figure, the axes, or the region specified byrect), the size inpixelsmight not match the number of elements incdata. This difference is because the number of elements incdatadepends on your screen resolution (and operating system settings), but pixels in MATLAB®might not correspond to the actual pixels on your screen.

  • Starting in R2015b, if you are using a high-resolution system, then the size ofcdatamight be larger than in previous releases or on other systems.

Limitations

  • getframedoes not support the following functionality inMATLAB Online™or inWeb Apps(MATLAB Compiler):

    • Capturing the contents of a figure created with theuifigurefunction or any axes in the figure.

    • Capturing the contents of an app created with App Designer or any axes in the app.

More About

collapse all

Pixels

Distances in pixels are independent of your system resolution on Windows®andMacintoshsystems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • OnMacintoshsystems, a pixel is 1/72nd of an inch.

On Linux®systems, the size of a pixel is determined by your system resolution.

Tips

  • For the fastest performance when usinggetframe, make sure that the figure is visible on the screen. If the figure is not visible,getframecan still capture the figure, but performance can be slower.

  • 控制图像的分辨率data, use theprintfunction instead. Thecdataoutput argument with print returns the image data. Theresolutioninput argument controls the resolution of the image.

Version History

Introduced before R2006a