File Exchange

image thumbnail

Image overlay

version 1.3 (3.72 KB) by Steve Eddins
Overlay a binary mask onto an image using a specified color


Updated 03 Dec 2019

View Version History

View License

The function IMOVERLAY creates a mask-based image overlay. It takes input image and a binary mask, and it produces an output image whose masked pixels have been replaced by a specified color.

NOTE: This original implementation of IMOVERLAY was superseded in R2016a by a new function, with the same name, in the Image Processing Toolbox. The version here has been renamed to IMOVERLAY_OLD.

Cite As

Steve Eddins (2021). Image overlay (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (60)


i want to submit the report in college so i want the report of this project??
can u help me in that

Steve Eddins

@KSHITIZ - I don't understand your question.


what about abstract?

Shuvo Das

Do it work in matlab15


Grzegorz Swinarski

Steve Eddins

Steve-Not with the function as is. You'd need to modify it to do the blending math.

Steve Evans

This worked really well for me - but i would like to control the transparency of the overlay - is there an easy way of doing this?

xing xiong

Sandhya Prabhakaran

thomas afriyie

thank you, is working

Steve Eddins

Gabriel-Jonathan, do you mean you want the output to be uint16? Then modify the code inside the function to call im2uint16 instead of im2uint8.

Everything runs smoothly and well. However is there a way to make this work on a 16 bit image?

bourr houssam

Abdollah Rahman

Abdollah Rahman

ujjwal baid

How to make it work for 16 bit image. I am working on 16 bit medical image.

afshin shoeibi


Matthew Eicholtz

Easy to understand and use. Works as expected. Thanks Steve!

Shajahan Sunoj

Awesome... Thanks Eddins.. It helped me a lot... It Works so well now...

Steve Eddins

Shajahan - this imoverlay.m has fewer than 134 lines in it, and it does not call imagesc. You must be using somebody else's imoverlay.m.

Shajahan Sunoj

Sorry. It does not work for me. Can anyone help me how to make it work?

I am trying to use your same image and same code as you showed in the cell segmentation demo. I am getting following errors.

Error using image
Incorrect number of arguments.

Error in imagesc (line 39)
hh = image(varargin{:},'CDataMapping','scaled');

Error in imoverlay (line 134)
hF = imagesc(F,climF);

Error in celltry (line 12)
overlay1 = imoverlay(I_eq, bw4_perim, [.3 1 .3]);

Matthew Schneck





Mohammad Ahmed

It was great. Keep up the good work. Thumbs up.

Massimo Ciacci

Steve Eddins

Image Analyst, thanks for your comments. I like your suggestion about accepting the output of bwboundaries as the 2nd input argument. I don't really understand your comment about bwperim, though.

Image Analyst

bwperim is not the only way to create outlines. It would be nice if imoverlay were smart enough to see if the input was a binary image, or a cell array that is the output of bwboundaries. A lot of times we threshold and then call bwboundaries. It would be a nice enhancement if it could take the output of bwboundaries as the location of the outlines to draw.

Steve Eddins

Andrew, you'll have to either pad or resize one of the images to match the other size to overlay them using this function. You could also consider using MATLAB graphics transparency features to overlay one image on another.


Very good tool. Is there any way you can overlay two images that are different sized without one of them becoming dis-formed?


I'd like to use this function visualize the clipped pixels (e.g. with value 256 in 8bit grayscale) in red, in the preview of a camera recording.

its possible to apply an arbitrary function to each video frame before its displayed in the preview with this:

however, I havent been able to combine this with imoverlay. Any suggestions??





Steve Eddins

Lasse - thanks, I have uploaded a new version based on your suggestion.


This might help to some people

out_red(logical(mask)) = color_uint8(1);
out_green(logical(mask)) = color_uint8(2);
out_blue(logical(mask)) = color_uint8(3);

Hope it helps..

I am not able to implement it. How should I use this function in my program?





is it i can find the upper and lower pixel value of my region..............


thanks. used in my code. will upload soon



This code was great.heyy i want the canny edge borders to be they are in green to get that???


Great work! saved me some precious time...


This is an excellent bit of code. It worked perfectly fine in my case.

Waleed El-Badry

that's an excellent piece of code.

Carlos Adrián Vargas Aguilera

Great tool. Now I can paint NaN's in black on imagesc.


Robert Misevski

Great tool work very well for what a needed to do.

Steve Eddins

Matt - I added a note and an example to the documentation based on your suggestion. Thanks!

Phillip SUn

great and loved it

B r

Matt Whitaker

Simple, useful and well styled and coded. Did something in my existing code similar but this is a bit faster and less memory. Steve, you might want to note in the documentation that if you have a double input outside the range of 0-1 (soemthing you typically use imagesc to display) that you would want to run mat2gray on it before passing to this function. A useful further enhancement would be either to auto detect and apply this or have an optional switch.

Chai Tan

Works great. Saves me a few lines of code! :) Thanks.

Lennart Burg

I think it works great. Thnx

Gil Hornung

I would like to overlay a picture which is not bw.

James Jones

??? Subscript indices must either be real positive integers or logicals.

Error in ==> imoverlay at 54
out_red(mask) = color_uint8(1);

MATLAB Release Compatibility
Created with R2006a
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!