exrwrite

Write image data to EXR file

Since R2022b

collapse all in page

Syntax

exrwrite(I,filename)
exrwrite(I,filename,Name=Value)

Description

exrwrite(I,filename) writes the grayscale or RGB image data I to the single part EXR file filename as half-precision values. By default, the function writes the file as a scanline image using ZIP compression. The function does not write alpha channel data to the file.

example

exrwrite(I,filename,Name=Value) specifies additional options for writing the EXR file using name-value arguments.

example

Examples

collapse all

Open Live Script

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");
Open Live Script

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
Open Live Script

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

collapse all

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 channel I(1) by an integer factor.

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

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

collapse 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: exrwrite(I,filename,Channels=["R"]) writes data from only the R channel to a new EXR file.

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

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 file filename.

  • When true, exrwrite creates a new part in the EXR file and writes the image data specified by I to this new part. If filename does not exist, then exrwrite 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 the PartName for the existing part to "Part_0" and for the new part to "Part_1". Subsequent calls to exrwrite 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 the DisplayWindow name-value argument.

Data Types: logical

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

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 in I. Each element in Channels maps to the corresponding channel in I. 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 mode used to store the image data, specified as "ZIP", "None", "RLE", "ZIPS", "PIZ", "PXR24", "B44", "B44A", "DWAA", or "DWAB".

Data Types: char | string

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

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

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

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

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

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

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

expand all

Version History

Introduced in R2022b

See Also

| | |