exrs (exr-rs)

This library is a 100% Rust and 100% safe code encoding and decoding library for the OpenEXR image file format. See the examples for a first impression.

OpenEXR is the de-facto standard image format in animation, VFX, and other computer graphics pipelines, for it can represent an immense variety of pixel data with lossless compression.

Features include:

• any number of images placed anywhere in 2d space
• any number of channels in an image (rgb, xyz, lab, depth, motion, mask, ...)
• any type of high dynamic range values (16bit float, 32bit float, 32bit unsigned integer) per channel
• any number of samples per pixel ("deep data")
• uncompressed pixel data for fast file access
• lossless compression for any image type
• lossy compression for non-deep image types for very small files
• load specific sections of an image without processing the whole file
• compress and decompress images in parallel
• embed any kind of meta data, including custom bytes, with full backwards compatibility

Current Status

This library is in an early stage of development. It only supports a few of all possible image types. Currently, deep data and complex compression algorithms are not supported yet.

Highly experimental!

Currently supported:

• Supported OpenEXR Features

  • custom attributes
  • multi-part images
  • multi-resolution images: mip maps, rip maps
  • any line order
  • extract meta data of any file, including files with deep data and any compression format
  • channel subsampling
  • deep data
  • compression methods (help wanted)
    • uncompressed
    • zip line
    • zip block
    • rle
    • piz
    • pxr24
    • b44, b44a
    • dwaa, dwab

• Nice Things

  • no external dependency or environment variable paths to set up
  • read meta data without having to load image data
  • read all contents at once
    • decompress image sections either in parallel or with low memory overhead
  • write all contents at once
    • compress blocks in parallel
  • read only some blocks dynamically
  • write blocks streams, one after another
  • progress callback
  • memory mapping

If you encounter an exr file that cannot be opened by this crate, please leave an issue on this repository, containing the image file.

Usage

[dependencies]
exr = "0.6.0"

The master branch of this repository is always an up-to-date version.

Example

Example: Write all image contents to an exr file at once.

fn main() {
    let size = Vec2(1024, 512);

    // create a channel containing 1024x512 f32 values
    let luma = Channel::new_linear(
        "Y".try_into().unwrap(), // OpenEXR only supports ascii, so this may fail
        Samples::F32(generate_f32_vector(size))
    );

    let layer = simple::Layer::new(
        "test-image".try_into().unwrap(), // layer name
        IntRect::from_dimensions(size.to_u32()), // set position to (0,0) and size to 1025x512
        smallvec![ luma ], // include the one channel we created
    );
    
    // create an exr file from a single layer (an exr file can have multiple layers)
    let image = Image::new_from_single_layer(layer.with_compression(Compression::RLE));

    println!("writing image with meta data {:#?}", image);

    // write the image, compressing in parallel with all available cpus
    image.write_to_file("./testout/constructed.exr", WriteOptions::high()).unwrap();
}

See the examples folder for more examples.

Motivation

Using the Rust bindings to OpenEXR requires compiling multiple C++ Libraries and setting environment variables, which I didn't quite feel like to do, so I wrote this library instead.

Also, I really wanted to have a library which had an 'X' in its name in my git repositories.

Goals

exrs aims to provide a safe and convenient interface to the OpenEXR file format.

This library does not try to be a general purpose image file or image processing library. Therefore, color conversion, subsampling, and mip map generation are left to other crates for now. As the original OpenEXR implementation supports those operations, this library may choose to support them later. Furthermore, this implementation does not try to produce byte-exact file output matching the original implementation, but only correct output.

Safety

This library uses no unsafe code. In fact, this crate is annotated with #[forbid(unsafe_code)]. Its dependencies use unsafe code, though.

All information from a file is handled with caution. Allocations have a safe maximum size that will not be exceeded at once.

What I am proud of

• Flexible API allows for custom parallelization
• Difficult to misuse API
• This is a pretty detailed README
• (more to come)

Specification

This library is modeled after the official OpenEXRFileLayout.pdf document. Unspecified behavior is concluded from the C++ library.

PRIORITIES

1. Support all compression formats
2. Support Deep Data
3. Simple rendering of common image formats
4. Profiling and other optimization
5. Tooling (Image Viewer App)