File Exchange

image thumbnail


version (673 KB) by Matt Smith
Create a color overlay of two images. Allows transparency and thresholding.


Updated 22 Apr 2015

View Version History

View License

IMOVERLAY allows you to easily display one image in color on top of another grayscale image. You can independently control the clim of each image, the colormap used for the top image, and the transparency. Resulting image can be displayed in a separate figure or in a supplied axis.
IMOVERLAY_TOOL is an interface to graphically overlay one image on top of another and manipulate colormap, thresholding, and transparency.
- Allows independent control of both images
- Workspace variables are selected via a dropdown menu
- Easily adjust colormap
- Adjustable transparency
- Load 3D or 4D datasets
- Export figure for saving
- Accelerator keys for quick selections

% Overlay one image transparently onto another
imB = phantom(256); % Background image
imF = rgb2gray(imread('ngc6543a.jpg')); % Foreground image
[hf,hb] = imoverlay(imB,imF,[40,180],[0,0.6],'jet',0.6);
colormap('hot'); % figure colormap still applies

% Use the interface for flexibility

Cite As

Matt Smith (2021). imoverlay (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (37)

Daniel Carr

Surya Gnyawali

I have rgb image as background image. I want to overlay a color image on top of this rgb. please help understanding your code. It looks exactly what I want. But it converts the background image to gray which I don't want. Thanks

Surya Gnyawali

Hi Matt Smith,

The code is amazing! However, can you display one color image on top of another color image?

Monchai Phonlakrai

Thank you. really appreciated.

Matthieu Huot

Yonni f

Fantastic tool. I am having difficulty figuring out how to add a title to the images. Does anyone have any suggestions?

Dominik Blum


SA Yoganathan

Excellent. Thanks for the submission.

Guillaume Le Goc

Sayantan Bhadra


This is a fantastic submission that allows me to easily overlay dose on top of voxelized image density data, made my life much easier

Matt J

For some reason, I'm finding that imoverlay disables zooming in the figure window (i.e., the spyglass icons don't work). Anyone else experience this as well? Is there a remedy?

Alex Jiskra

When I try to run the imoverlay function to display two images I am working with one gray scale image and one image in red green and blue. The error I receive is
"Error using imoverlay (line 68)
Front image has 3 dimensions!"
Is there any method of using imoverlay to display two images when one of them has 3 dimensions of color? Any help would be appreciated. Thanks

hi. how to make the coding not to display the overlay image. i means after call up the function, the image not show up instead need to use imshow to show the image. thank you

Matt Smith

'parula' is the new colormap introduced by Matlab in 2015 I believe. If you are using a version prior to that, you will not be able to use that colormap. sorry!


??? Undefined function or method 'parula' for input arguments of type

Error in ==> imoverlay_tool>parula2 at 811
J = parula(m); J(1,:) = [0,0,0];
When I type imoverlay_tool ...
I get this error...
someone can kindly help me?

Error in ==> imoverlay_tool>init at 386
cmap = eval(['colormap(' cmap_name ')']);

Error in ==> imoverlay_tool at 375
init( );

George Papas

Hi Matt.

Many thanks for this and for your sharing, it is really helpful and can be used for many different applications.

I would like to ask you whether I could somehow adapt your code so that I will be able plot a transparent image on top of another (but without using colors, only with actual grey values).

With many thanks in advance for your time,




Hi Matt,

Thank you, now it's working. And I'm glad to hear that my problem inspired you new ideas, I will be happy to try the new features when are implemented.

Best regards

Matt Smith

Isabel, I have just made a fix to the UI thanks to your interesting case. Your first image was all zeros. The color limits of an axes need to be increasing (ie. 2nd number needs to be greater than the first) so [0,0] failed. I have put a fix in there. Download this new one and it should work for you. You gave me ideas for a couple new improvements so stay tuned and thanks for your feedback!


Hi Matt, thank you for your answer. However, I checked and any of the elements of my images are NaN.

You can find the manual and automatic segmentation in these links, so you can try yourself.


Matt Smith

Isabel, thanks for using imoverlay! Perhaps there's an error because in your images you have NaN somewhere? The color limits are automatically chosen when you load new images based on the values within the images. Can you check your image files with the following:


It currently doesn't support NaN's in the image, but you could replace those with zeros or some number, use imoverlay clim edit boxes to put in a threshold where those would become transparent...If you want to post those images online somewhere I'd be happy to try them and take a look for myself

Good luck,


Dear Matt,

I'm trying to use your imoverlay tool to compare a manual segmentation to an automatic segmentation. I loaded the manual segmentation as background but when I tried to load the automatic segmentation as Foreground I got the folowing error, could you help me with that? I don't know why it's happening.

FYI: both images are 512x512x354 double

Error using set
Bad property value found.
Object Name: axes
Property Name: 'CLim'
Values must be increasing and non-NaN.

Error in imoverlay_tool/update_f_data (line 529)

Error in imoverlay_tool/variable_Callback (line 637)
if get(source,'Parent')==f_panel, update_f_data( );end

Error while evaluating uicontrol Callback

Brett Shoelson

Hi Matt,
Impressive work--thanks very much for sharing this!
I have a couple thoughts to share:
* It would be nice if your UI ignored my preference for docked windows; you could, for instance, include a 'windowstyle','normal' in your call to |figure|. Even in the function version of imoverlay, you create a visible-off figure; that generates a warning with my docked figure window.
* I like the inclusion of the 'renderer' in the figure call. That probably avoids a lot of issues.
* Very clever mapping of xdata to account for different-sized images!
* It would be nice to be able to pass in input image(s) to the UI.
Excellent work!

Zacharias Kandylakis

My issue is resolved. I used "Display Syntax" and tried changing the inputs from:




I guess the function needs to be sure the inputs are 2-dimensional or something.

So, my sincere thanks for your help and for supporting this tool. For my field of work, there is no other function out there that creates such smooth results.

Zacharias Kandylakis

So my sincere thanks for your help and for supporting this tool. For my field of work, there is no other function out there that creates such smooth results.

Matt Smith

Zacharias, on the upper right side of the tool, there's a button labeled "Display Syntax". If you click that, it will display in your command window the exact command line you'd need to run to give the exact display you see in the tool. Example:

[hFront,hBack] = imoverlay(phantom(256),rgb2gray(imread('ngc6543a.jpg')),[40,180],[0,0.6],'parula2',0.6);

Please let me know more details if you need more assistance.

Zacharias Kandylakis

I am just using the function. That is because I need to save multiple image overlays (maps), so the process must be automated. Is there a consistent way to save the figure results produced by the function, using code?

Matt Smith

Zacharias, if you select File->Export Figure from the imoverlay_tool GUI, you should be able to save the figure like any other Matlab figure. I just ran your three lines after exporting the figure and it saved the TIF properly. Please let me know if you still have trouble.

I am having a problem saving the results of the overlay.
I am using:


However, I have an odd result in the saved image. It is a figure menu which is undocked, and sits at the middle of the image. This does not appear when the figure is shown.

By paying close attention I observed that when a figure is opened by imoverlay.m this menu is the first thing plotted on the figure.
So I guess it must be "behind" the two images I am overlaying, so it also gets captured by getframe.

I am not using saveas() because it is very important to preserve the quality of the image.

Fatima zerari

Thank you for sharing your knowledge with us. I run imoverlay but I'm having the following error:
Error in imoverlay (line 133)
hF = imagesc(F,climF);

Error in segment1 (line 39)
overlay1 = imoverlay(I_eq, bw4_perim, [.3 1 .3]);
Thank you,

Matt J

Very nice.

Small bug, though (perhaps). When the syntax


is used on a pre-existing axes, ha, the colormap in the figure containing the pre-existing axes does not get overriden by 'cmap'.



Excellent functionality. I learned how to to transparent overlays with this GUI.


I have used this to overlay in presentations, posters, and publications and the results are always great.


This is exactly what I needed! Great work!

MATLAB Release Compatibility
Created with R2014b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!