imread

Read image from graphics file

Syntax

A = imread(filename)

A = imread(filename,fmt)

A = imread(___,idx)

A = imread(___,Name,Value)

[A,map] = imread(___)

[A,map,transparency] = imread(___)

Description

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.

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.

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

[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

Read and Display Image

Read a sample image.

A = imread('ngc6543a.jpg');

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

Display the image.

image(A)

Convert Indexed Image to RGB

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)

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 Specific Image in Multipage TIFF File

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

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

Return Alpha Channel of PNG Image

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 Specified Region of TIFF Image

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

filename — Name of graphics file

character vector | string scalar

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 Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, 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

fmt — Image format

character vector | string scalar

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

idx — Image to read

integer scalar | vector of integers

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

Frames — Frame to read

1 (default) | positive integer | vector of integers | '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

PixelRegion — Subimage to read

cell array in the form {rows,cols}

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

ReductionLevel — Reduction of image resolution

0 (default) | nonnegative integer

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

V79Compatible — Compatibility with MATLAB 7.9 (R2009b) and earlier

false (default) | true

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

BackgroundColor — Background color

'none' | integer | 3-element vector of integers

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

Index — Image to read

1 (default) | positive integer

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

Info — Information about image

structure array

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

PixelRegion — Region boundary

cell array

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

A — Image data

array

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

map — Colormap

m-by-3 matrix

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

transparency — Transparency information

matrix

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

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

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

See CUR — Cursor 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 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, 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 Compression	Lossless Compression	Output Class	Notes
1 bit	✓	✓	logical	Grayscale only
2 bit to 8 bit	✓	✓	uint8 or int8	Grayscale or RGB
9 bit to 16 bit	✓	✓	uint16 or int16	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 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 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 Three 8-bit samples/pixel.
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 Three 8-bit samples/pixel
32 bit	uint8	RGB 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 Depths	ZPixmaps	XYBitmaps	XYPixmaps	Output Class
1 bit	✓	–	✓	logical
8 bit	✓	–	–	uint8

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• This function supports reading of 8-bit JPEG images only. The input argument filename must be a valid absolute path or relative path.

• This function generates code that uses a precompiled, platform-specific shared library (Image Processing Toolbox).

• If you disable runtime error checking when generating your code and subsequently encounter a runtime error, the error is reported in one of these ways:

  • If filename is not a compile-time constant, an empty matrix is returned.

  • If filename is a compile-time constant, a black image of the same dimensions as filename is returned.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• This function supports reading of 8-bit JPEG images only. The input argument filename must be a valid absolute path or relative path.

• This function generates code that uses a precompiled, platform-specific shared library (Image Processing Toolbox).

• If you disable runtime error checking when generating your code and subsequently encounter a runtime error, the error is reported in one of these ways:

  • If filename is not a compile-time constant, an empty matrix is returned.

  • If filename is a compile-time constant, a black image of the same dimensions as filename is returned.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Usage notes and limitations:

• imread does not support reading Hierarchical Data Format (HDF), SVS, or TIFF files when you run imread in the background using backgroundPool or Parallel Computing Toolbox™ Threadpool.

For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

R2021b: Pixel Differences in JPEG 2000 Images

Pixel value differences might exist between JPEG 2000 images in R2021b and previous versions of MATLAB.