Code covered by the BSD License  

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


4.9 | 17 ratings Rate this file 95 Downloads (last 30 days) File Size: 41.3 KB File ID: #24323
image thumbnail

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



01 Jun 2009 (Updated )

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

Editor's Notes:

This file was selected as MATLAB Central Pick of the Week

| Watch this File

File Information

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.

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

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


This file inspired J Mouse Emu: Mouse Emulator (V2.3) and Volumetric 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)
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (31)
26 Jun 2014 Said

Great tool,it does exactly what i need!!

12 Jun 2014 Robin  
11 Jun 2014 Murray

Ok fair enough. But the other issue I have is that the rect used to specify the position is not consistent with java coordinates (mentioned in your code). These have coordinates at top left - yours is bottom left and for some inexplicable reason (0,0) is off screen in your coordinate system. I see there are "estimated uncertainties" but where do these come from? Should be just a simple translation/reflection between the two with zero uncertainty. I can reverse engineer the offset and subtract it out but will this be different each time?

09 Jun 2014 Yair Altman

Murray - that's the entire point: the only way to interactively select a screen-capture box anywhere on the desktop (not just within a Matlab figure) is to create an almost-transparent figure that spans the entire desktop area, and then let the user click-and-drag within it. You don't need to find the edges at all - simply drag a box of your requested screen-capture area and then the almost-transparent window will disappear and you will get your desired screen-capture.

A technical explanation is provided here:

09 Jun 2014 Murray

The mouse click window for interactively selecting a target area doesn't appear to work very well. A window appears and then disappears (almost) when the prompt comes up but it remains almost invisible - pretty much impossible to find the edges.

14 Apr 2014 Yair Altman

Hannu - you are using the utility incorrectly. Look at the usage examples in the description for examples.

25 Mar 2014 Hannu K

screencapture(axesHandle,'target','filename.jpg') seems to save an image that's all black. The same thing happens if I give the gcf handle as an input.

The axes is in a gui with many other axes. I use guy layout -toolbox to position everything if that matters anything. I also use openGL renderer as I need transparency but I tried painters with similar results.

If I simply call screencapture() I get the Mouse click -prompt, but when I press ok the prompt and my gui become unselectable. If i press the Matlab-icon in my windows7 toolbar I see a new blank Matlab figure named 'Figure2' in the preview but I can't select it. I can still close it from the red cross and after that the prompt and my gui become selectable once again but no figure is saved of course.

What am I doing wrong?

28 Feb 2014 Jack Kohoutek

Excellent, succeeds where getframe fails with complicated figures w/ subfigures and axes

15 Feb 2014 Yair Altman

@Philipp - this is a byproduct of the builtin javaaddpath function, as you have found. It is a limitation of this function that has existed for ages and as far as I know has no known workaround. You might try to contact MathWorks to ask for this to be fixed, but don't hold your hopes too high...

14 Feb 2014 Philipp Pruefer

I found a small problem that I can’t fix in the code.

I am using ScreenCapture in a GUI where I have defined a few global variables. All those variables are deleted when I run ScreenCapture for the first time. I traced it back to the following function 'javaaddpath' which seems to delete my global variables. It is only called for the first time I run ScreenCapture as afterwards the java file is loaded.

% Add the necessary Java class (ImageSelection) to the Java classpath
if ~exist('ImageSelection', 'class')
javaaddpath([cd,'\Tools\ScreenCapture'], '-end');

My workaround is to load the java class during GUI loading. But maybe there is a better way of managing this in the script? Maybe there is a problem with my Matlab version which is 7.13 at the moment. Maybe it is time to upgrade…

14 Feb 2014 Philipp Pruefer  
20 Jan 2014 N

Fails with R2013b, on OSX Mavericks.

In fact, this seems to be an OSX/JVM issue.

in imclipboard: Data translation failed: not an image format

java version "1.6.0_65"
Java(TM) SE Runtime Environment (build 1.6.0_65-b14-462-11M4609)
Java HotSpot(TM) 64-Bit Server VM (build 20.65-b04-462, mixed mode)

20 Jan 2014 N

Fails with R2013b, on OSX Mavericks.

In fact, this seems to be an OSX/JVM issue. Data translation failed: not an image format

24 Nov 2013 Yair Altman

@Hong - you would need to know the exact pixel position vector of the external application and then you could use ScreenCapture on it from within Matlab. I do not know of an easy way to programmatically get the position vector for an external process, but I assume that it's possible - you'll need to search online for a solution I'm afraid.

24 Nov 2013 Hong

Excellent job, thank you so much!

However, since I am not very familiar with matlab, I would like to ask how can I screencapture an area in other application, for example Chrome, such that I can keep monitoring the application and response to it in later stages? Thank you so much!

22 May 2013 Jeremy

Works well, but seems to not be compilable.

23 Apr 2013 Oliver Woodford

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

20 Apr 2013 Maysam Shahedi

It's cool!

19 Apr 2013 Adam Filion  
07 Feb 2013 Maofeng  
13 Aug 2012 Yair Altman

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

13 Aug 2012 Mikhail

Very nice!

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

27 Apr 2012 Joerg  
10 Apr 2012 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

09 Apr 2012 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!

08 Jan 2012 Yanxiong Li  
19 Jul 2011 Brandon  
25 Feb 2011 Dinie Muhammad  
18 Jan 2011 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.

23 Nov 2010 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.

02 Jun 2009 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...
% macro
conv=@(a,b,c) double(bitand(a,255^b))./255^c;
% capture screen contents at this pos
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;
% ...for display in a regular figure
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


03 Jun 2009

Handle missing output format; performance boost (thanks to Urs); fix minor root-handle bug; added toolbar button option

03 Jun 2009

updated attached screenshot with explanatory notes

16 Jan 2011

another performance boost (thanks to Jan Simon); some compatibility fixes for Matlab 6.5 (untested)

30 Jul 2012

Capture current object if w=h=0 (clicking a single point); extra input args sanity checks; fix for docked windows; include axes labels & ticks by default when capturing axes; use data-units position vector when capturing images; many edge-case fixes

28 Jan 2013

Fixed capture of Desktop (root); enabled rbbox anywhere on desktop (not necesarily in a Matlab figure); enabled output to clipboard (based on Jiro Doke's imclipboard utility); edge-case fixes; added Java compatibility check

12 Feb 2013

FEX page credit to Jiro Doke's imclipboard utility

14 Feb 2013

(a more prominent acknowledgement of Jiro's imclipboard tool on the FEX page) - no changes to the actual files

19 Apr 2013

Fixed bug in capture of non-square image; fixes for Win64

09 May 2014

Fixed bug when capturing interactive selection; only enable image formats when saving to an unspecified file via uiputfile

Contact us