imread

Read image from graphics file

Syntax

A = imread(filename)

A = imread(filename,fmt)

A = imread(___,idx)

A = imread(___,Name=Value)

[A,map]
= imread(___)

[A,map,transparency]
= imread(___)

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 and Display Image

Open Live Script

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.

Convert Indexed Image to RGB

Open Live Script

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 Specific Image in Multipage TIFF File

Open Live Script

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 Alpha Channel of PNG Image

Open Live Script

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 Specified Region of TIFF Image

Open Live Script

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.

Automatically Orient Images

Since R2024b

Open Live Script

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

`filename` — Name of graphics file
string scalar | character vector

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 Location	`scheme_name`
Amazon S3™	`s3`
Windows Azure^® Blob Storage	`wasb`, `wasbs`
HDFS™	`hdfs`

For more information, see Work with Remote Data.

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

`fmt` — Image format
string scalar | character vector

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"

`idx` — Image to read
integer scalar | vector of integers

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` — Frames to read
`1` (default) | positive integer | vector of integers | `"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"

JPEG Files

expand all

`AutoOrient` — Automatically orient image
`false` (default) | `true`

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

`PixelRegion` — Boundary of region to read
cell array of form `{rows,cols}`

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

`ReductionLevel` — Reduction of image resolution
`0` (default) | positive integer

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 2^L. 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.

`V79Compatible` — Compatibility with MATLAB 7.9 (R2009b) and earlier
`false` (default) | `true`

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

`BackgroundColor` — Background color
`"none"` | positive integer | number in range [0, 1] | three-element vector of numbers in range [0, 1]

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]

TIFF Files

expand all

`AutoOrient` — Automatically orient image
`false` (default) | `true`

Since R2024b

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

`Index` — Image to read
`1` (default) | positive integer

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.

`Info` — Information about image
structure array

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

`PixelRegion` — Boundary of region to read
cell array of form `{rows,cols}`

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

`AutoOrient` — Option to automatically orient image
true or 1 (default) | false or 0

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

`A` — Image data
array

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.

`map` — Colormap
three-column matrix

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

`transparency` — Transparency information
matrix

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

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

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	CUR — Cursor File	GIF — Graphics Interchange Format	HDF4 — Hierarchical Data Format
HEIF — High Efficiency Image File Format and HEIC — High Efficiency Image Container	ICO — Icon File	JPEG — Joint Photographic Experts Group	JPEG 2000 — Joint Photographic Experts Group 2000
PBM — Portable Bitmap	PCX — Windows Paintbrush	PGM — Portable Graymap	PNG — Portable Network Graphics
PPM — Portable Pixmap	RAS — Sun Raster	TIFF — Tagged Image File Format	XWD — X Window Dump

BMP — Windows Bitmap

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

Supported Bit Depths	No Compression	RLE Compression	Output Class	Notes
1 bit	✓	–	`logical`	–
4 bit or 8 bit	✓	✓	`uint8`	–
16 bit	✓	–	`uint8`	1 sample/pixel
24 bit	✓	–	`uint8`	3 samples/pixel
32 bit	✓	–	`uint8`	3 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 Depths	No Compression	Compression	Output Class
1 bit	✓	–	`logical`
4 bit	✓	–	`uint8`
8 bit	✓	–	`uint8`

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 Depths	No Compression	Compression	Output Class
1 bit	✓	–	`logical`
2 bit to 8 bit	✓	–	`uint8`

HDF4 — Hierarchical Data Format

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

Supported Bit Depths	Raster Image with Colormap	Raster Image Without Colormap	Output Class	Notes
8 bit	✓	✓	`uint8`	–
24 bit	–	✓	`uint8`	3 samples/pixel

HEIF — High Efficiency Image File Format and HEIC — High Efficiency Image Container

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

Supported Bit Depths	No Compression	Compression	Output Class	Notes
8 bit	✓	–	`uint8`	RGB
10 bit	✓	–	`uint8`	RGB
12 bit	✓	–	`uint8`	RGB

ICO — Icon File

See CUR — Cursor 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 Sample	Lossy Compression	Lossless Compression	Output Class	Notes
8 bit	✓	✓	`uint8`	Grayscale or RGB
12 bit	✓	✓	`uint16`	Grayscale or RGB
16 bit	–	✓	`uint16`	Grayscale

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 Compression	Lossless Compression	Output Class	Notes
1 bit	✓	✓	`logical`	Grayscale only
2 bit to 8 bit	✓	✓	`uint8` or `int8`	Grayscale or RGB
9 bit to 16 bit	✓	✓	`uint16` or `int16`	Grayscale 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 Depths	Raw Binary	ASCII (Plain) Encoded	Output Class
1 bit	✓	✓	`logical`

PCX — Windows Paintbrush

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

Supported Bit Depths	Output Class	Notes
1 bit	`logical`	Grayscale
8 bit	`uint8`	Grayscale or indexed
24 bit	`uint8`	RGB, 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 Depths Raw Binary ASCII (Plain) Encoded Output Class Notes

8 bit ✓ – uint8 –

16 bit ✓ – uint16 –

Arbitrary

–

✓

Supported Bit Depths	Raw Binary	ASCII (Plain) Encoded	Output Class	Notes
8 bit	✓	–	`uint8`	–
16 bit	✓	–	`uint16`	–
Arbitrary	–	✓	1- to 8-bit: `uint8` 9- to 16-bit: `uint16`	Values are scaled.

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 Depths	Output Class	Notes
1 bit	`logical`	Grayscale
2 bit or 4 bit	`uint8`	Grayscale
8 bit	`uint8`	Grayscale or indexed
16 bit	`uint16`	Grayscale or indexed
24 bit	`uint8`	RGB, three 8-bit samples/pixel
48 bit	`uint16`	RGB, 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 Depths	Raw Binary	ASCII (Plain) Encoded	Output Class
Up to 16 bit	✓	–	`uint8`
Arbitrary	–	✓	`uint8`, `uint16`, or `double`

RAS — Sun Raster

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

Supported Bit Depths	Output Class	Notes
1 bit	`logical`	Bitmap
8 bit	`uint8`	Indexed
24 bit	`uint8`	RGB, three 8-bit samples/pixel
32 bit	`uint8`	RGB 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 Depths	ZPixmaps	XYBitmaps	XYPixmaps	Output Class
1 bit	✓	–	✓	`logical`
8 bit	✓	–	–	`uint8`

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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 the AutoOrient 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 the imread function by using MATLAB 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 prebuilt libjpeg-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.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

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 the AutoOrient 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 the imread function by using MATLAB 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 prebuilt libjpeg-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.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

Usage notes and limitations:

imread does not support reading Hierarchical Data Format (HDF), SVS, TIFF, HEIF, or HEIC files when you run imread in the background using backgroundPool or Parallel Computing Toolbox™ Threadpool.

For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

expand all

R2025a: HEIF and HEIC image files support

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.

R2024b: Automatically orient JPEG and TIFF images

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

R2024b: Generate code for embedded targets

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

R2021b: Pixel differences in JPEG 2000 images

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

R2021a: Read only the first frame in a GIF file by default

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

R2020b: Read images from Aperio SVS and TIFF files containing JPEG 2000 compression

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

R2019b: Read images from multi-image PGM, PBM, or PPM files

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

imread

Syntax

Description

Examples

Read and Display Image

Convert Indexed Image to RGB

Read Specific Image in Multipage TIFF File

Return Alpha Channel of PNG Image

Read Specified Region of TIFF Image

Automatically Orient Images

Input Arguments

filename — Name of graphics file string scalar | character vector

fmt — Image format string scalar | character vector

idx — Image to read integer scalar | vector of integers

Name-Value Arguments

GIF Files

Frames — Frames to read 1 (default) | positive integer | vector of integers | "all"

JPEG Files

AutoOrient — Automatically orient image false (default) | true

JPEG 2000 Files

PixelRegion — Boundary of region to read cell array of form {rows,cols}

ReductionLevel — Reduction of image resolution 0 (default) | positive integer

V79Compatible — Compatibility with MATLAB 7.9 (R2009b) and earlier false (default) | true

PNG Files

BackgroundColor — Background color "none" | positive integer | number in range [0, 1] | three-element vector of numbers in range [0, 1]

TIFF Files

AutoOrient — Automatically orient image false (default) | true

Index — Image to read 1 (default) | positive integer

Info — Information about image structure array

PixelRegion — Boundary of region to read cell array of form {rows,cols}

HIEF and HEIC Files

AutoOrient — Option to automatically orient image true or 1 (default) | false or 0

Output Arguments

A — Image data array

map — Colormap three-column matrix

transparency — Transparency information matrix

More About

Bit Depth

Tips

Algorithms

BMP — Windows Bitmap

CUR — Cursor File

GIF — Graphics Interchange Format

HDF4 — Hierarchical Data Format

HEIF — High Efficiency Image File Format and HEIC — High Efficiency Image Container

ICO — Icon File

JPEG — Joint Photographic Experts Group

JPEG 2000 — Joint Photographic Experts Group 2000

PBM — Portable Bitmap

PCX — Windows Paintbrush

PGM — Portable Graymap

PNG — Portable Network Graphics

PPM — Portable Pixmap

RAS — Sun Raster

SVS — Aperio ScanScope Virtual Slide

TIFF — Tagged Image File Format

XWD — X Window Dump

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

R2025a: HEIF and HEIC image files support

R2024b: Automatically orient JPEG and TIFF images

R2024b: Generate code for embedded targets

R2021b: Pixel differences in JPEG 2000 images

R2021a: Read only the first frame in a GIF file by default

R2020b: Read images from Aperio SVS and TIFF files containing JPEG 2000 compression

R2019b: Read images from multi-image PGM, PBM, or PPM files

See Also

Functions

Live Editor Tasks

Topics

`filename` — Name of graphics file
string scalar | character vector

`fmt` — Image format
string scalar | character vector

`idx` — Image to read
integer scalar | vector of integers

`Frames` — Frames to read
`1` (default) | positive integer | vector of integers | `"all"`

`AutoOrient` — Automatically orient image
`false` (default) | `true`

`PixelRegion` — Boundary of region to read
cell array of form `{rows,cols}`

`ReductionLevel` — Reduction of image resolution
`0` (default) | positive integer

`V79Compatible` — Compatibility with MATLAB 7.9 (R2009b) and earlier
`false` (default) | `true`

`BackgroundColor` — Background color
`"none"` | positive integer | number in range [0, 1] | three-element vector of numbers in range [0, 1]

`AutoOrient` — Automatically orient image
`false` (default) | `true`

`Index` — Image to read
`1` (default) | positive integer

`Info` — Information about image
structure array

`PixelRegion` — Boundary of region to read
cell array of form `{rows,cols}`

`AutoOrient` — Option to automatically orient image
true or 1 (default) | false or 0

`A` — Image data
array

`map` — Colormap
three-column matrix

`transparency` — Transparency information
matrix

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.