MATLAB Function Reference

imread

Read image from graphics files

Syntax

• A = imread(filename,fmt)
  [X,map] = imread(filename,fmt)
  [...] = imread(filename)
  [...] = imread(URL,...)
  [...] = imread(...,idx)   (CUR, ICO, and 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 grayscale or truecolor image named filename into A. If the file contains a grayscale intensity image, A is a two-dimensional array. If the file contains a truecolor (RGB) image, A is a three-dimensional (m-by-n-by-3) array.

filename is a string that specifies the name of the graphics file, and fmt is a string that 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. If imread cannot find a file named filename, it looks for a file named filename.fmt. See Formats for a list of all the possible values for fmt.

[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://).

Formats

This table lists the possible values for fmt. 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	File Type
'bmp'	Windows Bitmap (BMP)
'cur'	Windows Cursor resources (CUR)
'gif'	Graphics Interchange Format (GIF)
'hdf'	Hierarchical Data Format (HDF)
'ico'	Windows Icon resources (ICO)
'jpg' or 'jpeg'	Joint Photographic Experts Group (JPEG)
'pbm'	Portable Bitmap (PBM)
'pcx'	Windows Paintbrush (PCX)
'pgm'	Portable Graymap (PGM)
'png'	Portable Network Graphics (PNG)
'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)
'ras'	Sun Raster (RAS)
'tif' or 'tiff'	Tagged Image File Format (TIFF)
'xwd'	X Windows Dump (XWD)

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

Format Support

This table summarizes the types of images that imread can read.

Format	Variants
BMP	1-bit, 4-bit, 8-bit, 16-bit, 24-bit, and 32-bit uncompressed images; 4-bit and 8-bit run-length encoded (RLE) images
CUR	1-bit, 4-bit, and 8-bit uncompressed images
HDF	8-bit raster image datasets, with or without an associated colormap; 24-bit raster image datasets
ICO	1-bit, 4-bit, and 8-bit uncompressed images
JPEG	Any baseline JPEG image; JPEG images with some commonly used extensions
PBM	Any 1-bit PBM image; raw (binary) or ASCII (plain) encoded
PCX	1-bit, 8-bit, and 24-bit images
PGM	Any standard PGM image; ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per gray value
PNG	Any PNG image, including 1-bit, 2-bit, 4-bit, 8-bit, and 16-bit grayscale images; 8-bit and 16-bit indexed images; 24-bit and 48-bit RGB images
PPM	Any PPM image; ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per color component
RAS	Any RAS image, including 1-bit bitmap, 8-bit indexed, 24-bit truecolor and 32-bit truecolor with alpha
TIFF	Any baseline TIFF 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; also 16-bit grayscale, 16-bit indexed, and 48-bit RGB images
XWD	1-bit and 8-bit ZPixmaps; XYBitmaps; 1-bit XYPixmaps

Class Support

In most of the image file formats supported by imread, pixels are stored using 8 or fewer bits per color plane. If the file contains only 1 bit per pixel, the class of the output (A or X) is logical. When reading other files with 8 or fewer bits per color plane, the class of the output is uint8. imread also supports reading 16-bit-per-pixel data from BMP, TIFF and PNG files. For 16-bit TIFF and PNG image files, the class of the output (A or X) is uint16 and for 16-bit BMP image files, the class of the output is 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.

Remarks

imread is a function in MATLAB.

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, imfinfo, imformats, imwrite, uint8, uint16

Bit-Mapped Images for related functions

importdata

imwrite