or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdcpp-api.mdfile-io.mdimage-data.mdindex.mdmetadata.md
tile.json

tessl/pypi-openexr

Professional-grade EXR image format library for high-dynamic-range scene-linear image data with multi-part and deep compositing support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/openexr@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-openexr@4.0.0

index.mddocs/

OpenEXR

Professional-grade EXR image format library for high-dynamic-range (HDR) scene-linear image data. OpenEXR provides comprehensive support for multi-channel images, deep compositing, multi-part files, and advanced compression methods used extensively in visual effects, animation, and professional photography workflows.

Package Information

  • Package Name: OpenEXR
  • Package Type: pypi
  • Language: Python (with C++ backend)
  • Installation: pip install OpenEXR

Core Imports

import OpenEXR

For working with image data arrays:

import OpenEXR
import numpy as np

For geometric types and metadata:

from OpenEXR import Imath

Basic Usage

import OpenEXR
import numpy as np

# Create image data
height, width = 480, 640
rgb_data = np.random.rand(height, width, 3).astype('f')

# Write EXR file
header = {
    "compression": OpenEXR.ZIP_COMPRESSION,
    "type": OpenEXR.scanlineimage
}
channels = {"RGB": rgb_data}

with OpenEXR.File(header, channels) as outfile:
    outfile.write("output.exr")

# Read EXR file
with OpenEXR.File("output.exr") as infile:
    header = infile.header()
    channels = infile.channels()
    rgb_pixels = channels["RGB"].pixels
    
    print(f"Image size: {infile.width()} x {infile.height()}")
    print(f"Channels: {list(channels.keys())}")

Architecture

OpenEXR uses a layered architecture optimized for professional image workflows:

  • File Layer: High-level file I/O with context management and multi-part support
  • Part Layer: Individual image components within multi-part files (beauty, depth, motion vectors, etc.)
  • Channel Layer: Named data channels with flexible pixel types and subsampling
  • Metadata Layer: Extensible header attributes for workflow information
  • Compression Layer: Multiple algorithms optimized for different content types
  • Core Layer: C++ backend providing high-performance encoding/decoding

This design enables OpenEXR's role as the standard for VFX and animation pipelines, supporting complex compositing workflows, HDR color spaces, and massive image resolutions with efficient storage and access patterns.

Capabilities

File I/O Operations

Primary interfaces for reading and writing EXR files, including scanline and tiled formats, with support for streaming operations and multi-threading.

class File:
    def __init__(self, filename: str, separate_channels: bool = False, header_only: bool = False): ...
    def __init__(self, header: dict, channels: dict): ...
    def __init__(self, parts: list): ...
    
    def __enter__(self): ...
    def __exit__(self, *args): ...
    
    def header(self, part_index: int = 0) -> dict: ...
    def channels(self, part_index: int = 0) -> dict: ...
    def write(self, filename: str) -> None: ...
    
    def width(self, part_index: int = 0) -> int: ...
    def height(self, part_index: int = 0) -> int: ...
    
    parts: list  # List of Part objects for multi-part files

File I/O Operations

Image Data Structures

Channel-based image representation with support for arbitrary pixel types, subsampling, and deep compositing data structures.

class Channel:
    def __init__(self, name: str = None, pixels: np.ndarray = None, 
                 xSampling: int = 1, ySampling: int = 1, pLinear: bool = False): ...
    def pixelType(self) -> int: ...
    
    name: str           # Channel name
    xSampling: int      # Horizontal subsampling factor
    ySampling: int      # Vertical subsampling factor
    pLinear: bool       # Premultiplied linear flag
    pixels: np.ndarray  # Pixel data array

class Part:
    def __init__(self, header: dict, channels: dict, name: str): ...
    def name(self) -> str: ...
    def shape(self) -> tuple: ...
    def width(self) -> int: ...
    def height(self) -> int: ...
    def compression(self) -> int: ...
    def type(self) -> int: ...
    def typeString(self) -> str: ...
    
    header: dict    # Part metadata
    channels: dict  # Channel data

Image Data Structures

Metadata and Headers

Extensible attribute system for storing image metadata, including standard attributes for color spaces, camera data, and custom application-specific information.

# Standard header attributes
header = {
    "compression": int,         # Compression method
    "type": int,               # Image type (scanline/tiled/deep)
    "dataWindow": tuple,       # Pixel data bounds
    "displayWindow": tuple,    # Display bounds
    "pixelAspectRatio": float, # Pixel aspect ratio
    "screenWindowCenter": tuple, # Screen window center
    "screenWindowWidth": float,  # Screen window width
}

Metadata and Headers

Advanced Features

Multi-part files, deep compositing images, advanced compression methods, and tiled storage for high-performance random access.

# Multi-part files
parts = [
    OpenEXR.Part(beauty_header, beauty_channels, "beauty"),
    OpenEXR.Part(depth_header, depth_channels, "depth"),
    OpenEXR.Part(motion_header, motion_channels, "motion")
]

# Compression constants
OpenEXR.NO_COMPRESSION     # No compression
OpenEXR.ZIP_COMPRESSION    # ZIP lossless compression
OpenEXR.PIZ_COMPRESSION    # PIZ wavelet compression
OpenEXR.DWAA_COMPRESSION   # DWAA lossy compression

Advanced Features

C++ API Reference

Low-level C++ interface for maximum performance, custom integrations, and advanced use cases requiring direct control over encoding/decoding operations.

// Primary C++ classes
class InputFile;               // Scanline input
class OutputFile;             // Scanline output
class TiledInputFile;         // Tiled input
class TiledOutputFile;        // Tiled output
class MultiPartInputFile;     // Multi-part input
class MultiPartOutputFile;    // Multi-part output

C++ API Reference

Types

# Pixel type constants
OpenEXR.UINT: int    # 32-bit unsigned integer
OpenEXR.HALF: int    # 16-bit floating point
OpenEXR.FLOAT: int   # 32-bit floating point

# Compression method constants  
OpenEXR.NO_COMPRESSION: int
OpenEXR.RLE_COMPRESSION: int
OpenEXR.ZIPS_COMPRESSION: int
OpenEXR.ZIP_COMPRESSION: int
OpenEXR.PIZ_COMPRESSION: int
OpenEXR.PXR24_COMPRESSION: int
OpenEXR.B44_COMPRESSION: int
OpenEXR.B44A_COMPRESSION: int
OpenEXR.DWAA_COMPRESSION: int
OpenEXR.DWAB_COMPRESSION: int
OpenEXR.HTJ2K256_COMPRESSION: int
OpenEXR.HTJ2K32_COMPRESSION: int

# Line order constants
OpenEXR.INCREASING_Y: int    # Top to bottom
OpenEXR.DECREASING_Y: int    # Bottom to top
OpenEXR.RANDOM_Y: int        # Random (tiled only)

# Image type constants
OpenEXR.scanlineimage: int   # Scanline format
OpenEXR.tiledimage: int      # Tiled format
OpenEXR.deepscanline: int    # Deep scanline format
OpenEXR.deeptile: int        # Deep tiled format

# Level mode constants
OpenEXR.ONE_LEVEL: int       # Single resolution level
OpenEXR.MIPMAP_LEVELS: int   # Mipmap levels
OpenEXR.RIPMAP_LEVELS: int   # Ripmap levels

# Level rounding mode constants  
OpenEXR.ROUND_DOWN: int      # Round down to lower level
OpenEXR.ROUND_UP: int        # Round up to higher level

# Environment map type constants
OpenEXR.ENVMAP_LATLONG: int  # Latitude/longitude mapping
OpenEXR.ENVMAP_CUBE: int     # Cube face mapping

# Utility Classes
class KeyCode:
    """Motion picture film characteristics."""
    def __init__(self, filmMfcCode: int = 0, filmType: int = 0, prefix: int = 0,
                 count: int = 0, perfOffset: int = 0, perfsPerFrame: int = 0, perfsPerCount: int = 0): ...
    
    filmMfcCode: int    # Film manufacturer code
    filmType: int       # Film type code  
    prefix: int         # Prefix
    count: int          # Count
    perfOffset: int     # Perforation offset
    perfsPerFrame: int  # Perforations per frame
    perfsPerCount: int  # Perforations per count

class TimeCode:
    """SMPTE time and control code."""
    def __init__(self, hours: int = 0, minutes: int = 0, seconds: int = 0, frame: int = 0,
                 dropFrame: bool = False, colorFrame: bool = False, fieldPhase: bool = False,
                 bgf0: bool = False, bgf1: bool = False, bgf2: bool = False,
                 binaryGroup1: int = 0, binaryGroup2: int = 0, binaryGroup3: int = 0,
                 binaryGroup4: int = 0, binaryGroup5: int = 0, binaryGroup6: int = 0,
                 binaryGroup7: int = 0, binaryGroup8: int = 0): ...
    
    hours: int          # Hours (0-23)
    minutes: int        # Minutes (0-59)
    seconds: int        # Seconds (0-59)
    frame: int          # Frame number
    dropFrame: bool     # Drop frame flag
    colorFrame: bool    # Color frame flag
    fieldPhase: bool    # Field phase flag

class Rational:
    """Rational number representation."""
    def __init__(self, n: int, d: int): ...
    
    n: int  # Numerator
    d: int  # Denominator