Learn more about MATLAB

imread - Read image from graphics file

Syntax

A = imread(filename, fmt) [X, map] = imread(...) [...] = imread(filename) [...] = imread(URL,...) [...] = imread(...,Param1,Val1,Param2,Val2...)

Description

A = imread(filename, fmt) reads a grayscale or color image from the file specified by the string filename. If the file is not in the current folder, or in a folder on the MATLAB path, specify the full pathname.

The text string fmt specifies the format of the file by its standard file extension. For example, specify 'gif' for Graphics Interchange Format files. To see a list of supported formats, with their file extensions, use the imformats function. If imread cannot find a file named filename, it looks for a file named filename.fmt.

The return value A is an array containing the image data. If the file contains a grayscale image, A is an M-by-N array. If the file contains a truecolor image, A is an M-by-N-by-3 array. For TIFF files containing color images that use the CMYK color space, A is an M-by-N-by-4 array. See TIFF in the Format-Specific Information section for more information.

The class of A depends on the bits-per-sample of the image data, rounded to the next byte boundary. For example, imread returns 24-bit color data as an array of uint8 data because the sample size for each color component is 8 bits. See Remarks for a discussion of bitdepths, and see Format-Specific Information for more detail about supported bitdepths and sample sizes for a particular format.

[X, map] = imread(...) reads the indexed image in filename into X and its associated colormap into map. Colormap values in the image file are automatically rescaled into the range [0,1].

[...] = imread(filename) attempts to infer the format of the file from its content.

[...] = imread(URL,...) reads the image from an Internet URL. The URL must include the protocol type (e.g., http://).

[...] = imread(...,Param1,Val1,Param2,Val2...) specifies parameters that control various characteristics of the operations for specific formats. For more information, see Format-Specific Information.

Remarks

Bitdepth is the number of bits used to represent each image pixel. Bitdepth 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 bitdepth of 24. Sometimes the sample size associated with a bitdepth can be ambiguous: does a 48-bit bitdepth represent six 8-bit samples, four 12-bit samples, or three 16-bit samples? The following format-specific sections provide sample size information to avoid this ambiguity.

Format-Specific Information

The following sections provide information about the support for specific formats, listed in alphabetical order by format name. These sections include information about format-specific syntaxes, if they exist.

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

Supported Bitdepths	No Compression	RLE Compression	Output Class	Notes
1-bit	x	–	logical
4-bit	x	x	`uint8`
8-bit	x	x	`uint8`
16-bit	x	–	`uint8`	1 sample/pixel
24-bit	x	–	`uint8`	3 samples/pixel
32-bit	x	–	`uint8`	3 samples/pixel (1 byte padding)

CUR — Cursor File

Supported Bitdepths	No Compression	Compression	Output Class
1-bit	x	–	logical
4-bit	x	–	`uint8`
8-bit	x	–	`uint8`

Format-specific syntaxes:

[...] = imread(..., idx) reads in one image from a multi-image icon or cursor file. idx is an integer value that specifies the order that the image appears in the file. For example, if idx is 3, imread reads the third image in the file. If you omit this argument, imread reads the first image in the file.

[A, map, alpha] = imread(...) returns the AND mask for the resource, which can be used to determine the transparency information. For cursor files, this mask may contain the only useful data.

Note By default, Microsoft Windows cursors are 32-by-32 pixels. MATLAB pointers must be 16-by-16. You will probably need to scale your image. If you have Image Processing Toolbox™, you can use the imresize function.

GIF — Graphics Interchange Format

Supported Bitdepths	No Compression	Compression	Output Class
1-bit	x	–	logical
2-bit to 8-bit	x	–	`uint8`

Format-specific syntaxes:

[...] = imread(..., idx) reads in one or more frames from a multiframe (i.e., animated) GIF file. idx must be an integer scalar or vector of integer values. For example, if idx is 3, imread reads the third image in the file. If idx is 1:5, imread returns only the first five frames.

[...] = imread(..., 'frames', idx) is the same as the syntax above except that idx can be 'all'. In this case, all the frames are read and returned in the order that they appear in the file.

Note Because of the way that GIF files are structured, all the frames must be read when a particular frame is requested. Consequently, it is much faster to specify a vector of frames or 'all' for idx than to call imread in a loop when reading multiple frames from the same GIF file.

HDF4 — Hierarchical Data Format

Supported Bitdepths	Raster Image with colormap	Raster image without colormap	Output Class	Notes
8-bit	x	x	`uint8`
24-bit	–	x	`uint8`	3 samples/pixel

Format-specific syntaxes:

[...] = imread(..., ref) reads in one image from a multi-image HDF4 file. ref is an integer value that specifies the reference number used to identify the image. For example, if ref is 12, imread reads the image whose reference number is 12. (Note that in an HDF4 file the 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.) If you omit this argument, imread reads the first image in the file.

ICO — Icon File

See CUR — Cursor File

JPEG — Joint Photographic Experts Group

imread can read any baseline JPEG image as well as JPEG images with some commonly used extensions. For information about support for JPEG 2000 files, see JPEG 2000.

Supported Bitdepths	Lossy Compression	Lossless Compression	Output Class	Notes
8-bit	x	x	`uint8`	Grayscale or RGB
12-bit	x	x	`uint16`	Grayscale
16-bit	–	x	`uint16`	Grayscale
36-bit	x	x	`uint16`	RGB Three 12-bit samples/pixel

JPEG 2000 — Joint Photographic Experts Group 2000

For information about JPEG files, see JPEG.

Note Only 1- and 3-sample images are supported. Indexed JPEG 2000 images are not supported.

Supported Bitdepths
(Bits-per-sample) Lossy Compression Lossless Compression Output Class Notes

1-bit x x logical Grayscale only

2- to 8-bit x x uint8 Grayscale
or RGB

9- to 16-bit x x uint16 Grayscale
or RGB

Supported Bitdepths (Bits-per-sample)	Lossy Compression	Lossless Compression	Output Class	Notes
1-bit	x	x	`logical`	Grayscale only
2- to 8-bit	x	x	`uint8`	Grayscale or RGB
9- to 16-bit	x	x	`uint16`	Grayscale or RGB

Format-specific syntaxes:

[...] = imread(..., 'Param1', value1, 'Param2', value2, ...) uses parameter-value pairs to control the read operation, described in the following table.

Parameter	Value
`'ReductionLevel'`	A non-negative integer specifying the reduction in the resolution of the image. For a reduction level L, the image resolution is reduced by a factor of 2^L. Its default value is `0` implying no reduction. The reduction level is limited by the total number of decomposition levels as specified by the`'WaveletDecompositionLevels'` field in the structure returned by the `imfinfo` function.
`'PixelRegion'`	`{ROWS, COLS}` — The `imread` function returns the sub-image specified by the boundaries in `ROWS` and `COLS`. `ROWS` and `COLS` must both be two-element vectors that denote the 1-based indices `[START STOP]`. If `'ReductionLevel'` is greater than 0, then `ROWS` and `COLS` are coordinates in the reduced-sized image.

PBM — Portable Bitmap

Supported Bitdepths	Raw Binary	ASCII (Plain) Encoded	Output Class
1-bit	x	x	logical

PCX — Windows Paintbrush

Supported Bitdepths	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

Supported Bitdepths	Raw Binary	ASCII (Plain) Encoded	Output Class
Up to 16-bit	x	–	`uint8`
Arbitrary	–	x

PNG — Portable Network Graphics

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

Format-specific syntaxes:

[...] = imread(...,'BackgroundColor',BG) composites any transparent pixels in the input image against the color specified in BG. If BG is 'none', then no compositing is performed. If the input image is indexed, BG must be an integer in the range [1,P] where P is the colormap length. If the input image is grayscale, BG should be an integer in the range [0,1]. If the input image is RGB, BG should be a three-element vector whose values are in the range [0,1]. The string 'BackgroundColor' may be abbreviated.

[A, map, alpha] = imread(...) returns the alpha channel if one is present; otherwise alpha is []. Note that map may be empty if the file contains a grayscale or truecolor image.

If you specify thealpha output argument, BG defaults to 'none', if not specified. Otherwise, if the PNG file contains a background color chunk, that color is used as the default value for BG. If alpha is not used and the file does not contain a background color chunk, then the default value for BG is 1 for indexed images; 0 for grayscale images; and [0 0 0] for truecolor (RGB) images.

PPM — Portable Pixmap

Supported Bitdepths	Raw Binary	ASCII (Plain) Encoded	Output Class
Up to 16-bit	x	–	`uint8`
Arbitrary	–	x

RAS — Sun Raster

The following table lists the supported bitdepths, compression, and output classes for RAS files.

Supported Bitdepths	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

TIFF — Tagged Image File Format

imread supports the following 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 because 8- 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

The following table lists the supported bit/sample and corresponding output classes for TIFF files.

Supported Bitdepths	Compression							Output Class	Notes
	None	Packbits	CCITT	RGB	ICCLAB	CIELAB	CMYK
1-bit	x	x	x	-	-	-	-	`logical`
8-bit	x	x	-	-	-	-	-	`uint8`
12-bit	-	-	-	-	-	-	-	`uint16`	Grayscale or Indexed
16-bit	-	-	-	-	-	-	-	`uint16`	Grayscale or Indexed
24-bit	x	x	-	x	x	x	-	`uint8`	3 samples
32-bit	-	-	-	-	-	-	x	`uint8`	4 samples
36-bit	-	-	-	x	-	-	-	`uint16`	3 samples
48-bit	-	-	-	x	x	x	-	`uint16`	3 samples
64-bit	-	-	-	-	-	-	x	`double`	4 samples

Note imread supports 8-bit integral and 32-bit floating point tiled TIFF images, with any compression and color space combination listed above, and 32-bit IEEE floating point images.

The following are format-specific syntaxes for TIFF files.

A = imread(...) returns color data that uses the RGB, CIELAB, ICCLAB, or CMYK color spaces. If the color image uses the CMYK color space, A is an M-by-N-by-4 array.

[...] = imread(..., 'Param1', value1, 'Param2', value2, ...) uses parameter/value pairs to control the read operation. The following table lists the parameters you can use.

Parameter Value

'Index' Positive integer specifying which image to read. For example, if you specify the value 3, imread reads the third image in the file. If you omit this argument, imread reads the first image in the file.

Parameter	Value
`'Index'`	Positive integer specifying which image to read. For example, if you specify the value `3`, `imread` reads the third image in the file. If you omit this argument, `imread` reads the first image in the file.
`'Info'`	Structure array returned by `imfinfo`. Note: When reading images from a multi-image TIFF file, passing the output of `imfinfo` as the value of the `'Info'` argument helps `imread` locate the images in the file more quickly.
`'PixelRegion'`	Cell array, `{Rows, Cols}`, specifying the boundaries of the region. `Rows` and `Cols` must be either two- or three-element vectors. If you specify two elements, the values denote the 1-based indices `[start stop]`. If you specify three elements, the values denote the 1-based indices `[start increment stop]`, to allow image downsampling.

'Info'

Structure array returned by imfinfo.

Note: When reading images from a multi-image TIFF file, passing the output of imfinfo as the value of the 'Info' argument helps imread locate the images in the file more quickly.

'PixelRegion' Cell array, {Rows, Cols}, specifying the boundaries of the region. Rows and Cols must be either two- or three-element vectors. If you specify two elements, the values denote the 1-based indices [start stop]. If you specify three elements, the values denote the 1-based indices [start increment stop], to allow image downsampling.

For copyright information, see the libtiffcopyright.txt file.

XWD — X Window Dump

The following table lists the supported bitdepths, compression, and output classes for XWD files.

Supported Bitdepths	ZPixmaps	XYBitmaps	XYPixmaps	Output Class
1-bit	x	–	x	`logical`
8-bit	x	–	–	`uint8`

Class Support

For most image file formats, imread uses 8 or fewer bits per color plane to store image pixels. The following table lists the class of the returned array for the data types used by the file formats.

Data Type Used in File	Class of Array Returned by imread
1-bit per pixel	`logical`
2- to 8-bits per color plane	`uint8`
9- to 16-bit per pixel	`uint16` (`BMP`, `JPEG`, `PNG`, and `TIFF`) For the 16-bit BMP packed format (5-6-5), MATLAB returns `uint8`

Data Type Used in File

Class of Array Returned by imread

1-bit per pixel

logical

2- to 8-bits per color plane

uint8

9- to 16-bit per pixel

uint16 (BMP, JPEG, PNG, and TIFF)

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

Note For indexed images, imread always reads the colormap into an array of class double, even though the image array itself may be of class uint8 or uint16.

Examples

Read sample image.

imdata = imread('ngc6543a.jpg');

Read sixth image in a TIFF file.

[X,map] = imread('your_image.tif',6);

Read fourth image in an HDF4 file.

info = imfinfo('your_hdf_file.hdf');
[X,map] = imread('your_hdf_file.hdf',info(4).Reference);

Read a 24-bit PNG image and set any of its fully transparent (alpha channel) pixels to red.

bg = [1 0 0];
A = imread('your_image.png','BackgroundColor',bg);

Return the alpha channel (if any) of a PNG image.

[A,map,alpha] = imread('your_image.png');

Read an ICO image, apply a transparency mask, and then display the image.

[a,b,c] = imread('your_icon.ico'); 
% Augment colormap for background color (white).
b2 = [b; 1 1 1]; 
% Create new image for display. 
d = ones(size(a)) * (length(b2) - 1); 
% Use the AND mask to mix the background and
% foreground data on the new image
d(c == 0) = a(c == 0); 
% Display new image
image(uint8(d)), colormap(b2)

imread - Read image from graphics file

Syntax

Description

Remarks

Format-Specific Information

BMP — Windows Bitmap

CUR — Cursor File

GIF — Graphics Interchange Format

HDF4 — Hierarchical Data Format

ICO — Icon File

JPEG — Joint Photographic Experts Group

JPEG 2000 — Joint Photographic Experts Group 2000

PBM — Portable Bitmap

PCX — Windows Paintbrush

PGM — Portable Graymap

PNG — Portable Network Graphics

PPM — Portable Pixmap

RAS — Sun Raster

TIFF — Tagged Image File Format

XWD — X Window Dump

Class Support

Examples

See Also

Recommended Products