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 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). This utility also enables adding a toolbar button for easy interactive screen-capture.

Syntax:
     imageData = screencapture(handle, position, filename, '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.

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

   'PropName',PropValue -
                  optional list of property pairs
                    e.g., screencapture('filename','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)
                    - 'filename' (default: '')
                    - 'toolbar' (figure handle; default: gcf)
                    this adds a screen-capture button to the figure's toolbar
                    If this parameter is sspecified, 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 filename.
 
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,'filename','myFigure.jpg'); % same as previous
   screencapture('toolbar',gcf); % adds a screen-capture button to gcf's toolbar
   screencapture('toolbar',[],'file','sc.bmp'); % same with default output filename
 
Bugs and suggestions:
   Please send to Yair Altman (altmany at gmail dot com)

• Acknowledgements: This submission has inspired the following:; jMouseEmu: Mouse Emulator (v2.2)
• MATLAB release: MATLAB 7.5 (R2007b)
• Other requirements: Requires Java engine, but as far as I can tell this utility does NOT use any undocumented/unsupported Matlab features. Developed on Matlab R2007b but should also work on other Matlab versions (untested - please report any issues)

[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

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

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

[Dinie Muhammad]

 

[Brandon]

 

[Yanxiong Li]