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 array C as an image that uses the full range of colors in the colormap. Each element of C specifies the color for one pixel of the image. The resulting image is an m-by-n grid of pixels where m 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
imagesc(x,y,C) specifiesthe image location. Use x and y tospecify the locations of the corners corresponding to C(1,1) and C(m,n).To specify both corners, set x and y astwo-element vectors. To specify the first corner and let imagesc determinethe other, set x and y as scalarvalues. 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 of imagesc(C). For more information, see High-Level Versus Low-Level Version.
imagesc('XData',x,'YData',y,'CData',C) specifies the image location. This syntax is the low-level version of imagesc(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, see Image Properties.
example
imagesc(___,clims) specifies the data values that map to the first and last elements of the colormap. Specify clims as a two-element vector of the form [cmin cmax], where values less than or equal to cmin map to the first color in the colormap and values greater than or equal to cmax map to the last color in the colormap. Specify clims after name-value pair arguments.
imagesc(ax,___) creates the image in the axes specified by ax instead of in the current axes (gca). Specify the axes as the first input argument.
example
im = imagesc(___) returnsthe Image object created. Use im toset properties of the image after it is created. You can specify thisoutput with any of the input argument combinations in the previoussyntaxes.
Examples
collapse all
Display Image of Matrix Data
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, imagesc scales the color limits so that image uses the full range of the colormap, where the smallest value in C maps 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
Control Image Placement
Open Live Script
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];imagesc(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). imagesc positions and orients the rest of the image between those two points.
Control Scaling of Data Values into Colormap
Open Live Script
Create C as an array of data values. Create an image of C and 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
Modify Image After Creation
Open Live Script
Create an image and return the image object, im. Then, make the image semitransparent by setting the AlphaData property of the image object.
C = [1 2 3; 4 5 6; 7 8 9];im = imagesc(C);
im.AlphaData = .5;
Add Image to Axes in 3-D View
Open Live Script
Create a surface plot. Then, add an image under the surface. imagesc displays the image in the xy-plane.
Z = 10 + peaks;surf(Z)hold onimagesc(Z)
Input Arguments
collapse all
C — Image color data
vector or matrix
Image color data, specified as a vector or a matrix. Each element of C defines a color for one pixel of the image. The elements of C map to colors in the colormap of the associated axes. The smallest value in C maps to the first color in the colormap and the largest value maps to the last color. The behavior of NaN elements is not defined.
Note
If you specify C as an m-by-n-by-3 array, then the imagesc function interprets the image as a truecolor (RGB) image. imagesc does not rescale pixel values of truecolor images. Use the rescale function to scale truecolor pixel values before calling imagesc.
To use the low-level version of the imagesc function instead, set the CData property as a name-value pair. For example, imagesc('CData',C).
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
x — Placement along x-axis
[1 size(C,2)] (default) | two-element vector | scalar
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). IfCis a 3-D array, thenmandnare 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
xhas more than two elements,imagescuses the first and last elements and ignores the other elements.To use the low-level version of the
imagescfunction instead, set the XData property by using a name-value argument. For example,imagesc('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)
y — Placement along y-axis
[1 size(C,1)] (default) | two-element vector | scalar
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). IfCis a 3-D array, thenmandnare 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
yhas more than two elements,imagescuses the first and last elements and ignores the other elements.To use the low-level version of the
imagescfunction instead, set the YData property by using a name-value argument. For example,imagesc('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)
clims — Color limits
two-element vector of form [cmin cmax]
Color limits, specified as a two-element vector of the form [cmincmax], where cmax is greater than cmin.Values in C that are less than or equal to cmin mapto the first color in the colormap. Values greater than or equal to cmax mapto the last color in the colormap. Values between cmin and cmax linearlymap to the colormap.
If you specify the color limits, then the imagesc functionsets the CLim property of the axes to the valuesspecified. If you do not specify the color limits, then imagesc setsthe CLim property of the axes to the minimum andmaximum values in C.
ax — Axes object
Axes object
Axes object. If you do not specify an Axes object,then imagesc uses the current axes.
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.
Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: imagesc([1 2 3],'AlphaData',0.5) displaysa semitransparent image.
The properties listed here are a subset of image properties.For a complete list, see Image Properties.
Output Arguments
collapse all
im — Image object
Image object
Image object. Use im toset properties of the image after it is created. For a list, see Image Properties.
More About
collapse all
High-Level Versus Low-Level Version
The imagesc function hastwo versions, the high-level version and the low-level version. Ifyou use imagesc with 'CData' asan input argument, then you are using the low-level version. Otherwise,you are using the high-level version.
The high-level version of imagesc calls newplot before plotting and sets theseaxes 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, setYDirto'normal'. This setting reverses both the y-axis and the image.View to
[0 90].
The low-level version of the imagesc functiondoes not call newplot and does not set theseaxes properties.
For both versions, the imagesc function sets:
The CData property of the
Imageobject to the values inC.The CDataMapping property of the
Imageobject to'scaled'.The CLim property of the
Axesobjectto the minimum and maximum values inC, unlessyou specify theclimsinput argument.
Tips
To read image data into MATLAB from graphicsfiles in various standard formats, such as TIFF, use imread. To write MATLAB image datato graphics files, use imwrite.The
imreadandimwritefunctionssupport various graphics file formats and compression schemes.To view or set the color limits of the axes, you can use the clim function.
Before R2022a: Use
caxis, which has the same syntaxes and arguments asclim.
Extended Capabilities
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
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).
Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.
Usage notes and limitations:
This function operates on distributed arrays, but executes in the client MATLAB.
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced before R2006a
expand all
R2023b: Display images with datetime, duration, or categorical pixel coordinates
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.
See Also
Functions
- colormap | colorbar | clim | imread | imwrite | imshow | image | imfinfo
Properties
- Image Properties
Topics
- Working with Image Types in MATLAB
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本 (日本語)
- 한국 (한국어)
Contact your local office
