OpenEXR Backwards Compatibility (1.7 and 2.0)¶

OpenEXR 1.7 and earlier format files are fully supported by OpenEXR 2.0.You can still use the 1.7 file format with the 2.0 library. If you usethe 2.0 format for single-part scan line image and tile image data, yourdata will be stored in the same way as the 1.7 files. You can recompileyour 1.7 files to take advantage of the new format EXRs (multiple-partfiles, and/or deep scan line and deep tile data).

New Features for OpenEXR 2.0: Multi-Part and Deep Data¶

The multi-part format is an extension of the OpenEXR 1.7 single-partfile format. In addition to supporting the OpenEXR 1.7 data storage (asingle scan line or tiled image), OpenEXR 2.0 files can be used to storemultiple views and/or deep data (deep scan line or deep tiles).

While you can continue to use the 1.7 format for files, these changes tothe file layout are required to support the new multi-part and deep datafeatures:

Integers¶

Binary integral numbers with 8, 16, 32 or 64 bits are stored as 1, 2, 4or 8 bytes. Integral numbers can be signed or unsigned. Signed numbersare represented using two’s complement. Integral numbers arelittle-endian (that is, the least significant byte is closest to thestart of the file).

OpenEXR uses the following six integer data types:

Floating-Point Numbers¶

Binary floating-point numbers with 16, 32 or 64 bits are stored as 2, 4or 8 bytes. The representation of 32-bit and 64-bit floating-pointnumbers conforms to the IEEE 754 standard. The representation of 16-bitfloating-point numbers is analogous to IEEE 754, but with 5 exponentbits and 10 bits for the fraction. The exponent bias is 15.Floating-point numbers are little-endian (that is: the least significantbits of the fraction are in the byte closest to the beginning of thefile, while the sign bit and the most significant bits of the exponentare in the byte closest to the end of the file).

The following table lists the names and sizes of OpenEXR’sfloating-point data types:

Text¶

Text strings are represented as sequences of 1-byte characters of typechar. Depending on the context, either the end of a string isindicated by a null character (0x00), or the length of the string isindicated by anint that precedes the string.

Packing¶

Data in an OpenEXR file are densely packed; the file contains no“padding”. For example, consider the following C struct:

structSI{shorts;inti;};

On most computers, the in-memory representation of anSI objectoccupies 8 bytes: 2 bytes fors, 2 padding bytes to ensure four-bytealignment ofi, and 4 bytes fori. In an OpenEXR file the sameobject would consume only 6 bytes: 2 bytes fors and 4 bytes fori.The 2 padding bytes are not stored in the file.

High-Level Layout¶

Depending on whether the pixels in an OpenEXR file are stored as scanlines or as tiles, the file consists of the following components:

It is the version field part which indicates whether the file is singleor multi-part and whether the file contains deep data. “Chunk” is ageneral term to describe blocks of pixel data. A chunk can be a scanline block, a tile or deep data (scan line or tile).

Deep data has no unique component structure of its own, but uses thestructure that the file would have if it did not have deep data in it.

Comparison between Single-Part and Multi-Part File Layouts¶

Multi-part files have the same high level structure as single-partOpenEXR files, except the header, offset table and chunk components canhave any number (two or more) parts. There must be the same number ofheaders as offset tables, and they must be in the same order. Inaddition, the header component of a multi-part file must end with a nullbyte (0x00). In multi-part files, each chunk contains a field thatindicates which part’s data it contains.

Magic Number¶

The magic number, of typeint, is always 20000630 (decimal). It allowsfile readers to distinguish OpenEXR files from other files, since thefirst four bytes of an OpenEXR file are always 0x76, 0x2f, 0x31 and0x01.

Version Field¶

The version field, of typeint, is the four-byte group following themagic number, and it is treated as two separate bit fields.

Structure¶

Attribute Layout¶

The layout of an attribute is as follows:

Theattributename and theattributetype are null-terminatedtext strings. Excluding the null byte, the name and type must each be asleast 1 byte and at most :

• 31 bytes long (if bit 10 is set to 0), or

• 255 bytes long (if bit 10 is set to 1).

Both single-part and multi-part files use the same attribute types.

Theattributesize, of typeint, indicates the size (in bytes) ofthe attribute value.

The layout of theattributevalue depends on the attributetype. The OpenEXR library predefines several different attributetypes. Application programs can define and store additional attributetypes.

Header Attributes (All Files)¶

The header of every OpenEXR file must contain at least the followingattributes:

For descriptions of what these attributes are for, seeTechnical Introduction to OpenEXR.

Tile Header Attribute¶

This attributes is required in the header for all files which containone or more tiles:

Multi-View Header Attribute¶

This attribute can be used in the header for multi-part files:

Multi-Part and Deep Data Header Attributes¶

These attributes are required in the header for all multi-part and/ordeep data OpenEXR files.

Deep Data Header Attributes¶

These attributes are required in the header for all files which containdeep data (deepscanline or deeptile):

For information about channel layout and a list of reserved channelnames, seeChannel Names inTechnical Introduction to OpenEXR.

Offset Tables¶

An offset table allows random access to pixel data chunks. An offsettable is a sequence of offsets, with one offset per chunk. Each offset(of typeunsignedlong) indicates the distance, in bytes, between thestart of the file and the start of the chunk.

Chunks can be of any of the four data types.

Offset Table Size¶

The number of entries in an offset table is defined in one of two ways:

1. If the multipart (12) bit is unset and the chunkCount is not present,the number of entries in the chunk table is computed using thedataWindow and tileDesc attributes and the compression format.

2. If the multipart (12) bit is set, the header must contain achunkCount attribute (which indicates the size of the table and thenumber of chunks).

Scan Lines¶

For scan line blocks, the line offset table is a sequence of scan lineoffsets, with one offset per scan line block. In the table, scan lineoffsets are ordered according to increasing scan line y coordinates.

Tiles¶

For tiles, the offset table is a sequence of tile offsets, one offsetper tile. In the table, scan line offsets are sorted the same way astiles inINCREASING_Y order.

Multi-Part¶

For multi-part files, each part defined in the header component has acorresponding chunk offset table.

Chunk Layout¶

A “chunk” is a general term for a pixel data block. The scan line andtile images have the same format that they did in OpenEXR 1.7. OpenEXR2.0 introduces two new types (deep scan line and deep tile).

The layout of each chunk is as follows:

Thepartnumber (of typeunsignedlong) is only present inmulti-part files. It indicates which part this chunk belongs to. 0indicates the chunk belongs to the part defined by the first header andthe first chunk offset table. The part number is omitted if themulti-part bit (12) is not set (this saves space and enforces backwardscompatibility to software which does not support multi-part files).

Thechunkdata is dependent on the type attribute - but (other thanthe part number) has the same structure as a single-part file of thesame format:

Regular Scan Line Blocks¶

For scan line images and deep scan line images, one or more scan linesmay be stored together as a scan line block. The number of scan linesper block depends on how the pixel data are compressed:

Each scan line block has a y coordinate of typeint. The block’s ycoordinate is equal to the pixel space y coordinate of the top scan linein the block. The top scan line block in the image is aligned with thetop edge of the data window (that is, the y coordinate of the top scanline block is equal to the data window’s minimum y).

If the height of the image’s data window is not a multiple of the numberof scan lines per block, then the block that contains the bottom scanline contains fewer scan lines than the other blocks.

Regular ImageTiles¶

Deep Data¶

Deep images store an arbitrarily long list of data at each pixellocation (each pixel contains a list of samples, and each samplecontains a fixed number of channels).