Main Content

imread

Read image from graphics file

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.

example

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 CUR, GIF, HDF4, ICO, PBM, PGM, PPM, SVS, and TIFF 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 arguments in addition to any of the input argument combinations in the previous syntaxes. For example, to orient a JPEG image automatically, set AutoOrient to true (since R2024b).

example

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

example

[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, transparency is the AND (opacity) mask.

example

Examples

collapse all

Read a sample image.

A = imread("ngc6543a.jpg");

The imread function returns a 650-by-600-by-3 array of type uint8.

Display the image.

image(A)

Figure contains an axes object. The axes object contains an object of type image.

Read the first image in a sample indexed image file.

[A,map] = imread("corn.tif");
whos A map
  Name        Size              Bytes  Class     Attributes

  A         415x312            129480  uint8               
  map       256x3                6144  double              

The indexed image A is a 415-by-312 matrix of type uint8, and the colormap map is a 256-by-3 matrix of type double. The dimensions of map indicate that the indexed image contains up to 256 colors.

Display the image.

imshow(A,map)

Figure contains an axes object. The hidden axes object contains an object of type image.

Convert the indexed image to an RGB image. The result is a 415-by-312-by-3 array of type double.

RGB = ind2rgb(A,map);

Check that the values of the RGB image are in the range [0, 1].

[minVal,maxVal] = bounds(RGB(:))
minVal = 
0.0078
maxVal = 
0.9765

Read and display the third image in a sample file.

[A,map] = imread("corn.tif",3);
imshow(A,map)

Figure contains an axes object. The hidden axes object contains an object of type image.

Return the alpha channel of a sample image.

[A,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 a specific region of pixels of a sample image.

Specify the PixelRegion name-value argument with a cell array of vectors indicating the boundaries of the region to read. The first vector describes the range of rows to read, and the second vector describes the range of columns to read.

[A,map] = imread("corn.tif",PixelRegion={[201 400] [151 250]});

The imread function reads the image data in rows 201–400 and columns 151–250 from corn.tif and returns the 200-by-100 array A.

Display the image.

imshow(A,map)

Figure contains an axes object. The hidden axes object contains an object of type image.

Since R2024b

Some image files contain orientation metadata in an exchangeable image file format (Exif) Orientation tag. When reading the image file with imread, you can orient the image data automatically according to this orientation tag by specifying the AutoOrient name-value argument as true.

Make a tiling of eight versions of the same image with different values in their Exif Orientation tags. The file clock_n.jpg has a value of n in its Exif Orientation tag. If you do not specify the AutoOrient name-value argument, then the images are read without regard to their respective Exif Orientation tag values.

filenames = "clock_" + string(1:8) + ".jpg";

for i = 1:8
    rawImages{i} = imread(filenames(i));
end

imshow(imtile(rawImages,BorderSize=[25 25],GridSize=[2 4]))

Figure contains an axes object. The hidden axes object contains an object of type image.

Use the AutoOrient name-value argument to transform each image according to its respective Exif Orientation tag value before reading the image data into the workspace. View the transformed images.

for i = 1:8
    orientedImages{i} = imread(filenames(i),AutoOrient=true);
end
imshow(imtile(orientedImages,BorderSize=[25 25],GridSize=[2 4]))

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

Name of the graphics file, specified as a string scalar or character vector.

Depending on the location of your file, filename can take 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.png"

Example: "\imgDir\myImage.bmp"

Uniform resource locator (URL)

If the file is located by an internet URL, then filename must contain the protocol type, such as http://.

Example: "http://my_hostname/my_path/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 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 Locationscheme_name
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

For more information, see Work with Remote Data.

Example: "s3://my_bucket/my_path/my_image.jpg"

Image format, specified as a string scalar or character vector indicating the standard file extension. Call imformats to see a list of supported formats and their file extensions.

Example: "png"

Image to read, specified as an integer scalar or, for GIF files, a vector of integers. For example, if idx is 3, then the imread function reads the third image in the file. For a GIF file, if idx is 1:5, then the imread function reads 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 specify the Frames name-value argument as "all". Because of the way that GIF files are structured, these syntaxes provide faster performance compared to calling imread in a loop.

Note

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: 2

Example: 6:10

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.

Example: imread("myImage.tif",Index=5) reads the fifth image of a TIFF file.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: imread("myImage.tif","Index",5) reads the fifth image of a TIFF file.

GIF Files

collapse all

Frames to read, specified as a positive integer, a vector of integers, or "all". For example, if you specify the value 3, then 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: 5

Example: 1:10

Example: "all"

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | string | char

JPEG Files

collapse all

Since R2024b

Automatically orient the image, specified as false or true. Specify AutoOrient as true to transform the data in filename according to the Exif Orientation tag in the image file. If you specify AutoOrient as false, the imread function ignores the Exif Orientation tag.

Data Types: logical

JPEG 2000 Files

collapse all

Boundary of region to read, specified as a cell array of the form {rows,cols}. The rows value describes the range of rows to read, and the cols value describes 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 region bounded by rows 1 and 2 and by columns 3 and 4 of the image data.

Note

If you specify ReductionLevel as a positive value, then specify PixelRegion in reference to the image after the reduction of resolution.

Example: {[1 100] [4 500]}

Reduction of the image resolution, specified as a nonnegative integer. If you specify ReductionLevel as value L, then the image resolution is reduced by a factor of 2L. 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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Compatibility with MATLAB 7.9 (R2009b) and earlier, specified as false or true. If you specify V79Compatible as true, then the returned grayscale or RGB image is consistent with previous versions of imread (MATLAB 7.9 (R2009b) and earlier).

Data Types: logical

PNG Files

collapse all

Background color, specified as "none", a positive integer, a number in the range [0, 1], or a three-element vector of numbers in the range [0, 1]. If you specify BackgroundColor as "none", then the imread function does not perform any compositing. Otherwise, the imread function 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 a number in the range [0, 1].

  • If the input image is RGB, then the value of BackgroundColor must be a three-element vector with numbers 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:

    • If the file contains a background color chunk, then the color of that chunk is the default value for BackgroundColor.

    • If the file does not contain a background color chunk:

      • If the input image is indexed, then the default value for BackgroundColor is 1.

      • If the input image is grayscale, then the default value for BackgroundColor is 0.

      • If the input image is RGB, then the default value for BackgroundColor is [0 0 0].

Example: 2

Example: 0.5

Example: [0.2 0.8 0.5]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | string | char

TIFF Files

collapse all

Since R2024b

Automatically orient the image, specified as false or true. Specify AutoOrient as true to transform the data in filename according to the Exif Orientation tag in the image file. If you specify AutoOrient as false, the imread function ignores the Exif Orientation tag.

Note

If you specify PixelRegion in addition to specifying AutoOrient as true, then the imread function first reads the specified region and then transforms the region according to the Exif Orientation tag in the file.

Data Types: logical

Image to read, specified as a positive integer. For example, if the value of Index is 3, then the imread function reads the third image in the file.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Information about the image, specified as a structure array returned by the imfinfo function. Use the Info name-value argument to help imread locate the images in a multi-image TIFF file more quickly.

Data Types: struct

Boundary of region to read, specified as a cell array of the form {rows,cols}. The rows value describes the range of rows to read, and the cols value describes the range of columns to read. Both rows and cols must be two- or three-element vectors containing 1-based indices.

  • A two-element vector of the form [start stop] for rows or cols specifies the first and last row or column to read. For example, {[1 2] [3 4]} reads the region bounded by rows 1 and 2 and by columns 3 and 4 of the image data.

  • A three-element vector of the form [start step stop] for rows or cols specifies the first and last row or column to read, along with a step size. For example, {[1 2 10] [4 3 12]} reads the region bounded by rows 1 and 10 and by columns 4 and 12 of the image data, with a horizontal step size of 2 and a vertical step size of 3.

Example: {[1 100] [4 500]}

Example: {[100 5 200] [250 2 500]}

Output Arguments

collapse all

Image data, returned as an array. If the image data has m rows and n columns, then:

  • If the file contains a grayscale image, then A is an m-by-n array of values that represent the intensity of the pixels in the image.

  • If the file contains an indexed image, then A is an m-by-n array of index values that refer to the rows of map.

  • If the file contains an RGB (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.

Colormap associated with the indexed image data in A, returned as a three-column matrix of class double.

Transparency information, returned as a matrix.

  • For PNG files:

    • If the alpha channel is present and you do not specify the BackgroundColor name-value argument, then transparency is the alpha channel.

    • If the alpha channel is not present or you specify the BackgroundColor name-value argument, then transparency is empty.

  • For CUR and ICO files, transparency is the AND (opacity) mask.

More About

collapse all

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, a 48-bit bit depth can represent six 8-bit samples, four 12-bit samples, or three 16-bit samples. See Algorithms for sample size information to avoid this ambiguity.

Tips

  • The AutoOrient name-value argument operates only on files of JPEG or TIFF format. If you specify the AutoOrient argument with files of any other format, then the argument has no effect. This behavior allows you to use the AutoOrient argument to attempt to orient collections of images automatically, even if some of the files in the collections are not of JPEG or TIFF format. (since R2024b)

  • This table shows how the imread function uses the value of the Exif Orientation tag to transform the image data when the AutoOrient name-value argument is true.

    Value of Orientation FieldDescription of Transformation
    1No transformation
    2Reflect about vertical axis
    3Rotate 180°
    4Reflect about vertical axis and then rotate 180°
    5Reflect about vertical axis and then rotate 90° counterclockwise
    6Rotate 90° clockwise
    7Reflect about vertical axis and then rotate 90° clockwise
    8Rotate 90° counterclockwise

    (since R2024b)

Algorithms

collapse all

For most image file formats, imread uses 8 or fewer bits per color plane to store image pixels. This table lists the data type 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.

These sections provide information about the support for specific formats, listed in alphabetical order by format name.

BMP — Windows Bitmap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit DepthsNo CompressionRLE CompressionOutput ClassNotes
1 bitlogical
4 bit or 8 bituint8
16 bituint81 sample/pixel
24 bituint83 samples/pixel
32 bituint83 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 DepthsNo CompressionCompressionOutput Class
1 bitlogical
4 bituint8
8 bituint8

Note

By default, Microsoft® Windows® cursors are 32-by-32 pixels. Because 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 DepthsNo CompressionCompressionOutput Class
1 bitlogical
2 bit to 8 bituint8

HDF4 — Hierarchical Data Format

This table lists supported bit depths and the data type of the output image data array.

Supported Bit DepthsRaster Image with ColormapRaster Image Without ColormapOutput ClassNotes
8 bituint8
24 bituint83 samples/pixel

ICO — Icon File

JPEG — Joint Photographic Experts Group

The imread function reads baseline JPEG images, as well as JPEG images with some commonly used extensions. For information on JPEG 2000 file support, see JPEG 2000 — Joint Photographic Experts Group 2000. This table lists supported bit depths and the data type of the output image data array.

Supported Bits per SampleLossy CompressionLossless CompressionOutput ClassNotes
8 bituint8Grayscale or RGB
12 bituint16Grayscale or RGB
16 bituint16Grayscale

JPEG 2000 — Joint Photographic Experts Group 2000

For information about JPEG files, see JPEG — Joint Photographic Experts Group. This table lists supported bit depths and the data type of the output image data array.

Supported Bits per Sample

Lossy CompressionLossless CompressionOutput ClassNotes
1 bitlogicalGrayscale only
2 bit to 8 bituint8 or int8Grayscale or RGB
9 bit to 16 bituint16 or int16Grayscale or RGB

Note

Indexed JPEG 2000 images are not supported. Only JP2 compatible color spaces are supported for JP2/JPX files. By default, the imread function returns all image channels in the order they are stored in the file.

PBM — Portable Bitmap

This table lists supported bit depths and the data type of the output image data array.

Supported Bit DepthsRaw BinaryASCII (Plain) EncodedOutput Class
1 bitlogical

PCX — Windows Paintbrush

This table lists supported bit depths and the data type of the output image data array.

Supported Bit DepthsOutput ClassNotes
1 bitlogicalGrayscale
8 bituint8Grayscale or indexed
24 bituint8RGB, 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 DepthsRaw BinaryASCII (Plain) EncodedOutput ClassNotes
8 bituint8
16 bituint16
Arbitrary

1- to 8-bit: uint8

9- 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 DepthsOutput ClassNotes
1 bitlogicalGrayscale
2 bit or 4 bituint8Grayscale
8 bituint8Grayscale or indexed
16 bituint16Grayscale or indexed
24 bituint8RGB, three 8-bit samples/pixel
48 bituint16RGB, 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 DepthsRaw BinaryASCII (Plain) EncodedOutput Class
Up to 16 bituint8
Arbitraryuint8, uint16, or double

RAS — Sun Raster

This table lists supported bit depths and the data type of the output image data array.

Supported Bit DepthsOutput ClassNotes
1 bitlogicalBitmap
8 bituint8Indexed
24 bituint8RGB, three 8-bit samples/pixel
32 bituint8RGB with Alpha, four 8-bit samples/pixel

SVS — Aperio ScanScope Virtual Slide

TIFF-based image file format. The imread function supports reading uncompressed and compressed images, including images with JPEG 2000 compression. For more information, see TIFF — Tagged Image File Format.

TIFF — Tagged Image File Format

The imread function reads most images supported by the TIFF specification or LibTIFF, and 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, and ICCLAB color spaces. If the color image uses the CMYK color space, A is an m-by-n-by-4 array (where m and n represent the number of rows and columns, respectively, in the image data). To determine which color space the file uses, 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, then the imread function 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.

The imread function reads and converts TIFF images as follows:

  • YCbCr images are converted into the RGB color space.

  • 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 the ICCLAB color space.

XWD — X Window Dump

This table lists the supported bit depths, compression, and the data type of the output image data array.

Supported Bit DepthsZPixmapsXYBitmapsXYPixmapsOutput Class
1 bitlogical
8 bituint8

Extended Capabilities

Version History

Introduced before R2006a

expand all

See Also

Functions

Live Editor Tasks