Documentation

imshow

Display image

Syntax

  • imshow(X,map) example
  • imshow(X,RX,map)
  • imshow(___,Name,Value...)
  • imshow(gpuarrayIM,___) example
  • 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.

imshow(I,[low high]) displays the grayscale image I, where [low high] is a two-element vector that specifies the display range for I. The value low (and any value less than low) displays as black and the value high (and any value greater than high) displays as white. imshow displays values in between as intermediate shades of gray.

imshow(I,[]) displays the grayscale image I, where [] is an empty matrix that specifies that you want imshow to scale the image based on the range of pixel values in I, using [min(I(:)) max(I(:))] as the display range.

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 specified by the text string filename.

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™.

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 | m-by-n-by-3 array

Input image, specified as a scalar, vector, or matrix representing a grayscale, RGB, or binary image. Multi-plane image inputs must be RGB images of size m-by-n-by-3. An RGB image can be uint8, uint16, single, or double. A grayscale image can be any numeric data type. A binary image is of class logical.

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

[low high] — Grayscale image display rangetwo-element vector

Grayscale image display range, specified as a two-element vector. For more information, see the 'DisplayRange' name-value pair argument.

Example: [50 250]

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

[] — Autoscaling indicatorempty matrix

Autoscaling indicator, specified as an empty matrix. For more information, see the 'DisplayRange' name-value pair argument.

Example: []

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 indices into the colormap specified by Map, an n-by-3 array of RGB values.

Data Types: single | double | uint8 | logical

map — Colormapn-by-3 array

Colormap, specified as an m-by-3 array of type single or double in the range [0 1], or an m-by-3 array of type uint8. Each row specifies an RGB color value.

Data Types: single | double | uint8

filename — Name of file containing an imagestring

Name of file containing an image, specified as a string. The image must be readable by imread or by dicomread. imshow displays the image 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.

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: imshow('board.tif','Border','tight')

'Border' — Figure window border spacevalue returned by iptgetpref('ImshowBorder') (default) | 'tight' | 'loose'

Figure window border space, specified as the strings 'tight' or 'loose'. When set to ‘loose', the figure window includes space around the image in the figure. When set to ‘tight', the figure window does not include any space around the image in the figure. If the image is very small or if the figure contains other objects besides an image and its axes, imshow might use a border regardless of how this parameter is set.

Example: imshow('board.tif','Border','tight')

Data Types: char

'Colormap' — Colormap (default) | m-by-3 matrix

Colormap, specified as an 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 ([]), then imshow ignores this parameter.

Example: newmap = copper; imshow('board.tif','Colormap',newmap)

Data Types: double

'DisplayRange' — Grayscale image display rangetwo-element vector [low high]

Grayscale image display range, specified as a two-element vector of the form [low high]. The imshow function displays the value low (and any value less than low) as black, and it displays the value high (and any value greater than high) as white. imshow displays values between low and high as intermediate shades of gray, using the default number of gray levels.

If I is an integer type, 'DisplayRange' defaults to the minimum and maximum representable values for that integer class. For images with floating point data, the default display range is [0 1]. If you specify an empty matrix ([]), imshow scales the image based on the range of pixel values in I, using [min(I(:)) max(I(:))] as the display range.

    Note:   Including the parameter name is optional, except when the image is specified by a file name. The syntax imshow(I,[low high]) is equivalent to imshow(I,'DisplayRange',[low high]). If you call imshow with a file name, then 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 | 'fit'

Initial magnification used to display an image, specified as the numeric scalar or the 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 you use imshow with the 'Reduce' parameter, the initial magnification must be 'fit'.

Example: h = imshow(I,'InitialMagnification','fit');

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

'Parent' — Parent axes of image objecthandle

Parent axes of image object, specified as a handle. Use the 'Parent' name-value argument to build a UI that gives you control of the figure and axes properties.

Data Types: function_handle

'Reduce' — Indicator for subsamplinglogical value

Subsample image in filename, specified as the logical values true or false. This argument is valid only when you use it with the name of a TIFF file. Use the Reduce argument to display overviews of very large images.

Data Types: logical

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

X-axis limits of nondefault coordinate system, specified as a two-element vector. This argument establishes a nondefault spatial coordinate system by specifying the image XData. The value can have more than two elements, but imshow uses only the first and last elements.

Example: 'Xdata',[100 200]

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

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

Y-axis limits of nondefault coordinate system, specified as a two-element vector. The value can have more than two elements, but imshow uses only the first and last elements.

Example: 'YData',[100 200]

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

Output Arguments

expand all

himage — Image objecthandle

Image object, 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. Use imtool to open the Image Viewer app, which 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. The Image Viewer presents an integrated environment for displaying images and performing some common image processing tasks.

You can also display images using the Plot tab on the MATLAB toolstrip. In your workspace, select the data you want to display. Select the Plots tab, expand the selection and choose imshow from the MATLAB Image Plots group.

More About

expand all

Tips

  • The imshow function is not supported when you start MATLAB with the -nojvm option.

  • 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.

Was this topic helpful?