Documentation

imread

Read image from graphics file

collapse all in page

Syntax

A = imread(filename)
A = imread(filename,fmt)
A = imread(___,idx)
A = imread(___,Name,Value)
[A,map] = imread(___)
[A,map,transparency] = imread(___)

Description

example

A= imread(filename)reads the image from the file specified byfilename, inferring the format of the file from its contents. Iffilenameis a multi-image file, thenimreadreads the first image in the file.

A= imread(filename,fmt)additionally specifies the format of the file with the standard file extension indicated byfmt. Ifimreadcannot find a file with the name specified byfilename, it looks for a file namedfilename.fmt.

A= imread(___,idx)从multi-i读取指定的图像或图像mage file. This syntax applies only to GIF, PGM, PBM, PPM, CUR, ICO, TIF, and HDF4 files. You must specify afilenameinput, and you can optionally specifyfmt.

example

A= imread(___,Name,Value)specifies format-specific options using one or more name-value pair arguments, in addition to any of the input arguments in the previous syntaxes.

example

[A,map] = imread(___)reads the indexed image infilenameintoAand reads its associated colormap intomap. Colormap values in the image file are automatically rescaled into the range[0,1].

example

[A,map,transparency] = imread(___)additionally returns the image transparency. This syntax applies only to PNG, CUR, and ICO files. For PNG files,transparencyis the alpha channel, if one is present. For CUR and ICO files, it is the AND (opacity) mask.

Examples

collapse all

Open Live Script

Read a sample image.

A = imread('ngc6543a.jpg');

imreadreturns a 650-by-600-by-3 array,A.

Display the image.

image(A)

Open Live Script

Read the first image in the sample indexed image file,corn.tif.

[X,cmap] = imread('corn.tif');

The indexed imageXis a 415-by-312 array of typeuint8. The colormapcmapis a 256-by-3 matrix of typedouble, therefore there are 256 colors in the indexed image. Display the image.

imshow(X,cmap)

Convert the indexed image to an RGB image. The result is a 415-by-312-by-3 array of typedouble.

RGB = ind2rgb(X,cmap);

Check that values of the RGB image are in the range [0, 1].

disp(['Range of RGB image is [',num2str(min(RGB(:))),', ',num2str(max(RGB(:))),'].'])
Range of RGB image is [0.0078431, 0.97647].
Open Live Script

Read the third image in the sample file,corn.tif.

[X,map] = imread('corn.tif',3);
Open Live Script

Return the alpha channel of the sample image,peppers.png.

[X,map,alpha] = imread('peppers.png'); whosalpha
Name Size Bytes Class Attributes alpha 0x0 0 double

No alpha channel is present, soalphais empty.

Open Live Script

Read a specific region of pixels of the sample image,corn.tif.

Specify the'PixelRegion'parameter with a cell array of vectors indicating the boundaries of the region to read. The first vector specifies the range of rows to read, and the second vector specifies the range of columns to read.

A = imread('corn.tif','PixelRegion',{[1,2],[2,5]});

imreadreads the image data in rows 1-2 and columns 2-5 fromcorn.tifand returns the 2-by-4 array,A.

Input Arguments

collapse all

Name of graphics file, specified as a character vector or string scalar.

Depending on the location of your file,filenamecan take on one of these forms.

Location

Form
Current folder or folder on the MATLAB®path

Specify the name of the file infilename.

Example:'myImage.jpg'

File in a folder

If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name.

Example:'C:\myFolder\myImage.ext'

Example:'\imgDir\myImage.ext'
URL

If the file is located by an internet URL, thenfilenamemust contain the protocol type such as,http://.

Example:'http://hostname/path_to_file/my_image.jpg'

Remote Location

If the file is stored at a remote location, thenfilenamemust contain the full path of the file specified as a uniform resource locator (URL) of the form:

scheme_name://path_to_file/my_file.ext

Based on your remote location,scheme_namecan be one of the values in this table.

Remote Location scheme_name
Amazon S3™ s3
Windows Azure®Blob Storage wasb,wasbs
HDFS™ hdfs

For more information, seeWork with Remote Data.

Example:'s3://bucketname/path_to_file/my_image.jpg'

For information on the bit depths, compression schemes, and color spaces supported for each file type, seeAlgorithms.

Data Types:char|string

Image format, specified as a character vector or string scalar indicating the standard file extension. Callimformatsto see a list of supported formats and their file extensions.

Example:'png'

Data Types:char|string

Image to read, specified as an integer scalar or, for GIF files, a vector of integers. For example, ifidxis 3, thenimreadreturns the third image in the file. For a GIF file, ifidxis1:5, thenimreadreturns only the first five frames. Theidxargument is supported only for multi-image GIF, CUR, ICO, and HDF4 files.

When reading multiple frames from the same GIF file, specifyidxas a vector of frames or use the'Frames','all'name-value pair argument. Because of the way that GIF files are structured, these syntaxes provide faster performance compared to callingimreadin a loop.

For HDF4 files,idxcorresponds to the reference number of the image to read. Reference numbers do not necessarily correspond to the order of the images in the file. You can useimfinfoto match image order with reference number.

Example:3

Data Types:double

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:'Index',5reads the fifth image of a TIFF file.

GIF文件

collapse all

Frames to read, specified as the comma-separated pair consisting of'Frames'and a positive integer, a vector of integers, or'all'. For example, if you specify the value 3,imreadreads the third frame in the file. If you specify'all', thenimreadreads all frames and returns them in the order in which they appear in the file.

Example:'frames',5

JPEG 2000 Files

collapse all

Subimage to read, specified as the comma-separated pair consisting of'PixelRegion'and a cell array of the form{rows,cols}. Therowsinput specifies the range of rows to read. Thecolsinput specifies the range of columns to read. Bothrowsandcolsmust be two-element vectors containing 1-based indices. For example,'PixelRegion',{[1 2],[3 4]}reads the subimage bounded by rows 1 and 2 and columns 3 and 4 in the image data. If the'ReductionLevel'value is greater than 0, thenrowsandcolsare coordinates of the subimage.

Example:'PixelRegion',{[1 100],[4 500]}

Reduction of the image resolution, specified as the comma-separated pair consisting of'ReductionLevel'and a nonnegative integer. For reduction levelL, the image resolution is reduced by a factor of 2^L. The reduction level is limited by the total number of decomposition levels as specified by the'WaveletDecompositionLevels'field in the output of theimfinfofunction.

Example:'ReductionLevel',5

Data Types:single|double

Compatibility with MATLAB 7.9 (R2009b) and earlier, specified as the comma-separated pair consisting of'V79Compatible'and eithertrueorfalse. If you specifytrue, then the returned grayscale or RGB image is consistent with previous versions ofimread(MATLAB 7.9 (R2009b) and earlier).

Example:'V79Compatible',true

Data Types:logical

PNG Files

collapse all

Background color, specified as'none', an integer, or a three-element vector of integers. IfBackgroundColoris'none', thenimreaddoes not perform any compositing. Otherwise,imreadblends transparent pixels with the background color.

  • If the input image is indexed, then the value ofBackgroundColormust be an integer in the range[1,P], wherePis the colormap length.

  • If the input image is grayscale, then the value ofBackgroundColormust be an integer in the range[0,1].

  • If the input image is RGB, then the value ofBackgroundColormust be a three-element vector with values in the range[0,1].

The default value forBackgroundColordepends on the presence of thetransparencyoutput argument and the image type:

  • If you request thetransparencyoutput argument, then the default value ofBackgroundColoris'none'.

  • If you do not request thetransparencyoutput and the PNG file contains a background color chunk, then that color is the default value forBackgroundColor.

  • If you do not request thetransparencyoutput and the file does not contain a background color chunk, then the default value forBackgroundColoris1for indexed images,0for grayscale images, and[0 0 0]for truecolor (RGB) images.

TIFF Files

collapse all

Image to read, specified as the comma-separated pair consisting of'Index'and a positive integer. For example, if the value ofIndexis 3, thenimreadreads the third image in the file.

Data Types:single|double

Information about the image, specified as the comma-separated pair consisting of'Info'and a structure array returned by theimfinfofunction. Use theInfoname-value pair argument to helpimreadlocate the images in a multi-image TIFF file more quickly.

Data Types:struct

Region boundary, specified as the comma-separated pair consisting of'PixelRegion'and a cell array of the form{rows,cols}. Therowsinput specifies the range of rows to read. Thecolsinput specifies the range of columns to read.rowsandcolsmust be either two-element or three-element vectors of 1-based indices. A two-element vector specifies the first and last rows or columns to read. For example,'PixelRegion',{[1 2],[3 4]}reads the region bounded by rows 1 and 2 and columns 3 and 4 in the image data.

A three-element vector must be in the form[start increment stop], wherestartis the first row or column to read,incrementis an incremental value, andstopis the last row or column to read. This syntax allows image downsampling. For example,'PixelRegion',{[1 2 10],[4 3 12]}reads the region bounded by rows 1 and 10 and columns 4 and 12, and samples data from every 2 pixels in the vertical direction, and every 3 pixels in the horizontal direction.

Example:'PixelRegion',{[1 100],[4 500]}

Data Types:cell

Output Arguments

collapse all

Image data, returned as an array.

  • If the file contains a grayscale image, then A is anm-by-narray.

  • If the file contains an indexed image, then A is anm-by-narray of index values corresponding to the color at that index inmap.

  • If the file contains a truecolor image, then A is anm-by-n-by-3 array.

  • If the file is a TIFF file containing color images that use the CMYK color space, then A is anm-by-n-by-4 array.

The class ofAdepends on the image format and the bit depth of the image data. For more information, seeAlgorithms

Colormap associated with the indexed image data inA, returned as anm-by-3 matrix of classdouble.

Transparency information, returned as a matrix. For PNG files,transparencyis the alpha channel, if present. If no alpha channel is present, or if you specify the'BackgroundColor'name-value pair argument, thentransparencyis empty. For CUR and ICO files,transparencyis the AND mask. For cursor files, this mask sometimes contains the only useful data.

More About

collapse all

Bit Depth

Bit depth is the number of bits used to represent each image pixel.

Bit depth is calculated by multiplying the bits-per-sample with the samples-per-pixel. Thus, a format that uses 8 bits for each color component (or sample) and three samples per pixel has a bit depth of 24. Sometimes the sample size associated with a bit depth can be ambiguous. For example, does a 48-bit bit depth represent six 8-bit samples, four 12-bit samples, or three 16-bit samples? SeeAlgorithmsfor sample size information to avoid this ambiguity.

Algorithms

collapse all

For most image file formats,imreaduses 8 or fewer bits per color plane to store image pixels. This table lists the class of the returned image array,A, for the bit depths used by the file formats.

Bit Depth in File

Class of Array Returned byimread

1 bit per pixel

logical

2 to 8 bits per color plane

uint8

9 to 16 bits per pixel

uint16(BMP,JPEG,PNG, andTIFF)

For the 16-bit BMP packed format (5-6-5), MATLAB returnsuint8

The following sections provide information about the support for specific formats, listed in alphabetical order by format name.

BMP — Windows Bitmap JPEG — Joint Photographic Experts Group PNG — Portable Network Graphics
CUR — Cursor File JPEG 2000 — Joint Photographic Experts Group 2000 PPM — Portable Pixmap
GIF — Graphics Interchange Format PBM — Portable Bitmap RAS — Sun Raster
HDF4 — Hierarchical Data Format PCX — Windows Paintbrush TIFF — Tagged Image File Format
ICO — Icon File PGM — Portable Graymap XWD — X Window Dump

BMP — Windows Bitmap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths No Compression RLE Compression Output Class Notes
1 bit ✓ – logical
4 bit ✓ ✓ uint8
8 bit ✓ ✓ uint8
16 bit ✓ – uint8 1 sample/pixel
24 bit ✓ – uint8 3 samples/pixel
32 bit ✓ – uint8 3 samples/pixel
(1 byte padding)

CUR — Cursor File

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths No Compression Compression Output Class
1 bit ✓ – logical
4 bit ✓ – uint8
8 bit ✓ – uint8

Note

By default, Microsoft®Windows®cursors are 32-by-32 pixels. Since MATLAB pointers must be 16-by-16, you might need to scale your image. If you have Image Processing Toolbox™, you can use theimresizefunction.

GIF — Graphics Interchange Format

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths No Compression Compression Output Class
1 bit ✓ – logical
2 bit to 8 bit ✓ – uint8

HDF4 — Hierarchical Data Format

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Raster Image with colormap Raster image without colormap Output Class Notes
8 bit ✓ ✓ uint8
24 bit – ✓ uint8 3 samples/pixel

ICO — Icon File

SeeCUR — Cursor File

JPEG — Joint Photographic Experts Group

imreadreads any baseline JPEG image, as well as JPEG images with some commonly used extensions. For information on JPEG 2000 file support, seeJPEG 2000.

Supported Bits per Sample Lossy Compression Lossless Compression Output Class Notes
8 bit ✓ ✓ uint8 Grayscale or RGB
12 bit ✓ ✓ uint16 Grayscale or RGB
16 bit – ✓ uint16 Grayscale

JPEG 2000 — Joint Photographic Experts Group 2000

For information about JPEG files, seeJPEG.

Note

索引图像JPEG 2000are not supported. Only JP2 compatible color spaces are supported for JP2/JPX files. By default, all image channels are returned in the order they are stored in the file.

Supported Bits per Sample

 Lossy Compression Lossless Compression Output Class Notes
1 bit ✓ ✓ logical Grayscale only
2 bit to 8 bit ✓ ✓ uint8orint8 Grayscale
or RGB
9 bit to 16 bit ✓ ✓ uint16orint16 Grayscale
or RGB

PBM — Portable Bitmap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Raw Binary ASCII (Plain) Encoded Output Class
1 bit ✓ ✓ logical

PCX — Windows Paintbrush

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Output Class Notes
1 bit logical Grayscale only
8 bit uint8 Grayscale or indexed
24 bit uint8 RGB
三个8位/像素样本

PGM — Portable Graymap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Raw Binary ASCII (Plain) Encoded Output Class Notes
8 bit ✓ – uint8
16 bit ✓ – uint16
Arbitrary – ✓ 1-bit to 8-bit:uint8
9-bit to 16-bit:uint16		 Values are scaled

PNG — Portable Network Graphics

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Output Class Notes
1 bit logical Grayscale
2 bit uint8 Grayscale
4 bit uint8 Grayscale
8 bit uint8 Grayscale or Indexed
16 bit uint16 Grayscale or Indexed
24 bit uint8 RGB
三个8位/像素样本.
48 bit uint16 RGB
Three 16-bit samples/pixel.

PPM — Portable Pixmap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Raw Binary ASCII (Plain) Encoded Output Class
Up to 16 bit ✓ – uint8
Arbitrary – ✓

RAS — Sun Raster

This table lists supported bit depths and the data type of the output image data array.

Supported Bit Depths Output Class Notes
1 bit logical Bitmap
8 bit uint8 Indexed
24 bit uint8 RGB
三个8位/像素样本
32 bit uint8 RGB with Alpha
Four 8-bit samples/pixel

TIFF — Tagged Image File Format

imread读最支持的TIFF图像金宝appspecification or LibTIFF. Theimreadfunction supports these TIFF capabilities:

  • Any number of samples per pixel

  • CCITT group 3 and 4 FAX, Packbits, JPEG, LZW, Deflate, ThunderScan compression, and uncompressed images

  • Logical, grayscale, indexed color, truecolor and hyperspectral images

  • RGB, CMYK, CIELAB, ICCLAB color spaces. If the color image uses the CMYK color space,Ais anm-by-n-by-4 array. To determine which color space is used, useimfinfoto get information about the graphics file and look at the value of thePhotometricInterpretationfield. If a file contains CIELAB color data,imreadconverts it to ICCLAB before bringing it into the MATLAB workspace. This conversion is necessary because 8-bit or 16-bit TIFF CIELAB-encoded values use a mixture of signed and unsigned data types that cannot be represented as a single MATLAB array.

  • Data organized into tiles or scanlines

imreadreads and converts TIFF images as follows:

  • YCbCr images are converted into the RGB colorspace.

  • All grayscale images are read as if black =0, white = largest value.

  • 1-bit images are returned as classlogical.

  • 16-bit floating-point images are returned as classsingle.

  • CIELab images are converted into ICCLab colorspace.

For copyright information, open thelibtiffcopyright.txtfile.

XWD — X Window Dump

This table lists the supported bit depths, compression, and output classes for XWD files.

Supported Bit Depths ZPixmaps XYBitmaps XYPixmaps Output Class
1 bit ✓ – ✓ logical
8 bit ✓ – – uint8

Extended Capabilities

See Also

|||||

Topics

Introduced before R2006a

MATLAB Documentation
金宝app

Try MATLAB, Simulink, and Other Products

Get trial now