MATLAB Function Reference

getframe - Capture movie frame

Syntax

getframe F = getframe F = getframe(h) F = getframe(h,rect)

Description

getframe returns a movie frame. The frame is a snapshot (pixmap) of the current axes or figure.

F = getframe gets a frame from the current axes.

F = getframe(h) gets a frame from the figure or axes identified by handle h.

F = getframe(h,rect) specifies a rectangular area from which to copy the pixmap. rect is relative to the lower left corner of the figure or axes h, in pixel units. rect is a four-element vector in the form [left bottom width height], where width and height define the dimensions of the rectangle.

getframe returns a movie frame, which is a structure having two fields:

cdata — The image data stored as a matrix of uint8 values. The dimensions of F.cdata are height-by-width-by-3.
colormap — The colormap stored as an n-by-3 matrix of doubles. F.colormap is empty on true color systems.

To capture an image, use this approach:

F = getframe(gcf);
image(F.cdata)
colormap(F.colormap)

Remarks

getframe is usually used in a for loop to assemble an array of movie frames for playback using movie. For example,

for j = 1:n	plotting commands
	F(j) = getframe;
end
movie(F)

If you are capturing frames of a plot that takes a long time to generate or are repeatedly calling getframe in a loop, make sure that your computer's screen saver does not activate and that your monitor does not turn off for the duration of the capture; otherwise one or more of the captured frames can contain graphics from your screen saver or nothing at all.

Note In situations where MATLAB^® software is running on a virtual desktop that is not currently visible on your monitor, calls to getframe will complete, but will capture a region on your monitor that corresponds to the position occupied by the figure or axes on the hidden desktop. Therefore, make sure that the window to be captured by getframe exists on the currently active desktop.

Capture Regions

Note that F = getframe returns the contents of the current axes, exclusive of the axis labels, title, or tick labels. F = getframe(gcf) captures the entire interior of the current figure window. To capture the figure window menu, use the form F = getframe(h,rect) with a rectangle sized to include the menu.

Resolution of Captured Frames

The resolution of the framed image depends on the size of the axes in pixels when getframe is called. As the getframe command takes a snapshot of the screen, if the axes is small in size (e.g., because you have restricted the view to a window within the axes), getframe will capture fewer screen pixels, and the captured image might have poor resolution if enlarged for display.

Capturing UIControls and Information Bars

If your figure contains uicontrols or displays the linking and brushing message bar along its top, F = getframe(figure_handle) captures them, along with the axes and any annotations displayed on the plot. F = getframe does not capture the message bar or uicontrols outside of the current axes. To avoid including the message bar when capturing the entire figure, click the X button on the message bar to dismiss it before running getframe. Once you do this, the message bar does not appear on subsequent figures unless you reset a preference to show it.

Examples

Make the peaks function vibrate.

Z = peaks; surf(Z)
axis tight
set(gca,'nextplot','replacechildren');
for j = 1:20
    surf(sin(2*pi*j/20)*Z,Z)
    F(j) = getframe;
end
movie(F,20) % Play the movie twenty times