Debian Codegraph @

.cargo/vendor/exr/README.md

raw
1 [![Rust Crate](https://img.shields.io/crates/v/exr.svg)](https://crates.io/crates/exr)
2 [![Crates.io MSRV](https://img.shields.io/crates/msrv/exr?label=minimum%20rust%20version)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
3 [![Rust Docs](https://docs.rs/exr/badge.svg)](https://docs.rs/exr)
4 [![Wasm Ready](https://img.shields.io/badge/wasm-supported-%236d0)](https://github.com/johannesvollmer/exrs/actions?query=branch%3Amaster)
5 [![downloads](https://img.shields.io/crates/d/exr)](https://crates.io/crates/exr)
6 [![Lines of Code](https://tokei.rs/b1/github/johannesvollmer/exrs?category=code)](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`.