diff options
Diffstat (limited to 'vendor/exr/README.md')
| -rw-r--r-- | vendor/exr/README.md | 303 |
1 files changed, 0 insertions, 303 deletions
diff --git a/vendor/exr/README.md b/vendor/exr/README.md deleted file mode 100644 index 04e5419..0000000 --- a/vendor/exr/README.md +++ /dev/null @@ -1,303 +0,0 @@ -[](https://docs.rs/exr) -[](https://crates.io/crates/exr) -[](https://blog.rust-lang.org/2022/02/24/Rust-1.59.0.html) -[](https://github.com/johannesvollmer/exrs/actions?query=branch%3Amaster) -[](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] little-endian architectures - - [ ] big-endian architectures __(help wanted)__ - - [x] b44, b44a (huge thanks to @narann) - - [ ] dwaa, dwab __(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] decompress 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 - - -<!-- detailed internal feature checklist: -- [x] Inspecting Metadata - - [x] Singlepart - - [x] Tiles - - [x] Scan lines - - [x] Deep Tiles - - [ ] Deep Scan Lines _(coded, but untested)_ - - [x] Multipart - - [x] Tiles - - [x] Scan lines - - [ ] Deep Tiles _(coded, but untested)_ - - [x] Deep Scan Lines - - [x] Multi Resolution - - [x] Singular Resolution - - [x] MipMaps - - [x] RipMaps _(coded, but untested)_ - - [x] Non-Standard Attributes - - [x] Reading those with known names and unknown names - - [x] Reading those with known types - - [x] Reading those with unknown types into a plain byte buffer - - [x] Nice API for preview attribute extraction - -- [ ] Decompressing Pixel Data - - [x] Any LineOrder - - [x] Any Pixel Type (`f16`, `f32`, `u32`) - - [x] Multipart - - [ ] Deep Data - - [x] Rip/Mip Maps _(coded, but untested)_ - - [ ] Nice API for RGBA conversion and displaying other color spaces? - - [ ] Compression Methods - - [x] Uncompressed - - [x] ZIPS - - [x] ZIP - - [x] RLE - - [x] PIZ - - [x] RXR24 - - [x] B44, B44A - - [ ] DWAA, DWAB - -- [ ] Writing images - - [x] Scan Lines - - [x] Tiles - - [x] Multipart - - [ ] Deep Data - - [x] User supplied line order - - [x] Rip/Mip Maps _(coded, but untested)_ - - [x] 100% correct meta data - - [x] Compression Methods - - [x] Uncompressed - - [x] ZIPS (lossless) - - [x] ZIP (lossless) - - [x] RLE (lossless) - - [x] PIZ (lossless) - - [x] PXR24 (lossless for f16 and u32) - - [x] B44, B44A - - [ ] DWAA, DWAB - -- [x] De/compressing multiple blocks in parallel - -- [ ] Profiling and real optimization - - [x] Memory Mapping - -- [x] IO Progress callback? -- [ ] SIMD -- [x] Detailed file validation - - [x] Channels with an x or y sampling rate other than 1 are allowed only in flat, scan-line based images. - - [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 - - [x] Scan-line based images cannot be multi-resolution images. (encoded in type system) - - [x] Scan-line based images cannot have unspecified line order apparently? - - [x] layer name is required for multipart images - - [x] Enforce minimum length of 1 for arrays - - [x] [Validate data_window matches data size when writing images] is not required because one is inferred from the other - - [x] Channel names and layer names must be unique - -- [x] Explore different APIs - - [x] Let user decide how to store data - - [x] Loading Metadata and specific tiles or blocks separately ---> - - -### Usage - -Add this to your `Cargo.toml`: -```toml -[dependencies] -exr = "1.71.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 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 `wasm-unknown-unknown` target. -Until WASM has threads, decoding and encoding will be slower for compressed files. -Of course, you will need to read from byte buffers 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 [`OpenEXRFileLayout.pdf`](http://www.openexr.com/documentation.html) -document. Unspecified behavior is concluded from the C++ library. - -### Roadmap -1. Support all compression formats (missing format: DWAA/DWAB) -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). - -### 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-rs`). -- Mips (Big Endian) `cross test --target mips-unknown-linux-gnu --verbose` - -To benchmark the library, simply run `cargo bench`.
\ No newline at end of file |