Documentation Center

  • Trial Software
  • Product Updates

imshow

Display image

Syntax

  • imshow(X,map) example
  • imshow(X,RX,map)
  • imshow(___,Name,Value...)
  • himage = imshow(___)

Description

example

imshow(I) displays the image I in a Handle Graphics® figure, where I is a grayscale, RGB (truecolor), or binary image. For binary images, imshow displays pixels with the value 0 (zero) as black and 1 as white.

example

imshow(I,RI) displays the image I with associated 2-D spatial referencing object RI.

example

imshow(X,map) displays the indexed image X with the colormap map. A color map matrix may have any number of rows, but it must have exactly 3 columns. Each row is interpreted as a color, with the first element specifying the intensity of red light, the second green, and the third blue. Color intensity can be specified on the interval 0.0 to 1.0.

imshow(X,RX,map) displays the indexed image X with associated 2-D spatial referencing object RX and colormap MAP.

example

imshow(filename) displays the image stored in the graphics file filename. The file must be in the current directory or on the MATLAB® path and must contain an image that can be read by imread or dicomread. imshow calls imread or dicomread to read the image from the file, but does not store the image data in the MATLAB workspace. If the file contains multiple images, imshow displays only the first one.

imshow(___,Name,Value...) displays the image, specifying additional options with one or more Name,Value pair arguments, using any of the previous syntaxes.

example

imshow(gpuarrayIM,___) displays the image contained in a gpuArray. This syntax requires the Parallel Computing Toolbox™.

example

imshow(I,[low high]) displays the grayscale image I, specifying the display range as a two-element vector, [low high]. For more information, see theDisplayRange parameter.

himage = imshow(___) returns the handle to the image object created by imshow.

Examples

expand all

Display image from file

Specify image file.

imshow('board.tif')

Display indexed image

Read indexed image and associated color map from file and display it.

[X,map] = imread('trees.tif');
imshow(X,map)

Display grayscale image

Read grayscale image from file and display it.

I = imread('cameraman.tif');
imshow(I)

Display grayscale image, adjusting display range

Read grayscale image and specify display range.

I = imread('cameraman.tif');
h = imshow(I,[0 80]);

Display grayscale image using associated spatial referencing object

Read image into workspace.

I = imread('pout.tif');

Create a spatial referencing object associated with the image. Then specify X and Y limits in a world coordinate system.

RI = imref2d(size(I));
RI.XWorldLimits = [0 3];
RI.YWorldLimits = [2 5];

Display the image, specifying the spatial referencing object.

imshow(I,RI);

Display Image on a GPU

Read image into a gpuArray.

X = gpuArray(imread('pout.tif'));

Display it.

figure; imshow(X)

Input Arguments

expand all

I — Input imagegrayscale image | RGB image | binary image

Input image, specified as a grayscale, RGB, or binary image.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

X — Indexed image2-D array of real numeric values.

Indexed image, specified as a 2-D array of real numeric values. The values in X are an index into Map, an n-by-3 array of RGB values.

Data Types: single | double | uint8 | logical

map — Colormapn-by-3 array

Colormap, specified as an n-by-3 array. Each row specified an RGB color value.

Data Types: single | double | uint8 | logical

filename — Name of file containing an imagetext string

Name of file containing an image, specified as a text string. The image must be readable by imread or by dicomread. imshow calls imread or dicomread to read the image from the file, but does not store the image data in the MATLAB workspace. If the file contains multiple images, imshow displays the first image in the file.

Data Types: char

RI — 2-D spatial referencing object associated with the input imageimref2d object

2-D spatial referencing object associated with input image, specified as an imref2d object .

RX — 2-D spatial referencing object associated with an indexed imageimref2d object

2-D spatial referencing object associated with an indexed image, specified as a imref2d object.

gpuarrayIM — Image to be processed on a graphics processing unit (GPU)gpuArray object

Image to be processed on a graphics processing unit (GPU), specified as a gpuArray.

[low high] — Display range of the imagetwo-element vector

Display range of the image, specified as a two-element vector.

Example: [50 250]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ‘Border','tight'

'Border' — Control whether figure window includes a bordervalue returned by iptgetpref('ImshowBorder') (default) | 'tight' or 'loose'

Controls whether imshow includes a border around the image displayed in the figure window. 'tight' or 'loose'There can still be a border if the image is very small, or if there are other objects besides the image and its axes in the figure.

Example:

Data Types: char

'Colormap' — Value of figure's colormap property (default) | 2–D, real, m-by-3 matrix

imshow uses this to set the figure's colormap property. Use this parameter to view grayscale images in false color. If you specify an empty colormap ([]), imshow ignores this parameter.

Example:

Data Types: double

'DisplayRange' — Display range of grayscale image[min(I(:)) max(I(:))] (default) | two-element vector

Display range of a grayscale image, specified as a two-element vector [LOW HIGH]. imshow displays the value low (and any value less than low) as black, and the value high (and any value greater than high) as white. Values in between are displayed as intermediate shades of gray, using the default number of gray levels. If you specify an empty matrix ([]), imshow uses [min(I(:)) max(I(:))]; that is, use the minimum value in I as black, and the maximum value as white.

    Note:   Including the parameter name is optional, except when the image is specified by a filename. The syntax imshow(I,[LOW HIGH]) is equivalent to imshow(I,'DisplayRange',[LOW HIGH]). When calling imshow with a filename, you must specify the 'DisplayRange' parameter.

Example: h = imshow(I,'DisplayRange',[0 80]);

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

'InitialMagnification' — Initial magnification used to display imagevalue returned by iptgetpref('ImshowInitialMagnification') (default) | numeric scalar value | text string 'fit'

Initial magnification used to display an image, specified as the numeric value or the text string ‘fit'.

When set to 100, imshow displays the image at 100% magnification (one screen pixel for each image pixel). When set to 'fit', imshow scales the entire image to fit in the window.

On initial display, imshow always displays the entire image. If the magnification value is large enough that the image would be too big to display on the screen, imshow warns and displays the image at the largest magnification that fits on the screen.

If the image is displayed in a figure with its 'WindowStyle' property set to 'docked', imshow warns and displays the image at the largest magnification that fits in the figure.

Note: If you specify the axes position (using subplot or axes), imshow ignores any initial magnification you might have specified and defaults to the 'fit' behavior.

When used with the 'Reduce' parameter, only 'fit' is allowed as an initial magnification.

Example:

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char

'Parent' — Axes that is the parent of the image objecthandle

Axes that is the parent of the image object, specified as a handle. Created by imshow.

    Note:   If you are building a GUI where you want to control the figure and axes properties, be sure to use the imshow(..., 'Parent', ax) syntax.

Data Types: function_handle

'Reduce' — Subsample image in filenamelogical value

Subsample image in filename, specified as a logical value. Only valid for TIFF images. Use this parameter to display overviews of very large images.

Data Types: logical

'Xdata' — Limits along X axis of a nondefault spatial coordinate systemtwo-element vector

Limits along X axis of a nondefault spatial coordinate system, specified as a two-element vector. Establishes a nondefault spatial coordinate system by specifying the image XData. The value can have more than two elements, but only the first and last elements are actually used.

Example: [100 200]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

'YData' — Limits along Y axis of a nondefault spatial coordinate systemtwo-element vector

Limits along Y axis of a nondefault spatial coordinate system, specified as a two-element vector. The value can have more than two elements, but only the first and last elements are actually used.

Example: [100 200]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

expand all

himage — Image object created by imshowhandle

Image object created by imshow, specified as a handle.

Alternative Functionality

App

imshow is the toolbox's fundamental image display function, optimizing figure, axes, and image object property settings for image display. imtool provides all the image display capabilities of imshow but also provides access to several other tools for navigating and exploring images, such as the Pixel Region tool, Image Information tool, and the Adjust Contrast tool. imtool presents an integrated environment for displaying images and performing some common image processing tasks.

The imshow function is not supported when MATLAB is started with the -nojvm option.

You can access imshow through the Plot Selector workspace tool, which is represented by this icon: . In your workspace, select the data you want to display. The Plot Selector icon changes to look like this: . Scroll down to Image Processing Toolbox Plots. Select imshow(I).

More About

expand all

Tips

  • You can use the iptsetpref function to set several toolbox preferences that modify the behavior of imshow.

    • 'ImshowBorder' controls whether imshow displays the image with a border around it.

    • 'ImshowAxesVisible' controls whether imshow displays the image with the axes box and tick labels.

    • 'ImshowInitialMagnification' controls the initial magnification for image display, unless you override it in a particular call by specifying imshow(...,'InitialMagnification',initial_mag).

    For more information about these preferences, see iptprefs.

See Also

| | | | | | | |

Was this topic helpful?