File Exchange

image thumbnail


version (31.5 KB) by Justin Solomon
This is a image slice viewer with built in scroll, contrast, zoom and ROI tools.


Updated 21 Jul 2017

View License

Use this class to make a self-contained image viewing panel within a GUI (or any figure). Similar to imtool but with the added ability to scroll through slices of an image stack. Only designed to view grayscale (intensity) images. Hopefully this will save people time when either designing a GUI or even when they just need to quickly look through an image stack.

Cite As

Justin Solomon (2020). imtool3D (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (35)


This is perfect! Thank you.

Ivo Maatman

Works beautifully! Thank you.

Janhavi Srirangaraj


Hi Justin,

Thank you for this tool. Perfectly designed. I've been using it daily for manual segmentation, roi stats, and for viewing .nii files.
During this time, I added several necessary features at the following link, might be of interest for you:

Mainly I added:
- Support for 5D volumes (scroll through time and volumeS with arrows)
- Keyboard shortcut
- Multi-label mask
- New tools for mask (interpolate slices, active contour...)
- Convert Mask2poly and poly2mask
- splines in polygons (double click a circle)

Feel free to reuse some features,
Hope that will help;

mohd akmal masud

Dear Justin,

i have problem as below. how could i put the graphicsHandles?

>> imtool3DROI(P)
Not enough input arguments.
Error in imtool3DROI (line 30)
ROI.graphicsHandles = graphicsHandles;

Duhee Jeon

Anup Marasu

How do i start this ?

Justin Solomon

@Burford thanks for your message. It doesn't look like UsefulTools is actually required (I ran a dependency report in the imtool3D folder and its didn't show anything from UsefulTool). I removed that statement from the readme file. However, for your specific bug, it looks like you don't have the range() function, which is part of the Statistics and Machine learning toolbox. Its just a simple little function that takes the max - min of a vector (or matrix). You could easily write that function yourself. I would have written my code to not use that function if I knew that range() was only in the stats toolbox. You could either write that range function yourself or replace that line of code in imtool3D.m file (line 715) to be r = max(tool.I(:)) - min(tool.I(:)); That should fix it.

R Burford

Can you comment as to whether the "Useful Tools" package from <> is actually required? I cannot get to that site, as it requires a login. Perhaps you might upload that tools suite to File Exchange?

I get the following error (on R2016b with Image Processing Toolbox):
Undefined function 'range' for input arguments of type 'double'.
Error in imtool3D/range (line 715)
r = range(tool.I(:));
Error in imtool3D>newLowerRangePosition (line 1173)
Error in
(line 1116)
Error while evaluating Figure WindowButtonMotionFcn

Justin Solomon

@Daniel, I just uploaded a new version (might take some time for Mathworks to approve it), but getting the latest version might solve your problem. Otherwise, your problem may be solved by converting the image type to double before viewing it with imtool3D. For example,

im; %Assumming your image stack is saved in a variable called im, try the line below
t = imtool3D(double(im));

Here are the mouse instructions:
Left Click = Window Level (i.e., contrast) adjustment
Right Click = Pan
Shift+Right Click = zoom

Hope that helps,

Daniel Kirschenbaum

I would really love to use this tool. I bump into some errors and wonder if someone could help me out.
I manage to load a .tif stack and scroll between the images. I use R2017a.

I'm not able to change the contrast and I don't see the GUI for the zoom. I also get an error when trying to select a ROI.
For changing contrast:
Error while evaluating Figure WindowButtonMotionFcn.

Undefined function 'log10' for input arguments of type 'uint16'.

Error in imtool3D>adjustContrastMouse (line 1148)
ord = round(log10(r));

Error in imtool3D>@(src,evnt)adjustContrastMouse(src,evnt,bp,tool.handles.Axes,tool,W,L)
(line 947)

Error while evaluating Figure WindowButtonMotionFcn.
ROI selectrion error:
Error using var (line 66)
Invalid data type. First input argument must be single or double.

Error in std (line 51)
y = sqrt(var(varargin{:}));

Error in imtool3DROI_rect/getMeasurements (line 175)
stats.STD = std(im);

Error in imtool3DROI_rect/newPosition (line 145)
stats = getMeasurements(ROI);

Error in imtool3DROI_rect (line 105)

Error in imtool3D>measureImageCallback (line 915)
ROI = imtool3DROI_rect(h.I);

Error in imtool3D>@(hObject,evnt)measureImageCallback(hObject,evnt,tool,'rectangle') (line
fun=@(hObject,evnt) measureImageCallback(hObject,evnt,tool,'rectangle');

Error while evaluating UIControl Callback.

Thank you,

Simon van Kranen

Hugo Santos

Matt Latourette

It's mostly bug fixes so far along with a bunch of stylistic changes (splitting up long lines, changing indentation, suppressing compiler warnings where appropriate). Next up, I'm now working on some code to allow ROIs in the imtool3D to be more closely integrated with a host application that is making use of the imtool3D in a GUI panel.

My use of the tool is for a preclinical DCE-MRI analysis tool I'm working on. I am using imtool3D to display the DCE time series and draw the ROIs for the analysis.

Justin Solomon

Thanks @Matt! Would you mind giving an executive summary of the changes you've made thus far? Anything major beyond bug fixes?

Matt Latourette

Great tool! I've made a fork with some modifications here: You're welcome to integrate any of my changes back into the main branch if they are useful to you.

Sébastien Tosi

A last feature I forgot to mention is a separate LUT for the Mask to represent label masks. That would actually be truly amazing to overlay segmentation results on an image.

Justin Solomon

Thanks for the positive feedback Sebastien. I'll think about adding some of those features in future releases. FYI, the voxel ratio is actually adjustable already. There's a method called setAspectRatio. I don't think I've added that methods in the documentation but its pretty straightforward.

Sébastien Tosi

Sébastien Tosi

This is an amazing tool! The only features I am missing are:

- View histogram in log scale
- Limit histogram to selected ROI
- 3D Rotate volume respect X and Y axis
- Adjustable voxel ratio
- Perform adjustable limited depth Z MIP
- Z MIP (interactive with 3D rotation)

Johan Lundberg

Thank You for sharing this amazing tool!


Justin Solomon

@Giorgio, I just uploaded a new version which has better window and leveling behavior. You can control how fast the window and leveling changes by changing the windowSpeed property (default it 2, increase this number to window faster).


Very nice tool!

Is it possible a faster window and leveling by mouse left click?

Ibraheem Al-Dhamari

You are welcome Justin, it would be also nice to display two different 3D images in different colors (good to visualize fusion results).

Justin Solomon

Thanks @Meade and @Ibraheem Al-Dhamari for pointing out this bug. I tend to just convert all my images to doubles when I read them in so I hadn't seen this error before. I'll include this fix in the next version.


Great code.

I get the following error when opening standard DICOM data using Matlab's baked in dicomread fnc:

---code below---
Error using .*
Integers can only be combined with integers of the same class, or scalar doubles.

Error in linspace (line 30)
y = d1 + (0:n1).*(d2 - d1)/n1;

Error in imtool3D (line 310)

---end code---

I changed line 310 to :

---code below---
---end code---

and it seemed to take care of it.
Thanks again!

Ibraheem Al-Dhamari

very nice tool :D
I changed these lines after311 to make it suitable for different image types e.g. I have an 256x256x60 int16 image and I got some errors but this code solved them:

would be nice if there is "undo button". Maybe I implement this when I have more time.

Justin Solomon

@Diana Carver, I just updated imtool3D to be compatible with R2014b. Hopefully should work for you now.

In case you're curious, the problem was that you can no longer make a double array of handles in R2014b. Thus cell2mat throws an error when trying to convert a cell array of handles to a double array of handles. This is because the new Matlab has drastically changed the graphics system. Graphics handles are now objects, and not doubles.

Diana Carver

Great tool! Only thing is, I just upgraded to 2014b and alas it no longer works. I get this error:

Error using cell2mat (line 52)
CELL2MAT does not support cell arrays containing cell arrays or objects.

Error in imtool3D (line 225)

Trying to debug it myself to figure out what went wrong.

Justin Solomon

@ Edwin
I just submitted a major update to the tool. The user now has access to all the underlying handles of the objects contained in the tool. You may be able to accomplish what you want now. (Though I'm not entirely clear on what exactly you want to do).

%get a structured variable of all the handles
handles = getHandles(tool)
%et the 'AlphaData' property of the image

Justin Solomon

@ Edwin
Thanks for the positive feedback. Unfortunately there is not an AlphaData property for this tool right now. I'm planning to make a major revision to this tool to make it easier to access the underlying image objects. It will be much easier to do what you describe in the next version. Stay tuned! (no timeline yet, really busy with other stuff at the moment).


Great tool! Is there an equivalent to an 'AlphaData' tag property for this tool? Trying to see if one could overlay a set of images and use this tool to scroll through it. Thanks!

Maysam Shahedi

Nice GUI!
You can use mouse wheel to switch slices. It makes the GUI easier to use.

Anna Rodrigues



Many bug fixes and improvements.

Added a "smart" paint brush. The brush works by doing a local binary Ostu threshold and then painting onto only the area that contains the most pixels. This lets you accurately capture the edge of a feature quickly.

Fixed a small bug related to windowing with the mouse.

Added a paint brush to adjust the overlay mask. The window and leveling should now work well for images for any dynamic range. Added a property (windowSpeed) that controls how quickly the window and level settings change with mouse movement.

Fixed typo.

Fixed one more window and level bug.

2.3.2- Squished a few bugs for older Matlab versions. Added method to set and get the transparency of the overlaid mask. Refined the panning and zooming.

Now the code makes sure the figure is centered when creating an imtool3D object in a new figure.

Added ability to overlay a semi-transparent mask on top of the image data. Also redesigned/simplified the ROI tools implementation.

Updated for compatibility with MATLAB R2014b. Also fixed a bug where an error was shown when a single slice image is viewed with imtool3D.

Updated to allow for multiple imtool3D objects in a single figure while being able to use the scroll wheel for each one.

Updated Screenshot

2.1- Added crop tool, help button, and button that resets the pan and zoom settings to show the entire image (useful when you're zoomed in and you just want to zoom out quickly.

New in version 2.0- Completely redesigned the tool. Window and leveling, pan, and zoom are now done with the mouse as is standard in most medical image viewers. Also the overall astestic design of the tool is improved with a new black theme. Added ab

Added the method:
ROI = getROIinfo(tool)
This lets the user get information about the currently selected ROI

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

Inspired: imtool3D_td, Brain Ruler