imread - Read image from graphics file - MATLAB (original) (raw)

Read image from graphics file

Syntax

Description

[A](#btnczv9-1-A) = imread([filename](#btnczv9-1%5Fsep%5Fmw%5F3c509488-6925-4904-a5a7-4b420a010c3e)) reads the image from the file specified byfilename, 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](#btnczv9-1-A) = imread([filename](#btnczv9-1%5Fsep%5Fmw%5F3c509488-6925-4904-a5a7-4b420a010c3e),[fmt](#btnczv9-1%5Fsep%5Fmw%5Ffadddc0e-e6d8-4592-b3d2-2de376dd7bcd)) additionally specifies the format of the file with the standard file extension indicated by fmt. Ifimread cannot find a file with the name specified by filename, it looks for a file named_filename.fmt_.

[A](#btnczv9-1-A) = imread(___,[idx](#btnczv9-1-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](#btnczv9-1-A) = imread(___,[Name=Value](#namevaluepairarguments)) 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](#btnczv9-1-A),[map](#btnczv9-1-map)] = imread(___) reads the indexed image infilename into A and reads the associated colormap of the image intomap. 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](#btnczv9-1-A),[map](#btnczv9-1-map),[transparency](#btnczv9-1-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.

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.

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

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

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

Read and display the third image in a sample file.

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

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.

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]))

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]))

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.

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, ifidx 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, specifyidx 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 asName1=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, thenimread reads the third frame in the file. If you specify "all", thenimread 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 asfalse or true. Specify AutoOrient astrue to transform the data infilename according to the ExifOrientation tag in the image file. If you specify AutoOrient asfalse, theimread 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 specifyPixelRegion 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 specifyReductionLevel as value_`L`_, then the image resolution is reduced by a factor of2_`L`_. The reduction level is limited by the total number of decomposition levels, as specified by theWaveletDecompositionLevels 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 asfalse or true. If you specify V79Compatible astrue, then the returned grayscale or RGB image is consistent with previous versions ofimread (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 theimread function does not perform any compositing. Otherwise, theimread 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], whereP 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 ofBackgroundColor must be a three-element vector with numbers in the range [0, 1].

The default value for BackgroundColor depends on the presence of thetransparency output argument and the image type:

• If you request thetransparency output argument, then the default value ofBackgroundColor is"none".
• If you do not request thetransparency output:
  • If the file contains a background color chunk, then the color of that chunk is the default value forBackgroundColor.
  • If the file does not contain a background color chunk:
    * If the input image is indexed, then the default value forBackgroundColor is1.
    * If the input image is grayscale, then the default value forBackgroundColor is0.
    * 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 asfalse or true. Specify AutoOrient astrue to transform the data infilename according to the ExifOrientation tag in the image file. If you specify AutoOrient asfalse, theimread function ignores the Exif Orientation tag.

Note

If you specify [PixelRegion](imread.html#mw%5F7af663ea-4021-498f-8764-38005b96e4c1) in addition to specifyingAutoOrient astrue, then theimread 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 is3, then theimread 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) or0 (false). SpecifyAutoOrient astrue to transform the data infilename according to the ExifOrientation tag in the image file. If you specify AutoOrient asfalse, theimread 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, thenA 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, thenA is an_`m`_-by-_`n`_ array of index values that refer to the rows ofmap.
• If the file contains an RGB (truecolor) image, thenA is an_`m`_-by-_`n`_-by-3 array.
• If the file is a TIFF file containing color images that use the CMYK color space, thenA 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, seeAlgorithms.

Colormap associated with the indexed image data inA, 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 theBackgroundColor name-value argument, then transparency is the alpha channel.
  • If the alpha channel is not present or you specify the BackgroundColor name-value argument, thentransparency is empty.
• For CUR and ICO files,transparency is the AND (opacity) mask.

More About

collapse all

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, 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 Field	Description of Transformation
  1	No transformation
  2	Reflect about vertical axis
  3	Rotate 180°
  4	Reflect about vertical axis and then rotate 180°
  5	Reflect about vertical axis and then rotate 90° counterclockwise
  6	Rotate 90° clockwise
  7	Reflect about vertical axis and then rotate 90° clockwise
  8	Rotate 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.

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

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

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

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.

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

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

This table lists the bit depths, compression, and data types supported by the function for HEIF and HEIC files. (since R2025a)

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.

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.

Note

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

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

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

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

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

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

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

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.

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, useimfinfo to get information about the graphics file and look at the value of the PhotometricInterpretation field. If a file contains CIELAB color data, then theimread 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 classlogical.
• 16-bit floating-point images are returned as classsingle.
• CIELAB images are converted into the ICCLAB color space.

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

Extended Capabilities

expand all

Usage notes and limitations:

• This function supports reading 8-bit JPEG images only. The input argument filename must be a valid absolute path or relative path.
• Code generation does not support theAutoOrient name-value argument.
• This function generates code that uses a precompiled,platform-specific shared library (Image Processing Toolbox).
• If you disable run-time error checking when generating your code and subsequently encounter a run-time error, the error is reported in one of these ways:
  • If filename is not a compile-time constant, an empty matrix is returned.
  • If filename is a compile-time constant, a black image of the same dimensions as filename is returned.
    Run-time error checking is disabled in code that is generated for embedded targets.
• You can generate code for embedded targets (such as the NVIDIA® Jetson™) that uses the imread function with 8-bit JPEG images. Follow these steps to generate code that you can use on embedded targets to read 8-bit JPEG images: (since R2024b)
  1. Generate C/C++ source code and a makefile for the MATLAB code that uses theimread function by usingMATLAB Coder™ with the appropriate configuration, hardware, and input settings.
  2. Compile libjpeg-turbo for the target, and install the shared libraries and header files. (Alternatively, for some targets, you might be able to use a prebuiltlibjpeg-turbo binary or to compile libjpeg-turbo on the target.)
  3. Compile the generated code by linking it with the libjpeg-turbo built for the target.

Usage notes and limitations:

• This function supports reading 8-bit JPEG images only. The input argument filename must be a valid absolute path or relative path.
• Code generation does not support theAutoOrient name-value argument.
• This function generates code that uses a precompiled,platform-specific shared library (Image Processing Toolbox).
• If you disable run-time error checking when generating your code and subsequently encounter a run-time error, the error is reported in one of these ways:
  • If filename is not a compile-time constant, an empty matrix is returned.
  • If filename is a compile-time constant, a black image of the same dimensions as filename is returned.
    Run-time error checking is disabled in code that is generated for embedded targets.
• You can generate code for embedded targets (such as the NVIDIA Jetson) that uses the imread function with 8-bit JPEG images. Follow these steps to generate code that you can use on embedded targets to read 8-bit JPEG images: (since R2024b)
  1. Generate C/C++ source code and a makefile for the MATLAB code that uses theimread function by usingMATLAB Coder with the appropriate configuration, hardware, and input settings.
  2. Compile libjpeg-turbo for the target, and install the shared libraries and header files. (Alternatively, for some targets, you might be able to use a prebuiltlibjpeg-turbo binary or to compile libjpeg-turbo on the target.)
  3. Compile the generated code by linking it with the libjpeg-turbo built for the target.

Version History

Introduced before R2006a

expand all

You can now use imread to get information about HEIF and HEIC image files.

This functionality requires MATLAB Support for HEIF/HEIC Image Format, which is available only on MATLAB desktop environment. However, you cannot use HEIF and HEIC image files in a standalone application workflow.

To install the support package:

• On the MATLAB Home tab, in the Environment section, select Add-Ons >Explore Add-Ons.
• In the Add-On Explorer search bar, search for MATLAB Support for HEIF/HEIC Image Format and then click the MATLAB Support for HEIF/HEIC Image Format add-on.

Apply Exif Orientation tag values to JPEG and TIFF images by using the AutoOrient name-value argument.

Using MATLAB Coder, you can generate code that uses theimread function with 8-bit JPEG images and then use the generated code on embedded targets.

Pixel value differences might exist between JPEG 2000 images in R2021b and previous releases of MATLAB.

When you read a GIF file without specifying additional arguments, theimread function reads only the first frame by default. Previously, imread read all the frames in the file by default.

You can read Aperio SVS microscopy image files and TIFF image files with JPEG 2000 compression.

You can read specified images from multi-image PGM, PBM, or PPM files.