image - Display image from array - MATLAB (original) (raw)

Syntax

Description

image([C](#buqdlnb-C)) displays the data in arrayC as an image. Each element of C specifies the color for 1 pixel of the image. The resulting image is anm-by-n grid of pixels wherem is the number of rows and n is the number of columns in C. The row and column indices of the elements determine the centers of the corresponding pixels.

example

image([x](#buqdlnb-x),[y](#buqdlnb-y),[C](#buqdlnb-C)) specifies the image location. Use x and y to specify the locations of the corners corresponding to C(1,1) and C(m,n). To specify both corners, set x and y as two-element vectors. To specify the first corner and let image determine the other, set x and y as scalar values. The image is stretched and oriented as applicable.

example

image('XData',[x](#buqdlnb-x),'YData',[y](#buqdlnb-y),'CData',[C](#buqdlnb-C)) specifies the image location. This syntax is the low-level version of image(x,y,C).

image(___,[Name,Value](#namevaluepairarguments)) specifies image properties using one or more name-value pair arguments. You can specify image properties with any of the input argument combinations in the previous syntaxes.

example

image([ax](#buqdlnb-ax),___) creates the image in the axes specified by ax instead of in the current axes (gca). The option ax can precede any of the input argument combinations in the previous syntaxes.

[im](#buqdlnb-im) = image(___) returns the Image object created. Use im to set properties of the image after it is created. You can specify this output with any of the input argument combinations in the previous syntaxes. For a list of image properties and descriptions, see Image Properties.

example

Examples

collapse all

Create matrix C. Display an image of the data in C. Add a colorbar to the graph to show the current colormap.

C = [0 2 4 6; 8 10 12 14; 16 18 20 22]; image(C) colorbar

By default, the CDataMapping property for the image is set to 'direct' so image interprets values in C as indices into the colormap. For example, the bottom right pixel corresponding to the last element in C, 22, uses the 22nd color of the colormap.

Scale the values to the full range of the current colormap by setting the CDataMapping property to 'scaled' when creating the image.

image(C,'CDataMapping','scaled') colorbar

Alternatively, you can use the imagesc function to scale the values instead of using image(C,'CDataMapping','scaled'). For example, use imagesc(C).

Place the image so that it lies between 5 and 8 on the _x_-axis and between 3 and 6 on the _y_-axis.

x = [5 8]; y = [3 6]; C = [0 2 4 6; 8 10 12 14; 16 18 20 22]; image(x,y,C)

Notice that the pixel corresponding to C(1,1) is centered over the point (5,3). The pixel corresponding to C(3,4) is centered over the point (8,6). image positions and orients the rest of the image between those two points.

Create C as a 3-D array of true colors. Use only red colors by setting the last two pages of the array to zeros.

C = zeros(3,3,3); C(:,:,1) = [.1 .2 .3; .4 .5 .6; .7 .8 .9]

C = C(:,:,1) =

0.1000    0.2000    0.3000
0.4000    0.5000    0.6000
0.7000    0.8000    0.9000

C(:,:,2) =

 0     0     0
 0     0     0
 0     0     0

C(:,:,3) =

 0     0     0
 0     0     0
 0     0     0

Display an image of the data in C.

Plot a line, and then create an image on top of the line. Return the image object.

plot(1:3) hold on C = [1 2 3; 4 5 6; 7 8 9]; im = image(C);

Make the image semitransparent so that the line shows through the image.

Read a JPEG image file.

C = imread('ngc6543a.jpg');

imread returns a 650-by-600-by-3 array, C.

Display the image.

Create a surface plot. Then, add an image under the surface. image displays the image in the _xy_-plane.

Z = 10 + peaks; surf(Z) hold on image(Z,'CDataMapping','scaled')

Input Arguments

collapse all

Image color data, specified in one of these forms:

• Vector or matrix — This format defines indexed image data. Each element of C defines a color for 1 pixel of the image. For example, C = [1 2 3; 4 5 6; 7 8 9];. The elements of C map to colors in the colormap of the associated axes. The CDataMapping property controls the mapping method.
• 3-D array of RGB triplets — This format defines true color image data using RGB triplet values. Each RGB triplet defines a color for 1 pixel of the image. An RGB triplet is a three-element vector that specifies the intensities of the red, green, and blue components of the color. The first page of the 3-D array contains the red components, the second page contains the green components, and the third page contains the blue components. Since the image uses true colors instead of colormap colors, the CDataMapping property has no effect.
  • If C is of type double, then an RGB triplet value of [0 0 0] corresponds to black and [1 1 1] corresponds to white.
  • If C is an integer type, then the image uses the full range of data to determine the color. For example, if C is of type uint8, then [0 0 0] corresponds to black and [255 255 255] corresponds to white. If CData is of type int8, then [-128 -128 -128] corresponds to black and [127 127 127] corresponds to white.
  • If C is of type logical, then [0 0 0] corresponds to black and [1 1 1] corresponds to white.

This illustration shows the relative dimensions of C for the two color models.

The behavior of NaN elements is not defined.

To use the low-level version of the image function instead, set theCData property as a name-value pair. For example,image('CData',C).

Converting Between double and Integer Data Types

When you call the image function with a vector or 2-D matrix and use the default CDataMapping value, you must offset your data values by 1 when converting between double values and integer types. This offset is not necessary whenCDataMapping is set to'scaled'.

For example, if U8 contains indexed image data of type uint8, you can convert it to typedouble using:

To convert indexed image data from type double to an integer type, subtract 1 and use round to ensure that all the values are integers. For example, if D contains indexed image data of type double, convert it touint8 using:

U8 = uint8(round(D - 1));

Converting Between Normalized double and Truecolor Values

To convert true color image data from an integer type to typedouble, rescale the data. For example, ifRGB8 is true color image data of typeuint8, convert it to double using:

To convert true color image data from type double to an integer type, rescale the data and use round to ensure that all the values are integers. For example, ifRGB is image data of typedouble, convert it to uint8 using:

RGB8 = uint8(round(RGB*255));

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

Placement along the _x_-axis, specified in one of these forms:

• Two-element vector — Use the first element as the location for the center of C(1,1) and the second element as the location for the center ofC(m,n), where [m,n] = size(C). If C is a 3-D array, then m and n are the first two dimensions. Evenly distribute the centers of the remaining elements of C between those two points.
  The width of each pixel is determined by the expression:
  (x(2)-x(1))/(size(C,2)-1)
  If x(1) > x(2), then the image is flipped left-right.
• Scalar — Center C(1,1) at this location and each following element one unit apart.

Note

• If x has more than two elements,image uses the first and last elements and ignores the other elements.
• To use the low-level version of theimage function instead, set theXData property by using a name-value argument. For example,image('XData',x,'YData',y,'CData',C).
• You cannot interactively pan or zoom outside the_x_-axis limits or_y_-axis limits of an image, unless the limits are already set outside the bounds of the image. If the limits are already outside the bounds, there is no such restriction. If other objects (such as a line) occupy the axes and extend beyond the bounds of the image, you can pan or zoom to the bounds of the other objects, but no further.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | datetime (since R2023b) | duration (since R2023b) | categorical (since R2023b)

Placement along _y_-axis, specified in one of these forms:

• Two-element vector — Use the first element as the location for the center of C(1,1) and the second element as the location for the center ofC(m,n), where [m,n] = size(C). If C is a 3-D array, then m and n are the first two dimensions. Evenly distribute the centers of the remaining elements of C between those two points.
  The height of each pixel is determined by the expression:
  (y(2)-y(1))/(size(C,1)-1)
  If y(1) > y(2), then the image is flipped up-down.
• Scalar — Center C(1,1) at this location and each following element one unit apart.

Note

• If y has more than two elements,image uses the first and last elements and ignores the other elements.
• To use the low-level version of theimage function instead, set theYData property by using a name-value argument. For example,image('XData',x,'YData',y,'CData',C).
• You cannot interactively pan or zoom outside the_x_-axis limits or_y_-axis limits of an image, unless the limits are already set outside the bounds of the image. If the limits are already outside the bounds, there is no such restriction. If other objects (such as a line) occupy the axes and extend beyond the bounds of the image, you can pan or zoom to the bounds of the other objects, but no further.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | datetime (since R2023b) | duration (since R2023b) | categorical (since R2023b)

Axes object. If you do not specify an Axes object, then image uses the current axes.

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=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.

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

Example: image([1 2 3],'AlphaData',0.5) displays a semitransparent image.

The properties listed here are a subset of image properties. For a complete list, see Image Properties.

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

Output Arguments

collapse all

Image object, returned as a scalar. Use im to set properties of the image after it is created. For a list, see Image Properties.

More About

collapse all

The image function has two versions, the high-level version and the low-level version. If you use image with 'CData' as an input argument, then you are using the low-level version. Otherwise, you are using the high-level version.

The high-level version of image calls newplot before plotting and sets these axes properties:

• Layer to'top'. The image is shown in front of any tick marks or grid lines.
• YDir to'reverse'. Values along the_y_-axis increase from top to bottom. To decrease the values from top to bottom, set YDir to'normal'. This setting reverses both the_y_-axis and the image.
• View to [0 90].

The low-level version of the image function does not call newplot and does not set these axes properties.

Tips

• To read image data into MATLAB from graphics files in various standard formats, such as TIFF, use imread. To write MATLAB image data to graphics files, use imwrite. The imread and imwrite functions support a variety of graphics file formats and compression schemes.

Extended Capabilities

expand all

The image function supports GPU array input with these usage notes and limitations:

• This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

Now you can specify the x and y arguments as datetime, duration, or categorical coordinate values. Previously, only numeric and logical coordinate values were supported.