imread (MATLAB Functions)

Read image from graphics file

Syntax

A = imread(filename,fmt)
[X,map] = imread(filename,fmt)
[...] = imread(filename)
[...] = imread(URL,...)
[...] = imread(...,idx)   (CUR, GIF, ICO, and TIFF only)
[...] = imread(...,'PixelRegion',{ROWS, COLS})  (TIFF only)
[...] = imread(...,'frames',idx) (GIF only)
[...] = imread(...,ref)   (HDF only)
[...] = imread(...,'BackgroundColor',BG) (PNG only)
[A,map,alpha] = imread(...) (ICO, CUR, and PNG only)

Description

The imread function supports four general syntaxes, described below. The imread function also supports several other format-specific syntaxes. See Special Case Syntax for information about these syntaxes.

A = imread(filename,fmt) reads a greyscale or color image from the file specified by the string filename, where the string fmt specifies the format of the file. If the file is not in the current directory or in a directory in the MATLAB path, specify the full pathname of the location on your system. For a list of all the possible values for fmt, see Supported Formats. If imread cannot find a file named filename, it looks for a file named filename.fmt.

imread returns the image data in the array A. If the file contains a grayscale image, A is a two-dimensional (M-by-N) array. If the file contains a color image, A is a three-dimensional (M-by-N-by-3) array. The class of the returned array depends on the data type used by the file format. See Class Support for more information.

For most file formats, the color image data returned uses the RGB color space. For TIFF files, however, imread can return 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. See the TIFF-Specific Syntax for more information.

[X,map] = imread(filename,fmt) reads the indexed image in filename into X and its associated colormap into map. The colormap values are rescaled to 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://).

Supported Formats

This table lists all the types of images that imread can read, in alphabetical order by the fmt abbreviation. You can also get a list of all supported formats by using the imformats function. Note that, for certain formats, imread may take additional parameters, described in Special Case Syntax.

Format
Full Name
Variants

'bmp'
Windows Bitmap (BMP)
1-bit, 4-bit, 8-bit, 16-bit, 24-bit, and 32-bit uncompressed images and 4-bit and 8-bit run-length encoded (RLE) images

'cur'
Windows Cursor resources (CUR)
1-bit, 4-bit, and 8-bit uncompressed images

'gif'
Graphics Interchange Format (GIF)
1-bit to 8-bit images

'hdf'
Hierarchical Data Format (HDF)
8-bit raster image data sets, with or without an associated colormap, and 24-bit raster image data sets

'ico'
Windows Icon resources (ICO)
1-bit, 4-bit, and 8-bit uncompressed images

'jpg' or 'jpeg'
Joint Photographic Experts Group (JPEG)
Any baseline JPEG image or JPEG image with some commonly used extensions, including:
Image Type          Bitdepth           Compression
grayscale               8- or 12-bit            lossy
grayscale               8-, 12-, or 16-bit    lossless
RGB                      24- and 36-bit        lossy or lossless

'pbm'
Portable Bitmap (PBM)
1-bit images using either raw (binary) or ASCII (plain) encoding

'pcx'
Windows Paintbrush (PCX)
1-bit, 8-bit, and 24-bit images

'pgm'
Portable Graymap (PGM)
ASCII (plain) encoding with arbitrary color depth, or raw (binary) encoding with up to 16 bits per gray value

'png'
Portable Network Graphics (PNG)
1-bit, 2-bit, 4-bit, 8-bit, and 16-bit grayscale images; 8-bit and 16-bit indexed images; and 24-bit and 48-bit RGB images

'pnm'
Portable Anymap (PNM)
PNM is not a file format itself. It is a common name for any of the other three members of the Portable Bitmap family of image formats: Portable Bitmap (PBM), Portable Graymap (PGM) and Portable Pixel Map (PPM).

'ppm'
Portable Pixmap (PPM)
ASCII (plain) encoding with arbitrary color depth or raw (binary) encoding with up to 16 bits per color component

'ras'
Sun Raster (RAS)
1-bit bitmap, 8-bit indexed, 24-bit truecolor and 32-bit truecolor with alpha data

'tif' or 'tiff'
Tagged Image File Format (TIFF)
Any baseline image, including 1-bit, 8-bit, and 24-bit uncompressed images; 1-bit, 8-bit, and 24-bit images with packbits compression; 1-bit images with CCITT compression; and 16-bit grayscale, 16-bit indexed, and 48-bit RGB images

'xwd'
X Windows Dump (XWD)
1-bit and 8-bit ZPixmaps, XYBitmaps, and 1-bit XYPixmaps

Format	Full Name	Variants
`'bmp'`	`Windows Bitmap (BMP)`	1-bit, 4-bit, 8-bit, 16-bit, 24-bit, and 32-bit uncompressed images and 4-bit and 8-bit run-length encoded (RLE) images
`'cur'`	`Windows Cursor resources (CUR)`	1-bit, 4-bit, and 8-bit uncompressed images
`'gif'`	`Graphics Interchange Format (GIF)`	1-bit to 8-bit images
`'hdf'`	`Hierarchical Data Format (HDF)`	8-bit raster image data sets, with or without an associated colormap, and 24-bit raster image data sets
`'ico'`	`Windows Icon resources (ICO)`	1-bit, 4-bit, and 8-bit uncompressed images
`'jpg' or 'jpeg'`	`Joint Photographic Experts Group (JPEG)`	Any baseline JPEG image or JPEG image with some commonly used extensions, including: Image Type Bitdepth Compression grayscale 8- or 12-bit lossy grayscale 8-, 12-, or 16-bit lossless RGB 24- and 36-bit lossy or lossless
`'pbm'`	`Portable Bitmap (PBM)`	1-bit images using either raw (binary) or ASCII (plain) encoding
`'pcx'`	`Windows Paintbrush (PCX)`	1-bit, 8-bit, and 24-bit images
`'pgm'`	`Portable Graymap (PGM)`	ASCII (plain) encoding with arbitrary color depth, or raw (binary) encoding with up to 16 bits per gray value
`'png'`	`Portable Network Graphics (PNG)`	1-bit, 2-bit, 4-bit, 8-bit, and 16-bit grayscale images; 8-bit and 16-bit indexed images; and 24-bit and 48-bit RGB images
`'pnm'`	`Portable Anymap (PNM)`	PNM is not a file format itself. It is a common name for any of the other three members of the Portable Bitmap family of image formats: Portable Bitmap (PBM), Portable Graymap (PGM) and Portable Pixel Map (PPM).
`'ppm'`	`Portable Pixmap (PPM)`	ASCII (plain) encoding with arbitrary color depth or raw (binary) encoding with up to 16 bits per color component
`'ras'`	`Sun Raster (RAS)`	1-bit bitmap, 8-bit indexed, 24-bit truecolor and 32-bit truecolor with alpha data
`'tif' or 'tiff'`	`Tagged Image File Format (TIFF)`	Any baseline image, including 1-bit, 8-bit, and 24-bit uncompressed images; 1-bit, 8-bit, and 24-bit images with packbits compression; 1-bit images with CCITT compression; and 16-bit grayscale, 16-bit indexed, and 48-bit RGB images
`'xwd'`	`X Windows Dump (XWD)`	1-bit and 8-bit ZPixmaps, XYBitmaps, and 1-bit XYPixmaps

Special Case Syntax

CUR- and ICO-Specific Syntax

[...] = 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 the Image Processing Toolbox, you can use the imresize function.

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

HDF-Specific Syntax

[...] = imread(...,ref) reads in one image from a multi-image HDF 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 HDF 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.

PNG-Specific Syntax

The discussion in this section is only relevant to PNG files that contain transparent pixels. A PNG file does not necessarily contain transparency data. Transparent pixels, when they exist, are identified by one of two components: a transparency chunk or an alpha channel. (A PNG file can only have one of these components, not both.)

The transparency chunk identifies which pixel values are treated as transparent. For example, if the value in the transparency chunk of an 8-bit image is 0.5020, all pixels in the image with the color 0.5020 can be displayed as transparent. An alpha channel is an array with the same number of pixels as are in the image, which indicates the transparency status of each corresponding pixel in the image (transparent or nontransparent).

Another potential PNG component related to transparency is the background color chunk, which (if present) defines a color value that can be used behind all transparent pixels. This section identifies the default behavior of the toolbox for reading PNG images that contain either a transparency chunk or an alpha channel, and describes how you can override it.

Case 1. You do not ask to output the alpha channel and do not specify a background color to use. For example,

[A,map] = imread(filename);
A = imread(filename);

If the PNG file contains a background color chunk, the transparent pixels are composited against the specified background color.

If the PNG file does not contain a background color chunk, the transparent pixels are composited against 0 for grayscale (black), 1 for indexed (first color in map), or [0 0 0] for RGB (black).

Case 2. You do not ask to output the alpha channel, but you specify the background color parameter in your call. For example,

[...] = imread(...,'BackgroundColor',bg);

The transparent pixels will be composited against the specified color. The form of bg depends on whether the file contains an indexed, intensity (grayscale), or RGB image. If the input image is indexed, bg should be an integer in the range [1,P] where P is the colormap length. If the input image is intensity, 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].

There is one exception to the toolbox's behavior of using your background color. If you set background to 'none' no compositing is performed. For example,

```
[...] = imread(...,'Back','none');
```

Note If you specify a background color, you cannot output the alpha channel.

Case 3. You ask to get the alpha channel as an output variable. For example,

[A,map,alpha] = imread(filename);
[A,map,alpha] = imread(filename,fmt);

No compositing is performed; the alpha channel is stored separately from the image (not merged into the image as in cases 1 and 2). This form of imread returns the alpha channel if one is present, and also returns the image and any associated colormap. If there is no alpha channel, alpha returns []. If there is no colormap, or the image is grayscale or truecolor, map may be empty.

TIFF-Specific Syntax

[...] = imread(...,idx) reads in one image from a multi-image TIFF file. idx is an integer value that specifies the order in which 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.

For TIFF files, imread can read color data represented in the RGB, CIELAB or ICCLAB color spaces. To determine which color space is used, look at the value of the PhotometricInterpretation field returned by imfinfo. Note, however, that if a file contains CIELAB color data, imread converts it to ICCLAB before bringing it into the MATLAB workspace. 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.

[...] = imread(...,'PixelRegion',{ROWS, COLS}) returns the sub-image specified by the boundaries in ROWS and COLS. For tiled TIFF images, imread reads only the tiles that encompass the region specified by ROWS and COLS, improving memory efficiency and performance. ROWS and COLS must be either two or three element vectors. If two elements are provided, they denote the 1-based indices [START STOP]. If three elements are provided, the indices [START INCREMENT STOP] allow image downsampling.

Class Support

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

Data Type Used in File
Class of Array Returned by imread

1-bit
logical

8-bits (or fewer) per color plane
uint8

12-bits
uint16

16-bits (JPEG, PNG, and TIFF)
uint16

16-bits (BMP only)
uint8

Data Type Used in File	Class of Array Returned by imread
1-bit	`logical`
8-bits (or fewer) per color plane	`uint8`
12-bits	`uint16`
16-bits (JPEG, PNG, and TIFF)	`uint16`
16-bits (BMP only)	`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

This example reads the sixth image in a TIFF file.

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

This example reads the fourth image in an HDF file.

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

This example reads a 24-bit PNG image and sets any of its fully transparent (alpha channel) pixels to red.

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

This example returns the alpha channel (if any) of a PNG image.

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

This example reads an ICO image, applies a transparency mask, and then displays 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)

See Also

double, fread, image, imfinfo, imformats, imwrite, uint8, uint16

Bit-Mapped Images for related functions

importdata imwrite