This library is a 100% Rust and 100% safe code library for reading and writing OpenEXR images.
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, like in Photoshop - any set of channels in an image (rgb, xyz, lab, depth, motion, mask, anything, ...) - three types of high dynamic range values (16bit float, 32bit float, 32bit unsigned integer) per channel - 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 on multiple threads in parallel - add arbitrary meta data to any image, including custom byte data, with full backwards compatibility - any number of samples per pixel ("deep data") (not yet supported)
This library has matured quite a bit, but should still be considered incomplete. For example, deep data and DWA compression algorithms are not supported yet.
If you encounter an exr file that cannot be opened by this crate but should be, please leave an issue on this repository, containing the image file.
The focus is set on supporting all feature and correctness; some performance optimizations are to be done.
What we can do:
Supported OpenEXR Features
Nice Things
read_rgba_file, write_rgba_file, read_all_data_from_file),
plus embracing common high-level Rust abstractionsread_all_data_from_file)
without knowing anything about the file in advancestd::io::Read and std::io::Write traitsAdd this to your Cargo.toml:
```toml
[dependencies]
exr = "1.5.2"
[profile.release] lto = true ```
The master branch of this repository always matches the crates.io version,
so you could also link the github repository master branch.
Example: generate an rgb exr file.
```rust extern crate exr;
/// To write your image data, you need to specify how to retrieve a single pixel from it. /// The closure may capture variables or generate data on the fly. fn main() { use exr::prelude::*;
// write a file, with 32-bit float precision per channel
write_rgba_file(
// this accepts paths or &str
"minimal_rgba.exr",
// image resolution is 2k
2048, 2048,
// generate (or lookup in your own image)
// an f32 rgb color for each of the 2048x2048 pixels
|x,y| {
(
x as f32 / 2048.0, // red
y as f32 / 2048.0, // green
1.0 - (y as f32 / 2048.0), // blue
1.0 // alpha
)
}
).unwrap();
} ```
See the the examples folder for more examples.
Or read the guide.
Using Rust bindings to a C++ library unfortunately requires compiling one or more 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.
exrs aims to provide a safe and convenient
interface to the OpenEXR file format. It is designed
to minimize the possibility of invalid files and runtime errors.
It contains a full-fledged image data structure that can contain any exr image,
but also grants access a low level block interface.
This library does not try to be a general purpose image file or image processing library. Therefore, color conversion, beautiful 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, instead, it is only aimed for correct output.
This library uses no unsafe code. In fact, this crate is annotated with #[forbid(unsafe_code)].
Some dependencies use unsafe code, though this is minimized by selecting dependencies carefully.
All information from a file is handled with caution. Allocations have a safe maximum size that will not be exceeded at once, to reduce memory exhaustion attacks.
To run all fast tests on your native system, use cargo test.
To start fuzzing on your native system indefinitely,
use cargo test --package exr --test fuzz fuzz -- --exact --ignored.
To run all fast tests on an emulated system, use one of the following commands.
Each command requires a running docker instance,
and cross-rs to be installed on your machine (cargo install cross-rs).
- Mips (Big Endian) cross test --target mips-unknown-linux-gnu --verbose
To benchmark the library, simply run cargo bench.
This library is modeled after the
official OpenEXRFileLayout.pdf
document. Unspecified behavior is concluded from the C++ library.