Debian Codegraph @

.cargo/vendor/exr/src/image/read/mod.rs

raw
1
2 //! Read an exr image.
3 //!
4 //! For great flexibility and customization, use the `read()` function.
5 //! The return value of the `read()` function must be further customized before reading a file.
6
7 //!
8 //! For very simple applications, you can alternatively use one of these functions:
9 //!
10 //! 1. `read_first_rgba_layer_from_file(path, your_constructor, your_pixel_setter)`:
11 //! You specify how to store the pixels.
12 //! The first layer containing rgba channels is then loaded from the file.
13 //! Fails if no rgba layer can be found.
14 //!
15 //! 1. `read_all_rgba_layers_from_file(path, your_constructor, your_pixel_setter)`:
16 //! You specify how to store the pixels.
17 //! All layers containing rgba channels are then loaded from the file.
18 //! Fails if any layer in the image does not contain rgba channels.
19 //!
20 //! 1. `read_first_flat_layer_from_file(path)`:
21 //! The first layer containing non-deep data with arbitrary channels is loaded from the file.
22 //! Fails if no non-deep layer can be found.
23 //!
24 //! 1. `read_all_flat_layers_from_file(path)`:
25 //! All layers containing non-deep data with arbitrary channels are loaded from the file.
26 //! Fails if any layer in the image contains deep data.
27 //!
28 //! 1. `read_all_data_from_file(path)`:
29 //! All layers with arbitrary channels and all resolution levels are extracted from the file.
30 //!
31 //! Note: Currently does not support deep data, and currently fails
32 //! if any layer in the image contains deep data.
33 //!
34
35 // The following three stages are internally used to read an image.
36 // 1. `ReadImage` - The specification. Contains everything the user wants to tell us about loading an image.
37 // The data in this structure will be instantiated and might be borrowed.
38 // 2. `ImageReader` - The temporary reader. Based on the specification of the blueprint,
39 // a reader is instantiated, once for each layer.
40 // This data structure accumulates the image data from the file.
41 // It also owns temporary data and references the blueprint.
42 // 3. `Image` - The clean image. The accumulated data from the Reader
43 // is converted to the clean image structure, without temporary data.
44
45 pub mod image;
46 pub mod layers;
47 pub mod any_channels;
48 pub mod levels;
49 pub mod samples;
50 pub mod specific_channels;
51
52 use crate::error::{Result};
53 use crate::image::read::samples::{ReadFlatSamples};
54 use std::path::Path;
55 use crate::image::{AnyImage, AnyChannels, FlatSamples, Image, Layer, FlatImage, PixelLayersImage, RgbaChannels};
56 use crate::image::read::image::ReadLayers;
57 use crate::image::read::layers::ReadChannels;
58 use crate::math::Vec2;
59 use crate::prelude::{PixelImage};
60 use crate::block::samples::FromNativeSample;
61
62
63 /// All resolution levels, all channels, all layers.
64 /// Does not support deep data yet. Uses parallel decompression and relaxed error handling.
65 /// Inspect the source code of this function if you need customization.
66 pub fn read_all_data_from_file(path: impl AsRef<Path>) -> Result<AnyImage> {
67 read()
68 .no_deep_data() // TODO deep data
69 .all_resolution_levels()
70 .all_channels()
71 .all_layers()
72 .all_attributes()
73 .from_file(path)
74 }
75
76 // FIXME do not throw error on deep data but just skip it!
77 /// No deep data, no resolution levels, all channels, all layers.
78 /// Uses parallel decompression and relaxed error handling.
79 /// Inspect the source code of this function if you need customization.
80 pub fn read_all_flat_layers_from_file(path: impl AsRef<Path>) -> Result<FlatImage> {
81 read()
82 .no_deep_data()
83 .largest_resolution_level()
84 .all_channels()
85 .all_layers()
86 .all_attributes()
87 .from_file(path)
88 }
89
90 /// No deep data, no resolution levels, all channels, first layer.
91 /// Uses parallel decompression and relaxed error handling.
92 /// Inspect the source code of this function if you need customization.
93 pub fn read_first_flat_layer_from_file(path: impl AsRef<Path>) -> Result<Image<Layer<AnyChannels<FlatSamples>>>> {
94 read()
95 .no_deep_data()
96 .largest_resolution_level()
97 .all_channels()
98 .first_valid_layer()
99 .all_attributes()
100 .from_file(path)
101 }
102
103 /// No deep data, no resolution levels, rgba channels, all layers.
104 /// If a single layer does not contain rgba data, this method returns an error.
105 /// Uses parallel decompression and relaxed error handling.
106 /// `Create` and `Set` can be closures, see the examples for more information.
107 /// Inspect the source code of this function if you need customization.
108 /// The alpha channel will contain the value `1.0` if no alpha channel can be found in the image.
109 ///
110 /// Using two closures, define how to store the pixels.
111 /// The first closure creates an image, and the second closure inserts a single pixel.
112 /// The type of the pixel can be defined by the second closure;
113 /// it must be a tuple containing four values, each being either `f16`, `f32`, `u32` or `Sample`.
114 // FIXME Set and Create should not need to be static
115 pub fn read_all_rgba_layers_from_file<R,G,B,A, Set:'static, Create:'static, Pixels: 'static>(
116 path: impl AsRef<Path>, create: Create, set_pixel: Set
117 )
118 -> Result<PixelLayersImage<Pixels, RgbaChannels>>
119 where
120 R: FromNativeSample, G: FromNativeSample, B: FromNativeSample, A: FromNativeSample,
121 Create: Fn(Vec2<usize>, &RgbaChannels) -> Pixels, // TODO type alias? CreateRgbaPixels<Pixels=Pixels>,
122 Set: Fn(&mut Pixels, Vec2<usize>, (R,G,B,A)),
123 {
124 read()
125 .no_deep_data()
126 .largest_resolution_level()
127 .rgba_channels(create, set_pixel)
128 .all_layers()
129 .all_attributes()
130 .from_file(path)
131 }
132
133 /// No deep data, no resolution levels, rgba channels, choosing the first layer with rgba channels.
134 /// Uses parallel decompression and relaxed error handling.
135 /// `Create` and `Set` can be closures, see the examples for more information.
136 /// Inspect the source code of this function if you need customization.
137 /// The alpha channel will contain the value `1.0` if no alpha channel can be found in the image.
138 ///
139 /// Using two closures, define how to store the pixels.
140 /// The first closure creates an image, and the second closure inserts a single pixel.
141 /// The type of the pixel can be defined by the second closure;
142 /// it must be a tuple containing four values, each being either `f16`, `f32`, `u32` or `Sample`.
143 // FIXME Set and Create should not need to be static
144 pub fn read_first_rgba_layer_from_file<R,G,B,A, Set:'static, Create:'static, Pixels: 'static>(
145 path: impl AsRef<Path>, create: Create, set_pixel: Set
146 )
147 -> Result<PixelImage<Pixels, RgbaChannels>>
148 where
149 R: FromNativeSample, G: FromNativeSample, B: FromNativeSample, A: FromNativeSample,
150 Create: Fn(Vec2<usize>, &RgbaChannels) -> Pixels, // TODO type alias? CreateRgbaPixels<Pixels=Pixels>,
151 Set: Fn(&mut Pixels, Vec2<usize>, (R,G,B,A)),
152 {
153 read()
154 .no_deep_data()
155 .largest_resolution_level()
156 .rgba_channels(create, set_pixel)
157 .first_valid_layer()
158 .all_attributes()
159 .from_file(path)
160 }
161
162
163 /// Utilizes the builder pattern to configure an image reader. This is the initial struct.
164 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
165 pub struct ReadBuilder;
166
167 /// Create a reader which can be used to load an exr image.
168 /// Allows you to exactly specify how to load the image, for example:
169 ///
170 /// ```no_run
171 /// use exr::prelude::*;
172 ///
173 /// // the type of the this image depends on the chosen options
174 /// let image = read()
175 /// .no_deep_data() // (currently required)
176 /// .largest_resolution_level() // or `all_resolution_levels()`
177 /// .all_channels() // or `rgba_channels(constructor, setter)`
178 /// .all_layers() // or `first_valid_layer()`
179 /// .all_attributes() // (currently required)
180 /// .on_progress(|progress| println!("progress: {:.1}", progress*100.0)) // optional
181 /// .from_file("image.exr").unwrap(); // or `from_buffered(my_byte_slice)`
182 /// ```
183 ///
184 /// You can alternatively use one of the following simpler functions:
185 /// 1. `read_first_flat_layer_from_file`
186 /// 1. `read_all_rgba_layers_from_file`
187 /// 1. `read_all_flat_layers_from_file`
188 /// 1. `read_all_data_from_file`
189 ///
190 // TODO not panic but skip deep layers!
191 pub fn read() -> ReadBuilder { ReadBuilder }
192
193 impl ReadBuilder {
194
195 /// Specify to handle only one sample per channel, disabling "deep data".
196 // TODO not panic but skip deep layers!
197 pub fn no_deep_data(self) -> ReadFlatSamples { ReadFlatSamples }
198
199 // pub fn any_resolution_levels() -> ReadBuilder<> {}
200
201 // TODO
202 // e. g. `let sum = reader.any_channels_with(|sample, sum| sum += sample)`
203 // e. g. `let floats = reader.any_channels_with(|sample, f32_samples| f32_samples[index] = sample as f32)`
204 // pub fn no_deep_data_with <S> (self, storage: S) -> FlatSamplesWith<S> { }
205
206 // pub fn flat_and_deep_data(self) -> ReadAnySamples { ReadAnySamples }
207 }