exrs (exr-rs)

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

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

  • deep data (next up)

  • line order

    • read any
    • write increasing-y
    • write any

  • compression methods (help wanted)

    • uncompressed
    • zip line
    • zip block
    • rle
    • piz
    • pxr24
    • b44, b44a
    • dwaa, dwab

• Nice Things

  • 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

Be sure to come back in a few weeks.

Example Usage

Read all contents of the exr file at once, including deep data, mip maps, and u32, f64, and f32 pixel data.

use exr::prelude::*;

// ReadOptions::default() includes multicore decompression
let image = FullImage::read_from_file("/images/test.exr", ReadOptions::default())?;
println("file meta data: {:#?}", image); // does not print actual pixel values

Writing all image contents at once:

use exr::prelude::*;

let image: FullImage = unimplemented!();
image.write_to_file("/images/written.exr", WriteOptions::default())?;

Cleanup Tasks Before Version 1.0

• remove all calls to Option::unwrap() and Result::unwrap()
• remove all print statements
• remove inappropriate assert! and debug_assert! calls, all unimplemented! calls, and use real Error handling instead
• reduce all not required pub usages
• revisit all TODO items
• remove all as casts

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
• 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.

Things that are not as specified in the PDF file (Or were forgotten):

• String Attributes don't store their length, because it can be inferred from the Attribute byte-size.
• Chunk Part-Number is not u64, but i32.

PRIORITIES

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