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]. This syntax does not apply to HEIF and HEIC image files as colormap is not supported by these file formats.

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.heif"

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

expand all

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

expand 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

expand 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

expand 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

expand 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

expand 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]}

HIEF and HEIC Files

Since R2025a

expand all

Option to automatically orient the image, specified as a numeric or logical 1 (true) or 0 (false). 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

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

Tips

  • The AutoOrient name-value argument operates only on files of JPEG, TIFF (since R2024b), HEIF, or HEIC (since R2025a) 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, TIFF (since R2024b), HEIF, or HEIC (since R2025a) format.

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

Extended Capabilities

expand all

Version History

Introduced before R2006a

expand all

See Also

Functions

Live Editor Tasks