| 1 |
[](https://crates.io/crates/exr) |
| 2 |
[](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) |
| 3 |
[](https://docs.rs/exr) |
| 4 |
[](https://github.com/johannesvollmer/exrs/actions?query=branch%3Amaster) |
| 5 |
[](https://crates.io/crates/exr) |
| 6 |
[](https://tokei.rs) |
| 7 |
|
| 8 |
# EXRS |
| 9 |
|
| 10 |
This library is a 100% Rust and 100% safe code library for |
| 11 |
reading and writing OpenEXR images. |
| 12 |
|
| 13 |
[OpenEXR](http://www.openexr.com/) |
| 14 |
is the de-facto standard image format in animation, VFX, and |
| 15 |
other computer graphics pipelines, for it can represent an immense variety of pixel data with lossless compression. |
| 16 |
|
| 17 |
Features include: |
| 18 |
- any number of layers placed anywhere in 2d space, like in Photoshop |
| 19 |
- any set of channels in an image (rgb, xyz, lab, depth, motion, mask, anything, ...) |
| 20 |
- three types of high dynamic range values (16bit float, 32bit float, 32bit unsigned integer) per channel |
| 21 |
- uncompressed pixel data for fast file access |
| 22 |
- lossless compression for any image type |
| 23 |
- lossy compression for non-deep image types to produce very small files |
| 24 |
- load specific sections of an image without processing the whole file |
| 25 |
- compress and decompress image pixels on multiple threads in parallel |
| 26 |
- add arbitrary meta data to any image, including custom byte data, with full backwards compatibility |
| 27 |
- any number of samples per pixel ("deep data") (not yet supported) |
| 28 |
|
| 29 |
### Current Status |
| 30 |
|
| 31 |
This library has matured quite a bit, but should still be considered incomplete. |
| 32 |
For example, deep data and DWA compression algorithms are not supported yet. |
| 33 |
|
| 34 |
If you encounter an exr file that cannot be opened by this crate but should be, |
| 35 |
please leave an issue on this repository, containing the image file. |
| 36 |
|
| 37 |
The focus is set on supporting all feature and correctness; |
| 38 |
some performance optimizations are to be done. |
| 39 |
|
| 40 |
__What we can do:__ |
| 41 |
|
| 42 |
- Supported OpenEXR Features |
| 43 |
- [x] custom attributes |
| 44 |
- [x] multi-part images (multiple layers, like Photoshop) |
| 45 |
- [x] multi-resolution images (mip maps, rip maps) |
| 46 |
- [x] access meta data and raw pixel blocks independently |
| 47 |
- [x] automatically crop away transparent pixels of an image (opt-in) |
| 48 |
- [ ] channel subsampling |
| 49 |
- [ ] deep data |
| 50 |
- [x] compression methods |
| 51 |
- [x] uncompressed |
| 52 |
- [x] zip line (lossless) |
| 53 |
- [x] zip block (lossless) |
| 54 |
- [x] rle (lossless) |
| 55 |
- [x] piz (lossless) (huge thanks to @dgsantana) |
| 56 |
- [x] pxr24 (lossless for f16 and u32) |
| 57 |
- [x] little-endian architectures |
| 58 |
- [ ] big-endian architectures __(help wanted)__ |
| 59 |
- [x] b44, b44a (huge thanks to @narann) |
| 60 |
- [ ] dwaa, dwab __(help wanted)__ |
| 61 |
|
| 62 |
- Nice Things |
| 63 |
- [x] no unsafe code, no undefined behaviour |
| 64 |
- [x] no CMake required or environment variables required |
| 65 |
- [x] re-imagined exr api with low barrier of entry |
| 66 |
(see `read_rgba_file`, `write_rgba_file`, `read_all_data_from_file`), |
| 67 |
plus embracing common high-level Rust abstractions |
| 68 |
- [x] a full-fledged image data structure that can contain any exr image, |
| 69 |
can open any image with a single function call (`read_all_data_from_file`) |
| 70 |
without knowing anything about the file in advance |
| 71 |
- [x] compress and decompress image sections either |
| 72 |
in parallel or with low memory overhead |
| 73 |
- [x] read and write progress callback |
| 74 |
- [x] write blocks streams, one after another |
| 75 |
- [x] memory mapping automatically supported |
| 76 |
by using the generic `std::io::Read` and `std::io::Write` traits |
| 77 |
|
| 78 |
|
| 79 |
<!-- detailed internal feature checklist: |
| 80 |
- [x] Inspecting Metadata |
| 81 |
- [x] Singlepart |
| 82 |
- [x] Tiles |
| 83 |
- [x] Scan lines |
| 84 |
- [x] Deep Tiles |
| 85 |
- [ ] Deep Scan Lines _(coded, but untested)_ |
| 86 |
- [x] Multipart |
| 87 |
- [x] Tiles |
| 88 |
- [x] Scan lines |
| 89 |
- [ ] Deep Tiles _(coded, but untested)_ |
| 90 |
- [x] Deep Scan Lines |
| 91 |
- [x] Multi Resolution |
| 92 |
- [x] Singular Resolution |
| 93 |
- [x] MipMaps |
| 94 |
- [x] RipMaps _(coded, but untested)_ |
| 95 |
- [x] Non-Standard Attributes |
| 96 |
- [x] Reading those with known names and unknown names |
| 97 |
- [x] Reading those with known types |
| 98 |
- [x] Reading those with unknown types into a plain byte buffer |
| 99 |
- [x] Nice API for preview attribute extraction |
| 100 |
|
| 101 |
- [ ] Decompressing Pixel Data |
| 102 |
- [x] Any LineOrder |
| 103 |
- [x] Any Pixel Type (`f16`, `f32`, `u32`) |
| 104 |
- [x] Multipart |
| 105 |
- [ ] Deep Data |
| 106 |
- [x] Rip/Mip Maps _(coded, but untested)_ |
| 107 |
- [ ] Nice API for RGBA conversion and displaying other color spaces? |
| 108 |
- [ ] Compression Methods |
| 109 |
- [x] Uncompressed |
| 110 |
- [x] ZIPS |
| 111 |
- [x] ZIP |
| 112 |
- [x] RLE |
| 113 |
- [x] PIZ |
| 114 |
- [x] RXR24 |
| 115 |
- [x] B44, B44A |
| 116 |
- [ ] DWAA, DWAB |
| 117 |
|
| 118 |
- [ ] Writing images |
| 119 |
- [x] Scan Lines |
| 120 |
- [x] Tiles |
| 121 |
- [x] Multipart |
| 122 |
- [ ] Deep Data |
| 123 |
- [x] User supplied line order |
| 124 |
- [x] Rip/Mip Maps _(coded, but untested)_ |
| 125 |
- [x] 100% correct meta data |
| 126 |
- [x] Compression Methods |
| 127 |
- [x] Uncompressed |
| 128 |
- [x] ZIPS (lossless) |
| 129 |
- [x] ZIP (lossless) |
| 130 |
- [x] RLE (lossless) |
| 131 |
- [x] PIZ (lossless) |
| 132 |
- [x] PXR24 (lossless for f16 and u32) |
| 133 |
- [x] B44, B44A |
| 134 |
- [ ] DWAA, DWAB |
| 135 |
|
| 136 |
- [x] De/compressing multiple blocks in parallel |
| 137 |
|
| 138 |
- [ ] Profiling and real optimization |
| 139 |
- [x] Memory Mapping |
| 140 |
|
| 141 |
- [x] IO Progress callback? |
| 142 |
- [ ] SIMD |
| 143 |
- [x] Detailed file validation |
| 144 |
- [x] Channels with an x or y sampling rate other than 1 are allowed only in flat, scan-line based images. |
| 145 |
- [x] If the headers include timeCode and chromaticities attributes, then the values of those attributes must also be the same for all parts of a file |
| 146 |
- [x] Scan-line based images cannot be multi-resolution images. (encoded in type system) |
| 147 |
- [x] Scan-line based images cannot have unspecified line order apparently? |
| 148 |
- [x] layer name is required for multipart images |
| 149 |
- [x] Enforce minimum length of 1 for arrays |
| 150 |
- [x] [Validate data_window matches data size when writing images] is not required because one is inferred from the other |
| 151 |
- [x] Channel names and layer names must be unique |
| 152 |
|
| 153 |
- [x] Explore different APIs |
| 154 |
- [x] Let user decide how to store data |
| 155 |
- [x] Loading Metadata and specific tiles or blocks separately |
| 156 |
--> |
| 157 |
|
| 158 |
|
| 159 |
### Usage |
| 160 |
|
| 161 |
> [!TIP] |
| 162 |
> 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. |
| 163 |
|
| 164 |
Add this to your `Cargo.toml`: |
| 165 |
```toml |
| 166 |
[dependencies] |
| 167 |
exr = "1.74.0" |
| 168 |
|
| 169 |
# also, optionally add this to your crate for smaller binary size |
| 170 |
# and better runtime performance |
| 171 |
[profile.release] |
| 172 |
lto = true |
| 173 |
``` |
| 174 |
|
| 175 |
The master branch of this repository always matches the `crates.io` version, |
| 176 |
so you could also link the github repository master branch. |
| 177 |
|
| 178 |
### Example |
| 179 |
|
| 180 |
Example: [generate an rgb exr file](https://github.com/johannesvollmer/exrs/blob/master/examples/0_write_rgba.rs). |
| 181 |
|
| 182 |
```rust |
| 183 |
extern crate exr; |
| 184 |
|
| 185 |
/// To write your image data, you need to specify how to retrieve a single pixel from it. |
| 186 |
/// The closure may capture variables or generate data on the fly. |
| 187 |
fn main() { |
| 188 |
use exr::prelude::*; |
| 189 |
|
| 190 |
// write a file, with 32-bit float precision per channel |
| 191 |
write_rgba_file( |
| 192 |
|
| 193 |
// this accepts paths or &str |
| 194 |
"minimal_rgba.exr", |
| 195 |
|
| 196 |
// image resolution is 2k |
| 197 |
2048, 2048, |
| 198 |
|
| 199 |
// generate (or lookup in your own image) |
| 200 |
// an f32 rgb color for each of the 2048x2048 pixels |
| 201 |
// (you could also create f16 values here to save disk space) |
| 202 |
|x,y| { |
| 203 |
( |
| 204 |
x as f32 / 2048.0, // red |
| 205 |
y as f32 / 2048.0, // green |
| 206 |
1.0 - (y as f32 / 2048.0), // blue |
| 207 |
1.0 // alpha |
| 208 |
) |
| 209 |
} |
| 210 |
|
| 211 |
).unwrap(); |
| 212 |
} |
| 213 |
``` |
| 214 |
|
| 215 |
See the [the examples folder](https://github.com/johannesvollmer/exrs/tree/master/examples) for more examples. |
| 216 |
|
| 217 |
Or read [the guide](https://github.com/johannesvollmer/exrs/tree/master/GUIDE.md). |
| 218 |
|
| 219 |
|
| 220 |
### Goals |
| 221 |
|
| 222 |
`exrs` aims to provide a safe and convenient |
| 223 |
interface to the OpenEXR file format. It is designed |
| 224 |
to minimize the possibility of invalid files and runtime errors. |
| 225 |
It contains a full-fledged image data structure that can contain any exr image, |
| 226 |
but also grants access a low level block interface. |
| 227 |
|
| 228 |
This library does not try to be a general purpose image file or image processing library. |
| 229 |
Therefore, color conversion, beautiful subsampling, and mip map generation are left to other crates for now. |
| 230 |
As the original OpenEXR implementation supports those operations, this library may choose to support them later. |
| 231 |
Furthermore, this implementation does not try to produce byte-exact file output |
| 232 |
matching the original implementation, instead, it is only aimed for correct output. |
| 233 |
|
| 234 |
#### Safety |
| 235 |
|
| 236 |
This library uses no unsafe code. In fact, this crate is annotated with `#[forbid(unsafe_code)]`. |
| 237 |
Some dependencies use unsafe code, though this is minimized by selecting dependencies carefully. |
| 238 |
|
| 239 |
All information from a file is handled with caution. |
| 240 |
Allocations have a safe maximum size that will not be exceeded at once, |
| 241 |
to reduce memory exhaustion attacks. |
| 242 |
|
| 243 |
### What I am proud of |
| 244 |
|
| 245 |
- Flexible API (choose how to store your data instead of receiving an allocated image) |
| 246 |
- Safe API (almost impossible to accidentally write invalid files) |
| 247 |
- "if it compiles, it runs" methodology |
| 248 |
- [Awesome Contributors!](CONTRIBUTORS.md) |
| 249 |
|
| 250 |
### Wasm |
| 251 |
This crate supports the `wasm-unknown-unknown` target. |
| 252 |
Until WASM has threads, decoding and encoding will be slower for compressed files. |
| 253 |
Of course, you will need to read from byte buffers instead of file handles. |
| 254 |
|
| 255 |
### Motivation |
| 256 |
|
| 257 |
This library does not support the toxic mindset of |
| 258 |
rewriting existing C++ code in Rust just for the sake of switching the language. |
| 259 |
The OpenEXR image format is defined by a proven |
| 260 |
and battle-tested reference implementation. |
| 261 |
|
| 262 |
However, as an alternative to the official reference implementation, |
| 263 |
this library has the opportunity to explore radically different |
| 264 |
designs, no matter what language it is written in. Neat! |
| 265 |
|
| 266 |
Also, I really wanted to have a library |
| 267 |
which had an 'X' in its name in my git repositories. |
| 268 |
|
| 269 |
Keep in mind that there are official Rust bindings to the C++ reference implementation, |
| 270 |
and they offer several advantages over this Rust implementation: |
| 271 |
- they support all the features and can read any file, no surprises |
| 272 |
- they are constantly driven by industry giants, |
| 273 |
so they have the higher probability of still being maintained in a decade |
| 274 |
- they are battle tested and relied upon by a lot of existing projects |
| 275 |
|
| 276 |
### Specification |
| 277 |
|
| 278 |
This library is modeled after the |
| 279 |
official [`OpenEXRFileLayout.pdf`](http://www.openexr.com/documentation.html) |
| 280 |
document. Unspecified behavior is concluded from the C++ library. |
| 281 |
|
| 282 |
### Roadmap |
| 283 |
1. Support all compression formats (missing format: DWAA/DWAB) |
| 284 |
1. Support subsampling |
| 285 |
1. Support Deep Data |
| 286 |
1. Automatic conversion between color spaces |
| 287 |
1. Profiling and other optimization |
| 288 |
1. Tooling (Image Viewer App, Metadata Extraction Tool, ...) |
| 289 |
|
| 290 |
## Contributing |
| 291 |
This project has awesome contributors and is welcoming for |
| 292 |
contributions on [Github](https://github.com/johannesvollmer/exrs). |
| 293 |
|
| 294 |
### Running Tests |
| 295 |
|
| 296 |
To run all fast tests on your native system, use `cargo test`. |
| 297 |
|
| 298 |
To start fuzzing on your native system indefinitely, |
| 299 |
use `cargo test --package exr --test fuzz fuzz -- --exact --ignored`. |
| 300 |
|
| 301 |
To run all fast tests on an emulated system, use one of the following commands. |
| 302 |
Each command requires a running `docker` instance, |
| 303 |
and `cross-rs` to be installed on your machine (`cargo install cross`). |
| 304 |
- Powerpc (Big Endian) `cross test --target powerpc-unknown-linux-gnu --verbose` |
| 305 |
|
| 306 |
You may also need to install the toolchain beforehand, using |
| 307 |
`rustup toolchain add stable-x86_64-unknown-linux-gnu --profile minimal --force-non-host` |
| 308 |
and `rustup target add powerpc-unknown-linux-gnu`. |
| 309 |
|
| 310 |
To benchmark the library, simply run `cargo bench`. |