Display image from array
collapse all in page
Syntax
image(C)
image(x,y,C)
image('CData',C)
image('XData',x,'YData',y,'CData',C)
image(___,Name,Value)
image(ax,___)
im = image(___)
Description
example
image(C)
displays the data in array C
as an image. Each element of C
specifies the color for 1 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
image(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 image
determinethe other, set x
and y
as scalarvalues. The image is stretched and oriented as applicable.
image('CData',C)
addsthe image to the current axes without replacing existing plots. Thissyntax is the low-level version of image(C)
. Formore information, see High-Level Versus Low-Level Version of Image.
image('XData',x,'YData',y,'CData',C)
specifiesthe image location. This syntax is the low-level version of image(x,y,C)
.
example
image(___,Name,Value)
specifiesimage properties using one or more name-value pair arguments. Youcan specify image properties with any of the input argument combinationsin the previous syntaxes.
image(ax,___)
createsthe image in the axes specified by ax
instead ofin the current axes (gca
). The option ax
canprecede any of the input argument combinations in the previous syntaxes.
example
im = image(___)
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. For a list of image properties and descriptions, see Image Properties.
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.
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)
.
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];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.
Display Image of 3-D Array of True Colors
Open Live Script
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.9000C(:,:,2) = 0 0 0 0 0 0 0 0 0C(:,:,3) = 0 0 0 0 0 0 0 0 0
Display an image of the data in C
.
image(C)
Modify Image After Creation
Open Live Script
Plot a line, and then create an image on top of the line. Return the image object.
plot(1:3)hold onC = [1 2 3; 4 5 6; 7 8 9];im = image(C);
Make the image semitransparent so that the line shows through the image.
im.AlphaData = 0.5;
Read and Display JPEG Image File
Open Live Script
Read a JPEG image file.
C = imread('ngc6543a.jpg');
imread
returns a 650-by-600-by-3 array, C
.
Display the image.
image(C)
Add Image to Axes in 3-D View
Open Live Script
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
C
— Image color data
vector or matrix | 3-D array of RGB triplets
Image color data, specified in one of these forms:
Vector or matrix — This format defines indexedimage data. Each element of
C
defines a color for1 pixel of the image. For example,C = [1 2 3; 4 5 6; 7 89];
. The elements ofC
map to colorsin the colormap of the associated axes. The CDataMapping propertycontrols the mapping method.3-D array of RGB triplets — This format definestrue color image data using RGB triplet values. Each RGB triplet definesa color for 1 pixel of the image. An RGB triplet is a three-elementvector that specifies the intensities of the red, green, and bluecomponents of the color. The first page of the 3-D array containsthe red components, the second page contains the green components,and the third page contains the blue components. Since the image usestrue colors instead of colormap colors, the
CDataMapping
propertyhas no effect.If
C
is of typedouble
,then an RGB triplet value of[0 0 0]
correspondsto black and[1 1 1]
corresponds to white.If
C
is an integer type, then theimage uses the full range of data to determine the color. For example,ifC
is of typeuint8
, then[00 0]
corresponds to black and[255 255 255]
correspondsto white. IfCData
is of typeint8
,then[-128 -128 -128]
corresponds to black and[127127 127]
corresponds to white.If
C
is of typelogical
,then[0 0 0]
corresponds to black and[11 1]
corresponds to white.
This illustration shows the relative dimensions of C
forthe two color models.
The behavior of NaN
elements is not defined.
To use the low-level version of the image
function instead, set the CData 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 when CDataMapping
is set to 'scaled'
.
For example, if U8
contains indexed image data of type uint8
, you can convert it to type double
using:
D = double(U8) + 1;
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 to uint8
using:
U8 = uint8(round(D - 1));
Converting Between Normalized double
and Truecolor Values
To convert true color image data from an integer type to type double
, rescale the data. For example, if RGB8
is true color image data of type uint8
, convert it to double
using:
RGB = double(RGB8)/255;
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, if RGB
is image data of type double
, convert it to uint8
using:
RGB8 = uint8(round(RGB*255));
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)
. IfC
is a 3-D array, thenm
andn
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 the
image
function instead, set the XData 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)
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)
. IfC
is a 3-D array, thenm
andn
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 the
image
function instead, set the YData 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)
ax
— Axes
object
Axes
object
Axes
object. If you do not specify an Axes
object,then image
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: image([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, returned as a scalar. 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 of Image
The image
function has twoversions, the high-level version and the low-level version. If youuse image
with 'CData'
as aninput 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 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, setYDir
to'normal'
. This setting reverses both the y-axis and the image.View to
[0 90]
.
The low-level version of the image
functiondoes not call newplot
and does not set theseaxes properties.
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
imread
andimwrite
functionssupport a variety of graphics file formats and compression schemes.
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 | imread | imwrite | imshow | imagesc | imfinfo
Properties
- Image Properties
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
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