Main Content

imread

Read image from graphics file

Description

example

A = imread(filename) reads the image from the file specified by filename, inferring the format of the file from its contents. If filename is a multi-image file, then imread reads the first image in the file.

A = imread(filename,fmt) additionally specifies the format of the file with the standard file extension indicated by fmt. If imread cannot find a file with the name specified by filename, it looks for a file named filename.fmt.

A = imread(___,idx) reads the specified image or images from a multi-image file. This syntax applies only to GIF, PGM, PBM, PPM, CUR, ICO, TIF, SVS, and HDF4 files. You must specify a filename input, and you can optionally specify fmt.

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 in filename into A and reads its associated colormap into map. 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, transparency is the alpha channel, if one is present. For CUR and ICO files, it is the AND (opacity) mask.

Examples

collapse all

Read a sample image.

A = imread('ngc6543a.jpg');

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

Display the image.

image(A)

Figure contains an axes object. The axes object contains an object of type image.

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

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

The indexed image X is a 415-by-312 array of type uint8. The colormap cmap is a 256-by-3 matrix of type double, therefore there are 256 colors in the indexed image. Display the image.

imshow(X,cmap)

Figure contains an axes object. The axes object contains an object of type image.

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

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].

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

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

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

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

  alpha      0x0                 0  double              

No alpha channel is present, so alpha is empty.

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]});

imread reads the image data in rows 1-2 and columns 2-5 from corn.tif and 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, filename can take on one of these forms.

Location

Form

Current folder or folder on the MATLAB® path

Specify the name of the file in filename.

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, then filename must 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, then filename must 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 the remote location, scheme_name can be one of the values in this table.

Remote Locationscheme_name
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

For more information, see Work 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, see Algorithms.

Data Types: char | string

Image format, specified as a character vector or string scalar indicating the standard file extension. Call imformats to 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, if idx is 3, then imread returns the third image in the file. For a GIF file, if idx is 1:5, then imread returns only the first five frames. The idx argument is supported only for multi-image GIF, CUR, ICO, and HDF4 files.

When reading multiple frames from the same GIF file, specify idx as 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 calling imread in a loop.

For HDF4 files, idx corresponds 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 use imfinfo to match image order with reference number.

Example: 3

Data Types: double

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

GIF Files

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, imread reads the third frame in the file. If you specify 'all', then imread reads 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}. The rows input specifies the range of rows to read. The cols input specifies the range of columns to read. Both rows and cols must 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, then rows and cols are 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 level L, 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 the imfinfo function.

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 either true or false. If you specify true, then the returned grayscale or RGB image is consistent with previous versions of imread (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. If BackgroundColor is 'none', then imread does not perform any compositing. Otherwise, imread blends transparent pixels with the background color.

  • If the input image is indexed, then the value of BackgroundColor must be an integer in the range [1,P], where P is the colormap length.

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

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

The default value for BackgroundColor depends on the presence of the transparency output argument and the image type:

  • If you request the transparency output argument, then the default value of BackgroundColor is 'none'.

  • If you do not request the transparency output and the PNG file contains a background color chunk, then that color is the default value for BackgroundColor.

  • If you do not request the transparency output and the file does not contain a background color chunk, then the default value for BackgroundColor is 1 for indexed images, 0 for 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 of Index is 3, then imread reads 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 the imfinfo function. Use the Info name-value pair argument to help imread locate 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}. The rows input specifies the range of rows to read. The cols input specifies the range of columns to read. rows and cols must 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], where start is the first row or column to read, increment is an incremental value, and stop is 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 an m-by-n array.

  • If the file contains an indexed image, then A is an m-by-n array of index values corresponding to the color at that index in map.

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

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

The class of A depends on the image format and the bit depth of the image data. For more information, see Algorithms

Colormap associated with the indexed image data in A, returned as an m-by-3 matrix of class double.

Transparency information, returned as a matrix. For PNG files, transparency is the alpha channel, if present. If no alpha channel is present, or if you specify the 'BackgroundColor' name-value pair argument, then transparency is empty. For CUR and ICO files, transparency is 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? See Algorithms for sample size information to avoid this ambiguity.

Algorithms

collapse all

For most image file formats, imread uses 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 by imread

1 bit per pixel

logical

2 to 8 bits per color plane

uint8

9 to 16 bits per pixel

uint16 (BMP, JPEG, PNG, and TIFF)

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

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

BMP — Windows Bitmap

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

Supported Bit DepthsNo CompressionRLE CompressionOutput ClassNotes
1 bitlogical 
4 bituint8 
8 bituint8 
16 bituint81 sample/pixel
24 bituint83 samples/pixel
32 bituint83 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 DepthsNo CompressionCompressionOutput Class
1 bitlogical
4 bituint8
8 bituint8

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. You can use the imresize function for this operation.

GIF — Graphics Interchange Format

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

Supported Bit DepthsNo CompressionCompressionOutput Class
1 bitlogical
2 bit to 8 bituint8

HDF4 — Hierarchical Data Format

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

Supported Bit DepthsRaster Image with colormapRaster image without colormapOutput ClassNotes
8 bituint8 
24 bituint83 samples/pixel

ICO — Icon File

JPEG — Joint Photographic Experts Group

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

Supported Bits per SampleLossy CompressionLossless CompressionOutput ClassNotes
8 bituint8Grayscale or RGB
12 bituint16Grayscale or RGB
16 bituint16Grayscale

JPEG 2000 — Joint Photographic Experts Group 2000

For information about JPEG files, see JPEG.

Note

Indexed JPEG 2000 images are 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 CompressionLossless CompressionOutput ClassNotes
1 bitlogicalGrayscale only
2 bit to 8 bituint8 or int8Grayscale
or RGB
9 bit to 16 bituint16 or int16Grayscale
or RGB

PBM — Portable Bitmap

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

Supported Bit DepthsRaw BinaryASCII (Plain) EncodedOutput Class
1 bitlogical

PCX — Windows Paintbrush

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

Supported Bit DepthsOutput ClassNotes
1 bitlogicalGrayscale only
8 bituint8Grayscale or indexed
24 bituint8RGB
Three 8-bit samples/pixel

PGM — Portable Graymap

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

Supported Bit DepthsRaw BinaryASCII (Plain) EncodedOutput ClassNotes
8 bituint8 
16 bituint16 
Arbitrary1-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 DepthsOutput ClassNotes
1 bitlogicalGrayscale
2 bituint8Grayscale
4 bituint8Grayscale
8 bituint8Grayscale or Indexed
16 bituint16Grayscale or Indexed
24 bituint8RGB
Three 8-bit samples/pixel.
48 bituint16RGB
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 DepthsRaw BinaryASCII (Plain) EncodedOutput Class
Up to 16 bituint8
Arbitrary 

RAS — Sun Raster

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

Supported Bit DepthsOutput ClassNotes
1 bitlogicalBitmap
8 bituint8Indexed
24 bituint8RGB
Three 8-bit samples/pixel
32 bituint8RGB with Alpha
Four 8-bit samples/pixel

Aperio SVS — Aperio ScanScope Virtual Slide

TIFF-based image file format. imread supports reading uncompressed and compressed images, including images with JPEG2000 compression. For more information, see TIFF — Tagged Image File Format.

TIFF — Tagged Image File Format

imread reads most images supported by the TIFF specification or LibTIFF. The imread function 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, A is an m-by-n-by-4 array. To determine which color space is used, use imfinfo to get information about the graphics file and look at the value of the PhotometricInterpretation field. If a file contains CIELAB color data, imread converts 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

imread reads 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 class logical.

  • 16-bit floating-point images are returned as class single.

  • CIELab images are converted into ICCLab colorspace.

XWD — X Window Dump

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

Supported Bit DepthsZPixmapsXYBitmapsXYPixmapsOutput Class
1 bitlogical
8 bituint8

Extended Capabilities

Version History

Introduced before R2006a

expand all

See Also

Functions

Live Editor Tasks