exrread
Description
[
reads the RGB (channels I
,alpha
] = exrread(filename
)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.
[
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,
I
,alpha
] = exrread(filename
,Name=Value
)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 theRY
channel.C-element string array — Specify multiple channels to read from the EXR file. For example,
["R","G","B","A"]
reads theR
,G
,B
, andA
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 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
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
| [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
For
subsampled images, you can maintain channel subsampling by setting the
|
N | By default, N is equal to
For subsampled images, you can maintain channel
subsampling by setting the |
C | If you specify the If you do not specify the
|
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
See Also
isexr
| exrinfo
| exrwrite
| exrHalfAsSingle
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)