OpenEXR

edit

OpenEXR stores scene-linear, high dynamic range images in 16-bit (half) or 32-bit floating-point samples, as rendering and visual-effects tools produce them. Files load as RgbaHalf or RgbaFloat pixels (luminance files as their gray formats), values above 1 included, and OpenExrEncoder compresses the stored samples losslessly by default, as scan lines or as tiles with mipmap or ripmap levels; the lossy compressions of OpenEXR (PXR24, B44, B44A, DWAA, DWAB) are used only when they are chosen. Conversion between the library's straight colors and OpenEXR's premultiplied colors can round them; this is not a general bit-exact source-pixel round-trip guarantee.

What is read and written

ReadingWriting
FilesScan-line and tiled files (the full-resolution level, or another level of mipmaps and ripmaps); one part of a multi-part file; deep data, flattenedSingle-part scan-line or tiled files: any tile size, one level, or mipmap and ripmap levels generated from the image (levels rounded down or up); increasing or decreasing line order (random order for tiles)
SamplesHALF, FLOAT and UINTHALF or FLOAT
ChannelsR, G, B, A, or Y (luminance) with or without A; or one layer of a file with other channelsR, G, B (and A for pixel formats with alpha), or Y for gray pixel formats
WindowsThe display window; an overscan cropped to it, or the data windowBoth windows are the image
CompressionNONE, RLE, ZIPS, ZIP, PIZ, PXR24, B44, B44A, DWAA, DWAB, ZSTD; HTJ2K256 and HTJ2K32 of HALF channelsNONE, RLE, ZIPS, ZIP (default) or PIZ, lossless; PXR24, B44, B44A, DWAA or DWAB, lossy, when chosen
MetadataChromaticities, the windowsChromaticities; dwaCompressionLevel for DWAA and DWAB

A file of half samples without an alpha channel loads as RgbaHalf, any other as RgbaFloat, in linear light. A luminance file (a Y channel) loads in the gray format of the same precision: GrayHalf, GrayFloat, or LaFloat with an alpha channel. The extra precision is used when dividing colors by alpha. Infinities and samples that are not numbers are kept, subject to the alpha conversion. The lossy compressions (PXR24, B44, DWAA, DWAB) decode to the same samples as OpenEXR, bit for bit: what they lose is lost when the file is written. HTJ2K256 and HTJ2K32 store each chunk as a high-throughput JPEG 2000 codestream, which the JPEG 2000 decoder of the library reads, losslessly.

Load and save an OpenEXR file

public static Image<Rgba32> ConvertOpenExr(string exrPath, string pizPath)
{
    // Half-only files without alpha load as RgbaHalf; other OpenEXR files load as RgbaFloat, in linear light
    using var hdr = Image.Load(exrPath);

    // PIZ compresses the stored samples losslessly, values above 1 included; alpha conversion can round colors
    hdr.Save(pizPath, new OpenExrEncoder { Compression = OpenExrCompression.Piz });

    // Integer pixels cannot hold the highlights: a typed load compresses them with a tone mapping
    return Image.Load<Rgba32>(exrPath, new ImageDecodeOptions
    {
        Conversion = new PixelConversionOptions { ToneMapping = new HdrToneMappingOptions() },
    });
}

Integer pixels cannot hold values above 1: loading an OpenEXR file as Rgba32 or Rgba64 rejects them, unless the conversion clips them or compresses the highlights with a tone mapping, as in the example. The same applies to saving floating-point images to other formats, with ImageEncoder.FloatingPointConversion. See Pixel formats.

Write tiles, mipmaps and lossy files

Renderers read textures by tiles, at the resolution a surface needs: a tiled file with mipmap levels lets them load only what they use. Review copies and plates whose exact samples do not matter can be several times smaller with a lossy compression:

public static void SaveOpenExrTextureAndPreview(Image hdr, string texturePath, string reviewPath)
{
    // Tiles of 64x64 pixels, with the mipmap levels a renderer reads: the encoder generates them by area average
    hdr.Save(texturePath, new OpenExrEncoder
    {
        Compression = OpenExrCompression.Zip,
        Tiling = new OpenExrTiling { TileWidth = 64, TileHeight = 64, LevelMode = OpenExrLevelMode.MipmapLevels },
    });

    // A lossy compression is only used when it is chosen: DWAB codes the colors as DCT blocks (alpha stays exact);
    // a larger level gives a smaller file and larger errors
    hdr.Save(reviewPath, new OpenExrEncoder { Compression = OpenExrCompression.Dwab, DwaCompressionLevel = 45 });
}

Tiling writes tiles instead of scan lines. Each tile is a chunk compressed on its own; the tiles at the right and bottom edges are clipped to the image. With MipmapLevels, the file also stores the image halved again and again down to one pixel; with RipmapLevels, every combination of halved widths and halved heights. The encoder generates the levels: each one is the area average of the samples the file stores for the previous one (colors premultiplied by alpha, so that transparent pixels do not darken the edges), rounded to the sample type. LevelRounding says how odd sizes are halved: a level of 5 pixels is followed by 2 with Down, by 3 with Up. The library reads the full-resolution level back; renderers and OpenImageIO read the others.

CompressionLines per chunkWhat is lost
Pxr2416The 8 low bits of the mantissa of float samples (a relative error below 2-16); half samples are exact
B4432Half samples, alpha included, in blocks of 4×4 stored in 14 bytes: small errors for smooth blocks, larger ones for blocks of very different values (or whose values cross zero); infinities and values that are not numbers become 0. Float samples are stored as they are
B44A32As B44, and a block of one value takes 3 bytes
Dwaa32The colors, coded as 8×8 DCT blocks of half values after a perceptual curve, at the level of DwaCompressionLevel (45 by default, as OpenEXR); float colors come back as half values. Alpha is stored without loss
Dwab256As DWAA, in larger chunks: smaller files

OpenEXR decodes these files to the samples the library decodes, bit for bit. A chunk that a compression does not shrink is stored uncompressed.

Read a layer of a renderer output

Renderers write depth (Z), other outputs in layers (diffuse.R, diffuse.G...) and often an overscan: a data window larger than the display window. The default options reject such a file, since those channels and pixels would be lost. ImageConfiguration.OpenExrDecoding selects what is read:

public static (Image Image, Point Origin) LoadRenderLayer(string exrPath, string layer)
{
    // Renderers store RGBA next to depth (Z) and other layers (diffuse.R, diffuse.G, ...), often with an overscan
    // around the display window: the default options reject such a file, since those channels and pixels would be lost
    var configuration = new ImageConfiguration
    {
        OpenExrDecoding = new OpenExrDecodingOptions
        {
            // "" is the default layer (R, G, B, A or Y); "diffuse" selects diffuse.R, diffuse.G, diffuse.B, diffuse.A
            Layer = layer,

            // DataWindow keeps every stored pixel instead
            WindowMode = OpenExrWindowMode.CropToDisplayWindow,
        },
    };

    // Identify, readers and collections take the same configuration, and report the same image
    var image = Image.Load(exrPath, new ImageDecodeOptions { Configuration = configuration });

    // The windows of the file, in its pixel coordinates: the cropped image starts at the display window
    var windows = image.Metadata.OpenExrWindows!;
    return (image, windows.DisplayWindowMin);
}
OptionWhat it doesDefault
LayerThe layer to decode: "" for the default layer, "diffuse" for diffuse.R, diffuse.G, diffuse.B and diffuse.A; the other channels are ignorednull: every channel must be R, G, B, A or Y
PartThe name of the part to decode in a multi-part file; the other parts are ignorednull: a multi-part file is rejected
DeepDataFlatten composites the samples of each pixel of deep dataReject
WindowModeDisplayWindow, CropToDisplayWindow (the pixels outside the display window are discarded) or DataWindow (every stored pixel is the image)DisplayWindow: an overscan is rejected

Read a part or deep data

A multi-part file stores several images, such as the two views of a stereo pair or the passes of a renderer. Deep data store a list of samples per pixel, each at its own depth, so that renders can be merged by depth. The default options reject both, since parts and depths would be lost:

public static (Image RightEye, Image Flattened) LoadStereoAndDeep(string stereoPath, string deepPath)
{
    // A multi-part file stores several images (the views of a stereo pair, the passes of a renderer): the default
    // options reject it, since the other parts would be lost. Part selects one by its name
    var stereo = new ImageConfiguration { OpenExrDecoding = new OpenExrDecodingOptions { Part = "right" } };
    var rightEye = Image.Load(stereoPath, new ImageDecodeOptions { Configuration = stereo });

    // Deep data store a list of samples per pixel, each at its depth (Z): Flatten composites them front to back, as
    // OpenEXR does, into one RGBA color per pixel; the depths are lost
    var deep = new ImageConfiguration { OpenExrDecoding = new OpenExrDecodingOptions { DeepData = OpenExrDeepDataMode.Flatten } };
    var flattened = Image.Load(deepPath, new ImageDecodeOptions { Configuration = deep });
    return (rightEye, flattened);
}

Part names the part to decode; the message of the UnsupportedImageFeatureException of a multi-part file lists the names of its parts. The other options apply to that part. DeepData set to Flatten composites the samples of each pixel front to back with the over operation, as OpenEXR flattens deep data: the samples are taken in the order the file stores them, until the accumulated alpha reaches 1. Deep data need a Z and an A channel, and load as RgbaFloat pixels.

The options apply to identification, eager loads, readers and collections alike. ImageMetadata.OpenExrWindows gives the two windows of the file; it is informational, and the encoder writes both windows from (0, 0). The decoder never falls back to another layer: a layer without color channel, a layer with RGB and luminance channels, a Y channel next to an X channel (a vector such as N.X, N.Y, N.Z, or CIE XYZ colors) and the chroma channels RY and BY are rejected with an UnsupportedImageFeatureException.

Options

OptionWhat it doesDefault
CompressionLossless: None, Rle, Zips, Zip or Piz (PIZ is usually the smallest for photos and noisy images); lossy: Pxr24, B44, B44A, Dwaa or DwabZip
DwaCompressionLevelThe level of DWAA and DWAB: larger is smaller and less exact; 0 keeps every coefficient a half value stores45
TilingTiles of TileWidth×TileHeight pixels (64×64 by default) and the LevelMode: OneLevel, MipmapLevels or RipmapLevelsnull: scan lines
LineOrderThe order of the chunks in the file: IncreasingY, DecreasingY, or RandomY for tiles onlyIncreasingY
PixelTypeHalf or Float; null chooses half for RgbaHalf and 8-bit pixels, float otherwisenull
AllowBitDepthReductionLets RgbaFloat and 16-bit pixels be rounded to half samples when PixelType is Halffalse
MetadataHandlingWhat to do with metadata OpenEXR cannot storeStrict

By default, RgbaHalf and 8-bit pixels are written as half samples, and RgbaFloat and 16-bit pixels as float samples. The gray formats (Gray8, Gray16, GrayHalf, GrayFloat) are written as a luminance channel Y, and LaHalf and LaFloat as Y and A; the half-precision gray formats are written as half samples. Integer pixels are written as their value divided by the largest sample (v / max).

Nonzero alpha multiplies the colors on encoding and divides them on decoding. Rounding, underflow or overflow can change the colors even with the default sample type. A zero alpha keeps its colors without multiplication or division. Lossless compression preserves the resulting stored samples, independently of integer normalization, half-sample rounding and alpha conversion.

Pitfalls

  • OpenEXR samples are linear light. An image labeled sRGB, which is the label of integer pixel formats, or with an ICC profile follows MetadataHandling, which rejects it by default: saving an 8-bit PNG as OpenEXR throws. A CICP description with linear transfer characteristics and BT.709, BT.2020, DCI-P3 or Display P3 primaries is written as chromaticities.
  • Compressed output needs a seekable destination (the offset table precedes the chunks); None does not, tiled or not.
  • A lossy compression changes the stored samples: B44 also changes alpha (and so the colors divided by it), and DWA stores float colors as half values. Keep a lossless master.
  • RandomY is only valid for tiles: scan-line output with it throws an ArgumentException.
  • The levels of a mipmap or a ripmap are always generated from the image; they cannot be given.
  • Half samples are limited to ±65,504: a larger finite value is rejected when it is written as half.
  • EXIF, XMP, an orientation, a resolution and text entries cannot be stored, and the attributes of a file other than its windows and chromaticities are not read. The encoder writes no UINT samples and no preview image.
  • The LJ2K compression, the HTJ2K256 and HTJ2K32 compressions of FLOAT or UINT channels, the chroma channels RY and BY, and, unless a layer is selected, channels other than R, G, B, A and Y (layers, depth) are rejected with an UnsupportedImageFeatureException. So are multi-part files without Part, and deep data without DeepData.
  • Deep data are only flattened: the samples and their depths are not available.
  • The decoder reads the full-resolution level of mipmaps and ripmaps. LevelX and LevelY decode another level, the image of its data window; AuxiliaryImageCollection lists the levels of a file and its preview image (8-bit RGBA, for display), and decodes them.
  • A file whose writer stopped before patching its offset table (zeros in the table) is rejected by default; the lenient decoding rebuilds the table from the chunks, as OpenEXR does, when they are all there.