Documentation

imagesc

Display image with scaled colors

collapse all in page

Syntax

imagesc(C)
imagesc(x,y,C)
imagesc('CData',C)
imagesc('XData',x,'YData',y,'CData',C)
imagesc(___,Name,Value)
imagesc(___,clims)
imagesc(ax,___)
im = imagesc(___)

Description

example

imagesc(C)displays the data in arrayCas an image that uses the full range of colors in the colormap. Each element ofCspecifies the color for one pixel of the image. The resulting image is anm-by-ngrid of pixels wheremis the number of rows andnis the number of columns inC. The row and column indices of the elements determine the centers of the corresponding pixels.

example

imagesc(x,y,C)specifies the image location. Usexandyto specify the locations of the corners corresponding toC(1,1)andC(m,n). To specify both corners, setxandyas two-element vectors. To specify the first corner and letimagescdetermine the other, setxandyas scalar values. The image is stretched and oriented as applicable.

imagesc('CData',C)adds the image to the current axes without replacing existing plots. This syntax is the low-level version ofimagesc(C). For more information, seeHigh-Level Versus Low-Level Version.

imagesc('XData',x,'YData',y,'CData',C)specifies the image location. This syntax is the low-level version ofimagesc(x,y,C).

imagesc(___,Name,Value)specifies image properties using one or more name-value pair arguments. You can specify name-value pair arguments after any of the input argument combinations in the previous syntaxes. For a list of image properties and descriptions, seeImage Properties.

example

imagesc(___,clims)specifies the data values that map to the first and last elements of the colormap. Specifyclimsas a two-element vector of the form[cmin cmax], where values less than or equal tocminmap to the first color in the colormap and values greater than or equal tocmaxmap to the last color in the colormap. Specifyclimsafter name-value pair arguments.

imagesc(ax,___)creates the image in the axes specified byaxinstead of in the current axes (gca). Specify the axes as the first input argument.

example

im= imagesc(___)returns theImageobject created. Useimto 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.

Examples

collapse all

Open Live Script

Create matrix C. Display an image of the data in C. Add a colorbar to the graph to show the current colormap. By default,imagescscales the color limits so that image uses the full range of the colormap, where the smallest value inCmaps to the first color in the colormap and the largest value maps to the last color.

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

Open Live Script

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

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

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

Open Live Script

CreateCas an array of data values. Create an image ofCand set the color limits so that values of 4 or less map to the first color in the colormap and values of 18 or more map to the last color in the colormap. Display a colorbar to show how the data values map into the colormap.

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

Open Live Script

Create an image and return the image object,im. Then, make the image semitransparent by setting theAlphaDataproperty of the image object.

C = [1 2 3; 4 5 6; 7 8 9]; im = imagesc(C);

im.AlphaData = .5;

Open Live Script

Create a surface plot. Then, add an image under the surface.imagescdisplays the image in the xy-plane.

Z = 10 + peaks; surf(Z) holdonimagesc(Z)

Input Arguments

collapse all

Image color data, specified as a vector or a matrix. Each element ofCdefines a color for one pixel of the image. The elements ofCmap to colors in the colormap of the associated axes. The smallest value inCmaps to the first color in the colormap and the largest value maps to the last color. The behavior ofNaNelements is not defined.

Note

If you specifyCas anm-by-n-by-3 array, then theimagescfunction interprets the image as a truecolor (RGB) image.imagescdoes not rescale pixel values of truecolor images. Use therescalefunction to scale truecolor pixel values before callingimagesc.

To use the low-level version of theimagescfunction instead, set theCDataproperty as a name-value pair. For example,imagesc('CData',C).

Converting Between Data Types

To convert grayscale image data from an integer type to typedouble, add 1. For example, ifX8is grayscale image data of typeuint8, convert it to typedoubleusing:

X64 = double(X8) + 1;

To convert grayscale image data from typedoubleto an integer type, subtract 1 and useroundto ensure that all the values are integers. For example, ifX64is grayscale image data of typedouble, convert it touint8using:

X8 = uint8(round(X64 - 1));

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

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

  • Two-element vector — Use the first element as the location for the center ofC(1,1)and the second element as the location for the center ofC(m,n), where[m,n] = size(C). IfCis a 3-D array, thenmandnare the first two dimensions. Evenly distribute the centers of the remaining elements ofCbetween those two points.

    The width of each pixel is determined by the expression:

    (x(2)-x(1))/(size(C,2)-1)

    Ifx(1)>x(2), then the image is flipped left-right.

  • Scalar — CenterC(1,1)at this location and each following element one unit apart.

To use the low-level version of theimagescfunction instead, set theXDataproperty as a name-value pair. For example,imagesc('XData',x,'YData',y,'CData',C).

你不能外交互式地拖动或缩放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

Placement alongy-axis, specified in one of these forms:

  • Two-element vector — Use the first element as the location for the center ofC(1,1)and the second element as the location for the center ofC(m,n), where[m,n] = size(C). IfCis a 3-D array, thenmandnare the first two dimensions. Evenly distribute the centers of the remaining elements ofCbetween those two points.

    The height of each pixel is determined by the expression:

    (y(2)-y(1))/(size(C,1)-1)

    Ify(1)>y(2), then the image is flipped up-down.

  • Scalar — CenterC(1,1)at this location and each following element one unit apart.

To use the low-level version of theimagescfunction instead, set theYDataproperty as a name-value pair. For example,imagesc('XData',x,'YData',y,'CData',C).

你不能外交互式地拖动或缩放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

Color limits, specified as a two-element vector of the form[cmin cmax], wherecmaxis greater thancmin. Values inCthat are less than or equal tocminmap to the first color in the colormap. Values greater than or equal tocmaxmap to the last color in the colormap. Values betweencminandcmaxlinearly map to the colormap.

If you specify the color limits, then theimagescfunction sets theCLimproperty of the axes to the values specified. If you do not specify the color limits, thenimagescsets theCLimproperty of the axes to the minimum and maximum values inC.

Axesobject. If you do not specify anAxesobject, thenimagescuses the current axes.

Name-Value Pair Arguments

Specify optional comma-separated pairs ofName,Valuearguments.Nameis the argument name andValueis the corresponding value.Namemust appear inside quotes. You can specify several name and value pair arguments in any order asName1,Value1,...,NameN,ValueN.

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

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

Transparency data, specified in one of these forms:

  • 标量-使用一致的透明度entire image.

  • Array the same size asCData— Use a different transparency value for each image element.

TheAlphaDataMappingproperty controls how MATLAB®interprets the alpha data transparency values.

Example:0.5

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

Interpretation ofAlphaDatavalues, specified as one of these values:

  • 'none'— Interpret the values as transparency values. A value of 1 or greater is completely opaque, a value of 0 or less is completely transparent, and a value between 0 and 1 is semitransparent.

  • 'scaled'— Map the values into the figure’s alphamap. The minimum and maximum alpha limits of the axes determine the alpha data values that map to the first and last elements in the alphamap, respectively. For example, if the alpha limits are[3 5], then alpha data values less than or equal to3map to the first element in the alphamap. Alpha data values greater than or equal to5alphamap映射到最后一个元素。TheALimproperty of the axes contains the alpha limits. TheAlphamapproperty of the figure contains the alphamap.

  • 'direct'— Interpret the values as indices into the figure’s alphamap. Values with a decimal portion are fixed to the nearest lower integer:

    • If the values are of typedoubleorsingle, then values of 1 or less map to the first element in the alphamap. Values equal to or greater than the length of the alphamap map to the last element in the alphamap.

    • If the values are of type integer, then values of 0 or less map to the first element in the alphamap. Values equal to or greater than the length of the alphamap map to the last element in the alphamap (or up to the range limits of the type). The integer types areuint8,uint16,uint32,uint64,int8,int16,int32, andint64.

    • If the values are of typelogical, then values of 0 map to the first element in the alphamap and values of 1 map to the second element in the alphamap.

Output Arguments

collapse all

Imageobject. Useimto set properties of the image after it is created. For a list, seeImage Properties.

More About

collapse all

High-Level Versus Low-Level Version

Theimagescfunction has two versions, the high-level version and the low-level version. If you useimagescwith'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 ofimagesccallsnewplotbefore plotting and sets these axes properties:

  • Layerto'top'. The image is shown in front of any tick marks or grid lines.

  • YDirto“反向”. Values along they-axis increase from top to bottom. To decrease the values from top to bottom, setYDirto'normal'. This setting reverses both they-axis and the image.

  • Viewto[0 90].

The low-level version of theimagescfunction does not callnewplotand does not set these axes properties.

For both versions, theimagescfunction sets:

  • TheCDataproperty of theImageobject to the values inC.

  • TheCDataMappingproperty of theImageobject to'scaled'.

  • TheCLimproperty of theAxesobject to the minimum and maximum values inC, unless you specify theclimsinput argument.

Tips

  • To read image data into MATLAB from graphics files in various standard formats, such as TIFF, useimread. To write MATLAB image data to graphics files, useimwrite. Theimreadandimwritefunctions support various graphics file formats and compression schemes.

  • To view or set the color limits of the axes, you can use thecaxisfunction.

Extended Capabilities

See Also

Functions

Properties

Topics

Introduced before R2006a

MATLAB Documentation
金宝app

Try MATLAB, Simulink, and Other Products

Get trial now