ScreenCapture - get a screen-capture of a figure frame or component

ScreenCapture gets a screen-capture of any Matlab GUI handle, or specified screen area rectangle

Description

ScreenCapture gets a screen-capture of any Matlab GUI handle (including desktop, figure, axes, image, or uicontrol), or a specified area rectangle located relative to the specified handle.

Screen area capture is possible by specifying the root (desktop) handle (=0).

The output can be either to an image file or to a Matlab matrix (useful for displaying via imshow() or for further processing), or to the system clipboard.

This utility also enables adding a toolbar button for easy interactive screen-capture.

Syntax:
     imageData = screencapture(handle, position, target, 'PropName',PropValue, ...)
 
Input Parameters:
     handle - optional handle to be used for screen-capture origin.
                  If empty/unsupplied then current figure (gcf) will be used.

     position - optional position array in pixels: [x,y,width,height].
                  If empty/unsupplied then the handle's position vector will be used.
                  If both handle and position are empty/unsupplied then the position
                    will be retrieved via interactive mouse-selection.
                  If handle is an image, then position is in data (not pixel) units, so the
                    captured region remains the same after figure/axes resize (like imcrop)

     target - optional filename for storing the screen-capture, or the 'clipboard' string.
                  If empty/unsupplied then no output to file will be done.
                  The file format will be determined from its extension (JPG/PNG/...).
                  Supported formats are those supported by the imwrite function.
                  If neither target nor imageData were specified, the user will be asked to
                    interactively specify the output file.

     'PropName',PropValue -
                  optional list of property pairs
                    e.g., screencapture('target','sc.png','pos',[10,20,30,40],'handle',gca)
                  PropNames may be abbreviated and are case-insensitive.
                  PropNames may also be given in whichever order.
                  Supported PropNames are:
                    - 'handle' (default: gcf handle)
                    - 'position' (default: gcf position array)
                    - 'target' (default: '')
                    - 'toolbar' (figure handle; default: gcf)
                    this adds a screen-capture button to the figure's toolbar
                    If this parameter is specified, then no screen-capture
                    will take place and the returned imageData will be [].

Output parameters:
     imageData - image data in a format acceptable by the imshow function.
                    If neither filename nor imageData were specified,
                    the user will be asked to interactively specify the output file.
 
Examples:
     imageData = screencapture; % interactively select screen-capture rectangle
     imageData = screencapture(hListbox); % capture image of a uicontrol
     imageData = screencapture(0, [20,30,40,50]); % select a small desktop region
     imageData = screencapture(gcf,[20,30,40,50]); % select a small figure region
     imageData = screencapture(gca,[10,20,30,40]); % select a small axes region
        imshow(imageData); % display the captured image in a matlab figure
        imwrite(imageData,'myImage.png'); % save the captured image to file
     screencapture(gcf,[],'myFigure.jpg'); % capture the entire figure into file
     screencapture('handle',gcf,'target','myFigure.jpg'); % same as previous
     screencapture('handle',gcf,'target','clipboard'); % copy to system clipboard
     screencapture('toolbar',gcf); % adds a screen-capture button to gcf's toolbar
     screencapture('toolbar',[],'target','sc.bmp'); % same with default output filename
 
Technical description:
     http://UndocumentedMatlab.com/blog/screencapture-utility/

Bugs and suggestions:
     Please send to Yair Altman (altmany at gmail dot com)

Acknowledgements

Imclipboard and Set Fig Transparency Set Figure Transparency / Fading inspired this file.

This file inspired J Mouse Emu: Mouse Emulator (V2.2) and Data Explorer.

• Required Products: MATLAB
• MATLAB release: MATLAB 7.5 (R2007b)
• Other requirements: Requires Java engine. Developed on Matlab 7.5 (R2007b) but should work on all Matlab versions 6.1 (R12.1) or newer (not fully tested - please report any issues)

[Oliver Woodford]

Great tool. Worked when getframe() didn't.

[Maysam Shahedi]

It's cool!

[Adam Filion]

 

[Maofeng]

 

[Yair Altman]

@Mikhail - ScreenCapture uses java.awt.Robot, which only captures a bitmap image

[Mikhail]

Very nice!

How about capturing to a vector file format instead of a bitmap?

[Joerg]

 

[Yair Altman]

@Lapili Sanchez - the screencapture code already contains a corrected version of us's code - it was corrected in the code after "us" posted his comment above.

Moreover, this code is currently not used, since I have included even faster code, based on Jan Simon's comment. It is Jan Simon's faster code that is the current infrastructure of screencapture.

Take a look at the getScreenCaptureImageData() function within screencapture.m for more information

[lapili Sanchez]

>> % macro
>> conv=@(a,b,c) double(bitand(a,255^b))./255^c;

Just a small correction, that sentence from 'us' code should be:
conv=@(a,b,c) double(bitand(a,256^b-256^(b-1)))./256^c;

Thanks anyway, that code is so fast!

[Yanxiong Li]

 

[Brandon]

 

[Dinie Muhammad]

 

[Jan Simon]

Thanks Yair! The new version works for Matlab 6.5, if you download James Tursa's typecast replacement from the FEX (#17476).
Capturing the whole screen does not match the edges exactly. E.g. this is exact:
img = screencapture(0, 'Position', [1,-2,1024,768]);
But then the top left three pixels are [255,0,0], [0,255,0] and [0,0,255]. The rest of the image is fine. Under Matlab 2009a these funny pixels do not appear.

[Jan Simon]

Thanks for this exhaustively implemented screen capture tool. It works with some tiny modifications even in Matlab 6.5.
The conversion from the INT32 from getDataStorage to a Matlab RGB array can be done in the half time. Just let TYPECAST split the INT32 values instead of expensive BITSHIFT and BITAND (line 401):
pixelsData = reshape(typecast( ...
jImage.getData.getDataStorage, 'uint8'), 4, w, h);
imgData = cat(3, ...
transpose(reshape(pixelsData(3, :, :), w, h)), ...
transpose(reshape(pixelsData(2, :, :), w, h)), ...
transpose(reshape(pixelsData(1, :, :), w, h)));
This is the most time consuming part and a further acceleration might be useful.

[us]

a very nice robot, which the FEX community has been looking for a long time...
two thoughts:
1) in interactive mode, the user looses the data if no output arg is selected, which may be a bit frustrating:
a) a warning(?)
b) a new figure displaying the result by default(?)
2) we've been using this approach, which may be a bit faster (depending on the size of the capture) by converting the planes in one shot using a macro...

% input
% xoff/yoff/xlen/ylen
% assign after loading java stuff...
rob=Robot;
% macro
conv=@(a,b,c) double(bitand(a,255^b))./255^c;
% capture screen contents at this pos
rec=Rectangle(xoff,yoff,xlen,ylen);
cap=rob.createScreenCapture(rec);
dat=cap.getData;
buf=dat.getDataStorage;
buf=typecast(buf(:),'uint32');
buf=reshape(buf,dat.getWidth,dat.getHeight).';
mm=zeros([size(buf),3]);
mm(:,:,3)=conv(buf,1,0); % bitand(buf,255^1)./255^0;
mm(:,:,2)=conv(buf,2,1); % bitand(buf,255^2)./255^1;
mm(:,:,1)=conv(buf,3,2); % bitand(buf,255^3)./255^2;
mm=mm./255;
% ...for display in a regular figure
figure;
set(gca,'position',[0,0,1,1]);
image(mm);
axis image;
axis off;

3) in principle, the robot itself can be used on any screen location; it would be nice - however, admittedly cumbersome - to add this feature

us