OpenExrDecodingOptions Class

Immutable options of the OpenEXR decoder (ImageConfiguration.OpenExrDecoding): the part and the channels it decodes, the window the image covers, and how deep data become pixels.

public sealed class OpenExrDecodingOptions

Remarks

They apply to every operation that reads an OpenEXR file: identification, eager loads, sequential readers and collections, which report and decode the same image. The defaults read only the files whose every part, every channel and every stored pixel is part of the image, and reject the others with an UnsupportedImageFeatureException.

A channel belongs to the layer named by its name up to its last dot: diffuse.R is the red channel of the layer diffuse, and R the red channel of the default layer, whose name is empty. A layer is decoded from its R, G, B and A channels, any of them (a missing color is 0, a missing alpha is 1), or from its Y (luminance) and A channels.

Constructors

NameDescription
OpenExrDecodingOptions()

OpenExrDecodingOptions()

public OpenExrDecodingOptions()

No documentation is available.

Properties

NameDescription
DeepDataGets how the pixels of deep data are decoded. Defaults to OpenExrDeepDataMode.Reject.
DefaultGets the default options: every channel decoded, and the display window as the image.
LayerGets the layer that is decoded, or null (the default) to decode every channel of the file. Use String.Empty for the default layer (the channels R, G, B, A and Y without prefix).
LevelXGets the index along x of the level of a tiled image with mipmap or ripmap levels that is decoded: 0 (the default) for the full resolution, 1 for the level of half the width, and so on.
LevelYGets the index along y of the level that is decoded: 0 (the default) for the full resolution (OpenExrDecodingOptions.LevelX).
PartGets the name of the part that is decoded (its name attribute), or null (the default) to decode files of one part only.
WindowModeGets the window the image covers. Defaults to OpenExrWindowMode.DisplayWindow.

Gets how the pixels of deep data are decoded. Defaults to OpenExrDeepDataMode.Reject.

public OpenExrDeepDataMode DeepData { get; init; }

Property value

OpenExrDeepDataMode

Exceptions

ArgumentOutOfRangeException
The value is not a defined OpenExrDeepDataMode.

Gets the default options: every channel decoded, and the display window as the image.

public static OpenExrDecodingOptions Default { get; }

Gets the layer that is decoded, or null (the default) to decode every channel of the file. Use String.Empty for the default layer (the channels R, G, B, A and Y without prefix).

public string? Layer { get; init; }

Property value

string?

Remarks

With null, every channel must be one of R, G, B, A and Y: a file with other channels (depth, layers, other outputs of a renderer) is rejected, since they would be lost.

With a layer, the channels of the layer are decoded and the other channels of the file are ignored: Z, the channels of the other layers, and the channels of the layer that are not colors. A layer that has no color channel (none of R, G, B and Y), that has both RGB channels and a luminance channel, that has chroma channels (RY, BY), or whose Y channel comes with an X channel (the components of a vector such as N.X, N.Y, N.Z, or CIE XYZ colors) is rejected with an UnsupportedImageFeatureException; the message of a missing layer lists the layers of the file that have colors: the decoder never guesses another layer.

Gets the index along x of the level of a tiled image with mipmap or ripmap levels that is decoded: 0 (the default) for the full resolution, 1 for the level of half the width, and so on.

public int LevelX { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is negative.

Remarks

A level other than the full resolution is an image of its own: its data window, from the corner of the data window of the file, whatever OpenExrDecodingOptions.WindowMode says (a level has no display window). The levels of a mipmap have the same index along both axes (OpenExrDecodingOptions.LevelX equals OpenExrDecodingOptions.LevelY); those of a ripmap may differ. A level that the image does not have, also any level other than (0, 0) of an image of one level, is rejected with an UnsupportedImageFeatureException (Missing level). AuxiliaryImageCollection lists the levels of a file.

Gets the index along y of the level that is decoded: 0 (the default) for the full resolution (OpenExrDecodingOptions.LevelX).

public int LevelY { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is negative.

Gets the name of the part that is decoded (its name attribute), or null (the default) to decode files of one part only.

public string? Part { get; init; }

Property value

string?

Remarks

A multi-part file holds several images, such as the views of a stereo pair, or the outputs of a renderer stored apart. With null, a file of several parts is rejected with an UnsupportedImageFeatureException whose message lists the names of its parts, since the other parts would be lost. With a name, that part is decoded and the other parts are ignored; a file that has no part of that name is rejected, also a single-part file whose part has another name or none.

The other options apply to the part: OpenExrDecodingOptions.Layer selects channels of its channels, and OpenExrDecodingOptions.WindowMode its windows.

Gets the window the image covers. Defaults to OpenExrWindowMode.DisplayWindow.

public OpenExrWindowMode WindowMode { get; init; }

Property value

OpenExrWindowMode

Exceptions

ArgumentOutOfRangeException
The value is not a defined OpenExrWindowMode.

Remarks

With OpenExrWindowMode.CropToDisplayWindow and OpenExrWindowMode.DataWindow, the data window counts against the size limits too (ImageResourceLimits.MaxWidth, ImageResourceLimits.MaxHeight and ImageResourceLimits.MaxFramePixels), since every chunk of it is decoded.