imtool

(To be removed) Open Image Tool

imtool will be removed in a future release. Use the Image Viewer app instead. For more information, see Version History.

Syntax

imtool

imtool(I)

imtool(I,range)

imtool(RGB)

imtool(BW)

imtool(X,cmap)

imtool(filename)

imtool(___,Name=Value)

hTool = imtool(___)

Description

The imtool function opens the Image Tool, which enables you to display images and perform common image processing tasks.

The tool provides all the image display capabilities of imshow, which optimizes figure, axes, and image object property settings for image display. The tool also provides access to several tools for navigating and exploring images, such as the Pixel Region tool, Image Information tool, and the Adjust Contrast tool.

imtool opens the Image Tool in an empty state. Use the File menu options Open or Import from Workspace to choose an image for display.

imtool(I) displays the grayscale image I in the Image Tool, using the default display range of the image data type.

imtool(I,range) displays the grayscale image I in the Image Tool, specifying the display range as range. The tool clips pixel values outside the display range to black or white and displays pixel values within the display range as intermediate shades of gray. The tool uses the default number of gray levels.

imtool(RGB) displays the truecolor image RGB in the Image Tool.

imtool(BW) displays the binary image BW in the Image Tool. Pixel values of 0 display as black; pixel values of 1 display as white.

imtool(X,cmap) displays the indexed image X with colormap cmap in the Image Tool.

imtool(filename) displays the image contained in the graphics file filename in the Image Tool.

imtool(___,Name=Value) displays the image, specifying name-value arguments that control various aspects of the image display.

hTool = imtool(___) returns the figure hTool containing the Image Tool.

Examples

Display Different Types of Images

Display a color image from a file.

imtool("board.tif")

Display an indexed image.

[X,map] = imread("trees.tif");
imtool(X,map)

Display a grayscale image.

I = imread("cameraman.tif");
imtool(I)

Input Arguments

I — 2-D grayscale image

m-by-n numeric matrix

2-D grayscale image, specified as an m-by-n numeric matrix.

Data Types: single | double | int16 | uint8 | uint16

range — Display range

2-element numeric vector | []

Display range of the grayscale image I, specified as one of these values.

Value	Description
[low high]	Image Tool displays pixels with the value low (and any value less than low) as black. Image Tool displays pixels with the value high (and any value greater than high) as white.
[]	Image Tool automatically sets the display range to [min(I(:)) max(I(:))]. The minimum value in I is displayed as black, and the maximum value is displayed as white.

Note

If you specify both the range argument and the DisplayRange name-value argument, then imtool sets the display range according to DisplayRange and ignores the value of range.

RGB — 2-D RGB image

m-by-n-by-3 numeric matrix

2-D RGB image, specified as an m-by-n-by-3 numeric matrix.

Data Types: single | double | uint8 | uint16

BW — 2-D binary image

m-by-n logical matrix

2-D binary image, specified as an m-by-n logical matrix.

Data Types: logical

X — 2-D indexed image

m-by-n numeric matrix

2-D indexed image, specified as an m-by-n numeric matrix.

Data Types: single | double | uint8 | logical

cmap — Colormap

c-by-3 numeric matrix

Colormap associated with indexed image X, specified as a c-by-3 numeric matrix containing the RGB values of c colors.

Note

If you specify both the cmap argument and the Colormap name-value argument, then imtool sets the colormap according to Colormap and ignores the value of cmap.

Data Types: single | double | int16 | uint8 | uint16

filename — Filename

string scalar | character vector

Filename of the graphics file containing the image, specified as a character vector. The file must contain an image that can be read by imread or dicomread or a reduced resolution dataset (R-Set) created by rsetwrite. If the file contains multiple images, the first one is displayed. The file must be in the current directory or on the MATLAB^® path.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: imtool(I,Colormap=jet) displays the grayscale image I using the jet colormap.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: imtool(I,"Colormap",jet) displays the grayscale image I using the jet colormap.

Colormap — Colormap

v-by-3 numeric matrix

Colormap, specified as a v-by-3 numeric matrix with values in the range [0, 1]. You can also create a colormap matrix using a predefined colormap function, such as parula or jet.

Example: Colormap=repmat([1:256]',1,3);

Example: Colormap=jet

Example: Colormap=parula(128)

Data Types: double

DisplayRange — Display range

2-element vector

Display range, specified as a 2-element vector of the form [low high].

Note

To set the display range when you call imtool with a filename, you must specify the DisplayRange name-value argument using the syntax imtool(filename,DisplayRange=[low high]).

InitialMagnification — Initial magnification

"adaptive" | "fit" | numeric scalar

Initial magnification, specified as one of these values.

Parameter	Value
"adaptive"	The entire image is visible on initial display. If the image is too large to display on the screen, then Image Tool displays the image at the largest magnification that fits on the screen.
"fit"	Image Tool scales the entire image to fit in the window.
numeric scalar	Image Tool scales the entire image as a percentage of the original image size. For example, if you specify 100, then Image Tool displays the image at 100% magnification (one screen pixel for each image pixel). Note When the image aspect ratio is such that less than one pixel would be displayed in either dimension at the requested magnification, Image Tool issues a warning and displays the image at 100%.

By default, the initial magnification parameter is set to the value returned by iptgetpref("ImtoolInitialMagnification"). To change the default initial magnification behavior, set the ImtoolInitialMagnification toolbox setting by using the iptsetpref function or by opening the Image Processing Toolbox™ Settings panel. For more information about the Settings panel, see iptprefs.

Interpolation — Interpolation technique

"nearest" (default) | "bilinear"

Interpolation technique used when scaling an image, specified as one of the following values.

Value	Description
"nearest"	Nearest neighbor interpolation
"bilinear"	Bilinear interpolation

Output Arguments

hTool — Image Tool figure

Figure object

Image Tool figure, returned as a Figure object.

More About

Large Data Support

To view very large TIFF or NITF images that will not fit into memory, you can use rsetwrite to create a reduced resolution dataset (R-Set) viewable in Image Tool. R-Sets can also improve performance of Image Tool for large images that fit in memory.

The following tools can be used with an R-Set: Overview, Zoom, Pan, Image Information, and Distance. Other tools, however, will not work with an R-Set. You cannot use the Pixel Region, Adjust Contrast, Crop Image, and Window/Level tools. Please note that the Pixel Information tool displays only the x and y coordinates of a pixel and not the associated intensity, index, or RGB values.

Specify Default Display Behavior

You can specify the default display behavior of Image Tool by using the Image Processing Settings window. To access the window, select File > Preferences in the Image Tool menu. You can also set settings programmatically by using the iptsetpref function.

Setting	Description
"ImtoolInitialMagnification"	Controls the initial magnification for image display. To override this toolbox setting, specify the "InitialMagnification" name-value argument when you call the imtool function, as follows: imtool(___,InitialMagnification=initial_mag)
"ImtoolStartWithOverview"	Controls whether the Overview tool opens automatically when you open an image using Image Tool. Possible values: true — Overview tool opens when you open an image. false — Overview tool does not open when you open an image. This is the default behavior.

For more information about these settings, see iptprefs.

Tips

• For grayscale images having integer types, the default display range is [intmin(class(I)) intmax(class(I))].

  For grayscale images of class single or double, the default display range is [0 1]. If the data range of a single or double image is much larger or smaller than the default display range, you might need to experiment with setting the display range to see features in the image that would not be visible using the default display range.

• You can close a specific Image Tool specified by the figure hTool by using this command:

  close(hTool)

  You can close all open instances of Image Tool by using this command:

  imtool close all

Version History

Introduced before R2006a

R2023b: imtool will be removed

imtool will be removed in a future release. In most situations, use the Image Viewer app instead. The app has more functionality and is easier to use than the Image Tool. To update your code, follow these steps:

• Replace instances of imtool with imageViewer.

• If the original code specifies the range or cmap input arguments, replace the arguments with the DisplayRange or Colormap name-value arguments, respectively.

• Ensure there are no output arguments.

Unlike the Image Tool, the Image Viewer app does not return a figure. If you want to display an image in Image Tool and return the figure that contains the tool, then use the images.compatibility.imtool.r2023b.imtool function instead. To update your code that displays an image and returns the Image Tool figure, replace instances of imtool with images.compatibility.imtool.r2023b.imtool. You do not need to modify the arguments.

Discouraged Usage	Recommended Replacement
This example uses the imtool function to display a grayscale image in the Image Tool. I = imread("cameraman.tif"); imtool(I)	Here is equivalent code that uses the imageViewer function to display the grayscale image in the Image Viewer app. I = imread("cameraman.tif"); imageViewer(I)
This example uses the imtool function to display a grayscale image in the Image Tool, setting the initial display range and interpolation method. I = imread("cameraman.tif"); imtool(I,[5 250],Interpolation="bilinear")	Here is equivalent code that uses the imageViewer function to display the grayscale image and set the initial display range and interpolation method. You must set the display range using the DisplayRange name-value argument. I = imread("cameraman.tif"); imageViewer(I,DisplayRange=[5 250],Interpolation="bilinear")
This example uses the imtool function to display an indexed image in the Image Tool, specifying the colormap. [I,map] = imread("trees.tif"); imtool(I,map)	Here is equivalent code that uses the imageViewer function to display the indexed image. You must specify the colormap using the Colormap name-value argument. [I,map] = imread("trees.tif"); imageViewer(I,Colormap=map)
This example uses the imtool function to display a grayscale image in the Image Tool and returns the figure containing the Image Tool. I = imread("cameraman.tif"); hTool = imtool(I);	Here is equivalent code that uses the images.compatibility.imtool.r2023b.imtool function to display a grayscale image in the Image Tool and return the figure containing the Image Tool. I = imread("cameraman.tif"); hTool = images.compatibility.imtool.r2023b.imtool(I);