imread - Read image from graphics file

Synopsis

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

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 directory, or in a directory 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://).

See the format-specific sections for additional syntaxes.

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. The following is a list of links to the various sections.

BMP — Windows® Bitmap

The following table lists the supported bitdepths, compression, and output classes for BMP data.

Supported BitdepthsNo CompressionRLE CompressionOutput ClassNotes
1-bitxlogical 
4-bitxxuint8 
8-bitxxuint8 
16-bitxuint81 sample/pixel
24-bitxuint83 samples/pixel
32-bitxuint83 samples/pixel
(1 byte padding)

CUR — Cursor File

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

Supported BitdepthsNo CompressionCompressionOutput Class
1-bitxlogical
4-bitxuint8
8-bitxuint8

The following are format-specific syntaxes for Cursor files and Icon files.

[...] = imread(..., idx)    CUR or ICO 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(...)    CUR or ICO 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.

GIF — Graphics Interchange Format

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

Supported BitdepthsNo CompressionCompressionOutput Class
1-bitxlogical
2-bit to 8-bitxuint8

The following are format-specific syntaxes for GIF files.

[...] = imread(..., idx)    GIF 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)    GIF 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.

HDF4 — Hierarchical Data Format

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

Supported BitdepthsRaster Image with colormapRaster image without colormapOutput ClassNotes
8-bitxxuint8 
24-bituint83 samples/pixel

The following are format-specific syntaxes for HDF4 files.

[...] = imread(..., ref)    HDF4 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. The following table lists the supported bitdepths, compression, and output classes for JPEG files.

Supported BitdepthsLossy CompressionLossless CompressionOutput ClassNotes
8-bitxxuint8Grayscale or RGB
12-bitxxuint16Grayscale
16-bitxuint16Grayscale
36-bitxxuint16RGB
Three 12-bit samples/pixel

PBM — Portable Bitmap

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

Supported BitdepthsRaw BinaryASCII (Plain) EncodedOutput Class
1-bitxxlogical

PCX — Windows® Paintbrush

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

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

PGM — Portable Graymap

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

Supported BitdepthsRaw BinaryASCII (Plain) EncodedOutput Class
Up to 16-bitxuint8
Arbitraryx 

PNG — Portable Network Graphics

The following table lists the supported bitdepths, compression, and output classes for PNG data.

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

The following are format-specific syntaxes for PNG files.

[...] = imread(...,'BackgroundColor',BG)   PNG 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(...)   PNG 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 the alpha output argument is specified, BG defaults to 'none', if not specified by the user. 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 images.

PPM — Portable Pixmap

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

Supported BitdepthsRaw BinaryASCII (Plain) EncodedOutput Class
Up to 16-bitxuint8
Arbitraryx 

RAS — Sun™ Raster

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

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

TIFF — Tagged Image File Format

imread supports the following TIFF capabilities:

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

Bits-per-SampleSample FormatOutput Class
1integerlogical
2 – 8integeruint8
9 – 16integeruint16
17 – 32integeruint32
32floatsingle
33 – 64integeruint64
64floatdouble

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

[...] = imread(..., 'PixelRegion', {ROWS, COLS}) returns the subimage 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.

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.

XWD — X Window Dump

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

Supported BitdepthsZPixmapsXYBitmapsXYPixmapsOutput Class
1-bitxxlogical
8-bitxuint8

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

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

  


 © 1984-2008- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS