.. toctree:: :caption: Standard Attributes
OpenEXR files store metadata in attributes. The attributes marked below as
"required" are present in every .exr file and specify values essential to
every image.
The optional attributes store extra information in a conventional form. These
tables give the presumed definitions of the most common data associated with
.exr image files.
| attribute name | type | definition |
|
displayWindow required |
Box2i |
The boundaries of an OpenEXR image in pixel space. The display window is defined by the coordinates of the pixels in the upper left and lower right corners. See Overview of the OpenEXR File Format for more details. |
|
dataWindow required |
Box2i |
An OpenEXR file may not have pixel data for all the pixels in the display window, or the file may have pixel data beyond the boundaries of the display window. The region for which pixel data are available is defined by a second axis-parallel rectangle in pixel space, the data window. See Overview of the OpenEXR File Format for more details. |
|
originalDataWindow |
Box2i |
If application software crops an image, then it should save the data window of the original, un-cropped image in the originalDataWindow attribute. |
|
pixelAspectRatio
required |
float |
Width divided by height of a pixel when the image is displayed with the correct aspect ratio. A pixel's width (height) is the distance between the centers of two horizontally (vertically) adjacent pixels on the display. |
|
screenWindowCenter required |
V2f |
The screenWindowCenter and screenWindowWidth describe the perspective projection that produced the image. Programs that deal with images as purely two-dimensional objects may not be able so generate a description of a perspective projection. Those programs should set screenWindowWidth to 1, and screenWindowCenter to (0, 0). |
|
screenWindowWidth required |
V2f | |
|
lineOrder required |
LineOrder |
Specifies in what order the scan lines in the file are stored in the file:
|
|
compression required |
Compression |
Specifies the compression method applied to the pixel data of all channels in the file.
|
|
channels
required |
ChannelList |
A description of the image channels stored in the file. |
| attribute name | type | definition |
|
name required for multi-part images |
string |
The name attribute defines the name of each part. The name of each part must be unique. Names may contain '*.*' characters to present a tree-like structure of the parts in a file. |
|
type required for multi-part images |
string |
Data types are defined by the type attribute. There are four types:
|
|
version required for multi-part images |
int |
Version 1 data for all part types is described in the section on the OpenEXR File Layout. |
|
chunkCount required for multi-part images |
int |
Indicates the number of chunks in this part. Required if the multipart bit (12) is set. This attribute is created automatically by the library; the user does not need to compute it. |
|
tiles required for multi-part images |
TileDescription |
This attribute is required only for tiled files. It specifies the size of the tiles, and the file's level mode. |
These attributes describe the position and orientation of the physical or CG camera at the time of capture. All are optional.
| attribute name | type | definition |
| worldToCamera | M44f |
For images generated by 3D computer graphics rendering, a matrix that transforms 3D points from the world to the camera coordinate space of the renderer. The camera coordinate space is left-handed. Its origin indicates the location of the camera. The positive x and y axes correspond to the "right" and "up" directions in the rendered image. The positive z axis indicates the camera's viewing direction. (Objects in front of the camera have positive z coordinates.) Camera coordinate space in OpenEXR is the same as in Pixar's Renderman. |
| worldToNDC | M44f |
For images generated by 3D computer graphics rendering, a matrix that transforms 3D points from the world to the Normalized Device Coordinate (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 pointing down. The coordinates (0, 0) and (1, 1) correspond to the upper left 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 z coordinate. NDC space in OpenEXR is the same as in Pixar's Renderman. |
| sensorCenterOffset | V2f |
Horizontal and vertical distances, in microns, of the center of the light-sensitive area of the camera's sensor from a point on that sensor where a sensor surface normal would intersect the center of the lens mount. When compared to an image captured with a perfectly centered sensor, an image where both horizontal and vertical distances were positive would contain more content holding what was at the right and what was at the bottom of the scene being captured. |
| sensorOverallDimensions | V2f |
Dimensions of the light-sensitive area of the sensor, in millimeters, independent of the subset of that region from which image data are obtained. |
| sensorPhotositePitch | float |
Distance between centers of sensor photosites, in microns. |
| sensorAcquisitionRectangle | Box2i |
The rectangular area of the sensor containing photosites the contents of which are in one-to-one correspondence with the captured sensels, for a monochrome sensor, or with the reconstructed RGB pixels, for a sensor covered with color filter array material in a Bayer or a similar pattern. Because understanding the above formal definition is critical for many applications, including camera solvers, some short definitions:
The Wikipedia article on demosaicing covers the basics of these ideas quite well. In the case of sensels read from a monochrome sensor, the idea of a one-to-one relationship between sensels read from the photosite array and pixels in the data window can be straightforward. Often there is a conversion of the sensel data read from the photosites to a different representation (e.g. integer to float) along with scaling of the individual values. A common spatial scaling is from a 2880 x 1620 acquisition format to a 1920 x 1080 HD format. In this case, a camera solver will want to know the original set of photosites that contributed sensel values to the downscaler: their number, and their position. Through a combination of sensorAcquisitionRectangle, sensorPhotositePitch, sensorOverallDimensions and sensorCenterOffset, the application can know exactly the area on the sensor on which the light fell to create the sensel values that produced a monochrome image. RGB images are more complicated. RGB pixel reconstruction is a form of filtering, and kernels are square, with relatively small span, e.g. 5x5 or 7x7. Edge handling for the kernel is important; the Wikipedia article describing an image processing kernel covers it well. Elements of the reconstruction kernel that are never at the center of the kernel are not counted as part of the sensorAcquisitionRectangle. Recalling the simple case above of a non-spatially-scaled 2880 x 1620 monochrome image being in 1:1 correspondence with an array of photosites on the sensor, if we are instead reading from a CFA-covered sensor to reconstruct a 2880 x 1620 RGB image, the actual array of all photosites whose sensel values were fed into a 5x5 reconstruction kernel would not be 2880 x 1620, but 2884 x 1624. Nevertheless, the size of the sensorAcquisitionRectangle would be 2880 x 1620. Camera systems differ on how to handle the case where the position of the RGB reconstruction kernel is such that one or more elements of the kernel do not correspond to physical photosites; these are edge cases in every sense of the phrase. |
| xDensity | float |
Horizontal output density, in pixels per inch. The image's vertical output density is xDensity * pixelAspectRatio. |
| longitude | float |
For images of real objects, the location where the image was recorded. Longitude and latitude are in degrees east of Greenwich and north of the equator. Altitude is in meters above sea level. For example, Kathmandu, Nepal is at longitude 85.317, latitude 27.717, altitude 1305. |
| latitude | float | |
| altitude | float |
These attributes identify the camera. All are optional.
| attribute name | type | definition |
| cameraMake | string |
Manufacturer or vendor of the camera. If present, the value should be UTF-8-encoded and have a nonzero length. |
| cameraModel | string |
Model name or model number of the camera. If present, the value should be UTF-8-encoded and have a nonzero length. |
| cameraSerialNumber | string |
Serial number of the camera If present, the value should be UTF-8-encoded and have a nonzero length. Note that despite the name, the value can include non-digits as well as digits. |
| cameraFirmwareVersion | string |
The firmware version of the camera. If present, the value should be UTF-8-encoded and have a nonzero length. |
| cameraUuid | string |
Identifies this camera uniquely among all cameras from all vendors. Uniqueness could be accomplished with, e.g., a MAC address, a concatenation of cameraMake, cameraModel, cameraSerialNumber, etc. The string may have arbitrary format; it doesn't need to follow the UUID 128-bit string format, even though that is implied by the name. If present, the value should be UTF-8-encoded and have a nonzero length. |
| cameraLabel | string |
Text label identifying how the camera was used or assigned, e.g. "Camera 1 Left", "B Camera", "POV", etc If present, the value should be UTF-8-encoded and have a nonzero length. |
These attributes describe the camera settings. All are optional.
| attribute name | type | definition |
| cameraCCTSetting | float |
Color temperature, in Kelvin, configured for the physical or virtual camera creating or capturing the image. The cameraCCTSetting is primarily forensic, and indicates the stated color balance of a film stock, the color temperature setting on a physical digital camera or the nominal color temperature of the scene adopted white as passed to a virtual camera's API. A professional digital cinema cameras is not constrained to map every supplied correlated color temperature to a point on the curve of a Planckian radiator, or map every supplied color temperature to a chromaticity corresponding to a combination of the three principal components forming a basis for the CIE D series of illuminants. Often, lower color temperatures are on the Planckian locus, higher color temperatures are on a locus of CIE D series chromaticities, and the camera performs a crossfade (typically a linear crossfade) between the two for intermediate temperatures. That the start and end of the crossfade could differ for every camera vendor -- or even across cameras offered by the same vendor -- means that no universal algorithm can map a camera color temperature setting (combined with a tint setting, see below) into a scene adopted white chromaticity. The most common use for the cameraCCTSetting attribute is to feed its value into a camera-vendor-provided application or API, along with a cameraTintSetting attribute value, to reproduce the color processing done in-camera on set. If a cameraCCTSetting attribute is provided, and no cameraTintSetting is provided, then a value of zero should be passed to any application or API using the cameraCCTSetting and cameraTintSetting. |
| cameraTintSetting | float |
Green/magenta tint configured for the physical or virtual camera creating or capturing the image. The cameraTintSetting is primarily forensic. There is no vendor- independent mapping from a unit of tint to a distance on a chromaticity diagram. One camera vendor might choose a color space (e.g. the CIE 1960 UCS) and have a unit amount of tint represent some delta uv distance from the point by the cammeraCCTSetting and a tint value of 0. Another might choose to express the effect of tint by analogy to a traditional unit from a film workflow, e.g. a Kodak or Rosco color correction filter. About the only guaranteed commonality is that all camera vendor tint schemes have positive values shift the adopted scene white towards green, and negative values toward magenta. If the camera vendor maps cameraCCTSetting to a point defined by a linear crossfade between a Planckian blackbody locus and loci of CIE D Series illuminants, the slope of the tint isotherm at the exact points where the linear crossfade starts and ends can be indeterminate and an inverse mapping from chromaticity to a pair of CCT and tint can be one-to-many. The most common use for the cameraTintSetting attribute is to feed its value into a camera-vendor-provided application or API, along with a cameraCCTSetting attribute value, to reproduce the color processing done in-camera on set. |
| cameraColorBalance | V2f |
Chromaticity in CIE 1960 UCS coordinates indicating a color the user of the camera would like the camera to treat as neutral, and corresponding to a particular camera configuration of make, model, camera firmware version, CCT setting and tint setting. Note that this is not necessarily (or even probably) the same chromaticity as that of the scene adopted white stored in an adoptedNeutral attribute (if present). For example, if a physical digital cinema camera was configured with a CCT of 3200K and a tint of -3 (in some camera vendor dependent unit), and the camera output had been processed such that the image containing this attribute was encoded as per SMPTE ST 2065-4:2023, then the adoptedNeutral attribute would have the value corresponding to the ACES neutral chromaticity, very near that of CIE Illuminant D60, whereas the cameraColorBalance would have a chromaticity much, much warmer than that of the adoptedNeutral attribute. |
| isoSpeed | float |
The ISO speed of the film or the ISO setting of the camera that was used to record the image. |
| expTime | float |
Exposure time, in seconds |
| shutterAngle | float |
Shutter angle, in degrees For a physical film or digital camera, changing the shutter angle inexorably affects both motion blur and exposure. For a CG camera, the parameters to the renderer control whether or not changing the shutter angle affects simulation of either or both of these phenomena. |
| captureRate | Rational |
Capture rate, in frames per second, of the image sequence to which the image belongs, represented as a rational number For variable frame rates, time-lapse photography, etc. the capture rate r is calculated as: r = 1 / (tN - tNm1) where tn is the time, in seconds, of the center of frame N's exposure interval, and tNm1 is the time, in seconds, of the center of frame N-1's exposure interval. Both the numerator and denominator of r must be strictly positive.
|
These attributes identify the lens. All are optional.
| attribute name | type | definition |
| lensMake | string |
Manufacturer or vendor of the lens. If present, the value should be UTF-8-encoded and have a nonzero length.
|
| lensModel | string |
Model name or model number of the lens. If present, the value should be UTF-8-e coded and have a nonzero length. |
| lensSerialNumber | string |
Serial number of the lens Note that despite the name, the value can include non-digits as well as digits. If present, the value should be UTF-8-encoded and have a nonzero length. |
| lensFirmwareVersion | string |
Firmware version of the lens. If present, the value should be UTF-8-encoded and have a nonzero length. |
These attributes describe the lens settings. All are optional.
| attribute name | type | definition |
| nominalFocalLength | float |
Mumber printed on barrel of a prime lens, or number next to index mark on a zoom lens, in units of millimeters. Nominal focal length is appropriate for asset tracking of lenses (e.g. a camera rental house catalogs its lens stock by nominal focal length). |
| pinholeFocalLength | float |
In the simplest model of image formation, the distance between the pinhole and the image plane, in units of millimeters. When a CGI application supplies a method for an artist to provide focal length to some calculation, pinhole focal length is almost always the appropriate number to convey to the application. |
| effectiveFocalLength | float |
In the thick lens model, the effective focal length is the distance between the front focal point and the front nodal point, or equivalently the back focal point and the back nodal point, in units of millimeters. The effective focal length is an abstraction used in lens design and, unless a CGI application is sophisticated enough to be using the thick lens model, should not be supplied to the application; for normal CGI applications, pinhole focal length should be used. Note that the forward and back lens nodal points mentioned above are distinct in meaning and in position from the forward and back lens entrance pupils. A 'no-parallax' rotation is rotation around the forward lens entrance pupil. |
| entrancePupilOffset | float |
The axial distance from the image plane to the entrance pupil, in units of millimeters. A larger entrance pupil offset means the entrance pupil is closer to the object. Note that in some lens configurations, the entrance pupil offset can be negative. |
| aperture | float |
The f-number of the lens, computed as the ratio of lens effective focal length to the diameter of lens entrance pupil at the time the image was created or captured. |
| Stop | float |
The ratio of lens effective focal length to diameter of entrance pupil divided by the square root of the transmittance the lens presents to a paraxial ray. Note that tStop, like aperture, must be strictly positive; and that tStop will always be a larger number than aperture. |
| focus | float |
The camera's focus distance, in meters |
These attribute help to document the image. All are optional.
| attribute name | type | definition |
| owner | string |
Name of the owner of the image. |
| comments | string |
Additional image information in human-readable form, for example a verbal description of the image. |
| capDate | string |
The date when the image was created or captured, in local time, and formatted as YYYY:MM:DD hh:mm:ss, where YYYY is the year (4 digits, e.g. 2003), MM is the month (2 digits, 01, 02, ... 12), DD is the day of the month (2 digits, 01, 02, ... 31), hh is the hour (2 digits, 00, 01, ... 23), mm is the minute, and ss is the second (2 digits, 00, 01, ... 59). |
| utcOffset | float |
Universal Coordinated Time (UTC), in seconds: UTC == local time + utcOffset. |
| keyCode | KeyCode |
For motion picture film frames. Identifies film manufacturer, film type, film roll and frame position within the roll. |
| framesPerSecond | Rational |
Defines the nominal playback frame rate for image sequences, in frames per second. Every image in a sequence should have a framesPerSecond attribute, and the attribute value should be the same for all images in the sequence. If an image sequence has no framesPerSecond attribute, playback software should assume that the frame rate for the sequence is 24 frames per second. In order to allow exact representation of NTSC frame and field rates, framesPerSecond is stored as a rational number. A rational number is a pair of integers, n and d, that represents the value n/d. |
| timeCode | TimeCode |
Time and control code. |
| imageCounter | int |
An image number. For a sequence of images, the image number increases when the images are accessed in the intended play order. imageCounter can be used to order frames when more standard ordering systems are inapplicable, including but not limited to uniquely identifying frames of high-speed photography that would have identical time codes, ordering sequences of frames where some frames may have been captured and discarded due to real-time constraints, or ordering frames in a sequence that is intermittently accumulated from devices such as security cameras triggered by motion in an environment. |
| reelName | string |
Name for a sequence of unique images. If present, the value should be UTF-8-encoded and have a nonzero length. |
| ascFramingDecisionList | string |
JSON-encoded description of framing decisions associated with the captured image, in a format termed 'ASC-FDL', designed and documented by the American Society of Cinematographers (ASC). If present, the value should be UTF-8-encoded and have a nonzero length. |
These attributes describe the color characteristics of the image. All are optional.
| attribute name | type | definition |
| chromaticities | Chromaticities |
For RGB images, specifies the CIE (x,y) chromaticities of the primaries and the white point. |
| whiteLuminance | float |
For RGB images, defines the luminance, in Nits (candelas per square meter) of the RGB value (1.0, 1.0, 1.0).
If the chromaticities and the luminance of an RGB image are known, then it is possible to convert the image's pixels from RGB to CIE XYZ tristimulus values. |
| adoptedNeutral | V2f |
Specifies the CIE (x,y) coordinates that should be considered neutral during color rendering. Pixels in the image file whose (x,y) coordinates match the adoptedNeutral value should be mapped to neutral values on the display. |
These attributes relate to the application of the image in the motion picture pipeline. All are optional.
| attribute name | type | definition |
| envmap | Envmap |
If this attribute is present, the image represents an environment map. The attribute's value defines how 3D directions are mapped to 2D pixel locations. |
| wrapmodes | string |
Determines how texture map images are extrapolated. If an OpenEXR file 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 lower right corners of the data window. If the image is mapped onto a surface with texture coordinates outside the zero-to-one range, then the image must be extrapolated. This attribute tells the renderer how to do this extrapolation. The attribute contains either a pair of comma-separated keywords, to specify separate extrapolation modes for the horizontal and vertical directions; or a single keyword, to specify 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 equivalent to "clamp,black"). The keywords listed below are predefined; some renderers may support additional extrapolation modes:
|
| multiView | StringVector |
Defines the view names for multi-view image files. A multi-view image contains two or more views of the same scene, as seen from different viewpoints, for example a left-eye and a right-eye view for stereo displays. The multiView attribute lists the names of the views in an image, and a naming convention identifies the channels that belong to each view. |
| deepImageState | DeepImageState |
Specifies whether the pixels in a deep image are sorted and non-overlapping. Note: this attribute can be set by application code that writes a file in order to tell applications that read the file whether the pixel data must be cleaned up prior to image processing operations such as flattening. The OpenEXR library does not verify that the attribute is consistent with the actual state of the pixels. Application software may assume that the attribute is valid, as long as the software will not crash or lock up if any pixels are inconsistent with the deepImageState attribute. See Interpreting OpenEXR Deep Pixels for more details. |
| idManifest | CompressedIDManifest |
ID manifest. |
These attributes are how obsolete and are no longer officially supported by file format. Note that you can still read and write images that contain these attributes.
| attribute name | definition |
| dwaCompressionLevel |
Sets the quality level for images compressed with the DWAA or DWAB method. |
| renderingTransform |
Specify the names of the CTL functions that implements the intended color rendering and look modification transforms for this image. |
| lookModTransform | |
| maxSamplesPerPixel |
Stores the maximum number of samples used by any single pixel within a deep image. If this number is small, it may be appropriate to read the deep image into a fix-sized buffer for processing. However, this number may be very large. Note that the library never actually enforced the correctness of this value, so if it appears in legacy files, it should not be trusted. |