exrread

Read image data from EXR file

Since R2022b

Syntax

[I,alpha] = exrread(filename)

[I,alpha] = exrread(filename,Name=Value)

Description

[I,alpha] = exrread(filename) reads the RGB (channels R, G, B), grayscale (channel Y), or YUV (channels Y, RY, BY) image data from the first part of the EXR file specified by filename. Each part of an EXR file contains a separate image, such as different views of a scene. If the file contains YUV image data, the function converts the image from YUV to RGB. For subsampled YUV images, the function upsamples the RY and BY channels to match the size of the Y channel. If the file contains multiresolution image data, exrread reads data from only the highest resolution level.

[I,alpha] = exrread(filename,Name=Value) specifies additional options for reading the EXR image data using name-value arguments. You can use name-value arguments to read image data from specific channels, read channels with names other than those listed for RGB, grayscale and YUV images, maintain channel subsampling, or read image data from a specific part of a mulitpart EXR file. For example, PartIdentifier=2 reads image data from the second part of the EXR file.

Examples

Read Image Data from EXR File

Read the image data from an EXR file. By default, exrread reads image data from only the first part of the EXR file.

[im,alpha] = exrread("office.exr");

The function returns the image data, im, as an array with three channels, indicating an RGB image.

whos im

  Name        Size                 Bytes  Class     Attributes

  im        600x903x3            6501600  single              

Convert the image data in the EXR file from a high dynamic range (HDR) image to a lower dynamic range suitable for display. Display the converted image data.

rgb = tonemap(im);
imshow(rgb)

The function also returns the alpha channel data alpha.

whos alpha

  Name         Size               Bytes  Class     Attributes

  alpha      600x903            2167200  single              

Read Specified Image Channels from EXR File

Read the image data from an EXR file. Specify the Channels name-value argument to read from only the channels labeled R and G in the file metadata. By default, exrread reads image data only from the first part of the EXR file.

[im,alpha] = exrread("office.exr",Channels=["R","G"]);

The output image data array contains two channels.

whos im

  Name        Size                 Bytes  Class     Attributes

  im        600x903x2            4334400  single              

Because you did not specify to read from the alpha channel A, the function returns the alpha output argument as an empty array.

whos alpha

  Name       Size            Bytes  Class     Attributes

  alpha      0x0                 0  single              

Input Arguments

filename — Name of EXR file to read

character vector | string scalar

Name of the EXR file to read, specified as a character vector or string scalar. filename can contain the absolute path to the file, a relative path from the current directory, or a relative path from a directory on the MATLAB^® path. The file must be a valid EXR file for which the isexr function returns true. The file can be a single part or multipart EXR file.

Data Types: char | string

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: exrread(filename,Channels=["Y","RY","BY"],PartIdentifier=3) reads image data from the Y, RY, and BY channels in the third part of an EXR file.

Channels — Channels from which to read image data

character vector | string scalar | C-element string array

Channels from which to read image data, specified as a character vector, string scalar, or C-element string array. C is the number of channels to read from the EXR file.

• Character vector or string scalar — Specify a single channel to read from the EXR file. For example, 'RY' or "RY" specifies the RY channel.

• C-element string array — Specify multiple channels to read from the EXR file. For example, ["R","G","B","A"] reads the R, G, B, and A channels from the EXR file.

You can specify any combination of channels that are present in the file and have the same data type and subsampling rate. The spelling and capitalization of each channel must match the name of a channel listed in the ChannelInfo field of the structure returned for the file by the exrinfo function.

If you do not specify the Channels name-value argument, the default value depends on which channels are present in the file. If the R, G, and B channels are present, with or without additional channels, then Channels is ["R","G","B"]. If only the Y channel is present, then Channels is "Y". If the R, RY, and BY channels are present, then Channels is ["Y","RY","BY"]. If the file does not contain any of these channels, the function returns an error.

Data Types: char | string

PartIdentifier — Part from which to read image data

1 (default) | integer in range [1, P] | character vector | string scalar

Part from which to read image data, specified by number or by its name in the structure returned by exrinfo.

Part Identifier	Value	Example
Number	Numeric integer in the range [1, P], where P is the number of parts in the file. Specify PartIdentifier as an index of the P-by-1 structure returned by exrinfo. If two parts in the EXR file have the same name, you must specify them by using a numeric part identifier.	[I,alpha] = exrread(filename,PartIdentifier=2) reads image data from the second part of the EXR file filename.
Name	Character vector or string scalar. Specify PartIdentifier as one of the part names in the PartName field of the structure returned by exrinfo. The specified name must match the spelling and capitalization of one of the names in the file. If the specified name is not present in the EXR file filename, exrread returns an error.	[I,alpha] = exrread(filename,PartIdentifier="right") reads the image data from the part of the EXR file with a PartName value of "right".

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

Output Arguments

I — EXR image data

M-by-N-by-C numeric array

EXR image data, returned as an M-by-N-by-C numeric array. The dimensions of I are defined in this table:

Dimension	Description
M	By default, M is equal to info.DataWindow(4)-info.DataWindow(2)+1, where DataWindow is a field in the structure returned by exrinfo that specifies the image data window. For subsampled images, you can maintain channel subsampling by setting the Channels name-value argument. In this case, M is equal to (info.DataWindow(4)-info.DataWindow(2)+1)/ySubsampling, where ySubsampling is the subsampling rate in the y-direction. The ChannelInfo field of the structure returned by exrinfo specifies the subsampling rate in the YSubSampling column.
N	By default, N is equal to info.DataWindow(3)-info.DataWindow(1)+1. DataWindow is a field in the structure returned by exrinfo that specifies the image data window. For subsampled images, you can maintain channel subsampling by setting the Channels name-value argument. In this case, N is equal to (info.DataWindow(3)-info.DataWindow(1)+1)/xSubsampling, where xSubsampling is the subsampling rate in the x-direction. The ChannelInfo field of the structure returned by exrinfo specifies the subsampling rate in the XSubSampling column.
C	If you specify the Channels name-value argument, then C is equal to the number of channels specified by Channels. If you do not specify the Channels name-value argument, the function determines C using these processes: If the image contains the R, G, and B channels, then exrread reads the image as an M-by-N-by-3 RGB image. If the image contains only the Y channel, then exrread reads the image as an M-by-N-by-1 grayscale image. If the image part contains the Y, RY, and BY channels, then the image is processed as a YUV image. If the image is in the first part of the EXR file, then exrread converts the image to an M-by-N-by-3 RGB image. Note Automatic conversion of YUV images to RGB is supported only for the first part of an EXR file. If you specify the PartIdentifier name-value argument as a value other than 1 or the name of the first part, you must read data from the Y, RY, and BY channels by specifying the Channels name-value argument. If the part contains image data with all of these channels, then exrread reads only the R, G, and B channels as an M-by-N-by-3 RGB image.

The EXR file format supports several data types for storing image data. This table lists the supported data types in EXR files and the corresponding data type of I in MATLAB.

EXR Data Type	MATLAB Data Type
"half" — Half precision	single
"float" — Floating point	single
"unsigned int" — Unsigned integers	uint32

alpha — Transparency channel data

M-by-N numeric matrix | []

Transparency channel data, returned as an M-by-N numeric matrix or an empty array. exrread returns alpha as an M-by-N numeric matrix if you do not specify the Channels name-value argument and the A channel is present in the file. In this case, M-by-N match the first two dimensions of the image data I, and alpha is the same data type as I.

If you specify the Channels name-value argument, or if the A channel is not present in the file, then exrread returns alpha as an empty array. If you include "A" when specifying the Channels name-value argument, then the function returns the alpha data as part of I, instead.

Extended Capabilities

Thread-Based Environment

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

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2022b