exrwrite
Description
exrwrite(
specifies additional options for writing the EXR file using name-value arguments.I
,filename
,Name=Value
)
Examples
Write Image Data to EXR File
Read the image data from an EXR file.
im = exrread("office.exr");
Write the image data in im
to a new EXR file with a different file name. By default, exwrite
writes the data as half-precision values to a single-part scanline EXR file.
exrwrite(im,"outfile.exr");
Write Specified Image Channel to EXR File
Read the image data from an EXR file.
im = exrread("office.exr");
Write the image data in the first channel of im
to a new EXR file. Label the channel in the metadata of the new file as "Y"
.
exrwrite(im(:,:,1),"outfile.exr",Channels="Y");
Read the metadata of the new file. The ChannelInfo
field of the metadata structure specifies the label, precision, and subsampling information for the channel.
info = exrinfo("outfile.exr");
info.ChannelInfo
ans=1×3 table
PixelType XSubSampling YSubSampling
_________ ____________ ____________
Y "half" 1 1
Append Image Data to Existing EXR File
Read the image data from an EXR file.
im = exrread("office.exr");
Write the image data in im
to a new EXR file. Specify the part name of the image as "Original"
.
exrwrite(im,"outfile.exr",PartName="Original");
Read the metadata of the new EXR file. The exrinfo
function stores the metadata as a scalar structure.
metadata = exrinfo("outfile.exr"); whos metadata
Name Size Bytes Class Attributes metadata 1x1 10814 struct
Append a second copy of the image data to outfile.exr
. Specify the name of the new part as "Duplicate"
.
exrwrite(im,"outfile.exr",AppendToFile=true,PartName="Duplicate");
Read the metadata of the updated EXR file. The metadata is now a 2-by-1 structure array, with attributes for each image part. The PartName
field contains both part names.
metadata = exrinfo("outfile.exr"); whos metadata
Name Size Bytes Class Attributes metadata 2x1 21329 struct
metadata.PartName
ans = "Original"
ans = "Duplicate"
Input Arguments
I
— Image data to write
numeric array | C-element cell array of 2-D matrices
Image data to write, specified as a numeric array or a C-element
cell array of 2-D matrices. If you do not specify the Channels
name-value argument, then I
must be a grayscale or RGB image.
Specify a grayscale image as an M-by-N numeric matrix or a 1-element cell array containing an M-by-N numeric matrix.
Specify an RGB image as an M-by-N-by-3 numeric array or a 3-element cell array of M-by-N matrices. Each 2-D matrix can be of a different data type.
If you specify the Channels
argument, you can specify
I
as one of these options:
M-by-N-by-C numeric array, where C is the number of channels specified by
Channels
.C-element cell array of 2-D matrices. Each 2-D matrix can be of a different data type. To write subsampled image data, each 2-D matrix in
I(2:end)
must have the same dimensions, and these dimensions must differ from the dimensions of the 2-D matrix of the first channelI(1)
by an integer factor.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| cell
filename
— Name of file to write
character vector | string scalar
Name of the file to write, specified as a character vector or a string scalar.
filename
can contain the absolute path to the file or a relative
path from the current directory. The file name must include the file extension
.exr
. By default, the function converts the values in
I
to half-precision values using the exrHalfAsSingle
function before writing the 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: exrwrite(I,filename,Channels=["R"])
writes data from only the
R
channel to a new EXR file.
Alpha
— Alpha channel data
[]
(default) | M-by-N numeric matrix
Alpha channel data, specified as an M-by-N
numeric matrix, where M and N match the
corresponding dimensions of I
. The function writes the values in
Alpha
to the EXR file as half-precision values. You cannot
specify Alpha
if you include "A"
when you
specify the Channels
name-value argument.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
AppendToFile
— Append image data to existing EXR file
false
or 0
(default) | true
or 1
Append the image data to an existing EXR file, specified as a logical 0
(false
) or 1
(true
).
When false,
exrwrite
overwrites the image data stored in the first part of the existing EXR filefilename
.When true,
exrwrite
creates a new part in the EXR file and writes the image data specified byI
to this new part. Iffilename
does not exist, thenexrwrite
creates the file and writes the image data to the new file. Because multipart EXR files require part names, if the existing file has a single part with no name,exrwrite
sets thePartName
for the existing part to"Part_0"
and for the new part to"Part_1"
. Subsequent calls toexrwrite
add parts names in the same format.The display window size for the new and existing parts must match. To ensure equal display window sizes, specify
I
as an array the same size as the existing part, or specify theDisplayWindow
name-value argument.
Data Types: logical
Attributes
— EXR file attributes
[]
(default) | structure
EXR file attributes, specified as a structure. The structure must have the same
format as the structure returned in the AttributeInfo
field of the
exrinfo
output. You can use this argument to preserve the metadata of an existing EXR file if
you modify the image data and want to write the modified image data to a new EXR
file.
Data Types: struct
Channels
— Channel labels
character vector | string scalar | C-element string array
Channel labels for the metadata of the new EXR file, specified as one of these values:
If the image data
I
has one channel, specify the channel label as a character vector or string scalar.If
I
has multiple channels, specify the channel labels as a C-element string array, where C is the number of channels inI
. Each element inChannels
maps to the corresponding channel inI
. Channel labels must be nonempty and unique.
If you do not specify Channels
, then I
must have exactly one or three channels. If I
has one channel,
the default value of Channels
is "Y"
. If
I
has three channels, the default value is
["R","G","B"]
.
Data Types: char
| string
Compression
— Compression mode
"ZIP"
(default) | "None"
| "RLE"
| ...
Compression mode used to store the image data, specified as
"ZIP"
, "None"
, "RLE"
,
"ZIPS"
, "PIZ"
, "PXR24"
,
"B44"
, "B44A"
, "DWAA"
, or
"DWAB"
.
Data Types: char
| string
DataWindow
— Extents of data window
4-element row vector of integers
Extents of the data window in the new file metadata, specified as a 4-element vector of integers in the format [xstart ystart xend yend], where:
xstart and ystart specify the upper-left corner of the data window, in pixels.
xend and yend specify the lower-right corner of the data window, in pixels.
The origin of the pixel coordinate system is (0, 0). The coordinate
values can be positive or negative integers. The height and width of the data window,
determined by the window extents, must match the height and width of
I
. By default, exrwrite
creates a data
window the same size as I
with the upper-left corner at (0,
0).
Data Types: double
DisplayWindow
— Extents of display window
4-element row vector of integers
Extents of the display window in the new file metadata, specified as a 4-element vector of integers in the format [xstart ystart xend yend], where:
xstart and ystart specify the upper-left corner of the display window, in pixels.
xend and yend specify the lower-right corner of the display window, in pixels.
The origin of the pixel coordinate system is (0, 0). The coordinate
values can be positive or negative integers. By default, exrwrite
creates a display window the same size as I
with the upper-left
corner at (0, 0).
Data Types: double
LineOrder
— Order to store scanlines or tiles
"TopDown"
(default) | "BottomUp"
Order to store scanlines or tiles in the new EXR file, specified as one of these values:
"TopDown"
— Store scanlines or tiles in increasing order in the y-direction."BottomUp"
— Store scanlines or tiles in decreasing order in the y-direction.
Data Types: char
| string
PartName
— Name of part
""
(default) | character vector | string scalar
Name of the part in the new file metadata, specified as a character vector or
string scalar. By default, exrwrite
does not assign a part name
if you do not specify one. When you specify the AppendToFile
name-value argument as true
, exrwrite
adds
placeholder names when writing multipart files.
Example: PartName="right"
Data Types: char
| string
OutputType
— Data type of each channel to write
"half"
(default) | character vector | string scalar | C-element string array
Data type of each channel to write, specified as a character vector, string
scalar, or a C-element string array. C is the
number of channels to write. The valid data types for writing EXR channel data are
half
, uint32
, and single
.
Before writing the new EXR file, exrwrite
converts each channel
in I
to the data type specified by the corresponding element of
OutputType
.
To write all channels in the same data type, specify the
OutputType
as a character vector or string scalar. To write
each channel in a different data type, specify the OutputType
as
a C-element string array. If I
is a numeric
array, then all channels must have the same output type.
Example: OutputType="uint32"
writes all channel data as unsigned
integer values.
Example: OutputType=["half","half","single"]
writes the first
two channels as half-precision values and the third channel as single-precision
values.
Data Types: char
| string
TileDimensions
— Tile dimensions
2-element vector of positive integers
Tile dimensions, specified as a 2-element vector of positive integers in the
format [tileWidth tileHeight]
, where tileWidth
and tileHeight
are the width and height, respectively, of the image
tiles, in pixels. The tileWidth
and tileHeight
values must be less than or equal to the overall width and height of the image data
specified by I
.
Note
If you specify the TileDimensions
name-value argument, then
exrwrite
writes the new EXR file as a tiled image. Otherwise,
exrwrite
writes a scanline image.
Data Types: double
ViewName
— Name of view
""
(default) | character vector | string scalar
Name of the view in the new file metadata, specified as a character vector or
string scalar. If you do not specify a view name, exrwrite
uses
an empty string.
Data Types: char
| string
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
| exrread
| 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)