diff options
Diffstat (limited to 'vendor/exr/GUIDE.md')
| -rw-r--r-- | vendor/exr/GUIDE.md | 588 |
1 files changed, 588 insertions, 0 deletions
diff --git a/vendor/exr/GUIDE.md b/vendor/exr/GUIDE.md new file mode 100644 index 0000000..4f3cfaa --- /dev/null +++ b/vendor/exr/GUIDE.md @@ -0,0 +1,588 @@ +# Guide + +This document talks about the capabilities of OpenEXR and outlines the design of this library. +In addition to reading this guide, you should also have a look at the examples. + +Contents: +- Wording +- Why this is complicated +- One-liners for reading and writing simple images +- Reading a complex image +- The Image data structure +- Writing a complex image + +## Wording +Some names in this library differ from the classic OpenEXR conventions. +For example, an OpenEXR "multipart" is called a file with multiple "layers" in this library. +The old OpenEXR "layers" are called "grouped channels" instead. + +- `Image` Contains everything that an `.exr` file can contain. Includes metadata and multiple layers. +- `Layer` A grid of pixels that can be placed anywhere on the two-dimensional canvas +- `Channel` All samples of a single color component, such as red or blue. Also contains metadata. +- `Pixel` The color at an exact location in the image. Contains one sample for each channel. +- `Sample` The value (either f16, f32 or u32) of one channel at an exact location in the image. + Usually a simple number, such as the red value of the bottom left pixel. +- `Grouped Channels` Multiple channels may be grouped my prepending the same prefix to the name. + This behaviour is opt-in; it has to be enabled explicitly: + By default, channels are stored in a plain list, and channel names are unmodified. +- `pedantic: bool` When reading, pedantic being false will generally ignore + invalid information instead of aborting the reading process where possible. + When writing, pedantic being false will generally skip some expensive image validation checks. + +## OpenEXR | Complexity +This image format supports some features that you won't find in other image formats. +As a consequence, an exr file cannot necessarily be converted to other formats, +even when the loss of precision is acceptable. Furthermore, +an arbitrary exr image may include possibly unwanted data. +Supporting deep data, for example, might be unnecessary for some applications. + +To read an image, `exrs` must know which parts of an image you want to end up with, +and which parts of the file should be skipped. That's why you need +a little more code to read an exr file, compared to simpler file formats. + +### Possibly Undesired Features +- Arbitrary Channels: + `CMYK`, `YCbCr`, `LAB`, `XYZ` channels might not be interesting for you, + maybe you only want to accept `RGBA` images +- Deep Data: Multiple colors per pixel might not be interesting for you +- Resolution Levels: Mip Maps or Rip Maps might be unnecessary and can be skipped, + loading only the full resolution image instead +<!-- - TODO: Meta Data: Skip reading meta data --> + +# Simple Reading and Writing +There are a few very simple functions for the most common use cases. +For decoding an image file, use one of these functions +from the `exr::image::read` module (data structure complexity increasing): + +1. `read_first_rgba_layer_from_file(path, your_constructor, your_pixel_setter)` +1. `read_all_rgba_layers_from_file(path, your_constructor, your_pixel_setter)` +1. `read_first_flat_layer_from_file(path)` +1. `read_all_flat_layers_from_file(path)` +1. `read_all_data_from_file(path)` + +If you don't have a file path, or want to load any other channels than `rgba`, +then these simple functions will not suffice. The more complex approaches are +described later in this document. + +For encoding an image file, use one of these functions in the `exr::image::write` module: + +1. `write_rgba_file(path, width, height, |x,y| my_image.get_rgb_at(x,y))` +1. `write_rgb_file(path, width, height, |x,y| my_image.get_rgba_at(x,y))` + +These functions are only syntactic sugar. If you want to customize the data type, +the compression method, or write multiple layers, these simple functions will not suffice. +Again, the more complex approaches are described in the following paragraph. + +# Reading an Image + +Reading an image involves three steps: +1. Specify how to load an image by constructing an image reader. + 1. Start with `read()` + 1. Chain method calls to customize the reader +1. Call `from_file(path)`, `from_buffered(bytes)`, or `from_unbuffered(bytes)` + on the reader to actually load an image +1. Process the resulting image data structure or the error in your application + +The type of the resulting image depends on the reader you constructed. For example, +if you configure the reader to load mip map levels, the resulting image type +will contain an additional vector with the mip map levels. + +### Deep Data +The first choice to be made is whether you want to load deep data or not. +Deep data is where multiple colors are stored in one pixel at the same location. +Currently, deep data is not supported yet, so we always call `no_deep_data()`. + +```rust +fn main(){ + use exr::prelude::*; + let reader = read().no_deep_data(); +} +``` + +### Resolution Levels +Decide whether you want to load the largest resolution level, or all Mip Maps from the file. +Loading only the largest level actually skips portions of the image, which should be faster. + +Calling `largest_resolution_level()` will result in a single image (`FlatSamples`), +whereas calling `all_resolution_levels()` will result in multiple levels `Levels<FlatSamples>`. + +```rust +fn main(){ + use exr::prelude::*; + let reader = read().no_deep_data().largest_resolution_level(); + let reader = read().no_deep_data().all_resolution_levels(); +} +``` + +### Channels +Decide whether you want to load all channels in a dynamic list, or only load a fixed set of channels. + +Calling `all_channels()` will result in a `Vec<Channel<_>>`. + +```rust +fn main(){ + use exr::prelude::*; + let reader = read().no_deep_data().largest_resolution_level().all_channels(); +} +``` + +The alternative, `specific_channels()` allows you to exactly specify which channels should be loaded. +The usage follows the same builder pattern as the rest of the library. + +First, call `specific_channels()`. Then, for each channel you desire, +call either `required(channel_name)` or `optional(channel_name, default_value)`. +At last, call `collect_pixels()` to define how the pixels should be stored in an image. +This additional mechanism will not simply store the pixels in a `Vec<Pixel>`, but instead +works with a closure. This allows you to instantiate your own existing image type with +the pixel data from the file. + +```rust +fn main(){ + use exr::prelude::*; + + let reader = read() + .no_deep_data().largest_resolution_level() + + // load LAB channels, with chroma being optional + .specific_channels().required("L").optional("A", 0.0).optional("B", 0.0).collect_pixels( + + // create our image based on the resolution of the file + |resolution: Vec2<usize>, (l,a,b): &(ChannelDescription, Option<ChannelDescription>, Option<ChannelDescription>)|{ + if a.is_some() && b.is_some() { MyImage::new_lab(resolution) } + else { MyImage::new_luma(resolution) } + }, + + // insert a single pixel into out image + |my_image: &mut MyImage, position: Vec<usize>, (l,a,b): (f32, f16, f16)|{ + my_image.set_pixel_at(position.x(), position.y(), (l, a, b)); + } + + ); +} +``` + +The first closure is the constructor of your image, and the second closure is the setter for a single pixel in your image. +The tuple containing the channel descriptions and the pixel tuple depend on the channels that you defined earlier. +In this example, as we defined to load L,A and B, each pixel has three values. The arguments of the closure +can usually be inferred, so you don't need to declare the type of your image and the `Vec2<usize>`. +However, the type of the pixel needs to be defined. In this example, we define the pixel type to be `(f32, f16, f16)`. +All luma values will be converted to `f32` and all chroma values will be converted to `f16`. +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. +The `Sample` type is a dynamic enum over the other types, which allows you to keep the original sample type of each image. + +_Note: Currently, up to 32 channels are supported, which is an implementation problem. +Open an issue if this is not enough for your use case. Alternatively, +you can always use `all_channels()`, which has no limitations._ + +####RGBA Channels +For rgba images, there is a predefined simpler alternative to `specific_channels` called `rgb_channels` and `rgba_channels`. +It works just the same as `specific_channels` and , but you don't need to specify the names of the channels explicitly. + +```rust +fn main(){ + use exr::prelude::*; + + let reader = read() + .no_deep_data().largest_resolution_level() + + // load rgba channels + // with alpha being optional, defaulting to 1.0 + .rgba_channels( + + // create our image based on the resolution of the file + |resolution, &(r,g,b,a)|{ + if a.is_some() { MyImage::new_with_alpha(resolution.x(), resolution.y()) } + else { MyImage::new_without_alpha(resolution.x(), resolution.y()) } + }, + + // insert a single pixel into out image + |my_image, position, (r,g,b,a): (f32, f32, f32, f16)|{ + my_image.set_pixel_at(position.x(), position.y(), (r,g,b,a)); + } + + ); +} +``` + + +### Layers +Use `all_layers()` to load a `Vec<Layer<_>>` or use `first_valid_layer()` to only load +the first `Layer<_>` that matches the previously defined requirements +(for example, the first layer without deep data and cmyk channels). + + +```rust +fn main() { + use exr::prelude::*; + + let image = read() + .no_deep_data().largest_resolution_level() + .all_channels().all_layers(); + + let image = read() + .no_deep_data().largest_resolution_level() + .all_channels().first_valid_layer(); +} +``` + +### Attributes +Currently, the only option is to load all attributes by calling `all_attributes()`. + +### Progress Notification +This library allows you to listen for the file reading progress by calling `on_progress(callback)`. +If you don't need this, you can just omit this call. + +```rust +fn main() { + use exr::prelude::*; + + let image = read().no_deep_data().largest_resolution_level() + .all_channels().first_valid_layer().all_attributes() + .on_progress(|progress: f64| println!("progress: {:.3}", progress)); +} +``` + +### Parallel Decompression +By default, this library uses all the available CPU cores if the pixels are compressed. +You can disable this behaviour by additionally calling `non_parallel()`. + +```rust +fn main() { +use exr::prelude::*; + + let image = read().no_deep_data().largest_resolution_level() + .all_channels().first_valid_layer().all_attributes() + .non_parallel(); +} +``` + +### Byte Sources +Any `std::io::Read` byte source can be used as input. However, this library also offers a simplification for files. +Call `from_file(path)` to load an image from a file. Internally, this wraps the file in a buffered reader. +Alternatively, you can call `from_buffered` or `from_unbuffered` (which wraps your reader in a buffered reader) to read an image. + +```rust +fn main() { +use exr::prelude::*; + + let read = read().no_deep_data().largest_resolution_level() + .all_channels().first_valid_layer().all_attributes(); + + let image = read.clone().from_file("D:/images/file.exr"); // also accepts `Path` and `PathBuf` and `String` + let image = read.clone().from_unbuffered(web_socket); + let image = read.clone().from_buffered(Cursor::new(byte_vec)); +} +``` + +### Results and Errors +The type of image returned depends on the options you picked. +The image is wrapped in a `Result<..., exr::error::Error>`. +This error type allows you to differentiate between three types of errors: +- `Error::Io(std::io::Error)` for file system errors (for example, "file does not exist" or "missing access rights") +- `Error::NotSupported(str)` for files that may be valid but contain features that are not supported yet +- `Error::Invalid(str)` for files that do not contain a valid exr image (files that are not exr or damaged exr) + +## Full Example +Loading all channels from the file: +```rust +fn main() { + use exr::prelude::*; + + // the type of the this image depends on the chosen options + let image = read() + .no_deep_data() // (currently required) + .largest_resolution_level() // or `all_resolution_levels()` + .all_channels() // or `rgba_channels` or `specific_channels() ...` + .all_layers() // or `first_valid_layer()` + .all_attributes() // (currently required) + .on_progress(|progress| println!("progress: {:.1}", progress * 100.0)) // optional + //.non_parallel() // optional. discouraged. just leave this line out + .from_file("image.exr").unwrap(); // or `from_buffered(my_byte_slice)` +} +``` + + +# The `Image` Data Structure + +For great flexibility, this crate does not offer a plain data structure to represent an exr image. +Instead, the `Image` data type has a generic parameter, allowing for different image contents. + +```rust +fn main(){ + // this image contains only a single layer + let single_layer_image: Image<Layer<_>> = Image::from_layer(my_layer); + + // this image contains an arbitrary number of layers (notice the S for plural on `Layers`) + let multi_layer_image: Image<Layers<_>> = Image::new(attributes, smallvec![ layer1, layer2 ]); + + // this image can contain the compile-time specified channels + let single_layer_rgb_image : Image<Layer<SpecificChannels<_, _>>> = Image::from_layer(Layer::new( + dimensions, attributes, encoding, + RgbaChannels::new(sample_types, rgba_pixels) + )); + + // this image can contain all channels from a file, even unexpected ones + let single_layer_image : Image<Layer<AnyChannels<_>>> = Image::from_layer(Layer::new( + dimensions, attributes, encoding, + AnyChannels::sort(smallvec![ channel_x, channel_y, channel_z ]) + )); + +} +``` + +The following pseudo code illustrates the image data structure. +The image should always be constructed using the constructor functions such as `Image::new(...)`, +because these functions watch out for invalid image contents. + +``` +Image { + attributes: ImageAttributes, + + // the layer data can be either a single layer a list of layers + layer_data: Layer | SmallVec<Layer> | Vec<Layer> | &[Layer] (writing only), +} + +Layer { + + // the channel data can either be a fixed set of known channels, or a dynamic list of arbitrary channels + channel_data: SpecificChannels | AnyChannels, + + attributes: LayerAttributes, + size: Vec2<usize>, + encoding: Encoding, +} + +SpecificChannels { + channels: [any tuple containing `ChannelDescription` or `Option<ChannelDescription>`], + + // the storage is usually a closure or a custom type which implements the `GetPixel` trait + storage: impl GetPixel | impl Fn(Vec2<usize>) -> Pixel, + where Pixel = any tuple containing f16 or f32 or u32 values +} + +AnyChannels { + list: SmallVec<AnyChannel> +} + +AnyChannel { + name: Text, + sample_data: FlatSamples | Levels, + quantize_linearly: bool, + sampling: Vec2<usize>, +} + +Levels = Singular(FlatSamples) | Mip(FlatSamples) | Rip(FlatSamples) +FlatSamples = F16(Vec<f16>) | F32(Vec<f32>) | U32(Vec<u32>) +``` + +As a consequence, one of the simpler image types is `Image<Layer<AnyChannels<FlatSamples>>>`. If you +enable loading multiple resolution levels, you will instead get the type `Image<Layer<AnyChannels<Levels<FlatSamples>>>>`. + +While you can put anything inside an image, +it can only be written if the content of the image implements certain traits. +This allows you to potentially write your own channel storage system. + + +# Writing an Image + +Writing an image involves three steps: +1. Construct the image data structure, starting with an `exrs::image::Image` +1. Call `image_data.write()` to obtain an image writer +1. Customize the writer, for example in order to listen for the progress +1. Write the image by calling `to_file(path)`, `to_buffered(bytes)`, or `to_unbuffered(bytes)` on the reader + + +### Image +You will currently need an `Image<_>` at the top level. The type parameter is the type of layer. + +The following variants are recommended: +- `Image::from_channels(resolution, channels)` where the pixel data must be `SpecificChannels` or `AnyChannels`. +- `Image::from_layer(layer)` where the layer data must be one `Layer`. +- `Image::empty(attributes).with_layer(layer1).with_layer(layer2)...` where the two layers can have different types +- `Image::new(image_attributes, layer_data)` where the layer data can be `Layers` or `Layer`. +- `Image::from_layers(image_attributes, layer_vec)` where the layer data can be `Layers`. + +```rust +fn main() { + use exr::prelude::*; + + // single layer constructors + let image = Image::from_layer(layer); + let image = Image::from_channels(resolution, channels); + + // use this if the layers have different types + let image = Image::empty(attributes).with_layer(layer1).with_layer(layer2); + + // use this if the layers have the same type and the above method does not work for you + let image = Image::from_layers(attributes, smallvec![ layer1, layer2 ]); + + // this constructor accepts any layers object if it implements a certain trait, use this for custom layers + let image = Image::new(attributes, layers); + + + // create an image writer + image.write() + + // print progress (optional, you can remove this line) + .on_progress(|progress:f64| println!("progress: {:.3}", progress)) + + // use only a single cpu (optional, you should remove this line) + // .non_parallel() + + // alternatively call to_buffered() or to_unbuffered() + // the file path can be str, String, Path, PathBuf + .to_file(path); +} +``` + +### Layers +The simple way to create layers is to use `Layers<_>` or `Layer<_>`. +The type parameter is the type of channels. + +Use `Layer::new(resolution, attributes, encoding, channels)` to create a layer. +Alternatively, use `smallvec![ layer1, layer2 ]` to create `Layers<_>`, which is a type alias for a list of layers. + +```rust +fn main() { + use exr::prelude::*; + + let layer = Layer::new( + (1024, 800), + LayerAttributes::named("first layer"), // name required, other attributes optional + Encoding::FAST_LOSSLESS, // or Encoding { .. } or Encoding::default() + channels + ); + + let image = Image::from_layer(layer); +} +``` + + +### Channels +You can create either `SpecificChannels` to write a fixed set of channels, or `AnyChannels` for a dynamic list of channels. + +```rust +fn main() { + use exr::prelude::*; + + let channels = AnyChannels::sort(smallvec![ channel1, channel2, channel3 ]); + let image = Image::from_channels((1024, 800), channels); +} +``` + +Alternatively, write specific channels. Start with `SpecificChannels::build()`, +then call `with_channel(name)` as many times as desired, then call `collect_pixels(..)` to define the colors. +You need to provide a closure that defines the content of the channels: Given the pixel location, +return a tuple with one element per channel. The tuple can contain `f16`, `f32` or `u32` values, +which then will be written to the file, without converting any value to a different type. + +```rust +fn main() { + use exr::prelude::*; + + let channels = SpecificChannels::build() + .with_channel("L").with_channel("B") + .with_pixel_fn(|position: Vec2<usize>| { + let (l, b) = my_image.lookup_color_at(position.x(), position.y()); + (l as f32, f16::from_f32(b)) + }); + + let image = Image::from_channels((1024, 800), channels); +} +``` + +#### RGB, RGBA +There is an even simpler alternative for rgba images, namely `SpecificChannels::rgb` and `SpecificChannels::rgba`: +This is mostly the same as the `SpecificChannels::build` option. + +The rgb method works with three channels per pixel, +whereas the rgba method works with four channels per pixel. The default alpha value of `1.0` will be used +if the image does not contain alpha. +```rust +fn main() { + use exr::prelude::*; + + let channels = SpecificChannels::rgba(|_position| + (0.4_f32, 0.2_f32, 0.1_f32, f16::ONE) + ); + + let channels = SpecificChannels::rgb(|_position| + (0.4_f32, 0.2_f32, 0.1_f32) + ); + + let image = Image::from_channels((1024, 800), channels); +} +``` + +### Channel +The type `AnyChannel` can describe every possible channel and contains all its samples for this layer. +Use `AnyChannel::new(channel_name, sample_data)` or `AnyChannel { .. }`. +The samples can currently only be `FlatSamples` or `Levels<FlatSamples>`, and in the future might be `DeepSamples`. + +### Samples +Currently, only flat samples are supported. These do not contain deep data. +Construct flat samples directly using `FlatSamples::F16(samples_vec)`, `FlatSamples::F32(samples_vec)`, or `FlatSamples::U32(samples_vec)`. +The vector contains all samples of the layer, row by row (from top to bottom), from left to right. + +### Levels +Optionally include Mip Maps or Rip Maps. +Construct directly using `Levels::Singular(flat_samples)` or `Levels::Mip { .. }` or `Levels::Rip { .. }`. +Put this into the channel, for example`AnyChannel::new("R", Levels::Singular(FlatSamples::F32(vec)))`. + +## Full example +Writing a flexible list of channels: +```rust +fn main(){ + // construct an image to write + let image = Image::from_layer( + Layer::new( // the only layer in this image + (1920, 1080), // resolution + LayerAttributes::named("main-rgb-layer"), // the layer has a name and other properties + Encoding::FAST_LOSSLESS, // compress slightly + AnyChannels::sort(smallvec![ // the channels contain the actual pixel data + AnyChannel::new("R", FlatSamples::F32(vec![0.6; 1920*1080 ])), // this channel contains all red values + AnyChannel::new("G", FlatSamples::F32(vec![0.7; 1920*1080 ])), // this channel contains all green values + AnyChannel::new("B", FlatSamples::F32(vec![0.9; 1920*1080 ])), // this channel contains all blue values + ]), + ) + ); + + image.write() + .on_progress(|progress| println!("progress: {:.1}", progress*100.0)) // optional + .to_file("image.exr").unwrap(); +} +``` + + +### Pixel Closures +When working with specific channels, the data is not stored directly. +Instead, you provide a closure that stores or loads pixels in your existing image data structure. + +If you really do not want to provide your own storage, you can use the predefined structures from +`exr::image::pixel_vec`, such as `PixelVec<(f32,f32,f16)>` or `create_pixel_vec`. +Use this only if you don't already have a pixel storage. + +```rust +fn main(){ + let read = read() + .no_deep_data().largest_resolution_level() + .rgba_channels( + PixelVec::<(f32,f32,f32,f16)>::constructor, // how to create an image + PixelVec::set_pixel, // how to update a single pixel in the image + )/* ... */; +} +``` + + +## Low Level Operations +The image abstraction builds up on some low level code. +You can use this low level directly, +as shown in the examples `custom_write.rs` and `custom_read.rs`. +This allows you to work with +raw OpenEXR pixel blocks and chunks directly, +or use custom parallelization mechanisms. + +You can find these low level operations in the `exr::block` module. +Start with the `block::read(...)` +and `block::write(...)` functions. + |