[](https://crates.io/crates/exr)
[](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
[](https://docs.rs/exr)
[](https://www.npmjs.com/package/exrs)
[](https://crates.io/crates/exr)
[](https://tokei.rs)
# EXRS
This library is a 100% Rust and 100% safe code library for
reading and writing OpenEXR images.
[OpenEXR](http://www.openexr.com/)
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)
### Current Status
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
- [x] custom attributes
- [x] multi-part images (multiple layers, like Photoshop)
- [x] multi-resolution images (mip maps, rip maps)
- [x] access meta data and raw pixel blocks independently
- [x] automatically crop away transparent pixels of an image (opt-in)
- [ ] channel subsampling
- [ ] deep data
- [x] compression methods
- [x] uncompressed
- [x] zip line (lossless)
- [x] zip block (lossless)
- [x] rle (lossless)
- [x] piz (lossless) (huge thanks to @dgsantana)
- [x] pxr24 (lossless for f16 and u32)
- [x] b44, b44a (huge thanks to @narann)
- [~] dwaa, dwab
- [X] decoding (hunge thanks to @zinezockt)
- [ ] encoding __(help wanted)__
- Nice Things
- [x] no unsafe code, no undefined behaviour
- [x] no CMake required or environment variables required
- [x] re-imagined exr api with low barrier of entry
(see `read_rgba_file`, `write_rgba_file`, `read_all_data_from_file`),
plus embracing common high-level Rust abstractions
- [x] a full-fledged image data structure that can contain any exr image,
can open any image with a single function call (`read_all_data_from_file`)
without knowing anything about the file in advance
- [x] compress and decompress image sections either
in parallel or with low memory overhead
- [x] read and write progress callback
- [x] write blocks streams, one after another
- [x] memory mapping automatically supported
by using the generic `std::io::Read` and `std::io::Write` traits
### Usage
> [!TIP]
> If you want to use the newest version of `exrs` with an older Rust version, you can still do that, by forcing Rust to use an older version of the `half` crate via `cargo update -p half --precise 2.2.1`, or downgrade all dependencies via `cargo +nightly -Zminimal-versions generate-lockfile`. Version `half 2.3.0` and higher have an MSRV above 1.61.
Add this to your `Cargo.toml`:
```toml
[dependencies]
exr = "1.74.1"
# 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 always matches the `crates.io` version,
so you could also link the github repository master branch.
### Example
Example: [generate an rgb exr file](https://github.com/johannesvollmer/exrs/blob/master/examples/0_write_rgba.rs).
```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
// (you could also create f16 values here to save disk space)
|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](https://github.com/johannesvollmer/exrs/tree/master/examples) for more examples.
Or read [the guide](https://github.com/johannesvollmer/exrs/tree/master/GUIDE.md).
### Goals
`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.
#### Safety
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.
### What I am proud of
- Flexible API (choose how to store your data instead of receiving an allocated image)
- Safe API (almost impossible to accidentally write invalid files)
- "if it compiles, it runs" methodology
- [Awesome Contributors!](CONTRIBUTORS.md)
### Wasm
This crate supports the `wasm32-unknown-unknown` target for use in browsers and Node.js.
#### npm Package
For JavaScript/TypeScript projects, install the [`exrs`](https://www.npmjs.com/package/exrs) package from npm:
```bash
npm install exrs
```
```javascript
import { init, encodeExr, decodeExr } from 'exrs';
await init();
const bytes = encodeExr({
width: 1920,
height: 1080,
layers: [{ name: 'rgba', channels: 'rgba', data: rgbaPixels }]
});
```
See the [exrs-wasm documentation](exrs-wasm/js/README.md) for the full API reference.
#### Notes
- Until WASM has threads, decoding and encoding will be slower for compressed files
- Read from byte buffers (`Uint8Array`) instead of file handles
### Motivation
This library does not support the toxic mindset of
rewriting existing C++ code in Rust just for the sake of switching the language.
The OpenEXR image format is defined by a proven
and battle-tested reference implementation.
However, as an alternative to the official reference implementation,
this library has the opportunity to explore radically different
designs, no matter what language it is written in. Neat!
Also, I really wanted to have a library
which had an 'X' in its name in my git repositories.
Keep in mind that there are official Rust bindings to the C++ reference implementation,
and they offer several advantages over this Rust implementation:
- they support all the features and can read any file, no surprises
- they are constantly driven by industry giants,
so they have the higher probability of still being maintained in a decade
- they are battle tested and relied upon by a lot of existing projects
### Specification
This library is modeled after the
official [`OpenEXR Documentation`](https://openexr.com/en/latest/)
document. Saved older PDFs in /specification. Unspecified behavior is concluded from the C++ library.
### Roadmap
1. Support all compression formats
1. Support subsampling
1. Support Deep Data
1. Automatic conversion between color spaces
1. Profiling and other optimization
1. Tooling (Image Viewer App, Metadata Extraction Tool, ...)
## Contributing
This project has awesome contributors and is welcoming for
contributions on [Github](https://github.com/johannesvollmer/exrs).
### Code Formatting
This repository uses Rustfmt's standard style. Continuous Integration checks formatting on every pull request and will fail if files are not properly formatted.
How to format locally:
- Format the entire workspace in-place:
- `cargo +nightly fmt --all`
- Check formatting without changing files (what CI runs):
- `cargo +nightly fmt --all -- --check`
If `cargo +nightly fmt` is not found, install the Rustfmt component via Rustup:
- Install Rustfmt for your current toolchain:
- `rustup component add rustfmt`
- If needed, ensure the stable toolchain is installed, then add Rustfmt explicitly:
- `rustup toolchain install nightly`
- `rustup component add --toolchain nightly rustfmt`
You may also configure your editor to run `cargo +nightly fmt` on save.
### Running Tests
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`).
- Powerpc (Big Endian) `cross test --target powerpc-unknown-linux-gnu --verbose`
You may also need to install the toolchain beforehand, using
`rustup toolchain add stable-x86_64-unknown-linux-gnu --profile minimal --force-non-host`
and `rustup target add powerpc-unknown-linux-gnu`.
To benchmark the library, simply run `cargo bench`.
#### SIMD tests (Intel SDE)
The DWA inverse-DCT has SIMD kernels (AVX2 and SSE2) that are selected at
runtime via [`pulp`](https://crates.io/crates/pulp), mirroring OpenEXR's own
cpuid dispatch. Each tier has its own feature-gated integration test:
- `tests/avx2.rs` — requires the `avx2-tests` feature, exercises the AVX2 kernel
- `tests/sse2.rs` — requires the `sse2-tests` feature, exercises the SSE2 kernel
These tests are **opt-in** and are excluded from the normal `cargo test` run. A
test only passes if the requested tier is actually available on the CPU it runs
on, so the AVX2 test needs an AVX2-capable CPU and the SSE2 test additionally
asserts that AVX2 is *not* present (so it verifies the fallback path).
Because most machines only expose their native tier, we run these tests under
[Intel SDE](https://www.intel.com/content/www/us/en/developer/articles/tool/software-development-emulator.html)
(Software Development Emulator), which emulates a chosen microarchitecture. This
is exactly what the `SIMD tests` CI workflow does. To reproduce it locally:
1. **Install Intel SDE.** Download it from the link above and put the `sde64`
binary on your `PATH` (or note its full path). SDE runs on x86-64 Linux,
macOS, and Windows.
2. **Build the test binary without running it,** then locate the executable:
```bash
cargo test --test avx2 --features avx2-tests --no-run
cargo test --test sse2 --features sse2-tests --no-run
```
Cargo prints the path to the compiled test binary (under `target/debug/deps/`).
3. **Run that binary under SDE,** selecting a chip that exposes the target tier:
```bash
sde64 -hsw -- target/debug/deps/avx2-<hash> --nocapture
sde64 -mrm -- target/debug/deps/sse2-<hash> --nocapture
```
> [!IMPORTANT]
> Do **not** set a global `RUSTFLAGS="-C target-feature=+avx2"` (or similar) to
> run these tests. This is a runtime-dispatched library: forcing a target
> feature globally would bake AVX2 into otherwise-portable code, break the
> plain x86-64 baseline, and make the fallback tests meaningless. The kernels
> already carry their own per-function `#[target_feature]`, so no global flag is
> needed — SDE alone controls which tier the runtime dispatch selects.
If your own CPU already exposes the required tier, you can skip SDE and run the
test directly (e.g. `cargo test --test sse2 --features sse2-tests` on any
x86-64 machine, since SSE2 is part of the baseline).