Technical Introduction to OpenEXR¶
Features of OpenEXR¶
A unique combination of features makes OpenEXR a good fit forhigh-quality image processing and storage applications:
- high dynamic range
Pixel data are stored as 16-bit or 32-bit floating-pointnumbers. With 16 bits, the representable dynamic range issignificantly higher than the range of most image capture devices:109 or 30 f-stops without loss of precision, and an additional 10f-stops at the low end with some loss of precision. Most 8-bit fileformats have around 7 to 10 stops.
- good color resolution
With 16-bit floating-point numbers, color resolution is 1024 stepsper f-stop, as opposed to somewhere around 20 to 70 steps per f-stopfor most 8-bit file formats. Even after significant processing (forexample, extensive color correction) images tend to show nonoticeable color banding.
- compatible with graphics hardware
The 16-bit floating-point data format is fully compatible with the16-bit frame-buffer data format used in some new graphicshardware. Images can be transferred back and forth between anOpenEXR file and a 16-bit floating-point frame buffer without losingdata.
Most of the data compression methods currently implemented inOpenEXR are lossless; repeatedly compressing and uncompressing animage does not change the image data. With the lossless compressionmethods, photographic images with significant amounts of film graintend to shrink to somewhere between 35 and 55 percent of theiruncompressed size. OpenEXR also supports lossy compression, whichtends to shrink image files more than lossless compression, butdoesn’t preserve the image data exactly. New lossless and lossycompression schemes can be added in the future.
- arbitrary image channels
OpenEXR images can contain an arbitrary number and combination ofimage channels, for example red, green, blue, and alpha; luminanceand sub-sampled chroma channels; depth, surface normal directions,or motion vectors.
- scan line and tiled images, multi-resolution images
Pixels in an OpenEXR file can be stored either as scan lines or astiles. Tiled image files allow random-access to rectangularsub-regions of an image. Multiple versions of a tiled image, eachwith a different resolution, can be stored in a singlemulti-resolution OpenEXR file.
Multi-resolution images, often called “mipmaps” or “ripmaps”, arecommonly used as texture maps in 3D rendering programs to acceleratefiltering during texture lookup, or for operations like stereo imagematching. Tiled multiresultion images are also useful forimplementing fast zooming and panning in programs that interactivelydisplay very large images.
- ability to store additional data
Often it is necessary to annotate images with additional data; forexample, color timing information, process tracking data, or cameraposition and view direction. OpenEXR allows storing of an arbitrarynumber of extra attributes, of arbitrary type, in an imagefile. Software that reads OpenEXR files ignores attributes it doesnot understand.
- easy-to-use C++ and C programming interfaces
In order to make writing and reading OpenEXR files easy, the fileformat was designed together with a C++ programming interface. Twolevels of access to image files are provided: a fully generalinterface for writing and reading files with arbitrary sets of imagechannels, and a specialized interface for the most common case (red,green, blue, and alpha channels, or some subset ofthose). Additionally, a C-callable version of the programminginterface supports reading and writing OpenEXR files from programswritten in C.
Many application programs expect image files to be scan linebased. With the OpenEXR programming interface, applications thatcannot handle tiled images can treat all OpenEXR files as if theywere scan line based; the interface automatically converts tiles toscan lines.
The C++ and C interfaces are implemented in the open-source OpenEXRlibrary.
- fast multi-threaded file reading and writing
The OpenEXR library supports multi-threaded reading or writing of anOpenEXR image file: while one thread performs low-level file inputor output, multiple other threads simultaneously encode or decodeindividual pieces of the file.
- portability
The OpenEXR file format is hardware and operating systemindependent. While implementing the C and C++ programminginterfaces, an effort was made to use only language features andlibrary functions that comply with the C and C++ ISO standards.
- multi-view
A “multi-view” image shows the same scene from multiple differentpoints of view. A common application is 3D stereo imagery, where aleft-eye and a right-eye view of a scene are stored in a singlefile.
- deep data
Support for a new data type has been added: deep data. Deep imagesstore an arbitrarily long list of data at each pixel location. Thisis different from multichannel or ‘deep channel images’ which canstore a potentially large, but fixed, amount of information at eachpixel. In a deep image, each pixel stores a different amount ofdata.
This allows for more accurate compositing of objects which occludeeach other, and provides a method for storing opacity data in the zdirection (particularly useful for stereo images which haveatmospheric effects such fog).
- multi-part
Multi-part files allow for storing multiple images in one OpenEXRfile. One important application is to store layers of channelsseparately. This allows for faster access when only a subset of thechannels needs reading. It also permits layers to have differingdata layout (for example, for different compression, or differentlayout) and different data windows.
It also allows some layers to be stored as deep data and others asregular images. With multi-part files, different views are stored indifferent parts.
Overview of the OpenEXR File Format¶
Definitions and Terminology¶
Pixel space¶
Pixel space is a 2D coordinate system with x increasing from left toright and y increasing from top to bottom.Pixels are data samples,taken at integer coordinate locations in pixel space.
Display window¶
The boundaries of an OpenEXR image are given as an axis-parallelrectangular region in pixel space, thedisplay window. The displaywindow is defined by the positions of the pixels in the upper left andlower right corners, (xmin, ymin) and(xmax, ymax).
Data window¶
An OpenEXR file may not have pixel data for all the pixels in thedisplay window, or the file may have pixel data beyond the boundaries ofthe display window. The region for which pixel data are available isdefined by a second axis-parallel rectangle in pixel space, thedatawindow.
Examples:
Assume that we are producing a movie with a resolution of 1920 by1080 pixels. The display window for all frames of the movie is (0, 0)- (1919, 1079). For most images, in particular finished frames thatwill be recorded on film, the data window is the same as thedisplay window, but for some images that are used in producing thefinished frames, the data window differs from the display window.
For a background plate that will be heavily post-processed, extrapixels, beyond the edge of the film frame, are recorded and thedata window is set to (-100, -100) - (2019, 1179). The extra pixelsare not normally displayed. Their existence allows operations suchas large-kernel blurs or simulated camera shake to avoid edgeartifacts.
While tweaking a computer-generated element, an artist repeatedlyrenders the same frame. To save time, the artist renders only asmall region of interest close to the center of the image. The datawindow of the image is set to (1000, 400) - (1400, 800). When theimage is displayed, the display program fills the area outside ofthe data window with some default color.
Image channels and sampling rates¶
Every OpenEXR image contains one or moreimage channels. Eachchannel has a name, a data type, and x and ysampling rates.
The channel’s name is a text string, for exampleR,Z oryVelocity. The name tells programs that read the image file how tointerpret the data in the channel.
For a few channel names, interpretation of the data is predefined:
name | interpretation |
|---|---|
R | red intensity |
G | green intensity |
B | blue intensity |
A | alpha/opacity: 0.0 means the pixel is transparent; 1.0 meansthe pixel is opaque. By convention, all color channels arepremultiplied by alpha, so that |
Three channel data types are currently supported:
type name | description |
|---|---|
| 16-bit floating-point numbers; for regular image data. (SeeThe half Data Type. |
| 32-bit IEEE-754 floating-point numbers; used where the range orprecision of 16-bit number is not sufficient (for example,depth channels). |
| 32-bit unsigned integers; for discrete per-pixel data such asobject identifiers. |
The channel’s x and y sampling rates, sx and sy,determine for which of the pixels in the image’s data window data arestored in the file. Data for a pixel at pixel space coordinates (x, y)are stored only if
and
For RGBA (red, green, blue, alpha) images, sx and syare 1 for all channels, and each channel contains data for everypixel. For other types of images, some channels may besub-sampled. For example, in images with one luminance channel, Y, andtwo croma channels, RY and BY, sx and sy would be 1for the Y channel, but for the RY and BY channels, sx and sy might be set to 2, indicating that chroma data are only givenfor one out of every four pixels. (See alsoLuminance/ChromaImages).
Projection, camera coordinate system and screen window¶
Many images are generated by a perspectiveprojection. We assumethat a camera is located at the origin, O, of a 3Dcamera coordinatesystem. The camera looks along the positive z axis. The positive xand y axes correspond to the camera’sleft andup directions. The3D scene is projected onto the z = 1 plane. The image recorded by thecamera is bounded by a rectangle, thescreen window. In pixel space,the screen window corresponds to the file’s display window. In thefile, the size and position of the screen window are specified by thex and y coordinates of the window’s center, C, and by the window’swidth, W. The screen window’s height can be derived from C, W, thedisplay window and the pixel aspect ratio.
Scan lines¶
In scan line based files, the image’s pixels are stored in horizontalrows, orscan lines. A file whose data window is (xmin, ymin) - (xmax, ymax) contains ymax -ymin + 1 scan lines. Each scan line contains xmax -xmin + 1 pixels.
Scan line based files cannot contain multi-resolution images.
Tiles¶
In tiled files, the image is subdivided into an array of smallerrectangles, calledtiles. Each tile contains px by py pixels. An image whose data window is (xmin, ymin) - (xmax, ymax) contains ceil(w/px) by ceil(h/py) tiles, where w and h are the widthand height of the data window:
The upper left corner of the upper left tile is aligned with the upperleft corner of the data window, at (xmin, ymin). Therightmost column and the bottom row of tiles may extend outside thedata window. If a tile contains pixels that are outside the datawindow, then those extra pixels are discarded when the tile is storedin the file.
Levels and level modes¶
A single tiled OpenEXR files may contain multiple versions of the sameimage, each with a different resolution. Each version is called alevel. The number of levels in a file and their resolutions dependon the file’slevel mode. Currently, OpenEXR supports three levelmodes:
mode name | description | |||||||||
| The file contains only a single full-resolution level. A tiled | |||||||||
| The file contains multiple versions of the image. Eachsuccessive level is half the resolution of the previous levelin both dimensions. The lowest-resolution level contains only asingle pixel. For example, if the first level, with fullresolution, contains 16×8 pixels, then the file contains fourmore levels with 8×4, 4×2, 2×1, and 1×1 pixels respectively. | |||||||||
| Like
|
Level numbers, level size and rounding mode¶
Levels are identified bylevel numbers. A level number is a pair ofintegers, (lx, ly). Level(0,0) is thehighest-resolution level, withw byh pixels. Level (lx, ly) contains
by
pixels, where rf(x) is a rounding function, either floor(x) orceil(x), depending on the file’slevel size rounding mode(ROUND_DOWN orROUND_UP).
MIPMAP_LEVELS files contain only levels where lx = ly.ONE_LEVEL files contain only level(0,0).
Examples:
1. The levels in aRIPMAP_LEVELS file whose highest-resolutionlevel contains 4 by 4 pixels have the following level numbers:
width | ||||
4 | 2 | 1 | ||
4 | (0,0) | (1,0) | (2,0) | |
height | 2 | (0,1) | (1,1) | (2,1) |
1 | (0,2) | (1,2) | (2,2) | |
In an equivalentMIPMAP_LEVELS file, only levels (0,0), (1,1), and (2,2)are present.
2. In a MIPMAP_LEVELS file with a highest-resolution level of 15 by 17pixels, the resolutions of the remaining levels depend on the levelsize rounding mode:
rounding mode | level resolution |
|---|---|
| 15×17, 7×8, 3×4, 1×2, 1×1 |
| 15×17, 8×9, 4×5, 2×3, 1×2, 1×1 |
Tile coordinates¶
In a file with multiple levels, tiles have the same size, regardlessof their level. Lower-resolution levels contain fewer, rather thansmaller, tiles. Within a level, a tile is identified by a pair ofintegertile coordinates, which specify the tile’s column androw. The upper left tile has coordinates (0,0). In order to identify atile uniquely in a multi-resolution file, both the tile coordinatesand the level number are needed.
View¶
Aview is a set of image channels, identified by naming conventionand the view header attribute. This is usually used to store stereofiles, with one view for each eye. Views can be stored in separatefiles, or together in a single file.
Part¶
Apart is made up of a header and an associated offset table andpixels. In a single-part file, there is one header, one offset table,and corresponding pixel data. In a multi-part file, there can be twoor more parts - with each part having one header, one offset table andcorresponding pixel data.
Note: This is different from a multi-view file, though you canstore views as separate parts if you wish.
Deep Data¶
OpenEXR 2.0 supportsdeep data. Deep data images store anarbitrarily long list of data at each pixel location. This isdifferent from multichannel or ‘deep channel images’ which can store apotentially large, but fixed, amount of information at each pixel. Ina deep image, each pixel stores a different amount of data.
Deep data can be deep scaline data or deep tile data, the type isdefined in the header attributes for that part. Deep data is supportedin single-part and multi-part files. In single-part files, it formsthe deep scan line block or deep tile component. In multi-part filesit can be stored in any chunk regardless of the data type stored inother chunks.
Each pixel contains a list ofsamples. Each sample contains afixed number ofchannels. Typically, the data is used to storedeep z-buffer information, where each sample represents the colour ata different depth.
Some users choose to use a different file extension to indicate thatan OpenEXR contains deep data (for example, to allow an appropriateviewer to load when double-clicking a file). In such circumstances,the extension DXR (“DepthEXR”) is recommended. However, since v2.0files can contain a mixture of flat and deep data this practice shouldbe discouraged in favour of the EXR extension.
File Structure¶
An OpenEXR file is made up of: theheader and thepixels.
Header¶
The header is a list ofattributes that describe the pixels. Anattribute is a named data item of an arbitrary type. To ensure thatOpenEXR files written by one program can be read by other programs,certain required attributes must be present in all OpenEXR fileheaders:
attribute name | description |
|---|---|
| The image’s display and data window. |
| Width divided by height of a pixel when the image is displayedwith the correct aspect ratio. A pixel’s width (height) is thedistance between the centers of two horizontally (vertically)adjacent pixels on the display. |
| Description of the image channels stored in the file. |
| Specifies the compression method applied to the pixel data ofall channels in the file. |
| Specifies in what order the scan lines in the file are storedin the file (increasing Y, decreasing Y, or, for tiled images,also random Y). |
| Describe the perspective projection that produced the image.Programs that deal with images as purely two-dimensionalobjects may not be able so generate a description of aperspective projection. Those programs should setscreenWindowWidth to 1, and screenWindowCenter to (0, 0). |
| This attribute is required only for tiled files. It specifiesthe size of the tiles, and the file’s level mode. |
In addition to the required attributes, a program may place any numberof additional attributes in the file’s header. Often it is necessaryto annotate images with additional data, for example color timinginformation, process tracking data, or camera position and viewdirection. Those data can be packaged as extra attributes in the imagefile’s header.
Multi-View Header Attributes¶
This attribute is required in the header for multi-view OpenEXR files.
attribute name | notes |
|---|---|
| Specifies the view this part is associated with (mostly usedfor files which stereo views).* A value of |
For more information about multi-view files, seeStoring Multi-View Images in OpenEXR Files.
Multi-part and Deep Data Attributes¶
These attributes are required in the header for all multi-part and/ordeep data OpenEXR files.
attribute name | notes |
|---|---|
| The name attribute defines the name of each part. The name ofeach part must be unique. Names may contain ‘.’ characters topresent a tree-like structure of the parts in a file. |
| Data types are defined by the type attribute. There are fourtypes:
|
| version 1 data for all part types is described inOpenEXR File Layout. |
|
|
| Required for parts of type |
Deep Data Header Attributes¶
These attributes are required in the header for all files which containdeep data (deepscanline or deeptile):
name | notes |
|---|---|
| Stores the maximum number of samples used by any single pixelwithin the image. If this number is small, it may beappropriate to read the deep image into a fix-sized buffer forprocessing. However, this number may be very large. |
| There are two deep data types:
|
| Should be set to 1. ( It will be changed if the format isupdated.) |
| Required if |
Pixels¶
Achunk is a set of pixel data of a particular format or data type(scanlines (or groups of scanlines), tiles and deep data). Thestructure of a chunk is defined by the type of pixel data stored init.
In multi-part files, each part has it’s own chunk and each chunk has apart number at the beginning to correlate them with a header.
Scan line based¶
When a scan line based image file is written, the scan lines must bewritten either in increasingY order (top scan line first) or indecreasingY order (bottom scan line first). When a scan linebased file is read, random access to the scan lines is possible; thescan lines can be read in any order. Reading the scan lines in thesame order as they were written causes the file to be readsequentially, without “seek” operations, and as fast as possible.
Tiled image¶
When a tiled image file is written or read, the tiles can be accessedin any order. When a tiled file is written, the OpenEXR library maybuffer and sort the tiles, depending on the file’s line order. If thetiles in a file have been sorted into a predictable sequence,application programs reading the file can avoid slow “seek” operationsby reading the tiles sequentially, in the order as they appear in thefile.
For tiled files, line order is interpreted as follows:
line order | description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| The tiles for each level are stored in a contiguousblock. The levels are ordered like this:
where:
if the file’s level mode is
if the level mode is
if the level mode is In each level, the tiles are stored in the following order:
where tx and ty are the number of tiles in the x and ydirection respectively, for that particular level. | ||||||||||||||||||||||||||||||||
| Levels are ordered as for
| ||||||||||||||||||||||||||||||||
| When a file is written, tiles are not sorted; they are stored in the file in theorder they are produced by the application program. If an application program produces tiles in an essentially random order, selecting |
Deep Data¶
Deep data is supported in single-part and multi-part files. Insingle-part files, it forms the deep scan line block or deep tilecomponent. In multi-part files it can be stored in any chunkregardless of what other data is stored in other chunks.
Data Compression¶
OpenEXR currently offers several different data compression methods, withvarious speed versus compression ratio tradeoffs. Optionally, thepixels can be stored in uncompressed form. With fast filesystems,uncompressed files can be written and read significantly faster thancompressed files.
Compressing an image with a lossless method preserves the imageexactly; the pixel data are not altered. Compressing an image with alossy method preserves the image only approximately; the compressedimage looks like the original, but the data in the pixels may havechanged slightly.
Supported compression schemes:
name | description |
|---|---|
PIZ (lossless) | A wavelet transform is applied to the pixel data, and the result isHuffman-encoded. This scheme tends to provide the best compression ratiofor the types of images that are typically processed at Industrial Light& Magic. Files are compressed and decompressed at roughly the samespeed. For photographic images with film grain, the files are reduced tobetween 35 and 55 percent of their uncompressed size. PIZ compression works well for scan line based files, and also for tiledfiles with large tiles, but small tiles do not shrinkmuch. (PIZ-compressed data start with a relatively long header; if theinput to the compressor is short, adding the header tends to offset anysize reduction of the input.) |
ZIPS (lossless) | Uses the open source deflate library for IETF RFC 1950 compression.Unlike ZIP compression, this operates one scan line at a time. |
ZIP (lossless) | Differences between horizontally adjacent pixels are compressed using theopen source deflate library for IETF RFC 1950 compression. ZIPdecompression is faster than PIZ decompression, but ZIP may belarger. Photographic images tend to shrink to between 45 and 55percent of their uncompressed size. Multi-resolution files are often used as texture maps for 3Drenderers. For this application, fast read accesses are usually moreimportant than fast writes, or maximum compression. For texture maps, ZIPis probably the best compression method. Unlike ZIPS compression, this operates in in blocks of 16 scan lines. |
RLE (lossless) | Differences between horizontally adjacent pixels are run-lengthencoded. This method is fast, and works well for images with large flatareas, but for photographic images, the compressed file size is usuallybetween 60 and 75 percent of the uncompressed size. |
PXR24 (lossy) | After reducing 32-bit floating-point data to 24 bits by rounding,differences between horizontally adjacent pixels are compressed withzlib, similar to ZIP. PXR24 compression preserves image channels of typeHALF and UINT exactly, but the relative error of FLOAT data increases toabout 3×10-5. This compression method works well for depthbuffers and similar images, where the possible range of values is verylarge, but where full 32-bit floating-point accuracy is notnecessary. Rounding improves compression significantly by eliminating thepixels’ 8 least significant bits, which tend to be very noisy, anddifficult to compress. Note: This lossy compression scheme is not supported in deep files. |
B44 (lossy) | Channels of type HALF are split into blocks of four by four pixels or 32bytes. Each block is then packed into 14 bytes, reducing the data to 44percent of their uncompressed size. When B44 compression is applied toRGB images in combination with luminance/chroma encoding (see below), thesize of the compressed pixels is about 22 percent of the size of theoriginal RGB data. Channels of type UINT or FLOAT are not compressed. Decoding is fast enough to allow real-time playback of B44-compressedOpenEXR image sequences on commodity hardware. The size of a B44-compressed file depends on the number of pixels in theimage, but not on the data in the pixels. All files with the sameresolution and the same set of channels have the same size. This can beadvantageous for systems that support real-time playback of imagesequences; the predictable file size makes it easier to allocate space onstorage media efficiently. Note: This lossy compression scheme is not supported in deep files. |
B44A (lossy) | Like B44, except for blocks of four by four pixels where all pixels havethe same value, which are packed into 3 instead of 14 bytes. For imageswith large uniform areas, B44A produces smaller files than B44compression. Note: This lossy compression scheme is not supported in deep files. |
DWAA (lossy) | Lossy compression of RGB data by quantizing discrete cosinetransform (DCT) components, in blocks of 32 scanlines. Moreefficient for partial buffer access. |
DWAB (lossy) | Lossy compression of RGB data by quantizing discrete cosinetransform (DCT) components, in blocks of 256 scanlines. Moreefficient space wise and faster to decode full frames than DWAAaccess. |
Luminance/Chroma Images¶
Encoding images with one luminance and two chroma channels, rather thanas RGB data, allows a simple but effective form of lossy datacompression that is independent of the compression methods listed above.The chroma channels can be stored at lower resolution than the luminancechannel. This leads to significantly smaller files, with only a smallreduction in image quality. The specialized RGBA interface in the OpenEXRlibrary directly supports reading and writing luminance/chroma images.When an application program writes an image file, it can choose eitherRGB or luminance/chroma format. When an image file with luminance/chromadata is read, the library automatically converts the pixels back to RGB.
Given linear RGB data, luminance, Y, is computed as a weighted sum of R,G, and B:
The values of the weighting factors, wR, wG, andwB, are derived from the chromaticities of the image’sprimaries and white point. (SeeRGB Color)
Chroma information is stored in two channels, RY and BY, which arecomputed like this:
The RY and BY channels can be low-pass filtered and subsampled withoutdegrading the original image very much. The RGBA interface in OpenEXRuses vertical and horizontal sampling rates of 2. Even though theresulting luminance/chroma images contain only half as much data, theyusually do not look noticeably different from the original RGB images.
Converting RGB data to luminance/chroma format also allowsspace-efficient storage of gray-scale images. Only the Y channel needsto be stored in the file. The RY and BY channels can be discarded. Ifthe original is already a gray-scale image, that is, every pixel’s red,green, and blue are equal, then storing only Y preserves the imageexactly; the Y channel is not subsampled, and the RY and BY channelscontain only zeroes.
The half Data Type¶
Image channels of type HALF are stored as 16-bit floating-pointnumbers. The 16-bit floating-point data type is implemented as a C++class,half, which was designed to behave as much as possible likethe standard floating-point data types built into the C++ language. Inarithmetic expressions, numbers of type half can be mixed freely withfloat anddouble numbers; in most cases, conversions to andfromhalf happen automatically.
half numbers have 1 sign bit, 5 exponent bits, and 10 mantissabits. The interpretation of the sign, exponent and mantissa isanalogous to IEEE-754 floating-point numbers.half supportsnormalized and denormalized numbers, infinities and NANs (Not ANumber). The range of representable numbers is roughly 6.0×10-8 `- 6.5×10:sup:`4; numbers smaller than 6.1×10-5are denormalized. Conversions fromfloat tohalf round themantissa to 10 bits; the 13 least significant bits arelost. Conversions fromhalf tofloat are lossless; allhalf numbers are exactly representable asfloat values.
The data type implemented by class half is identical to Nvidia’s16-bit floating-point format (fp16 /half). 16-bit data,including infinities and NANs, can be transferred between OpenEXRfiles and Nvidia 16-bit floating-point frame buffers without losingany bits.
What’s in the Numbers?¶
We store linear values in the RGB 16-bit floating-point numbers. Bythis we mean that each value is linear relative to the amount of lightin the depicted scene. This implies that display of images requiressome processing to account for the non-linear response of a typicaldisplay. In its simplest form, this is a power function to performgamma correction. There are many recent papers on the subject of tonemapping to represent the high dynamic range of light values on adisplay. By storing linear data in the file (double the number, doublethe light in the scene), we have the best starting point for thesedownstream algorithms. Also, most commercial renderers produce linearvalues (before gamma is applied to output to lower precision formats).
With this linear relationship established, the question remains, Whatnumber is white? The convention we employ is to determine a middlegray object, and assign it the photographic 18% gray value, or .18 inthe floating point scheme. Other pixel values can be easily determinedfrom there (a stop brighter is .36, another stop is .72). The value1.0 has no special significance (it is not a clamping limit, as inother formats); it roughly represents light coming from a 100%reflector (slightly brighter than paper white). But there are manybrighter pixel values available to represent objects such as fire andhighlights.
The range of normalized 16-bit floats can represent thirty stops ofinformation with 1024 steps per stop. We have eighteen and a halfstops over middle gray, and eleven and a half below. The denormalizednumbers provide an additional ten stops with decreasing precision perstop.
Recommendations¶
RGB Color¶
Simply calling the R channel red is not sufficient information todetermine accurately the color that should be displayed for a givenpixel value. The OpenEXR library defines achromaticities attribute,which specifies the CIE x,y coordinates for red, green, blue, andwhite; that is, for the RGB triples (1, 0, 0), (0, 1, 0), (0, 0, 1),and (1, 1, 1). The x,y coordinates of all possible RGB triples can bederived from the chromaticities attribute. If the primaries and whitepoint for a given display are known, a file-to-display color transformcan correctly be done. The OpenEXR library does not perform thistransformation; it is left to the display software. The chromaticitiesattribute is optional, and many programs that write OpenEXR omitit. If a file doesn’t have a chromaticities attribute, displaysoftware should assume that the file’s primaries and the white pointmatch Rec. ITU-R BT.709-3:
CIE x,y | |
|---|---|
red | 0.6400, 0.3300 |
green | 0.3000, 0.6000 |
blue | 0.1500, 0.0600 |
white | 0.3127, 0.3290 |
CIE XYZ Color¶
In an OpenEXR file whose pixels represent CIE XYZ tristimulus values,the pixels’ X, Y and Z components should be stored in the file’s R, Gand B channels. The file header should contain a chromaticitiesattribute with the following values:
CIE x,y | |
|---|---|
red | 1, 0 |
green | 0, 1 |
blue | 0, 0 |
white | 1/3, 1/3 |
Channel Names¶
An OpenEXR image can have any number of channels with arbitrary names.The specialized RGBA image interface assumes that channels with thenamesR,G,B andA mean red, green, blue and alpha. Nopredefined meaning has been assigned to any other channels. However,for a few channel names we recommend the interpretations given in thetable below. We expect this table to grow over time as users employOpenEXR for data such as shadow maps, motion-vector fields or imageswith more than three color channels.
name | interpretation |
|---|---|
Y | luminance, used either alone, for gray-scale images, or in combination withRY and BY for color images. |
RY, BY | chroma for luminance/chroma images, see above. |
AR, AG, AB | red, green and blue alpha/opacity, for colored mattes (required to compositeimages of objects like colored glass correctly). |
In an image file with many channels it is sometimes useful to groupthe channels intolayers, that is, into sets of channels thatlogically belong together. Grouping is done using a naming convention:channelC in layerL is calledL.C.
For example, an image may contain separate R, G and B channels forlight that originated at each of several different virtual lightsources. The channels in such an image might be calledlight1.R,light1.G,light1.B,light2.R,light2.G,light2.B,etc.
Layers can be nested. A name of the formL1.L2.L3 …Ln.C means thatlayerL1 contains a nested layerL2, whichin turn contains another nested layerL3, and so on tolayerLn, which contains channelC.
For example,light1.specular.R identifies theR channel in thespecular sub-layer of layerlight1.
Note that this naming convention does not describe a back-to-frontstacking order or any compositing operations for combining the layersinto a final image.
For another example of a channel naming convention, seeStoring Multi-View Images in OpenEXR Files.
Deep Data - Special Purpose Channels and Reserved Channel Names¶
Deep data parts reserve a set of channel names for sorts of data oftenused by developers. Only use these channel names for the correctpurpose (listed below). If there is a reserved channel name for thedata you are handling, always use the appropriate channel name.
name | definition | notes |
|---|---|---|
| depth of front (closest point) of sample[1] | All samples should be sorted according to their |
| Depth of back (farthest point) of sample[1] | If a sample has |
| sample opacity value | The light attenuated by this sample in isolation. |
| red, green blue values of sample | If a channel is present, then the cumulative pre-multipliedcolour between the front and the back of this sample ( |
| red, green, blue sample alpha values | Per-channel light attenuation of sample in isolation (similarto |
| object ID number | Samples belonging to the same object have the same ID number. |
Volumetric sample representation¶
Where samples have Z<ZBack, the sample isvolumetric. The sampleshould be assumed to have constant optical density between its frontand back. If it is necessary to split a sample at some depthd(whereZ<d<ZBack), Beer-Lambert’s equation should be used tocompute the alpha for the split sample:
Note: This isnot a linear increase in alpha between the frontand back and distances.
Standard Attributes¶
By adding attributes to an OpenEXR file, application programs canstore arbitrary auxiliary data along with the image. In order to makeit easier to exchange data among programs written by different people,the OpenEXR library defines a set of standard attributes for commonlyused data, such as colorimetric data (seeRGB Color, time and placewhere an image was recorded, or the owner of an image file’scontent. Whenever possible, application programs should store data instandard attributes, instead of defining their own.
By default, OpenEXR files have the following attributes:
- chromaticities
For RGB images, specifies the CIE (x,y) chromaticities of theprimaries and the white point.
- whiteLuminance
For RGB images, defines the luminance, in Nits (candelas per squaremeter) of the RGB value (1.0, 1.0, 1.0).
If the chromaticities and the whiteLuminance of an RGB image areknown, then it is possible to convert the image’s pixels from RGB toCIE XYZ tristimulus values.
- adoptedNeutral
Specifies the CIE (x,y) coordinates that should be consideredneutral during color rendering. Pixels in the image file whose(x,y) coordinates match the adoptedNeutral value should be mapped toneutral values on the display.
- renderingTransform, lookModTransform
Specify the names of the CTL functions that implements the intendedcolor rendering and look modification transforms for this image.
- xDensity
Horizontal output density, in pixels per inch. The image’s verticaloutput density is xDensity * pixelAspectRatio.
- owner
Name of the owner of the image.
- comments
Additional image information in human-readable form, for example averbal description of the image.
- capDate
The date when the image was created or captured, in local time, andformatted as
YYYY:MM:DDhh:mm:ss, whereYYYYis the year (4digits, e.g. 2003),MMis the month (2 digits, 01, 02, … 12),DDis the day of the month (2 digits, 01, 02, … 31), hh is thehour (2 digits, 00, 01, … 23), mm is the minute, and ss is thesecond (2 digits, 00, 01, … 59).- utcOffset
Universal Coordinated Time (UTC), in seconds: UTC == local time +utcOffset
- longitude,latitude,altitude
For images of real objects, the location where the image wasrecorded. Longitude and latitude are in degrees east of Greenwichand north of the equator. Altitude is in meters above sea level.For example, Kathmandu, Nepal is at longitude 85.317, latitude27.717, altitude 1305.
- focus
The camera’s focus distance, in meters.
- exposure
Exposure time, in seconds.
- aperture
The camera’s lens aperture, in f-stops (focal length of the lensdivided by the diameter of the iris opening).
- isoSpeed
The ISO speed of the film or image sensor that was used to recordthe image.
- envmap
If this attribute is present, the image represents an environmentmap. The attribute’s value defines how 3D directions are mapped to2D pixel locations.
- keyCode
For motion picture film frames. Identifies film manufacturer, filmtype, film roll and frame position within the roll.
- timeCode
Time and control code
- wrapmodes
Determines how texture map images are extrapolated. If an OpenEXRfile is used as a texture map for 3D rendering, texture coordinates(0.0, 0.0) and (1.0, 1.0) correspond to the upper left and lowerright corners of the data window. If the image is mapped onto asurface with texture coordinates outside the zero-to-one range, thenthe image must be extrapolated. This attribute tells the rendererhow to do this extrapolation. The attribute contains either a pairof comma-separated keywords, to specify separate extrapolation modesfor the horizontal and vertical directions; or a single keyword, tospecify extrapolation in both directions (e.g. “clamp,periodic” or“clamp”). Extra white space surrounding the keywords is allowed,but should be ignored by the renderer (“clamp, black “ is equivalentto “clamp,black”). The keywords listed below are predefined; somerenderers may support additional extrapolation modes:
- black
pixels outside the zero-to-one range are black
- clamp
texture coordinates less than 0.0 and greater than 1.0 are clampedto 0.0 and 1.0 respectively.
- periodic
the texture image repeats periodically
- mirror
the texture image repeats periodically, but every other instanceis mirrored
- framesPerSecond
Defines the nominal playback frame rate for image sequences, inframes per second. Every image in a sequence should have aframesPerSecond attribute, and the attribute value should be thesame for all images in the sequence. If an image sequence has noframesPerSecond attribute, playback software should assume that theframe rate for the sequence is 24 frames per second.
In order to allow exact representation of NTSC frame and fieldrates, framesPerSecond is stored as a rational number. A rationalnumber is a pair of integers, n and d, that represents the valuen/d.
- multiView
Defines the view names for multi-view image files. A multi-viewimage contains two or more views of the same scene, as seen fromdifferent viewpoints, for example a left-eye and a right-eye viewfor stereo displays. The multiView attribute lists the names of theviews in an image, and a naming convention identifies the channelsthat belong to each view.
- worldToCamera
For images generated by 3D computer graphics rendering, a matrixthat transforms 3D points from the world to the camera coordinatespace of the renderer.
The camera coordinate space is left-handed. Its origin indicatesthe location of the camera. The positive x and y axes correspond tothe “right” and “up” directions in the rendered image. The positivez axis indicates the camera’s viewing direction. (Objects in frontof the camera have positive z coordinates.)
Camera coordinate space in OpenEXR is the same as in Pixar’sRenderman.
- worldToNDC
For images generated by 3D computer graphics rendering, a matrixthat transforms 3D points from the world to the Normalized DeviceCoordinate (NDC) space of the renderer.
NDC is a 2D coordinate space that corresponds to the image plane,with positive x and pointing to the right and y positive pointingdown. The coordinates (0, 0) and (1, 1) correspond to the upperleft and lower right corners of the OpenEXR display window.
To transform a 3D point in word space into a 2D point in NDC space,multiply the 3D point by the worldToNDC matrix and discard the zcoordinate.
NDC space in OpenEXR is the same as in Pixar’s Renderman.
- deepImageState
Specifies whether the pixels in a deep image are sorted andnon-overlapping.
Note: this attribute can be set by application code that writes afile in order to tell applications that read the file whether thepixel data must be cleaned up prior to image processing operationssuch as flattening. The OpenEXR library does not verify that theattribute is consistent with the actual state of the pixels.Application software may assume that the attribute is valid, as longas the software will not crash or lock up if any pixels areinconsistent with the deepImageState attribute.
- originalDataWindow
If application software crops an image, then it should save the datawindow of the original, un-cropped image in the originalDataWindowattribute.
- dwaCompressionLevel
Sets the quality level for images compressed with the DWAA or DWABmethod.
- ID Manifest
ID manifest. SeeA scheme for storing object ID manifests inopenEXR images for details.
- colorInteropID
Color Interop ID. Provides a mechanism to identify the color space of the RGB images.SeeAn ID for Color InteropandIdentifying the Color Space of OpenEXR Files for details.New in OpenEXR v3.4.
Premultiplied vs. Un-Premultiplied Color Channels¶
TheA,AR,AG, andAB channels in an OpenEXR imagerepresent alpha or opacity: 0.0 means the pixel is transparent; 1.0means the pixel is opaque. By convention, all color channels arepremultiplied by alpha, so that
performs a correct “over” operation.
Describing the color channels as “premultiplied” is a shorthand fordescribing a correct “over” operation. With un-premultiplied colorchannels “over” operations would require computing
“Premultiplied” does not mean that pixels with zero alpha and non-zerocolor channels are illegal. Such a pixel represents an object thatemits light even though it is completely transparent, for example, acandle flame.
In the visual effects industry premultiplied color channels are thenorm, and application software packages typically use internal imagerepresentations that are also premultiplied.
Managing Un-Premultiplied Color Channels¶
However, some applications use an internal representation where thecolor channels have not been premultiplied by alpha. Since pixels withzero alpha and non-zero color can and do occur in OpenEXR images,application programs with un-premultiplied color channels should takecare to avoid discarding the color information in pixels with zeroalpha. After reading an OpenEXR image such an application must undothe premultiplication by dividing the color channels by alpha. Thisdivision fails when alpha is zero. The application software could setall color channels to zero wherever the alpha channel is zero, butthis might alter the image in an irreversible way. For example, theflame on top of a candle would simply disappear and could not berecovered.
If the internal un-premultiplied image representation uses 32-bitfloating-point numbers then one way around this problem might be toset alpha to max (h, alpha) before dividing, where h is a very smallbut positive value (h should be a power of two and less than half ofthe smallest positive 16-bit floating-point value). The result of thedivision becomes well-defined, and the division can be undone later,when the image is saved in a new OpenEXR file. Depending on theapplication software there may be other ways to preserve colorinformation in pixels with zero alpha.
[1](1,2)Z andZBack distances are the z-coordinate of the point in cameraspace (that is, the distance to plane on which point lies), not theactual distance to the point.
If a part containsRA,GA and/orBA channels, it must not also containan A channel.
