Debian Codegraph @

.cargo/vendor/exr/src/block/chunk.rs

raw
1
2 //! Read and write already compressed pixel data blocks.
3 //! Does not include the process of compression and decompression.
4
5 use crate::meta::attribute::{IntegerBounds};
6
7 /// A generic block of pixel information.
8 /// Contains pixel data and an index to the corresponding header.
9 /// All pixel data in a file is split into a list of chunks.
10 /// Also contains positioning information that locates this
11 /// data block in the referenced layer.
12 /// The byte data is in little-endian format,
13 /// as these bytes will be written into the file directly.
14 #[derive(Debug, Clone)]
15 pub struct Chunk {
16
17 /// The index of the layer that the block belongs to.
18 /// This is required as the pixel data can appear in any order in a file.
19 // PDF says u64, but source code seems to be i32
20 pub layer_index: usize,
21
22 /// The compressed pixel contents.
23 /// This data is compressed and in little-endian format.
24 pub compressed_block: CompressedBlock,
25 }
26
27 /// The raw, possibly compressed pixel data of a file.
28 /// Each layer in a file can have a different type.
29 /// Also contains positioning information that locates this
30 /// data block in the corresponding layer.
31 /// Exists inside a `Chunk`.
32 /// The byte data is in little-endian format,
33 /// as these bytes will be written into the file directly.
34 #[derive(Debug, Clone)]
35 pub enum CompressedBlock {
36
37 /// Scan line blocks of flat data.
38 ScanLine(CompressedScanLineBlock),
39
40 /// Tiles of flat data.
41 Tile(CompressedTileBlock),
42
43 /// Scan line blocks of deep data.
44 DeepScanLine(CompressedDeepScanLineBlock),
45
46 /// Tiles of deep data.
47 DeepTile(CompressedDeepTileBlock),
48 }
49
50 /// A `Block` of possibly compressed flat scan lines.
51 /// Corresponds to type attribute `scanlineimage`.
52 /// The byte data is in little-endian format,
53 /// as these bytes will be written into the file directly.
54 #[derive(Debug, Clone)]
55 pub struct CompressedScanLineBlock {
56
57 /// The block's y coordinate is the pixel space y coordinate of the top scan line in the block.
58 /// The top scan line block in the image is aligned with the top edge of the data window.
59 pub y_coordinate: i32,
60
61 /// One or more scan lines may be stored together as a scan line block.
62 /// The number of scan lines per block depends on how the pixel data are compressed.
63 /// For each line in the tile, for each channel, the row values are contiguous.
64 /// This data is compressed and in little-endian format.
65 pub compressed_pixels_le: Vec<u8>,
66 }
67
68 /// This `Block` is a tile of flat (non-deep) data.
69 /// Corresponds to type attribute `tiledimage`.
70 /// The byte data is in little-endian format,
71 /// as these bytes will be written into the file directly.
72 #[derive(Debug, Clone)]
73 pub struct CompressedTileBlock {
74
75 /// The tile location.
76 pub coordinates: TileCoordinates,
77
78 /// One or more scan lines may be stored together as a scan line block.
79 /// The number of scan lines per block depends on how the pixel data are compressed.
80 /// For each line in the tile, for each channel, the row values are contiguous.
81 /// This data is compressed and in little-endian format.
82 pub compressed_pixels_le: Vec<u8>,
83 }
84
85 /// Indicates the position and resolution level of a `TileBlock` or `DeepTileBlock`.
86 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
87 pub struct TileCoordinates {
88
89 /// Index of the tile, not pixel position.
90 pub tile_index: Vec2<usize>,
91
92 /// Index of the Mip/Rip level.
93 pub level_index: Vec2<usize>,
94 }
95
96 /// This `Block` consists of one or more deep scan lines.
97 /// Corresponds to type attribute `deepscanline`.
98 /// The byte data is in little-endian format,
99 /// as these bytes will be written into the file directly.
100 #[derive(Debug, Clone)]
101 pub struct CompressedDeepScanLineBlock {
102
103 /// The block's y coordinate is the pixel space y coordinate of the top scan line in the block.
104 /// The top scan line block in the image is aligned with the top edge of the data window.
105 pub y_coordinate: i32,
106
107 /// Count of samples.
108 pub decompressed_sample_data_size: usize,
109
110 /// The pixel offset table is a list of integers, one for each pixel column within the data window.
111 /// Each entry in the table indicates the total number of samples required
112 /// to store the pixel in it as well as all pixels to the left of it.
113 pub compressed_pixel_offset_table: Vec<i8>,
114
115 /// One or more scan lines may be stored together as a scan line block.
116 /// The number of scan lines per block depends on how the pixel data are compressed.
117 /// For each line in the tile, for each channel, the row values are contiguous.
118 pub compressed_sample_data_le: Vec<u8>,
119 }
120
121 /// This `Block` is a tile of deep data.
122 /// Corresponds to type attribute `deeptile`.
123 /// The byte data is in little-endian format,
124 /// as these bytes will be written into the file directly.
125 #[derive(Debug, Clone)]
126 pub struct CompressedDeepTileBlock {
127
128 /// The tile location.
129 pub coordinates: TileCoordinates,
130
131 /// Count of samples.
132 pub decompressed_sample_data_size: usize,
133
134 /// The pixel offset table is a list of integers, one for each pixel column within the data window.
135 /// Each entry in the table indicates the total number of samples required
136 /// to store the pixel in it as well as all pixels to the left of it.
137 pub compressed_pixel_offset_table: Vec<i8>,
138
139 /// One or more scan lines may be stored together as a scan line block.
140 /// The number of scan lines per block depends on how the pixel data are compressed.
141 /// For each line in the tile, for each channel, the row values are contiguous.
142 pub compressed_sample_data_le: Vec<u8>,
143 }
144
145
146 use crate::io::*;
147
148 impl TileCoordinates {
149
150 /// Without validation, write this instance to the byte stream.
151 pub fn write<W: Write>(&self, write: &mut W) -> UnitResult {
152 i32::write_le(usize_to_i32(self.tile_index.x(), "tile x")?, write)?;
153 i32::write_le(usize_to_i32(self.tile_index.y(), "tile y")?, write)?;
154 i32::write_le(usize_to_i32(self.level_index.x(), "level x")?, write)?;
155 i32::write_le(usize_to_i32(self.level_index.y(), "level y")?, write)?;
156 Ok(())
157 }
158
159 /// Read the value without validating.
160 pub fn read(read: &mut impl Read) -> Result<Self> {
161 let tile_x = i32::read_le(read)?;
162 let tile_y = i32::read_le(read)?;
163
164 let level_x = i32::read_le(read)?;
165 let level_y = i32::read_le(read)?;
166
167 if level_x > 31 || level_y > 31 {
168 // there can be at most 31 levels, because the largest level would have a size of 2^31,
169 // which exceeds the maximum 32-bit integer value.
170 return Err(Error::invalid("level index exceeding integer maximum"));
171 }
172
173 Ok(TileCoordinates {
174 tile_index: Vec2(tile_x, tile_y).to_usize("tile coordinate index")?,
175 level_index: Vec2(level_x, level_y).to_usize("tile coordinate level")?
176 })
177 }
178
179 /// The indices which can be used to index into the arrays of a data window.
180 /// These coordinates are only valid inside the corresponding one header.
181 /// Will start at 0 and always be positive.
182 pub fn to_data_indices(&self, tile_size: Vec2<usize>, max: Vec2<usize>) -> Result<IntegerBounds> {
183 let x = self.tile_index.x() * tile_size.width();
184 let y = self.tile_index.y() * tile_size.height();
185
186 if x >= max.x() || y >= max.y() {
187 Err(Error::invalid("tile index"))
188 }
189 else {
190 Ok(IntegerBounds {
191 position: Vec2(usize_to_i32(x, "tile x")?, usize_to_i32(y, "tile y")?),
192 size: Vec2(
193 calculate_block_size(max.x(), tile_size.width(), x)?,
194 calculate_block_size(max.y(), tile_size.height(), y)?,
195 ),
196 })
197 }
198 }
199
200 /// Absolute coordinates inside the global 2D space of a file, may be negative.
201 pub fn to_absolute_indices(&self, tile_size: Vec2<usize>, data_window: IntegerBounds) -> Result<IntegerBounds> {
202 let data = self.to_data_indices(tile_size, data_window.size)?;
203 Ok(data.with_origin(data_window.position))
204 }
205
206 /// Returns if this is the original resolution or a smaller copy.
207 pub fn is_largest_resolution_level(&self) -> bool {
208 self.level_index == Vec2(0, 0)
209 }
210 }
211
212
213
214 use crate::meta::{MetaData, BlockDescription, calculate_block_size};
215
216 impl CompressedScanLineBlock {
217
218 /// Without validation, write this instance to the byte stream.
219 pub fn write<W: Write>(&self, write: &mut W) -> UnitResult {
220 debug_assert_ne!(self.compressed_pixels_le.len(), 0, "empty blocks should not be put in the file bug");
221
222 i32::write_le(self.y_coordinate, write)?;
223 u8::write_i32_sized_slice_le(write, &self.compressed_pixels_le)?;
224 Ok(())
225 }
226
227 /// Read the value without validating.
228 pub fn read(read: &mut impl Read, max_block_byte_size: usize) -> Result<Self> {
229 let y_coordinate = i32::read_le(read)?;
230 let compressed_pixels_le = u8::read_i32_sized_vec_le(read, max_block_byte_size, Some(max_block_byte_size), "scan line block sample count")?;
231 Ok(CompressedScanLineBlock { y_coordinate, compressed_pixels_le })
232 }
233 }
234
235 impl CompressedTileBlock {
236
237 /// Without validation, write this instance to the byte stream.
238 pub fn write<W: Write>(&self, write: &mut W) -> UnitResult {
239 debug_assert_ne!(self.compressed_pixels_le.len(), 0, "empty blocks should not be put in the file bug");
240
241 self.coordinates.write(write)?;
242 u8::write_i32_sized_slice_le(write, &self.compressed_pixels_le)?;
243 Ok(())
244 }
245
246 /// Read the value without validating.
247 pub fn read(read: &mut impl Read, max_block_byte_size: usize) -> Result<Self> {
248 let coordinates = TileCoordinates::read(read)?;
249 let compressed_pixels_le = u8::read_i32_sized_vec_le(read, max_block_byte_size, Some(max_block_byte_size), "tile block sample count")?;
250 Ok(CompressedTileBlock { coordinates, compressed_pixels_le })
251 }
252 }
253
254 impl CompressedDeepScanLineBlock {
255
256 /// Without validation, write this instance to the byte stream.
257 pub fn write<W: Write>(&self, write: &mut W) -> UnitResult {
258 debug_assert_ne!(self.compressed_sample_data_le.len(), 0, "empty blocks should not be put in the file bug");
259
260 i32::write_le(self.y_coordinate, write)?;
261 u64::write_le(self.compressed_pixel_offset_table.len() as u64, write)?;
262 u64::write_le(self.compressed_sample_data_le.len() as u64, write)?; // TODO just guessed
263 u64::write_le(self.decompressed_sample_data_size as u64, write)?;
264 i8::write_slice_le(write, &self.compressed_pixel_offset_table)?;
265 u8::write_slice_le(write, &self.compressed_sample_data_le)?;
266 Ok(())
267 }
268
269 /// Read the value without validating.
270 pub fn read(read: &mut impl Read, max_block_byte_size: usize) -> Result<Self> {
271 let y_coordinate = i32::read_le(read)?;
272 let compressed_pixel_offset_table_size = u64_to_usize(u64::read_le(read)?, "deep table size")?;
273 let compressed_sample_data_size = u64_to_usize(u64::read_le(read)?, "deep size")?;
274 let decompressed_sample_data_size = u64_to_usize(u64::read_le(read)?, "raw deep size")?;
275
276 // doc said i32, try u8
277 let compressed_pixel_offset_table = i8::read_vec_le(
278 read, compressed_pixel_offset_table_size,
279 6 * u16::MAX as usize, Some(max_block_byte_size),
280 "deep scan line block table size"
281 )?;
282
283 let compressed_sample_data_le = u8::read_vec_le(
284 read, compressed_sample_data_size,
285 6 * u16::MAX as usize, Some(max_block_byte_size),
286 "deep scan line block sample count"
287 )?;
288
289 Ok(CompressedDeepScanLineBlock {
290 y_coordinate,
291 decompressed_sample_data_size,
292 compressed_pixel_offset_table,
293 compressed_sample_data_le,
294 })
295 }
296 }
297
298
299 impl CompressedDeepTileBlock {
300
301 /// Without validation, write this instance to the byte stream.
302 pub fn write<W: Write>(&self, write: &mut W) -> UnitResult {
303 debug_assert_ne!(self.compressed_sample_data_le.len(), 0, "empty blocks should not be put in the file bug");
304
305 self.coordinates.write(write)?;
306 u64::write_le(self.compressed_pixel_offset_table.len() as u64, write)?;
307 u64::write_le(self.compressed_sample_data_le.len() as u64, write)?; // TODO just guessed
308 u64::write_le(self.decompressed_sample_data_size as u64, write)?;
309 i8::write_slice_le(write, &self.compressed_pixel_offset_table)?;
310 u8::write_slice_le(write, &self.compressed_sample_data_le)?;
311 Ok(())
312 }
313
314 /// Read the value without validating.
315 pub fn read(read: &mut impl Read, hard_max_block_byte_size: usize) -> Result<Self> {
316 let coordinates = TileCoordinates::read(read)?;
317 let compressed_pixel_offset_table_size = u64_to_usize(u64::read_le(read)?,"deep table size")?;
318 let compressed_sample_data_size = u64_to_usize(u64::read_le(read)?, "deep size")?; // TODO u64 just guessed
319 let decompressed_sample_data_size = u64_to_usize(u64::read_le(read)?, "raw deep size")?;
320
321 let compressed_pixel_offset_table = i8::read_vec_le(
322 read, compressed_pixel_offset_table_size,
323 6 * u16::MAX as usize, Some(hard_max_block_byte_size),
324 "deep tile block table size"
325 )?;
326
327 let compressed_sample_data_le = u8::read_vec_le(
328 read, compressed_sample_data_size,
329 6 * u16::MAX as usize, Some(hard_max_block_byte_size),
330 "deep tile block sample count"
331 )?;
332
333 Ok(CompressedDeepTileBlock {
334 coordinates,
335 decompressed_sample_data_size,
336 compressed_pixel_offset_table,
337 compressed_sample_data_le,
338 })
339 }
340 }
341
342 use crate::error::{UnitResult, Result, Error, u64_to_usize, usize_to_i32, i32_to_usize};
343 use crate::math::Vec2;
344
345 /// Validation of chunks is done while reading and writing the actual data. (For example in exr::full_image)
346 impl Chunk {
347
348 /// Without validation, write this instance to the byte stream.
349 pub fn write(&self, write: &mut impl Write, header_count: usize) -> UnitResult {
350 debug_assert!(self.layer_index < header_count, "layer index bug"); // validation is done in full_image or simple_image
351
352 if header_count != 1 { usize_to_i32(self.layer_index, "layer index")?.write_le(write)?; }
353 else { assert_eq!(self.layer_index, 0, "invalid header index for single layer file"); }
354
355 match self.compressed_block {
356 CompressedBlock::ScanLine (ref value) => value.write(write),
357 CompressedBlock::Tile (ref value) => value.write(write),
358 CompressedBlock::DeepScanLine (ref value) => value.write(write),
359 CompressedBlock::DeepTile (ref value) => value.write(write),
360 }
361 }
362
363 /// Read the value without validating.
364 pub fn read(read: &mut impl Read, meta_data: &MetaData) -> Result<Self> {
365 let layer_number = i32_to_usize(
366 if meta_data.requirements.is_multilayer() { i32::read_le(read)? } // documentation says u64, but is i32
367 else { 0_i32 }, // reference the first header for single-layer images
368 "chunk data part number"
369 )?;
370
371 if layer_number >= meta_data.headers.len() {
372 return Err(Error::invalid("chunk data part number"));
373 }
374
375 let header = &meta_data.headers[layer_number];
376 let max_block_byte_size = header.max_block_byte_size();
377
378 let chunk = Chunk {
379 layer_index: layer_number,
380 compressed_block: match header.blocks {
381 // flat data
382 BlockDescription::ScanLines if !header.deep => CompressedBlock::ScanLine(CompressedScanLineBlock::read(read, max_block_byte_size)?),
383 BlockDescription::Tiles(_) if !header.deep => CompressedBlock::Tile(CompressedTileBlock::read(read, max_block_byte_size)?),
384
385 // deep data
386 BlockDescription::ScanLines => CompressedBlock::DeepScanLine(CompressedDeepScanLineBlock::read(read, max_block_byte_size)?),
387 BlockDescription::Tiles(_) => CompressedBlock::DeepTile(CompressedDeepTileBlock::read(read, max_block_byte_size)?),
388 },
389 };
390
391 Ok(chunk)
392 }
393 }
394