OpenEXR — Read and write EXR format images

Available Types

class OpenEXR.InputFile

The InputFile object is used to read an EXR file.

>>> import OpenEXR
>>> print len(OpenEXR.InputFile("GoldenGate.exr").channel('R')), "bytes of red data"
2170640 bytes of red data

The following data items and methods are supported:

header() → dict

Return the header of the open file. The header is a dictionary, see EXR header values.

channel(cname[, pixel_type[, scanLine1[, scanLine2]]]) → string

Read a channel from the OpenEXR image.

Parameters:

• cname (str) – the name of the channel in the image, for example “R”.
• pixel_type (Imath.PixelType) – desired pixel type of returned channel data. If not specified, the channel’s pixel data is returned in the format specified in the header.
• scanLine1 (int) – First scanline to return data for
• scanLine2 (int) – Last scanline to return data for

This method returns channel data in the format specified by pixel_type. If scanLine1 and scanLine2 are not supplied, then the method reads the entire image. Note that this method returns the channel data as a Python string: the caller must then convert it to the appropriate format as necessary.

channels(cnames[, pixel_type[, scanLine1[, scanLine2]]]) → strings

Multiple-channel version of channel().

Parameters:

• cnames (iterator yielding str) – the names of the channel in the image, for example “R”.
• pixel_type (Imath.PixelType) – desired pixel type of returned channel data. If not specified, the channel’s pixel data is returned in the format specified in the header.
• scanLine1 (int) – First scanline to return data for
• scanLine2 (int) – Last scanline to return data for

cnames is an iterator which specifies channels just as in the cname argument of channel():

>>> import OpenEXR
>>> golden = OpenEXR.InputFile("GoldenGate.exr")
>>> (r, g, b) = golden.channels("RGB")
>>> print len(r), len(g), len(b)
2170640 2170640 2170640

When reading multi-channel images, this method is significantly faster than reading single channels using calls to channel().

close()

Close the open file. Calling this method is mandatory, otherwise the file will be incomplete. However, as a convenience, the object’s destructor calls this method, so any open files are automatically closed at program exit.

isComplete()

isComplete() returns True if all pixels in the data window are present in the input file, or False if any pixels are missing. (Another program may still be busy writing the file, or file writing may have been aborted prematurely.)

class OpenEXR.OutputFile(filename, header)

Creates the EXR file filename, with given header. header contains the image’s properties represented as a dictionary - for example the one created by the convenience function Header().

>>> import OpenEXR, array
>>> data = array.array('f', [ 1.0 ] * (640 * 480)).tostring()
>>> exr = OpenEXR.OutputFile("out.exr", OpenEXR.Header(640,480))
>>> exr.writePixels({'R': data, 'G': data, 'B': data})

The following data items and methods are supported:

writePixels(dict[, scanlines])

Write the specified channels to the OpenEXR image. dict specifies multiple channels. If scanlines is not specified, then the entire image is assumed. dict specifies each channel’s data as channel:data, where channel and data are both strings. This method uses the file’s header to determine the format of the data (FLOAT, HALF or UINT) for each channel. If the string data is not of the appropriate size, this method raises an exception.

currentScanLine() → int

Return the current scan line being written.

close()

Close the open file. This method may be called multiple times. As a convenience, the object’s destructor calls this method.

Available Functions

OpenEXR.isOpenExrFile(filename) → bool

Returns True if the filename exists, is readable, and contains a valid EXR image.

>>> import OpenEXR
>>> print OpenEXR.isOpenExrFile("no-such-file")
False
>>> print OpenEXR.isOpenExrFile("lena.jpg")
False
>>> print OpenEXR.isOpenExrFile("GoldenGate.exr")
True

Note that a file may may valid, but not complete. To check if a file is complete, use InputFile.isComplete().

OpenEXR.Header(width, height) → dict

Convenience function that creates the EXR header for an image of size width x height with EXR mandatory entries set to appropriate defaults. An EXR header is a dictionary - see EXR header values for details of legal header contents.

>>> import OpenEXR
>>> print OpenEXR.Header(640,480)
{'compression': ZIP_COMPRESSION,
 'pixelAspectRatio': 1.0,
 'displayWindow': (0, 0) - (639, 479),
 'channels': {'R': FLOAT (1, 1), 'B': FLOAT (1, 1), 'G': FLOAT (1, 1)},
 'dataWindow': (0, 0) - (639, 479),
 'screenWindowCenter': (0.0, 0.0),
 'screenWindowWidth': 1.0,
 'lineOrder': INCREASING_Y}

EXR header values

This module represents EXR headers as regular Python dictionaries. In this dictionary the keys are strings, and the values are such that OpenEXR can determine their type. The module Imath provides many of the classes for attribute types.

>>> import OpenEXR
>>> print OpenEXR.InputFile("GoldenGate.exr").header()
{'tiles': None,
 'capDate': '2004:01:04 18:10:00',
 'compression': PIZ_COMPRESSION,
 'latitude': 37.827701568603516,
 'pixelAspectRatio': 1.0,
 'altitude': 274.5,
 'displayWindow': (0, 0) - (1261, 859),
 'focus': inf,
 'comments': 'View from Hawk Hill towards San Francisco',
 'screenWindowWidth': 1.1499999761581421,
 'channels': {'R': HALF (1, 1), 'B': HALF (1, 1), 'G': HALF (1, 1)},
 'isoSpeed': 50.0,
 'utcOffset': 28800.0,
 'longitude': -122.49960327148438,
 'dataWindow': (0, 0) - (1261, 859),
 'screenWindowCenter': (0.0, 0.0),
 'aperture': 2.7999999523162842,
 'preview': <Imath.PreviewImage instance 100x68>,
 'owner': 'Copyright 2004 Industrial Light & Magic',
 'expTime': 8.0,
 'lineOrder': INCREASING_Y}

Values in the dictionary may be:

string

header['owner'] = 'Copyright 2007 James Bowman'

float

header['isoSpeed'] = 50.0

int

header['version'] = 1001

dict

A dict represents the image’s channels. In the dict, the keys are the channel names, and the values are of class Imath.Channel:

header['channels'] = { 'L' : Imath.Channel(PixelType(OpenEXR.HALF)),
                       'Z' : Imath.Channel(PixelType(OpenEXR.FLOAT))}

Imath.Box2i

header['dataWindow'] = Imath.Box2i(Imath.point(0,0), Imath.point(640,480))

Imath.Box2f

header['regionOfInterest'] = Imath.Box2f(Imath.point(75.0,75.0),
                                         Imath.point(100.0,100.0))

Imath.V2f

header['originMarker'] = Imath.point(0.378, 0.878)

Imath.LineOrder

header['lineOrder'] = Imath.LineOrder(Imath.LineOrder.INCREASING_Y)

Imath.PreviewImage

A preview image, specified by height, width, and a string of length 4*width*height. The pixels are in RGBA order.:

header['preview'] = Imath.PreviewImage(320,200,pixels)

or to use a PIL image as an EXR preview:

header['preview'] = Imath.PreviewImage(im.size[0], im.size[1], im.convert("RGBA").tostring())

Imath.Compression

header['Compression'] = Imath.Compression(Imath.Compression.PIZ_COMPRESSION)

Imath.Chromaticities

Specifies (x, y) chromaticities for red, green, blue and white components:

header['chromaticities'] = Imath.Chromaticities(Imath.chromaticity(0,0))