karelpeeters / exrs

100% Safe Rust OpenEXR file library

EXRS

This library is a 100% Rust and 100% safe code library for reading and writing OpenEXR images. 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 layers 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 to produce very small files
• load specific sections of an image without processing the whole file
• compress and decompress image pixels in parallel
• embed any kind of meta data, including custom structs, 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 (lossless)
    • zip block (lossless)
    • rle (lossless)
    • piz (lossless)
    • pxr24 (lossless for f16 and u32)
    • 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
  • read and write progress callback
  • abortable read and write
  • write blocks streams, one after another
  • 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

Add this to your Cargo.toml:

[dependencies]
exr = "1.1.0"

# also, optionally add this to your crate for smaller binary size 
# and better runtime performance
[profile.release]
lto = true

The master branch of this repository is always an up-to-date version, so you could also link the github repository master branch.

Example

Example: generate an rgb exr file.

extern crate exr;

fn main() {
    // write a file with 16-bit alpha and 32-bit color precision
    exr::prelude::write_rgba_file(
        "tests/images/out/minimal_rgb.exr",
        2048, 2048, // write an image with 2048x2048 pixels
        |x,y| ( // generate (or lookup in your own image) an f32 rgb color for each of the 2048x2048 pixels
                x as f32 / 2048.0, // red
                y as f32 / 2048.0, // green
                1.0 - (y as f32 / 2048.0), // blue
                f16::from_f32(0.8) // 16-bit alpha
        )
    ).unwrap();
}

See the the examples folder for more examples.

Or read the guide.

Motivation

Using any Rust bindings to the original OpenEXR library unfortunately requires compiling multiple C++ Libraries and possibly 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)

Running Tests

To run all fast tests, use cargo test. To start fuzzing indefinitely, use cargo test --package exr --test fuzz fuzz -- --exact --ignored.

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)