Debian Codegraph @

.cargo/vendor/exr/GUIDE.md

raw
1 # Guide
2
3 This document talks about the capabilities of OpenEXR and outlines the design of this library.
4 In addition to reading this guide, you should also have a look at the examples.
5
6 Contents:
7 - Wording
8 - Why this is complicated
9 - One-liners for reading and writing simple images
10 - Reading a complex image
11 - The Image data structure
12 - Writing a complex image
13
14 ## Wording
15 Some names in this library differ from the classic OpenEXR conventions.
16 For example, an OpenEXR "multipart" is called a file with multiple "layers" in this library.
17 The old OpenEXR "layers" are called "grouped channels" instead.
18
19 - `Image` Contains everything that an `.exr` file can contain. Includes metadata and multiple layers.
20 - `Layer` A grid of pixels that can be placed anywhere on the two-dimensional canvas
21 - `Channel` All samples of a single color component, such as red or blue. Also contains metadata.
22 - `Pixel` The color at an exact location in the image. Contains one sample for each channel.
23 - `Sample` The value (either f16, f32 or u32) of one channel at an exact location in the image.
24 Usually a simple number, such as the red value of the bottom left pixel.
25 - `Grouped Channels` Multiple channels may be grouped my prepending the same prefix to the name.
26 This behaviour is opt-in; it has to be enabled explicitly:
27 By default, channels are stored in a plain list, and channel names are unmodified.
28 - `pedantic: bool` When reading, pedantic being false will generally ignore
29 invalid information instead of aborting the reading process where possible.
30 When writing, pedantic being false will generally skip some expensive image validation checks.
31
32 ## OpenEXR | Complexity
33 This image format supports some features that you won't find in other image formats.
34 As a consequence, an exr file cannot necessarily be converted to other formats,
35 even when the loss of precision is acceptable. Furthermore,
36 an arbitrary exr image may include possibly unwanted data.
37 Supporting deep data, for example, might be unnecessary for some applications.
38
39 To read an image, `exrs` must know which parts of an image you want to end up with,
40 and which parts of the file should be skipped. That's why you need
41 a little more code to read an exr file, compared to simpler file formats.
42
43 ### Possibly Undesired Features
44 - Arbitrary Channels:
45 `CMYK`, `YCbCr`, `LAB`, `XYZ` channels might not be interesting for you,
46 maybe you only want to accept `RGBA` images
47 - Deep Data: Multiple colors per pixel might not be interesting for you
48 - Resolution Levels: Mip Maps or Rip Maps might be unnecessary and can be skipped,
49 loading only the full resolution image instead
50 <!-- - TODO: Meta Data: Skip reading meta data -->
51
52 # Simple Reading and Writing
53 There are a few very simple functions for the most common use cases.
54 For decoding an image file, use one of these functions
55 from the `exr::image::read` module (data structure complexity increasing):
56
57 1. `read_first_rgba_layer_from_file(path, your_constructor, your_pixel_setter)`
58 1. `read_all_rgba_layers_from_file(path, your_constructor, your_pixel_setter)`
59 1. `read_first_flat_layer_from_file(path)`
60 1. `read_all_flat_layers_from_file(path)`
61 1. `read_all_data_from_file(path)`
62
63 If you don't have a file path, or want to load any other channels than `rgba`,
64 then these simple functions will not suffice. The more complex approaches are
65 described later in this document.
66
67 For encoding an image file, use one of these functions in the `exr::image::write` module:
68
69 1. `write_rgba_file(path, width, height, |x,y| my_image.get_rgb_at(x,y))`
70 1. `write_rgb_file(path, width, height, |x,y| my_image.get_rgba_at(x,y))`
71
72 These functions are only syntactic sugar. If you want to customize the data type,
73 the compression method, or write multiple layers, these simple functions will not suffice.
74 Again, the more complex approaches are described in the following paragraph.
75
76 # Reading an Image
77
78 Reading an image involves three steps:
79 1. Specify how to load an image by constructing an image reader.
80 1. Start with `read()`
81 1. Chain method calls to customize the reader
82 1. Call `from_file(path)`, `from_buffered(bytes)`, or `from_unbuffered(bytes)`
83 on the reader to actually load an image
84 1. Process the resulting image data structure or the error in your application
85
86 The type of the resulting image depends on the reader you constructed. For example,
87 if you configure the reader to load mip map levels, the resulting image type
88 will contain an additional vector with the mip map levels.
89
90 ### Deep Data
91 The first choice to be made is whether you want to load deep data or not.
92 Deep data is where multiple colors are stored in one pixel at the same location.
93 Currently, deep data is not supported yet, so we always call `no_deep_data()`.
94
95 ```rust
96 fn main(){
97 use exr::prelude::*;
98 let reader = read().no_deep_data();
99 }
100 ```
101
102 ### Resolution Levels
103 Decide whether you want to load the largest resolution level, or all Mip Maps from the file.
104 Loading only the largest level actually skips portions of the image, which should be faster.
105
106 Calling `largest_resolution_level()` will result in a single image (`FlatSamples`),
107 whereas calling `all_resolution_levels()` will result in multiple levels `Levels<FlatSamples>`.
108
109 ```rust
110 fn main(){
111 use exr::prelude::*;
112 let reader = read().no_deep_data().largest_resolution_level();
113 let reader = read().no_deep_data().all_resolution_levels();
114 }
115 ```
116
117 ### Channels
118 Decide whether you want to load all channels in a dynamic list, or only load a fixed set of channels.
119
120 Calling `all_channels()` will result in a `Vec<Channel<_>>`.
121
122 ```rust
123 fn main(){
124 use exr::prelude::*;
125 let reader = read().no_deep_data().largest_resolution_level().all_channels();
126 }
127 ```
128
129 The alternative, `specific_channels()` allows you to exactly specify which channels should be loaded.
130 The usage follows the same builder pattern as the rest of the library.
131
132 First, call `specific_channels()`. Then, for each channel you desire,
133 call either `required(channel_name)` or `optional(channel_name, default_value)`.
134 At last, call `collect_pixels()` to define how the pixels should be stored in an image.
135 This additional mechanism will not simply store the pixels in a `Vec<Pixel>`, but instead
136 works with a closure. This allows you to instantiate your own existing image type with
137 the pixel data from the file.
138
139 ```rust
140 fn main(){
141 use exr::prelude::*;
142
143 let reader = read()
144 .no_deep_data().largest_resolution_level()
145
146 // load LAB channels, with chroma being optional
147 .specific_channels().required("L").optional("A", 0.0).optional("B", 0.0).collect_pixels(
148
149 // create our image based on the resolution of the file
150 |resolution: Vec2<usize>, (l,a,b): &(ChannelDescription, Option<ChannelDescription>, Option<ChannelDescription>)|{
151 if a.is_some() && b.is_some() { MyImage::new_lab(resolution) }
152 else { MyImage::new_luma(resolution) }
153 },
154
155 // insert a single pixel into out image
156 |my_image: &mut MyImage, position: Vec<usize>, (l,a,b): (f32, f16, f16)|{
157 my_image.set_pixel_at(position.x(), position.y(), (l, a, b));
158 }
159
160 );
161 }
162 ```
163
164 The first closure is the constructor of your image, and the second closure is the setter for a single pixel in your image.
165 The tuple containing the channel descriptions and the pixel tuple depend on the channels that you defined earlier.
166 In this example, as we defined to load L,A and B, each pixel has three values. The arguments of the closure
167 can usually be inferred, so you don't need to declare the type of your image and the `Vec2<usize>`.
168 However, the type of the pixel needs to be defined. In this example, we define the pixel type to be `(f32, f16, f16)`.
169 All luma values will be converted to `f32` and all chroma values will be converted to `f16`.
170 The pixel type can be any combination of `f16`, `f32`, `u32` or `Sample` values, in a tuple with as many entries as there are channels.
171 The `Sample` type is a dynamic enum over the other types, which allows you to keep the original sample type of each image.
172
173 _Note: Currently, up to 32 channels are supported, which is an implementation problem.
174 Open an issue if this is not enough for your use case. Alternatively,
175 you can always use `all_channels()`, which has no limitations._
176
177 ####RGBA Channels
178 For rgba images, there is a predefined simpler alternative to `specific_channels` called `rgb_channels` and `rgba_channels`.
179 It works just the same as `specific_channels` and , but you don't need to specify the names of the channels explicitly.
180
181 ```rust
182 fn main(){
183 use exr::prelude::*;
184
185 let reader = read()
186 .no_deep_data().largest_resolution_level()
187
188 // load rgba channels
189 // with alpha being optional, defaulting to 1.0
190 .rgba_channels(
191
192 // create our image based on the resolution of the file
193 |resolution, &(r,g,b,a)|{
194 if a.is_some() { MyImage::new_with_alpha(resolution.x(), resolution.y()) }
195 else { MyImage::new_without_alpha(resolution.x(), resolution.y()) }
196 },
197
198 // insert a single pixel into out image
199 |my_image, position, (r,g,b,a): (f32, f32, f32, f16)|{
200 my_image.set_pixel_at(position.x(), position.y(), (r,g,b,a));
201 }
202
203 );
204 }
205 ```
206
207
208 ### Layers
209 Use `all_layers()` to load a `Vec<Layer<_>>` or use `first_valid_layer()` to only load
210 the first `Layer<_>` that matches the previously defined requirements
211 (for example, the first layer without deep data and cmyk channels).
212
213
214 ```rust
215 fn main() {
216 use exr::prelude::*;
217
218 let image = read()
219 .no_deep_data().largest_resolution_level()
220 .all_channels().all_layers();
221
222 let image = read()
223 .no_deep_data().largest_resolution_level()
224 .all_channels().first_valid_layer();
225 }
226 ```
227
228 ### Attributes
229 Currently, the only option is to load all attributes by calling `all_attributes()`.
230
231 ### Progress Notification
232 This library allows you to listen for the file reading progress by calling `on_progress(callback)`.
233 If you don't need this, you can just omit this call.
234
235 ```rust
236 fn main() {
237 use exr::prelude::*;
238
239 let image = read().no_deep_data().largest_resolution_level()
240 .all_channels().first_valid_layer().all_attributes()
241 .on_progress(|progress: f64| println!("progress: {:.3}", progress));
242 }
243 ```
244
245 ### Parallel Decompression
246 By default, this library uses all the available CPU cores if the pixels are compressed.
247 You can disable this behaviour by additionally calling `non_parallel()`.
248
249 ```rust
250 fn main() {
251 use exr::prelude::*;
252
253 let image = read().no_deep_data().largest_resolution_level()
254 .all_channels().first_valid_layer().all_attributes()
255 .non_parallel();
256 }
257 ```
258
259 ### Byte Sources
260 Any `std::io::Read` byte source can be used as input. However, this library also offers a simplification for files.
261 Call `from_file(path)` to load an image from a file. Internally, this wraps the file in a buffered reader.
262 Alternatively, you can call `from_buffered` or `from_unbuffered` (which wraps your reader in a buffered reader) to read an image.
263
264 ```rust
265 fn main() {
266 use exr::prelude::*;
267
268 let read = read().no_deep_data().largest_resolution_level()
269 .all_channels().first_valid_layer().all_attributes();
270
271 let image = read.clone().from_file("D:/images/file.exr"); // also accepts `Path` and `PathBuf` and `String`
272 let image = read.clone().from_unbuffered(web_socket);
273 let image = read.clone().from_buffered(Cursor::new(byte_vec));
274 }
275 ```
276
277 ### Results and Errors
278 The type of image returned depends on the options you picked.
279 The image is wrapped in a `Result<..., exr::error::Error>`.
280 This error type allows you to differentiate between three types of errors:
281 - `Error::Io(std::io::Error)` for file system errors (for example, "file does not exist" or "missing access rights")
282 - `Error::NotSupported(str)` for files that may be valid but contain features that are not supported yet
283 - `Error::Invalid(str)` for files that do not contain a valid exr image (files that are not exr or damaged exr)
284
285 ## Full Example
286 Loading all channels from the file:
287 ```rust
288 fn main() {
289 use exr::prelude::*;
290
291 // the type of the this image depends on the chosen options
292 let image = read()
293 .no_deep_data() // (currently required)
294 .largest_resolution_level() // or `all_resolution_levels()`
295 .all_channels() // or `rgba_channels` or `specific_channels() ...`
296 .all_layers() // or `first_valid_layer()`
297 .all_attributes() // (currently required)
298 .on_progress(|progress| println!("progress: {:.1}", progress * 100.0)) // optional
299 //.non_parallel() // optional. discouraged. just leave this line out
300 .from_file("image.exr").unwrap(); // or `from_buffered(my_byte_slice)`
301 }
302 ```
303
304
305 # The `Image` Data Structure
306
307 For great flexibility, this crate does not offer a plain data structure to represent an exr image.
308 Instead, the `Image` data type has a generic parameter, allowing for different image contents.
309
310 ```rust
311 fn main(){
312 // this image contains only a single layer
313 let single_layer_image: Image<Layer<_>> = Image::from_layer(my_layer);
314
315 // this image contains an arbitrary number of layers (notice the S for plural on `Layers`)
316 let multi_layer_image: Image<Layers<_>> = Image::new(attributes, smallvec![ layer1, layer2 ]);
317
318 // this image can contain the compile-time specified channels
319 let single_layer_rgb_image : Image<Layer<SpecificChannels<_, _>>> = Image::from_layer(Layer::new(
320 dimensions, attributes, encoding,
321 RgbaChannels::new(sample_types, rgba_pixels)
322 ));
323
324 // this image can contain all channels from a file, even unexpected ones
325 let single_layer_image : Image<Layer<AnyChannels<_>>> = Image::from_layer(Layer::new(
326 dimensions, attributes, encoding,
327 AnyChannels::sort(smallvec![ channel_x, channel_y, channel_z ])
328 ));
329
330 }
331 ```
332
333 The following pseudo code illustrates the image data structure.
334 The image should always be constructed using the constructor functions such as `Image::new(...)`,
335 because these functions watch out for invalid image contents.
336
337 ```
338 Image {
339 attributes: ImageAttributes,
340
341 // the layer data can be either a single layer a list of layers
342 layer_data: Layer | SmallVec<Layer> | Vec<Layer> | &[Layer] (writing only),
343 }
344
345 Layer {
346
347 // the channel data can either be a fixed set of known channels, or a dynamic list of arbitrary channels
348 channel_data: SpecificChannels | AnyChannels,
349
350 attributes: LayerAttributes,
351 size: Vec2<usize>,
352 encoding: Encoding,
353 }
354
355 SpecificChannels {
356 channels: [any tuple containing `ChannelDescription` or `Option<ChannelDescription>`],
357
358 // the storage is usually a closure or a custom type which implements the `GetPixel` trait
359 storage: impl GetPixel | impl Fn(Vec2<usize>) -> Pixel,
360 where Pixel = any tuple containing f16 or f32 or u32 values
361 }
362
363 AnyChannels {
364 list: SmallVec<AnyChannel>
365 }
366
367 AnyChannel {
368 name: Text,
369 sample_data: FlatSamples | Levels,
370 quantize_linearly: bool,
371 sampling: Vec2<usize>,
372 }
373
374 Levels = Singular(FlatSamples) | Mip(FlatSamples) | Rip(FlatSamples)
375 FlatSamples = F16(Vec<f16>) | F32(Vec<f32>) | U32(Vec<u32>)
376 ```
377
378 As a consequence, one of the simpler image types is `Image<Layer<AnyChannels<FlatSamples>>>`. If you
379 enable loading multiple resolution levels, you will instead get the type `Image<Layer<AnyChannels<Levels<FlatSamples>>>>`.
380
381 While you can put anything inside an image,
382 it can only be written if the content of the image implements certain traits.
383 This allows you to potentially write your own channel storage system.
384
385
386 # Writing an Image
387
388 Writing an image involves three steps:
389 1. Construct the image data structure, starting with an `exrs::image::Image`
390 1. Call `image_data.write()` to obtain an image writer
391 1. Customize the writer, for example in order to listen for the progress
392 1. Write the image by calling `to_file(path)`, `to_buffered(bytes)`, or `to_unbuffered(bytes)` on the reader
393
394
395 ### Image
396 You will currently need an `Image<_>` at the top level. The type parameter is the type of layer.
397
398 The following variants are recommended:
399 - `Image::from_channels(resolution, channels)` where the pixel data must be `SpecificChannels` or `AnyChannels`.
400 - `Image::from_layer(layer)` where the layer data must be one `Layer`.
401 - `Image::empty(attributes).with_layer(layer1).with_layer(layer2)...` where the two layers can have different types
402 - `Image::new(image_attributes, layer_data)` where the layer data can be `Layers` or `Layer`.
403 - `Image::from_layers(image_attributes, layer_vec)` where the layer data can be `Layers`.
404
405 ```rust
406 fn main() {
407 use exr::prelude::*;
408
409 // single layer constructors
410 let image = Image::from_layer(layer);
411 let image = Image::from_channels(resolution, channels);
412
413 // use this if the layers have different types
414 let image = Image::empty(attributes).with_layer(layer1).with_layer(layer2);
415
416 // use this if the layers have the same type and the above method does not work for you
417 let image = Image::from_layers(attributes, smallvec![ layer1, layer2 ]);
418
419 // this constructor accepts any layers object if it implements a certain trait, use this for custom layers
420 let image = Image::new(attributes, layers);
421
422
423 // create an image writer
424 image.write()
425
426 // print progress (optional, you can remove this line)
427 .on_progress(|progress:f64| println!("progress: {:.3}", progress))
428
429 // use only a single cpu (optional, you should remove this line)
430 // .non_parallel()
431
432 // alternatively call to_buffered() or to_unbuffered()
433 // the file path can be str, String, Path, PathBuf
434 .to_file(path);
435 }
436 ```
437
438 ### Layers
439 The simple way to create layers is to use `Layers<_>` or `Layer<_>`.
440 The type parameter is the type of channels.
441
442 Use `Layer::new(resolution, attributes, encoding, channels)` to create a layer.
443 Alternatively, use `smallvec![ layer1, layer2 ]` to create `Layers<_>`, which is a type alias for a list of layers.
444
445 ```rust
446 fn main() {
447 use exr::prelude::*;
448
449 let layer = Layer::new(
450 (1024, 800),
451 LayerAttributes::named("first layer"), // name required, other attributes optional
452 Encoding::FAST_LOSSLESS, // or Encoding { .. } or Encoding::default()
453 channels
454 );
455
456 let image = Image::from_layer(layer);
457 }
458 ```
459
460
461 ### Channels
462 You can create either `SpecificChannels` to write a fixed set of channels, or `AnyChannels` for a dynamic list of channels.
463
464 ```rust
465 fn main() {
466 use exr::prelude::*;
467
468 let channels = AnyChannels::sort(smallvec![ channel1, channel2, channel3 ]);
469 let image = Image::from_channels((1024, 800), channels);
470 }
471 ```
472
473 Alternatively, write specific channels. Start with `SpecificChannels::build()`,
474 then call `with_channel(name)` as many times as desired, then call `collect_pixels(..)` to define the colors.
475 You need to provide a closure that defines the content of the channels: Given the pixel location,
476 return a tuple with one element per channel. The tuple can contain `f16`, `f32` or `u32` values,
477 which then will be written to the file, without converting any value to a different type.
478
479 ```rust
480 fn main() {
481 use exr::prelude::*;
482
483 let channels = SpecificChannels::build()
484 .with_channel("L").with_channel("B")
485 .with_pixel_fn(|position: Vec2<usize>| {
486 let (l, b) = my_image.lookup_color_at(position.x(), position.y());
487 (l as f32, f16::from_f32(b))
488 });
489
490 let image = Image::from_channels((1024, 800), channels);
491 }
492 ```
493
494 #### RGB, RGBA
495 There is an even simpler alternative for rgba images, namely `SpecificChannels::rgb` and `SpecificChannels::rgba`:
496 This is mostly the same as the `SpecificChannels::build` option.
497
498 The rgb method works with three channels per pixel,
499 whereas the rgba method works with four channels per pixel. The default alpha value of `1.0` will be used
500 if the image does not contain alpha.
501 ```rust
502 fn main() {
503 use exr::prelude::*;
504
505 let channels = SpecificChannels::rgba(|_position|
506 (0.4_f32, 0.2_f32, 0.1_f32, f16::ONE)
507 );
508
509 let channels = SpecificChannels::rgb(|_position|
510 (0.4_f32, 0.2_f32, 0.1_f32)
511 );
512
513 let image = Image::from_channels((1024, 800), channels);
514 }
515 ```
516
517 ### Channel
518 The type `AnyChannel` can describe every possible channel and contains all its samples for this layer.
519 Use `AnyChannel::new(channel_name, sample_data)` or `AnyChannel { .. }`.
520 The samples can currently only be `FlatSamples` or `Levels<FlatSamples>`, and in the future might be `DeepSamples`.
521
522 ### Samples
523 Currently, only flat samples are supported. These do not contain deep data.
524 Construct flat samples directly using `FlatSamples::F16(samples_vec)`, `FlatSamples::F32(samples_vec)`, or `FlatSamples::U32(samples_vec)`.
525 The vector contains all samples of the layer, row by row (from top to bottom), from left to right.
526
527 ### Levels
528 Optionally include Mip Maps or Rip Maps.
529 Construct directly using `Levels::Singular(flat_samples)` or `Levels::Mip { .. }` or `Levels::Rip { .. }`.
530 Put this into the channel, for example`AnyChannel::new("R", Levels::Singular(FlatSamples::F32(vec)))`.
531
532 ## Full example
533 Writing a flexible list of channels:
534 ```rust
535 fn main(){
536 // construct an image to write
537 let image = Image::from_layer(
538 Layer::new( // the only layer in this image
539 (1920, 1080), // resolution
540 LayerAttributes::named("main-rgb-layer"), // the layer has a name and other properties
541 Encoding::FAST_LOSSLESS, // compress slightly
542 AnyChannels::sort(smallvec![ // the channels contain the actual pixel data
543 AnyChannel::new("R", FlatSamples::F32(vec![0.6; 1920*1080 ])), // this channel contains all red values
544 AnyChannel::new("G", FlatSamples::F32(vec![0.7; 1920*1080 ])), // this channel contains all green values
545 AnyChannel::new("B", FlatSamples::F32(vec![0.9; 1920*1080 ])), // this channel contains all blue values
546 ]),
547 )
548 );
549
550 image.write()
551 .on_progress(|progress| println!("progress: {:.1}", progress*100.0)) // optional
552 .to_file("image.exr").unwrap();
553 }
554 ```
555
556
557 ### Pixel Closures
558 When working with specific channels, the data is not stored directly.
559 Instead, you provide a closure that stores or loads pixels in your existing image data structure.
560
561 If you really do not want to provide your own storage, you can use the predefined structures from
562 `exr::image::pixel_vec`, such as `PixelVec<(f32,f32,f16)>` or `create_pixel_vec`.
563 Use this only if you don't already have a pixel storage.
564
565 ```rust
566 fn main(){
567 let read = read()
568 .no_deep_data().largest_resolution_level()
569 .rgba_channels(
570 PixelVec::<(f32,f32,f32,f16)>::constructor, // how to create an image
571 PixelVec::set_pixel, // how to update a single pixel in the image
572 )/* ... */;
573 }
574 ```
575
576
577 ## Low Level Operations
578 The image abstraction builds up on some low level code.
579 You can use this low level directly,
580 as shown in the examples `custom_write.rs` and `custom_read.rs`.
581 This allows you to work with
582 raw OpenEXR pixel blocks and chunks directly,
583 or use custom parallelization mechanisms.
584
585 You can find these low level operations in the `exr::block` module.
586 Start with the `block::read(...)`
587 and `block::write(...)` functions.
588