Build Directory FromIterator

This enables a test for the encoder's DirectoryOffset but it seems to
fit nicely with the current design, too.

.github/workflows/rust.yml

@@ -45,6 +45,10 @@ jobs:
     - name: Cargo check
       run: cargo check --features "${{ matrix.feature }}" --no-default-features
 
+    - name: Cargo clippy
+      if: ${{ matrix.feature != '' }}
+      run: cargo clippy --no-deps --all-features --all-targets -- -D warnings
+
   other_archs:
     # github actions does not support 32-bit or big endian systems directly, but
     # it does support QEMU. so we install qemu, then build and run the tests on

CHANGES.md

@@ -1,3 +1,44 @@
+# Version 0.10.4 (unreleased)
+
+- `Directory` now implements `FromIterator<(Tag, Value)>`.
+
+# Version 0.10.3
+
+New features:
+- Group 4 `fax` is now recognized as a compression type and decoded.
+- A crate feature `fax` controls related dependencies, on by default.
+
+Changes:
+- The presence of PhotometricInterpretation::WhiteIsZero now returns an error
+  if the color type can not be inverted by the library where they were
+  previously silently ignored. Please report any missing color types.
+
+Fixes:
+- The PhotometricInterpretation::WhiteIsZero is now also applied to 1-bit
+  images, as well as 2-bit and 4-bit sample types where previously the presence
+  of this tag was ignored.
+
+# Version 0.10.2
+
+Republished 0.10.1, fixing an accidentally removed method (`Decoder::find_tag_unsigned_vec`).
+
+# Version 0.10.1
+
+New features:
+ - Added a dedicated `Directory` type (#277)
+ - Expose methods related to `Directory` publicly (#278)
+ - Implement writing directories (#281, #283)
+ - Add ICC (color profile) to the set of known tags (#287)
+ - Added `Decoder.inner()` to access the underlying reader (#289)
+ - Added methods for reading into a pre-allocated byte buffer (#285)
+
+Changes:
+ - No longer perform color conversion when decoding embedded JPEG. This fixes decoding for JPEG images with alpha channel. (#274)
+ - More lenient LZW decoding to match libtiff (#231)
+
+Fixes:
+ - Fixed seeking multiple times in a row (#279)
+
 # Version 0.10.0
 
 New features:

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tiff"
-version = "0.10.0"
+version = "0.10.3"
 edition = "2021"
 resolver = "2"
 
@@ -20,19 +20,24 @@ exclude = ["tests/images/*", "tests/fuzz_images/*"]
 half = { version = "2.4.1" }
 quick-error = "2.0.1"
 
+# Rename to avoid confusion with the feature name.
+fax34 = { package = "fax", version = "0.2.6", optional = true }
 flate2 = { version = "1.0.20", optional = true }
 weezl = { version = "0.1.10", optional = true }
 zstd = { version = "0.13", optional = true }
-zune-jpeg = { version = "0.4.17", optional = true }
+zune-jpeg = { version = "0.5.1", optional = true }
 
 [dev-dependencies]
 criterion = "0.3.1"
+# We may already depend on this via flate2
+crc32fast = "1.5"
 
 [features]
-default = ["deflate", "jpeg", "lzw"]
+default = ["deflate", "fax", "jpeg", "lzw"]
 
 # Compression algorithms
 deflate = ["dep:flate2"]
+fax = ["dep:fax34"]
 jpeg = ["dep:zune-jpeg"]
 lzw = ["dep:weezl"]
 zstd = ["dep:zstd"]

README.md

@@ -36,6 +36,7 @@ This table lists photometric interpretations and sample formats which are suppor
 | LZW      | ✓        | ✓        |
 | Deflate  | ✓        | ✓        |
 | PackBits | ✓        | ✓        |
+| Fax4     | ✓        | not yet  |
 | JPEG     | ✓        | not yet  |
 | ZSTD     | ✓        | not yet  |
 

src/bytecast.rs

@@ -10,6 +10,9 @@
 //! the unsafe code guidelines).
 //!
 //! TODO: Would like to use std-lib here.
+// Until we implement predictors for f16, we don't need f16_as_ne_bytes. (Due to the macro we do
+// not apply this directly to the functions). And rust-version is not new enough for `expect`.
+#![allow(dead_code)]
 use std::{mem, slice};
 
 use half::f16;

src/decoder/ifd.rs

@@ -332,6 +332,12 @@ impl Value {
     }
 }
 
+/// A combination of type, count, and offset.
+///
+/// In a TIFF the data offset portion of an entry is used for inline data in case the length of the
+/// encoded value does not exceed the size of the offset field. Since the size of the offset field
+/// depends on the file kind (4 bytes for standard TIFF, 8 bytes for BigTIFF) the interpretation of
+/// this struct is only complete in combination with file metadata.
 #[derive(Clone)]
 pub struct Entry {
     type_: Type,
@@ -349,12 +355,14 @@ impl ::std::fmt::Debug for Entry {
 }
 
 impl Entry {
+    /// Create a new entry fit to be added to a standard TIFF IFD.
     pub fn new(type_: Type, count: u32, offset: [u8; 4]) -> Entry {
         let mut entry_off = [0u8; 8];
         entry_off[..4].copy_from_slice(&offset);
         Entry::new_u64(type_, count.into(), entry_off)
     }
 
+    /// Create a new entry with data for a Big TIFF IFD.
     pub fn new_u64(type_: Type, count: u64, offset: [u8; 8]) -> Entry {
         Entry {
             type_,
@@ -376,7 +384,10 @@ impl Entry {
     }
 
     /// Returns a mem_reader for the offset/value field
-    fn r(&self, byte_order: ByteOrder) -> EndianReader<io::Cursor<Vec<u8>>> {
+    pub(crate) fn offset_field_reader(
+        &self,
+        byte_order: ByteOrder,
+    ) -> EndianReader<io::Cursor<Vec<u8>>> {
         EndianReader::new(io::Cursor::new(self.offset.to_vec()), byte_order)
     }
 
@@ -392,43 +403,25 @@ impl Entry {
         }
 
         let bo = reader.byte_order;
-
-        let tag_size = match self.type_ {
-            Type::BYTE | Type::SBYTE | Type::ASCII | Type::UNDEFINED => 1,
-            Type::SHORT | Type::SSHORT => 2,
-            Type::LONG | Type::SLONG | Type::FLOAT | Type::IFD => 4,
-            Type::LONG8
-            | Type::SLONG8
-            | Type::DOUBLE
-            | Type::RATIONAL
-            | Type::SRATIONAL
-            | Type::IFD8 => 8,
-        };
-
-        let value_bytes = match self.count.checked_mul(tag_size) {
-            Some(n) => n,
-            None => {
-                return Err(TiffError::LimitsExceeded);
-            }
-        };
+        let value_bytes = self.type_.value_bytes(self.count)?;
 
         // Case 2: there is one value.
         if self.count == 1 {
             // 2a: the value is 5-8 bytes and we're in BigTiff mode.
             if bigtiff && value_bytes > 4 && value_bytes <= 8 {
                 return Ok(match self.type_ {
-                    Type::LONG8 => UnsignedBig(self.r(bo).read_u64()?),
-                    Type::SLONG8 => SignedBig(self.r(bo).read_i64()?),
-                    Type::DOUBLE => Double(self.r(bo).read_f64()?),
+                    Type::LONG8 => UnsignedBig(self.offset_field_reader(bo).read_u64()?),
+                    Type::SLONG8 => SignedBig(self.offset_field_reader(bo).read_i64()?),
+                    Type::DOUBLE => Double(self.offset_field_reader(bo).read_f64()?),
                     Type::RATIONAL => {
-                        let mut r = self.r(bo);
+                        let mut r = self.offset_field_reader(bo);
                         Rational(r.read_u32()?, r.read_u32()?)
                     }
                     Type::SRATIONAL => {
-                        let mut r = self.r(bo);
+                        let mut r = self.offset_field_reader(bo);
                         SRational(r.read_i32()?, r.read_i32()?)
                     }
-                    Type::IFD8 => IfdBig(self.r(bo).read_u64()?),
+                    Type::IFD8 => IfdBig(self.offset_field_reader(bo).read_u64()?),
                     Type::BYTE
                     | Type::SBYTE
                     | Type::ASCII
@@ -445,13 +438,13 @@ impl Entry {
             // 2b: the value is at most 4 bytes or doesn't fit in the offset field.
             return Ok(match self.type_ {
                 Type::BYTE => Byte(self.offset[0]),
-                Type::SBYTE => SignedByte(i8::from(self.offset[0] as i8)),
+                Type::SBYTE => SignedByte(self.offset[0] as i8),
                 Type::UNDEFINED => Byte(self.offset[0]),
-                Type::SHORT => Short(self.r(bo).read_u16()?),
-                Type::SSHORT => SignedShort(self.r(bo).read_i16()?),
-                Type::LONG => Unsigned(self.r(bo).read_u32()?),
-                Type::SLONG => Signed(self.r(bo).read_i32()?),
-                Type::FLOAT => Float(self.r(bo).read_f32()?),
+                Type::SHORT => Short(self.offset_field_reader(bo).read_u16()?),
+                Type::SSHORT => SignedShort(self.offset_field_reader(bo).read_i16()?),
+                Type::LONG => Unsigned(self.offset_field_reader(bo).read_u32()?),
+                Type::SLONG => Signed(self.offset_field_reader(bo).read_i32()?),
+                Type::FLOAT => Float(self.offset_field_reader(bo).read_f32()?),
                 Type::ASCII => {
                     if self.offset[0] == 0 {
                         Ascii("".to_string())
@@ -460,28 +453,28 @@ impl Entry {
                     }
                 }
                 Type::LONG8 => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     UnsignedBig(reader.read_u64()?)
                 }
                 Type::SLONG8 => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     SignedBig(reader.read_i64()?)
                 }
                 Type::DOUBLE => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     Double(reader.read_f64()?)
                 }
                 Type::RATIONAL => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     Rational(reader.read_u32()?, reader.read_u32()?)
                 }
                 Type::SRATIONAL => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     SRational(reader.read_i32()?, reader.read_i32()?)
                 }
-                Type::IFD => Ifd(self.r(bo).read_u32()?),
+                Type::IFD => Ifd(self.offset_field_reader(bo).read_u32()?),
                 Type::IFD8 => {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?;
+                    reader.goto_offset(self.offset_field_reader(bo).read_u32()?.into())?;
                     IfdBig(reader.read_u64()?)
                 }
             });
@@ -512,7 +505,7 @@ impl Entry {
                     ));
                 }
                 Type::SHORT => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(Short(r.read_u16()?));
@@ -520,7 +513,7 @@ impl Entry {
                     return Ok(List(v));
                 }
                 Type::SSHORT => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(SignedShort(r.read_i16()?));
@@ -528,7 +521,7 @@ impl Entry {
                     return Ok(List(v));
                 }
                 Type::LONG => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(Unsigned(r.read_u32()?));
@@ -536,7 +529,7 @@ impl Entry {
                     return Ok(List(v));
                 }
                 Type::SLONG => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(Signed(r.read_i32()?));
@@ -544,7 +537,7 @@ impl Entry {
                     return Ok(List(v));
                 }
                 Type::FLOAT => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(Float(r.read_f32()?));
@@ -552,7 +545,7 @@ impl Entry {
                     return Ok(List(v));
                 }
                 Type::IFD => {
-                    let mut r = self.r(bo);
+                    let mut r = self.offset_field_reader(bo);
                     let mut v = Vec::new();
                     for _ in 0..self.count {
                         v.push(Ifd(r.read_u32()?));
@@ -571,74 +564,149 @@ impl Entry {
         }
 
         // Case 4: there is more than one value, and it doesn't fit in the offset field.
+        let mut v;
+        self.set_reader_offset(bo, bigtiff, reader)?;
+
         match self.type_ {
-            // TODO check if this could give wrong results
-            // at a different endianess of file/computer.
-            Type::BYTE => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                let mut buf = [0; 1];
-                reader.inner().read_exact(&mut buf)?;
-                Ok(UnsignedBig(u64::from(buf[0])))
-            }),
-            Type::SBYTE => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(SignedBig(i64::from(reader.read_i8()?)))
-            }),
-            Type::SHORT => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Short(reader.read_u16()?))
-            }),
-            Type::SSHORT => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(SignedShort(reader.read_i16()?))
-            }),
-            Type::LONG => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Unsigned(reader.read_u32()?))
-            }),
-            Type::SLONG => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Signed(reader.read_i32()?))
-            }),
-            Type::FLOAT => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Float(reader.read_f32()?))
-            }),
-            Type::DOUBLE => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Double(reader.read_f64()?))
-            }),
+            Type::BYTE | Type::UNDEFINED => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(bytes.iter().copied().map(Byte))
+                })
+            }
+            Type::SBYTE => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(bytes.iter().copied().map(|v| SignedByte(v as i8)))
+                })
+            }
+            Type::SHORT => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(2)
+                            .map(|ch| Short(u16::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::SSHORT => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(2)
+                            .map(|ch| SignedShort(i16::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::LONG => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(4)
+                            .map(|ch| Unsigned(u32::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::SLONG => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(4)
+                            .map(|ch| Signed(i32::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::FLOAT => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(4)
+                            .map(|ch| Float(f32::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::DOUBLE => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(8)
+                            .map(|ch| Double(f64::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
             Type::RATIONAL => {
-                self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                    Ok(Rational(reader.read_u32()?, reader.read_u32()?))
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(bytes.chunks_exact(8).map(|ch| {
+                        Rational(
+                            u32::from_ne_bytes(ch[..4].try_into().unwrap()),
+                            u32::from_ne_bytes(ch[4..].try_into().unwrap()),
+                        )
+                    }))
                 })
             }
             Type::SRATIONAL => {
-                self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                    Ok(SRational(reader.read_i32()?, reader.read_i32()?))
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(bytes.chunks_exact(8).map(|ch| {
+                        SRational(
+                            i32::from_ne_bytes(ch[..4].try_into().unwrap()),
+                            i32::from_ne_bytes(ch[4..].try_into().unwrap()),
+                        )
+                    }))
                 })
             }
-            Type::LONG8 => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(UnsignedBig(reader.read_u64()?))
-            }),
-            Type::SLONG8 => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(SignedBig(reader.read_i64()?))
-            }),
-            Type::IFD => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(Ifd(reader.read_u32()?))
-            }),
-            Type::IFD8 => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(IfdBig(reader.read_u64()?))
-            }),
-            Type::UNDEFINED => {
-                self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                    let mut buf = [0; 1];
-                    reader.inner().read_exact(&mut buf)?;
-                    Ok(Byte(buf[0]))
+            Type::LONG8 => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(8)
+                            .map(|ch| UnsignedBig(u64::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::SLONG8 => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(8)
+                            .map(|ch| SignedBig(i64::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::IFD => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(4)
+                            .map(|ch| Ifd(u32::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
+                })
+            }
+            Type::IFD8 => {
+                v = Self::vec_with_capacity(self.count, limits)?;
+                self.decode_values(self.count, self.type_, reader, |bytes| {
+                    v.extend(
+                        bytes
+                            .chunks_exact(8)
+                            .map(|ch| IfdBig(u64::from_ne_bytes(ch.try_into().unwrap()))),
+                    )
                 })
             }
             Type::ASCII => {
                 let n = usize::try_from(self.count)?;
-                if n > limits.decoding_buffer_size {
-                    return Err(TiffError::LimitsExceeded);
-                }
 
-                if bigtiff {
-                    reader.goto_offset(self.r(bo).read_u64()?)?
-                } else {
-                    reader.goto_offset(self.r(bo).read_u32()?.into())?
+                if n > limits.decoding_buffer_size {
+                    return Err(dbg!(TiffError::LimitsExceeded));
                 }
 
                 let mut out = vec![0; n];
@@ -647,43 +715,81 @@ impl Entry {
                 if let Some(first) = out.iter().position(|&b| b == 0) {
                     out.truncate(first);
                 }
-                Ok(Ascii(String::from_utf8(out)?))
+
+                return Ok(Ascii(String::from_utf8(out)?));
             }
-        }
+        }?;
+
+        Ok(List(v))
     }
 
-    #[inline]
-    fn decode_offset<R, F>(
-        &self,
+    fn vec_with_capacity(
         value_count: u64,
-        bo: ByteOrder,
-        bigtiff: bool,
         limits: &super::Limits,
-        reader: &mut EndianReader<R>,
-        decode_fn: F,
-    ) -> TiffResult<Value>
-    where
-        R: Read + Seek,
-        F: Fn(&mut EndianReader<R>) -> TiffResult<Value>,
-    {
+    ) -> Result<Vec<Value>, TiffError> {
         let value_count = usize::try_from(value_count)?;
+
         if value_count > limits.decoding_buffer_size / mem::size_of::<Value>() {
             return Err(TiffError::LimitsExceeded);
         }
 
-        let mut v = Vec::with_capacity(value_count);
+        Ok(Vec::with_capacity(value_count))
+    }
 
+    fn set_reader_offset<R>(
+        &self,
+        bo: ByteOrder,
+        bigtiff: bool,
+        reader: &mut EndianReader<R>,
+    ) -> TiffResult<()>
+    where
+        R: Read + Seek,
+    {
         let offset = if bigtiff {
-            self.r(bo).read_u64()?
+            self.offset_field_reader(bo).read_u64()?
         } else {
-            self.r(bo).read_u32()?.into()
+            self.offset_field_reader(bo).read_u32()?.into()
         };
+
         reader.goto_offset(offset)?;
 
-        for _ in 0..value_count {
-            v.push(decode_fn(reader)?)
+        Ok(())
+    }
+
+    #[inline]
+    fn decode_values<R, F>(
+        &self,
+        value_count: u64,
+        type_: Type,
+        reader: &mut EndianReader<R>,
+        mut collect: F,
+    ) -> TiffResult<()>
+    where
+        R: Read + Seek,
+        F: FnMut(&[u8]),
+    {
+        let mut total_bytes = type_.value_bytes(value_count)?;
+        let mut buffer = [0u8; 512];
+
+        let buf_unit = usize::from(type_.byte_len());
+        let mul_of_ty = buffer.len() / buf_unit * buf_unit;
+
+        let cls = type_.endian_bytes();
+        let native = ByteOrder::native();
+
+        while total_bytes > 0 {
+            // `now <= mul_of_ty < 512` so casting is mathematical
+            let now = total_bytes.min(mul_of_ty as u64);
+            total_bytes -= now;
+
+            let buffer = &mut buffer[..now as usize];
+            reader.inner().read_exact(buffer)?;
+
+            reader.byte_order.convert_endian_bytes(cls, buffer, native);
+            collect(buffer);
         }
-        Ok(List(v))
+
+        Ok(())
     }
 }
 

src/decoder/image.rs

@@ -9,7 +9,9 @@ use crate::tags::{
 use crate::{
     ColorType, Directory, TiffError, TiffFormatError, TiffResult, TiffUnsupportedError, UsageError,
 };
+
 use std::io::{self, Cursor, Read, Seek};
+use std::num::NonZeroUsize;
 use std::sync::Arc;
 
 #[derive(Debug)]
@@ -29,10 +31,10 @@ pub(crate) struct TileAttributes {
 
 impl TileAttributes {
     pub fn tiles_across(&self) -> usize {
-        (self.image_width + self.tile_width - 1) / self.tile_width
+        self.image_width.div_ceil(self.tile_width)
     }
     pub fn tiles_down(&self) -> usize {
-        (self.image_height + self.tile_length - 1) / self.tile_length
+        self.image_height.div_ceil(self.tile_length)
     }
     fn padding_right(&self) -> usize {
         (self.tile_width - self.image_width % self.tile_width) % self.tile_width
@@ -143,12 +145,15 @@ impl Image {
                     .map(SampleFormat::from_u16_exhaustive)
                     .collect();
 
+                let Some(format) = sample_format.first().copied() else {
+                    // Reject empty sample formats
+                    return Err(TiffFormatError::InvalidTagValueType(Tag::SampleFormat).into());
+                };
                 // TODO: for now, only homogenous formats across samples are supported.
-                if !sample_format.windows(2).all(|s| s[0] == s[1]) {
+                if !sample_format.iter().all(|&s| s == format) {
                     return Err(TiffUnsupportedError::UnsupportedSampleFormat(sample_format).into());
                 }
-
-                sample_format[0]
+                format
             }
             None => SampleFormat::Uint,
         };
@@ -342,6 +347,9 @@ impl Image {
                     ),
                 )),
             },
+            // TODO: treatment of WhiteIsZero is not quite consistent with `invert_colors` that is
+            // later called when that interpretation is read. That function does not support
+            // Multiband as a color type and will error. It's unclear how to resolve that exactly.
             PhotometricInterpretation::BlackIsZero | PhotometricInterpretation::WhiteIsZero => {
                 match self.samples {
                     1 => Ok(ColorType::Gray(self.bits_per_sample)),
@@ -363,11 +371,29 @@ impl Image {
         }
     }
 
+    pub(crate) fn minimum_row_stride(&self, dims: (u32, u32)) -> Option<NonZeroUsize> {
+        let (width, height) = dims;
+
+        let row_stride = u64::from(width)
+            .saturating_mul(self.samples_per_pixel() as u64)
+            .saturating_mul(self.bits_per_sample as u64)
+            .div_ceil(8);
+
+        // Note: row stride should be smaller than the len if we have an actual buffer. If there
+        // are no pixels in the buffer (height _or_ width is 0) then the stride is not well defined
+        // and we return `None`.
+        (height > 0)
+            .then_some(row_stride as usize)
+            .and_then(NonZeroUsize::new)
+    }
+
     fn create_reader<'r, R: 'r + Read>(
         reader: R,
         compression_method: CompressionMethod,
         compressed_length: u64,
-        #[allow(unused_variables)] jpeg_tables: Option<&[u8]>,
+        // FIXME: these should be `expect` attributes or we choose another way of passing them.
+        #[cfg_attr(not(feature = "jpeg"), allow(unused_variables))] jpeg_tables: Option<&[u8]>,
+        #[cfg_attr(not(feature = "fax"), allow(unused_variables))] dimensions: (u32, u32),
     ) -> TiffResult<Box<dyn Read + 'r>> {
         Ok(match compression_method {
             CompressionMethod::None => Box::new(reader),
@@ -419,13 +445,14 @@ impl Image {
                 let mut jpeg_data = Vec::new();
                 jpeg_reader.read_to_end(&mut jpeg_data)?;
 
-                let mut decoder = zune_jpeg::JpegDecoder::new(jpeg_data);
+                let mut decoder =
+                    zune_jpeg::JpegDecoder::new(zune_core::bytestream::ZCursor::new(jpeg_data));
                 let mut options: zune_core::options::DecoderOptions = Default::default();
 
                 // Disable color conversion by setting the output colorspace to the input
                 // colorspace.
                 decoder.decode_headers()?;
-                if let Some(colorspace) = decoder.get_input_colorspace() {
+                if let Some(colorspace) = decoder.input_colorspace() {
                     options = options.jpeg_set_out_colorspace(colorspace);
                 }
 
@@ -435,6 +462,12 @@ impl Image {
 
                 Box::new(Cursor::new(data))
             }
+            #[cfg(feature = "fax")]
+            CompressionMethod::Fax4 => Box::new(super::stream::Group4Reader::new(
+                dimensions,
+                reader,
+                compressed_length,
+            )?),
             method => {
                 return Err(TiffError::UnsupportedError(
                     TiffUnsupportedError::UnsupportedCompressionMethod(method),
@@ -625,12 +658,12 @@ impl Image {
         let chunk_row_bits = (u64::from(chunk_dims.0) * u64::from(self.bits_per_sample))
             .checked_mul(samples as u64)
             .ok_or(TiffError::LimitsExceeded)?;
-        let chunk_row_bytes: usize = ((chunk_row_bits + 7) / 8).try_into()?;
+        let chunk_row_bytes: usize = chunk_row_bits.div_ceil(8).try_into()?;
 
         let data_row_bits = (u64::from(data_dims.0) * u64::from(self.bits_per_sample))
             .checked_mul(samples as u64)
             .ok_or(TiffError::LimitsExceeded)?;
-        let data_row_bytes: usize = ((data_row_bits + 7) / 8).try_into()?;
+        let data_row_bytes: usize = data_row_bits.div_ceil(8).try_into()?;
 
         // TODO: Should these return errors instead?
         assert!(output_row_stride >= data_row_bytes);
@@ -641,13 +674,14 @@ impl Image {
             compression_method,
             *compressed_bytes,
             self.jpeg_tables.as_deref().map(|a| &**a),
+            chunk_dims,
         )?;
 
-        if output_row_stride == chunk_row_bytes as usize {
+        if output_row_stride == chunk_row_bytes {
             let tile = &mut buf[..chunk_row_bytes * data_dims.1 as usize];
             reader.read_exact(tile)?;
 
-            for row in tile.chunks_mut(chunk_row_bytes as usize) {
+            for row in tile.chunks_mut(chunk_row_bytes) {
                 super::fix_endianness_and_predict(
                     row,
                     color_type.bit_depth(),
@@ -657,7 +691,7 @@ impl Image {
                 );
             }
             if photometric_interpretation == PhotometricInterpretation::WhiteIsZero {
-                super::invert_colors(tile, color_type, self.sample_format);
+                super::invert_colors(tile, color_type, self.sample_format)?;
             }
         } else if chunk_row_bytes > data_row_bytes && self.predictor == Predictor::FloatingPoint {
             // The floating point predictor shuffles the padding bytes into the encoded output, so
@@ -674,15 +708,11 @@ impl Image {
                     _ => unreachable!(),
                 }
                 if photometric_interpretation == PhotometricInterpretation::WhiteIsZero {
-                    super::invert_colors(row, color_type, self.sample_format);
+                    super::invert_colors(row, color_type, self.sample_format)?;
                 }
             }
         } else {
-            for (_i, row) in buf
-                .chunks_mut(output_row_stride)
-                .take(data_dims.1 as usize)
-                .enumerate()
-            {
+            for row in buf.chunks_mut(output_row_stride).take(data_dims.1 as usize) {
                 let row = &mut row[..data_row_bytes];
                 reader.read_exact(row)?;
 
@@ -700,7 +730,7 @@ impl Image {
                     predictor,
                 );
                 if photometric_interpretation == PhotometricInterpretation::WhiteIsZero {
-                    super::invert_colors(row, color_type, self.sample_format);
+                    super::invert_colors(row, color_type, self.sample_format)?;
                 }
             }
         }

src/decoder/mod.rs

@@ -1,5 +1,7 @@
+use std::alloc::{Layout, LayoutError};
 use std::collections::BTreeMap;
 use std::io::{self, Read, Seek};
+use std::num::NonZeroUsize;
 
 use crate::tags::{
     CompressionMethod, IfdPointer, PhotometricInterpretation, PlanarConfiguration, Predictor,
@@ -136,7 +138,7 @@ impl DecodingResult {
         }
     }
 
-    pub fn as_buffer(&mut self, start: usize) -> DecodingBuffer {
+    pub fn as_buffer(&mut self, start: usize) -> DecodingBuffer<'_> {
         match *self {
             DecodingResult::U8(ref mut buf) => DecodingBuffer::U8(&mut buf[start..]),
             DecodingResult::U16(ref mut buf) => DecodingBuffer::U16(&mut buf[start..]),
@@ -197,6 +199,88 @@ impl<'a> DecodingBuffer<'a> {
     }
 }
 
+/// Information on the byte buffer that should be supplied to the decoder.
+///
+/// This is relevant for [`Decoder::read_image_bytes`] and [`Decoder::read_chunk_bytes`] where the
+/// caller provided buffer must fit the expectations of the decoder to be filled with data from the
+/// current image.
+#[non_exhaustive]
+pub struct BufferLayoutPreference {
+    /// Minimum byte size of the buffer to read image data.
+    pub len: usize,
+    /// Minimum number of bytes to represent a row of image data of the requested content.
+    pub row_stride: Option<NonZeroUsize>,
+}
+
+/// The count and matching discriminant for a `DecodingBuffer`.
+#[derive(Clone)]
+enum DecodingExtent {
+    U8(usize),
+    U16(usize),
+    U32(usize),
+    U64(usize),
+    F16(usize),
+    F32(usize),
+    F64(usize),
+    I8(usize),
+    I16(usize),
+    I32(usize),
+    I64(usize),
+}
+
+impl DecodingExtent {
+    fn to_result_buffer(&self, limits: &Limits) -> TiffResult<DecodingResult> {
+        match *self {
+            DecodingExtent::U8(count) => DecodingResult::new_u8(count, limits),
+            DecodingExtent::U16(count) => DecodingResult::new_u16(count, limits),
+            DecodingExtent::U32(count) => DecodingResult::new_u32(count, limits),
+            DecodingExtent::U64(count) => DecodingResult::new_u64(count, limits),
+            DecodingExtent::F16(count) => DecodingResult::new_f16(count, limits),
+            DecodingExtent::F32(count) => DecodingResult::new_f32(count, limits),
+            DecodingExtent::F64(count) => DecodingResult::new_f64(count, limits),
+            DecodingExtent::I8(count) => DecodingResult::new_i8(count, limits),
+            DecodingExtent::I16(count) => DecodingResult::new_i16(count, limits),
+            DecodingExtent::I32(count) => DecodingResult::new_i32(count, limits),
+            DecodingExtent::I64(count) => DecodingResult::new_i64(count, limits),
+        }
+    }
+
+    fn preferred_layout(self) -> TiffResult<Layout> {
+        fn overflow(_: LayoutError) -> TiffError {
+            TiffError::LimitsExceeded
+        }
+
+        match self {
+            DecodingExtent::U8(count) => Layout::array::<u8>(count),
+            DecodingExtent::U16(count) => Layout::array::<u16>(count),
+            DecodingExtent::U32(count) => Layout::array::<u32>(count),
+            DecodingExtent::U64(count) => Layout::array::<u64>(count),
+            DecodingExtent::F16(count) => Layout::array::<f16>(count),
+            DecodingExtent::F32(count) => Layout::array::<f32>(count),
+            DecodingExtent::F64(count) => Layout::array::<f64>(count),
+            DecodingExtent::I8(count) => Layout::array::<i8>(count),
+            DecodingExtent::I16(count) => Layout::array::<i16>(count),
+            DecodingExtent::I32(count) => Layout::array::<i32>(count),
+            DecodingExtent::I64(count) => Layout::array::<i64>(count),
+        }
+        .map_err(overflow)
+    }
+
+    fn assert_layout(self, buffer: usize) -> TiffResult<()> {
+        let needed_bytes = self.preferred_layout()?.size();
+        if buffer < needed_bytes {
+            Err(TiffError::UsageError(
+                UsageError::InsufficientOutputBufferSize {
+                    needed: needed_bytes,
+                    provided: buffer,
+                },
+            ))
+        } else {
+            Ok(())
+        }
+    }
+}
+
 #[derive(Debug, Copy, Clone, PartialEq)]
 /// Chunk type of the internal representation
 pub enum ChunkType {
@@ -206,6 +290,7 @@ pub enum ChunkType {
 
 /// Decoding limits
 #[derive(Clone, Debug)]
+#[non_exhaustive]
 pub struct Limits {
     /// The maximum size of any `DecodingResult` in bytes, the default is
     /// 256MiB. If the entire image is decoded at once, then this will
@@ -218,10 +303,6 @@ pub struct Limits {
     /// Maximum size for intermediate buffer which may be used to limit the amount of data read per
     /// segment even if the entire image is decoded at once.
     pub intermediate_buffer_size: usize,
-    /// The purpose of this is to prevent all the fields of the struct from
-    /// being public, as this would make adding new fields a major version
-    /// bump.
-    _non_exhaustive: (),
 }
 
 impl Limits {
@@ -234,10 +315,9 @@ impl Limits {
     /// naturally, the machine running the program does not have infinite memory.
     pub fn unlimited() -> Limits {
         Limits {
-            decoding_buffer_size: usize::max_value(),
-            ifd_value_size: usize::max_value(),
-            intermediate_buffer_size: usize::max_value(),
-            _non_exhaustive: (),
+            decoding_buffer_size: usize::MAX,
+            ifd_value_size: usize::MAX,
+            intermediate_buffer_size: usize::MAX,
         }
     }
 }
@@ -248,7 +328,6 @@ impl Default for Limits {
             decoding_buffer_size: 256 * 1024 * 1024,
             intermediate_buffer_size: 128 * 1024 * 1024,
             ifd_value_size: 1024 * 1024,
-            _non_exhaustive: (),
         }
     }
 }
@@ -289,27 +368,82 @@ pub struct IfdDecoder<'lt> {
 }
 
 fn rev_hpredict_nsamp(buf: &mut [u8], bit_depth: u8, samples: usize) {
-    match bit_depth {
-        0..=8 => {
+    fn one_byte_predict<const N: usize>(buf: &mut [u8]) {
+        for i in N..buf.len() {
+            buf[i] = buf[i].wrapping_add(buf[i - N]);
+        }
+    }
+
+    fn two_bytes_predict<const N: usize>(buf: &mut [u8]) {
+        for i in (2 * N..buf.len()).step_by(2) {
+            let v = u16::from_ne_bytes(buf[i..][..2].try_into().unwrap());
+            let p = u16::from_ne_bytes(buf[i - 2 * N..][..2].try_into().unwrap());
+            buf[i..][..2].copy_from_slice(&(v.wrapping_add(p)).to_ne_bytes());
+        }
+    }
+
+    fn four_bytes_predict<const N: usize>(buf: &mut [u8]) {
+        for i in (N * 4..buf.len()).step_by(4) {
+            let v = u32::from_ne_bytes(buf[i..][..4].try_into().unwrap());
+            let p = u32::from_ne_bytes(buf[i - 4 * N..][..4].try_into().unwrap());
+            buf[i..][..4].copy_from_slice(&(v.wrapping_add(p)).to_ne_bytes());
+        }
+    }
+
+    match (bit_depth, samples) {
+        // Note we can't use `windows` or so due to the overlap between each iteration. We split
+        // the cases by the samples / lookback constant so that each is optimized individually.
+        // This is more code generated but each loop can then have a different vectorization
+        // strategy.
+        (0..=8, 1) => one_byte_predict::<1>(buf),
+        (0..=8, 2) => one_byte_predict::<2>(buf),
+        (0..=8, 3) => one_byte_predict::<3>(buf),
+        (0..=8, 4) => one_byte_predict::<4>(buf),
+        // The generic, sub-optimal case for the above.
+        (0..=8, _) => {
             for i in samples..buf.len() {
                 buf[i] = buf[i].wrapping_add(buf[i - samples]);
             }
         }
-        9..=16 => {
+        (9..=16, 1) => {
+            two_bytes_predict::<1>(buf);
+        }
+        (9..=16, 2) => {
+            two_bytes_predict::<2>(buf);
+        }
+        (9..=16, 3) => {
+            two_bytes_predict::<3>(buf);
+        }
+        (9..=16, 4) => {
+            two_bytes_predict::<4>(buf);
+        }
+        (9..=16, _) => {
             for i in (samples * 2..buf.len()).step_by(2) {
                 let v = u16::from_ne_bytes(buf[i..][..2].try_into().unwrap());
                 let p = u16::from_ne_bytes(buf[i - 2 * samples..][..2].try_into().unwrap());
                 buf[i..][..2].copy_from_slice(&(v.wrapping_add(p)).to_ne_bytes());
             }
         }
-        17..=32 => {
+        (17..=32, 1) => {
+            four_bytes_predict::<1>(buf);
+        }
+        (17..=32, 2) => {
+            four_bytes_predict::<2>(buf);
+        }
+        (17..=32, 3) => {
+            four_bytes_predict::<3>(buf);
+        }
+        (17..=32, 4) => {
+            four_bytes_predict::<4>(buf);
+        }
+        (17..=32, _) => {
             for i in (samples * 4..buf.len()).step_by(4) {
                 let v = u32::from_ne_bytes(buf[i..][..4].try_into().unwrap());
                 let p = u32::from_ne_bytes(buf[i - 4 * samples..][..4].try_into().unwrap());
                 buf[i..][..4].copy_from_slice(&(v.wrapping_add(p)).to_ne_bytes());
             }
         }
-        33..=64 => {
+        (33..=64, _) => {
             for i in (samples * 8..buf.len()).step_by(8) {
                 let v = u64::from_ne_bytes(buf[i..][..8].try_into().unwrap());
                 let p = u64::from_ne_bytes(buf[i - 8 * samples..][..8].try_into().unwrap());
@@ -396,11 +530,22 @@ fn fix_endianness_and_predict(
     }
 }
 
-fn invert_colors(buf: &mut [u8], color_type: ColorType, sample_format: SampleFormat) {
+fn invert_colors(
+    buf: &mut [u8],
+    color_type: ColorType,
+    sample_format: SampleFormat,
+) -> TiffResult<()> {
     match (color_type, sample_format) {
-        (ColorType::Gray(8), SampleFormat::Uint) => {
+        // Where pixels do not cross a byte boundary
+        (ColorType::Gray(1 | 2 | 4 | 8), SampleFormat::Uint) => {
             for x in buf {
-                *x = 0xff - *x;
+                // Equivalent to both of the following:
+                //
+                // *x = 0xff - *x
+                // *x = !*x
+                //
+                // since -x = !x+1
+                *x = !*x;
             }
         }
         (ColorType::Gray(16), SampleFormat::Uint) => {
@@ -433,42 +578,31 @@ fn invert_colors(buf: &mut [u8], color_type: ColorType, sample_format: SampleFor
                 x.copy_from_slice(&(1.0 - v).to_ne_bytes());
             }
         }
-        _ => {}
+        _ => {
+            return Err(TiffError::UnsupportedError(
+                TiffUnsupportedError::UnknownInterpretation,
+            ))
+        }
     }
+
+    Ok(())
 }
 
 /// Fix endianness. If `byte_order` matches the host, then conversion is a no-op.
 fn fix_endianness(buf: &mut [u8], byte_order: ByteOrder, bit_depth: u8) {
-    match byte_order {
-        ByteOrder::LittleEndian => match bit_depth {
-            0..=8 => {}
-            9..=16 => buf.chunks_exact_mut(2).for_each(|v| {
-                v.copy_from_slice(&u16::from_le_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-            17..=32 => buf.chunks_exact_mut(4).for_each(|v| {
-                v.copy_from_slice(&u32::from_le_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-            _ => buf.chunks_exact_mut(8).for_each(|v| {
-                v.copy_from_slice(&u64::from_le_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-        },
-        ByteOrder::BigEndian => match bit_depth {
-            0..=8 => {}
-            9..=16 => buf.chunks_exact_mut(2).for_each(|v| {
-                v.copy_from_slice(&u16::from_be_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-            17..=32 => buf.chunks_exact_mut(4).for_each(|v| {
-                v.copy_from_slice(&u32::from_be_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-            _ => buf.chunks_exact_mut(8).for_each(|v| {
-                v.copy_from_slice(&u64::from_be_bytes((*v).try_into().unwrap()).to_ne_bytes())
-            }),
-        },
+    let host = ByteOrder::native();
+
+    let class = match bit_depth {
+        0..=8 => crate::tags::EndianBytes::One,
+        9..=16 => crate::tags::EndianBytes::Two,
+        17..=32 => crate::tags::EndianBytes::Four,
+        _ => crate::tags::EndianBytes::Eight,
     };
+
+    host.convert_endian_bytes(class, buf, byte_order);
 }
 
 impl<R: Read + Seek> Decoder<R> {
-    /// Create a new decoder that decodes from the stream ```r```
     pub fn new(mut r: R) -> TiffResult<Decoder<R>> {
         let mut endianess = Vec::with_capacity(2);
         (&mut r).take(2).read_to_end(&mut endianess)?;
@@ -652,6 +786,11 @@ impl<R: Read + Seek> Decoder<R> {
     }
 
     /// Returns the byte_order of the file.
+    ///
+    /// # Usage
+    ///
+    /// This is only relevant to interpreting raw bytes read from tags. The image decoding methods
+    /// will correct to the host byte order automatically.
     pub fn byte_order(&self) -> ByteOrder {
         self.value_reader.reader.byte_order
     }
@@ -665,6 +804,11 @@ impl<R: Read + Seek> Decoder<R> {
         }
     }
 
+    /// Returns a mutable reference to the stream being decoded.
+    pub fn inner(&mut self) -> &mut R {
+        self.value_reader.reader.inner()
+    }
+
     /// Reads a TIFF byte value
     #[inline]
     pub fn read_byte(&mut self) -> Result<u8, io::Error> {
@@ -837,17 +981,26 @@ impl<R: Read + Seek> Decoder<R> {
         chunk_index: u32,
         output_width: usize,
     ) -> TiffResult<()> {
-        let offset = self.image.chunk_file_range(chunk_index)?.0;
-        self.goto_offset_u64(offset)?;
-
         let output_row_stride = (output_width as u64)
             .saturating_mul(self.image.samples_per_pixel() as u64)
             .saturating_mul(self.image.bits_per_sample as u64)
-            / 8;
+            .div_ceil(8);
+
+        self.read_chunk_to_bytes(buffer.as_bytes_mut(), chunk_index, output_row_stride)
+    }
+
+    fn read_chunk_to_bytes(
+        &mut self,
+        buffer: &mut [u8],
+        chunk_index: u32,
+        output_row_stride: u64,
+    ) -> TiffResult<()> {
+        let offset = self.image.chunk_file_range(chunk_index)?.0;
+        self.goto_offset_u64(offset)?;
 
         self.image.expand_chunk(
             &mut self.value_reader,
-            buffer.as_bytes_mut(),
+            buffer,
             output_row_stride.try_into()?,
             chunk_index,
         )?;
@@ -856,56 +1009,109 @@ impl<R: Read + Seek> Decoder<R> {
     }
 
     fn result_buffer(&self, width: usize, height: usize) -> TiffResult<DecodingResult> {
-        let bits_per_sample = self.image().bits_per_sample;
+        self.result_extent(width, height)?
+            .to_result_buffer(&self.value_reader.limits)
+    }
 
+    // FIXME: it's unusual for this method to take a `usize` dimension parameter since those would
+    // typically come from the image data. The preferred consistent representation should be `u32`
+    // and that would avoid some unusual casts `usize -> u64` with a `u64::from` instead.
+    fn result_extent(&self, width: usize, height: usize) -> TiffResult<DecodingExtent> {
+        let bits_per_sample = self.image.bits_per_sample;
+
+        // If samples take up more than one byte, we expand it to a full number (integer or float)
+        // and the number of samples in that integer type just counts the number in the underlying
+        // image itself. Otherwise, a row is represented as the byte slice of bitfields without
+        // expansion.
         let row_samples = if bits_per_sample >= 8 {
             width
         } else {
-            ((((width as u64) * bits_per_sample as u64) + 7) / 8)
+            ((width as u64) * bits_per_sample as u64)
+                .div_ceil(8)
                 .try_into()
                 .map_err(|_| TiffError::LimitsExceeded)?
         };
 
         let buffer_size = row_samples
             .checked_mul(height)
-            .and_then(|x| x.checked_mul(self.image().samples_per_pixel()))
+            .and_then(|x| x.checked_mul(self.image.samples_per_pixel()))
             .ok_or(TiffError::LimitsExceeded)?;
 
-        let max_sample_bits = self.image().bits_per_sample;
-        let limits = &self.value_reader.limits;
+        Ok(match self.image().sample_format {
+            SampleFormat::Uint => match bits_per_sample {
+                n if n <= 8 => DecodingExtent::U8(buffer_size),
+                n if n <= 16 => DecodingExtent::U16(buffer_size),
+                n if n <= 32 => DecodingExtent::U32(buffer_size),
+                n if n <= 64 => DecodingExtent::U64(buffer_size),
+                n => {
+                    return Err(TiffError::UnsupportedError(
+                        TiffUnsupportedError::UnsupportedBitsPerChannel(n),
+                    ))
+                }
+            },
+            SampleFormat::IEEEFP => match bits_per_sample {
+                16 => DecodingExtent::F16(buffer_size),
+                32 => DecodingExtent::F32(buffer_size),
+                64 => DecodingExtent::F64(buffer_size),
+                n => {
+                    return Err(TiffError::UnsupportedError(
+                        TiffUnsupportedError::UnsupportedBitsPerChannel(n),
+                    ))
+                }
+            },
+            SampleFormat::Int => match bits_per_sample {
+                n if n <= 8 => DecodingExtent::I8(buffer_size),
+                n if n <= 16 => DecodingExtent::I16(buffer_size),
+                n if n <= 32 => DecodingExtent::I32(buffer_size),
+                n if n <= 64 => DecodingExtent::I64(buffer_size),
+                n => {
+                    return Err(TiffError::UnsupportedError(
+                        TiffUnsupportedError::UnsupportedBitsPerChannel(n),
+                    ))
+                }
+            },
+            format => {
+                return Err(TiffUnsupportedError::UnsupportedSampleFormat(vec![format]).into())
+            }
+        })
+    }
 
-        match self.image().sample_format {
-            SampleFormat::Uint => match max_sample_bits {
-                n if n <= 8 => DecodingResult::new_u8(buffer_size, limits),
-                n if n <= 16 => DecodingResult::new_u16(buffer_size, limits),
-                n if n <= 32 => DecodingResult::new_u32(buffer_size, limits),
-                n if n <= 64 => DecodingResult::new_u64(buffer_size, limits),
-                n => Err(TiffError::UnsupportedError(
-                    TiffUnsupportedError::UnsupportedBitsPerChannel(n),
-                )),
-            },
-            SampleFormat::IEEEFP => match max_sample_bits {
-                16 => DecodingResult::new_f16(buffer_size, limits),
-                32 => DecodingResult::new_f32(buffer_size, limits),
-                64 => DecodingResult::new_f64(buffer_size, limits),
-                n => Err(TiffError::UnsupportedError(
-                    TiffUnsupportedError::UnsupportedBitsPerChannel(n),
-                )),
-            },
-            SampleFormat::Int => match max_sample_bits {
-                n if n <= 8 => DecodingResult::new_i8(buffer_size, limits),
-                n if n <= 16 => DecodingResult::new_i16(buffer_size, limits),
-                n if n <= 32 => DecodingResult::new_i32(buffer_size, limits),
-                n if n <= 64 => DecodingResult::new_i64(buffer_size, limits),
-                n => Err(TiffError::UnsupportedError(
-                    TiffUnsupportedError::UnsupportedBitsPerChannel(n),
-                )),
-            },
-            format => Err(TiffUnsupportedError::UnsupportedSampleFormat(vec![format]).into()),
-        }
+    /// Returns the layout preferred to read the specified chunk with [`Self::read_chunk_bytes`].
+    ///
+    /// Returns the layout without being specific as to the underlying type for forward
+    /// compatibility. Note that, in general, a TIFF may contain an almost arbitrary number of
+    /// channels of individual *bit* length and format each.
+    ///
+    /// See [`Self::colortype`] to describe the sample types.
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only
+    /// indicate the layout needed to read the first data plane. This will be fixed in a future
+    /// major version of `tiff`.
+    pub fn image_chunk_buffer_layout(
+        &mut self,
+        chunk_index: u32,
+    ) -> TiffResult<BufferLayoutPreference> {
+        let data_dims = self.image().chunk_data_dimensions(chunk_index)?;
+        let layout = self
+            .result_extent(data_dims.0 as usize, data_dims.1 as usize)?
+            .preferred_layout()?;
+
+        let row_stride = self.image.minimum_row_stride(data_dims);
+
+        Ok(BufferLayoutPreference {
+            len: layout.size(),
+            row_stride,
+        })
     }
 
     /// Read the specified chunk (at index `chunk_index`) and return the binary data as a Vector.
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only read
+    /// the first sample's plane. This will be fixed in a future major version of `tiff`.
     pub fn read_chunk(&mut self, chunk_index: u32) -> TiffResult<DecodingResult> {
         let data_dims = self.image().chunk_data_dimensions(chunk_index)?;
 
@@ -916,6 +1122,32 @@ impl<R: Read + Seek> Decoder<R> {
         Ok(result)
     }
 
+    /// Read the specified chunk (at index `chunk_index`) into an allocated buffer.
+    ///
+    /// Returns a [`TiffError::UsageError`] if the chunk is smaller than the size indicated with a
+    /// call to [`Self::image_chunk_buffer_layout`]. Note that the alignment may be arbitrary, but
+    /// an alignment smaller than the preferred alignment may perform worse.
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only read
+    /// the first sample's plane. This will be fixed in a future major version of `tiff`.
+    pub fn read_chunk_bytes(&mut self, chunk_index: u32, buffer: &mut [u8]) -> TiffResult<()> {
+        let data_dims = self.image().chunk_data_dimensions(chunk_index)?;
+
+        let extent = self.result_extent(data_dims.0 as usize, data_dims.1 as usize)?;
+        extent.assert_layout(buffer.len())?;
+
+        let output_row_stride = u64::from(data_dims.0)
+            .saturating_mul(self.image.samples_per_pixel() as u64)
+            .saturating_mul(self.image.bits_per_sample as u64)
+            .div_ceil(8);
+
+        self.read_chunk_to_bytes(buffer, chunk_index, output_row_stride)?;
+
+        Ok(())
+    }
+
     /// Returns the default chunk size for the current image. Any given chunk in the image is at most as large as
     /// the value returned here. For the size of the data (chunk minus padding), use `chunk_data_dimensions`.
     pub fn chunk_dimensions(&self) -> (u32, u32) {
@@ -930,13 +1162,69 @@ impl<R: Read + Seek> Decoder<R> {
             .expect("invalid chunk_index")
     }
 
+    /// Returns the preferred buffer required to read the whole image with [`Self::read_image_bytes`].
+    ///
+    /// Returns the layout without being specific as to the underlying type for forward
+    /// compatibility. Note that, in general, a TIFF may contain an almost arbitrary number of
+    /// channels of individual *bit* length and format each.
+    ///
+    /// See [`Self::colortype`] to describe the sample types.
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only
+    /// indicate the layout needed to read the first data plane. This will be fixed in a future
+    /// major version of `tiff`.
+    pub fn image_buffer_layout(&mut self) -> TiffResult<BufferLayoutPreference> {
+        let data_dims @ (width, height) = (self.image.width, self.image.height);
+
+        let layout = self
+            .result_extent(width as usize, height as usize)?
+            .preferred_layout()?;
+
+        let row_stride = self.image.minimum_row_stride(data_dims);
+
+        Ok(BufferLayoutPreference {
+            len: layout.size(),
+            row_stride,
+        })
+    }
+
     /// Decodes the entire image and return it as a Vector
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only read
+    /// the first sample's plane. This will be fixed in a future major version of `tiff`.
     pub fn read_image(&mut self) -> TiffResult<DecodingResult> {
         let width = self.image().width;
         let height = self.image().height;
+
         let mut result = self.result_buffer(width as usize, height as usize)?;
+        self.read_image_bytes(result.as_buffer(0).as_bytes_mut())?;
+
+        Ok(result)
+    }
+
+    /// Decodes the entire image into a provided buffer.
+    ///
+    /// Returns a [`TiffError::UsageError`] if the chunk is smaller than the size indicated with a
+    /// call to [`Self::image_buffer_layout`]. Note that the alignment may be arbitrary, but an
+    /// alignment smaller than the preferred alignment may perform worse.
+    ///
+    /// # Bugs
+    ///
+    /// When the image is stored as a planar configuration, this method will currently only read
+    /// the first sample's plane. This will be fixed in a future major version of `tiff`.
+    pub fn read_image_bytes(&mut self, buffer: &mut [u8]) -> TiffResult<()> {
+        let width = self.image().width;
+        let height = self.image().height;
+
+        let extent = self.result_extent(width as usize, height as usize)?;
+        extent.assert_layout(buffer.len())?;
+
         if width == 0 || height == 0 {
-            return Ok(result);
+            return Ok(());
         }
 
         let chunk_dimensions = self.image().chunk_dimensions()?;
@@ -960,12 +1248,12 @@ impl<R: Read + Seek> Decoder<R> {
         let output_row_bits = (width as u64 * self.image.bits_per_sample as u64)
             .checked_mul(samples as u64)
             .ok_or(TiffError::LimitsExceeded)?;
-        let output_row_stride: usize = ((output_row_bits + 7) / 8).try_into()?;
+        let output_row_stride: usize = output_row_bits.div_ceil(8).try_into()?;
 
         let chunk_row_bits = (chunk_dimensions.0 as u64 * self.image.bits_per_sample as u64)
             .checked_mul(samples as u64)
             .ok_or(TiffError::LimitsExceeded)?;
-        let chunk_row_bytes: usize = ((chunk_row_bits + 7) / 8).try_into()?;
+        let chunk_row_bytes: usize = chunk_row_bits.div_ceil(8).try_into()?;
 
         let chunks_across = ((width - 1) / chunk_dimensions.0 + 1) as usize;
 
@@ -989,13 +1277,13 @@ impl<R: Read + Seek> Decoder<R> {
                 y * output_row_stride * chunk_dimensions.1 as usize + x * chunk_row_bytes;
             self.image.expand_chunk(
                 &mut self.value_reader,
-                &mut result.as_buffer(0).as_bytes_mut()[buffer_offset..],
+                &mut buffer[buffer_offset..],
                 output_row_stride,
                 chunk as u32,
             )?;
         }
 
-        Ok(result)
+        Ok(())
     }
 
     /// Get the IFD decoder for our current image IFD.
@@ -1053,6 +1341,15 @@ impl<R: Read + Seek> Decoder<R> {
         self.image_ifd().find_tag_unsigned(tag)
     }
 
+    /// Tries to retrieve a vector of all a tag's values and convert them to the desired unsigned
+    /// type.
+    pub fn find_tag_unsigned_vec<T: TryFrom<u64>>(
+        &mut self,
+        tag: Tag,
+    ) -> TiffResult<Option<Vec<T>>> {
+        self.image_ifd().find_tag_unsigned_vec(tag)
+    }
+
     /// Tries to retrieve a tag from the current image directory and convert it to the desired
     /// unsigned type. Returns an error if the tag is not present.
     pub fn get_tag_unsigned<T: TryFrom<u64>>(&mut self, tag: Tag) -> TiffResult<T> {

src/decoder/stream.rs

@@ -1,15 +1,7 @@
 //! All IO functionality needed for TIFF decoding
-
 use std::io::{self, BufRead, BufReader, Read, Seek, Take};
 
-/// Byte order of the TIFF file.
-#[derive(Clone, Copy, Debug)]
-pub enum ByteOrder {
-    /// little endian byte order
-    LittleEndian,
-    /// big endian byte order
-    BigEndian,
-}
+pub use crate::tags::ByteOrder;
 
 /// Reader that is aware of the byte order.
 #[derive(Debug)]
@@ -46,17 +38,6 @@ impl<R: Read> EndianReader<R> {
         })
     }
 
-    /// Reads an i8
-    #[inline(always)]
-    pub fn read_i8(&mut self) -> Result<i8, io::Error> {
-        let mut n = [0u8; 1];
-        self.reader.read_exact(&mut n)?;
-        Ok(match self.byte_order {
-            ByteOrder::LittleEndian => i8::from_le_bytes(n),
-            ByteOrder::BigEndian => i8::from_be_bytes(n),
-        })
-    }
-
     /// Reads an i16
     #[inline(always)]
     pub fn read_i16(&mut self) -> Result<i16, io::Error> {
@@ -135,20 +116,17 @@ impl<R: Read> EndianReader<R> {
     }
 }
 
-///
-/// # READERS
-///
-
-///
-/// ## Deflate Reader
-///
+//
+// # READERS
+//
 
+/// Type alias for the deflate Reader
 #[cfg(feature = "deflate")]
 pub type DeflateReader<R> = flate2::read::ZlibDecoder<R>;
 
-///
-/// ## LZW Reader
-///
+//
+// ## LZW Reader
+//
 
 /// Reader that decompresses LZW streams
 #[cfg(feature = "lzw")]
@@ -190,9 +168,6 @@ impl<R: Read> Read for LZWReader<R> {
                     }
                 }
                 Ok(weezl::LzwStatus::NoProgress) => {
-                    assert_eq!(result.consumed_in, 0);
-                    assert_eq!(result.consumed_out, 0);
-                    assert!(self.reader.buffer().is_empty());
                     return Err(io::Error::new(
                         io::ErrorKind::UnexpectedEof,
                         "no lzw end code found",
@@ -207,10 +182,11 @@ impl<R: Read> Read for LZWReader<R> {
     }
 }
 
-///
-/// ## PackBits Reader
-///
+//
+// ## PackBits Reader
+//
 
+/// Internal state machine for the PackBitsReader.
 enum PackBitsReaderState {
     Header,
     Literal,
@@ -278,6 +254,106 @@ impl<R: Read> Read for PackBitsReader<R> {
     }
 }
 
+#[cfg(feature = "fax")]
+pub struct Group4Reader<R: Read> {
+    decoder: fax34::decoder::Group4Decoder<io::Bytes<io::BufReader<io::Take<R>>>>,
+    line_buf: io::Cursor<Vec<u8>>,
+    height: u16,
+    width: u16,
+    y: u16,
+}
+
+#[cfg(feature = "fax")]
+impl<R: Read> Group4Reader<R> {
+    pub fn new(
+        dimensions: (u32, u32),
+        reader: R,
+        compressed_length: u64,
+    ) -> crate::TiffResult<Self> {
+        let width = u16::try_from(dimensions.0)?;
+        let height = u16::try_from(dimensions.1)?;
+
+        Ok(Self {
+            decoder: fax34::decoder::Group4Decoder::new(
+                io::BufReader::new(reader.take(compressed_length)).bytes(),
+                width,
+            )?,
+            line_buf: io::Cursor::new(Vec::with_capacity(width.into())),
+            width,
+            height,
+            y: 0,
+        })
+    }
+}
+
+#[cfg(feature = "fax")]
+impl<R: Read> Read for Group4Reader<R> {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        // Either we have not read any line or we are at the end of a line.
+        if self.line_buf.position() as usize == self.line_buf.get_ref().len()
+            && self.y < self.height
+        {
+            let next = self.decoder.advance().map_err(std::io::Error::other)?;
+
+            match next {
+                fax34::decoder::DecodeStatus::End => (),
+                fax34::decoder::DecodeStatus::Incomplete => {
+                    self.y += 1;
+
+                    // We known `transitions` yields exactly `self.width` items (per doc).
+                    // FIXME: performance. We do not need an individual pixel iterator, filling
+                    // memory especially for long runs can be much quicker. The `transitions` are
+                    // the positions at which each run-length ends, i.e. the prefix sum of run
+                    // lengths. Runs in fax4 start with white.
+                    let transitions = fax34::decoder::pels(self.decoder.transition(), self.width);
+
+                    let buffer = self.line_buf.get_mut();
+                    buffer.resize(usize::from(self.width).div_ceil(8), 0u8);
+
+                    let target = &mut buffer[..];
+
+                    // Note: it may seem strange to treat black as 0b1 and white as 0b0 despite all
+                    // our streams by default decoding as-if PhotometricInterpretation::BlackIsMin.
+                    // This is however consistent with libtiff. It seems that fax4's "White"
+                    // differs from what libtiff thinks of as "White". For content, a line of data
+                    // is in runlength encoding of white-black-white-black always starting with
+                    // white. In libtiff, the loop always does both colors in one go and the
+                    // structure is:
+                    //
+                    // ```
+                    // for (; runs < erun; runs += 2)
+                    //   // white run
+                    //       do { *lp++ = 0L; } while (…)
+                    //   // black run
+                    //       do { *lp++ = -1L; } while (…)
+                    // ```
+                    //
+                    // So indeed the Fax4::White run is implemented by filling with zeros.
+                    let mut bits = transitions.map(|c| match c {
+                        fax34::Color::Black => true,
+                        fax34::Color::White => false,
+                    });
+
+                    // Assemble bits in MSB as per our library representation for buffer.
+                    for byte in target {
+                        let mut val = 0;
+
+                        for (idx, bit) in bits.by_ref().take(8).enumerate() {
+                            val |= u8::from(bit) << (7 - idx % 8);
+                        }
+
+                        *byte = val;
+                    }
+
+                    self.line_buf.set_position(0);
+                }
+            }
+        }
+
+        self.line_buf.read(buf)
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

src/directory.rs

@@ -27,6 +27,8 @@ pub struct Directory {
 }
 
 impl Directory {
+    /// Create a directory in an initial state without entries. Note that an empty directory can
+    /// not be encoded in a file, it must contain at least one entry.
     pub fn empty() -> Self {
         Directory {
             entries: BTreeMap::new(),
@@ -72,6 +74,12 @@ impl Directory {
         self.entries.len()
     }
 
+    /// Check if there are any entries in this directory. Note that an empty directory can not be
+    /// encoded in the file, it must contain at least one entry.
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
     /// Get the pointer to the next IFD, if it was defined.
     pub fn next(&self) -> Option<IfdPointer> {
         self.next_ifd.map(|n| IfdPointer(n.get()))
@@ -96,6 +104,28 @@ impl Directory {
             }
         }
     }
+
+    pub(crate) fn encoded_len<K: crate::encoder::TiffKind>(&self) -> u64 {
+        let (len_count, len_offset);
+
+        match std::mem::size_of::<K::OffsetType>() {
+            offset @ 4 => {
+                // non-BigTiff uses a `u16` here.
+                len_count = 2;
+                len_offset = offset as u64;
+            }
+            offset => {
+                let offset = offset as u64;
+                // assuming BigTIFF
+                len_count = offset;
+                len_offset = offset;
+            }
+        }
+
+        // Each entry is 12 bytes in classic TIFF, 20 bytes in BigTIFF.
+        let entry_bytes = 4 + 2 * len_offset;
+        len_count + entry_bytes * self.entries.len() as u64 + len_offset
+    }
 }
 
 impl fmt::Debug for Directory {
@@ -110,6 +140,14 @@ impl fmt::Debug for Directory {
     }
 }
 
+impl core::iter::FromIterator<(Tag, Entry)> for Directory {
+    fn from_iter<T: IntoIterator<Item = (Tag, Entry)>>(iter: T) -> Self {
+        let mut dir = Directory::empty();
+        dir.extend(iter);
+        dir
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::Directory;

src/encoder/compression/deflate.rs

@@ -11,21 +11,17 @@ pub struct Deflate {
 /// It allows trading compression ratio for compression speed.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 #[non_exhaustive]
+#[derive(Default)]
 pub enum DeflateLevel {
     /// The fastest possible compression mode.
     Fast = 1,
     /// The conserative choice between speed and ratio.
+    #[default]
     Balanced = 6,
     /// The best compression available with Deflate.
     Best = 9,
 }
 
-impl Default for DeflateLevel {
-    fn default() -> Self {
-        DeflateLevel::Balanced
-    }
-}
-
 impl Deflate {
     /// Create a new deflate compressor with a specific level of compression.
     pub fn with_level(level: DeflateLevel) -> Self {

src/encoder/compression/uncompressed.rs

@@ -14,7 +14,7 @@ impl Compression for Uncompressed {
 
 impl CompressionAlgorithm for Uncompressed {
     fn write_to<W: Write>(&mut self, writer: &mut W, bytes: &[u8]) -> Result<u64, io::Error> {
-        writer.write(bytes).map(|byte_count| byte_count as u64)
+        writer.write_all(bytes).map(|()| bytes.len() as u64)
     }
 }
 

src/encoder/mod.rs

@@ -37,8 +37,9 @@ pub type Predictor = crate::tags::Predictor;
 #[cfg(feature = "deflate")]
 pub type DeflateLevel = compression::DeflateLevel;
 
-#[derive(Clone, Copy, PartialEq)]
+#[derive(Clone, Copy, PartialEq, Default)]
 pub enum Compression {
+    #[default]
     Uncompressed,
     #[cfg(feature = "lzw")]
     Lzw,
@@ -47,12 +48,6 @@ pub enum Compression {
     Packbits,
 }
 
-impl Default for Compression {
-    fn default() -> Self {
-        Self::Uncompressed
-    }
-}
-
 impl Compression {
     fn tag(&self) -> CompressionMethod {
         match self {
@@ -79,10 +74,10 @@ impl Compression {
 
 /// Encoder for Tiff and BigTiff files.
 ///
-/// With this type you can get a `DirectoryEncoder` or a `ImageEncoder`
+/// With this type you can get a [`DirectoryEncoder`] or a [`ImageEncoder`]
 /// to encode Tiff/BigTiff ifd directories with images.
 ///
-/// See `DirectoryEncoder` and `ImageEncoder`.
+/// See [`DirectoryEncoder`] and [`ImageEncoder`].
 ///
 /// # Examples
 /// ```
@@ -176,7 +171,7 @@ impl<W: Write + Seek, K: TiffKind> TiffEncoder<W, K> {
         Self::chain_directory(&mut self.writer, &mut self.last_ifd_chain)
     }
 
-    /// Create a [`DirectoryEncoder`] to encode an ifd directory.
+    /// Create a [`DirectoryEncoder`] to encode an ifd (directory).
     ///
     /// The caller is responsible for ensuring that the directory is a valid image in the main TIFF
     /// IFD sequence. To encode additional directories that are not linked into the sequence, use
@@ -185,7 +180,7 @@ impl<W: Write + Seek, K: TiffKind> TiffEncoder<W, K> {
         Self::chain_directory(&mut self.writer, &mut self.last_ifd_chain)
     }
 
-    /// Create a [`DirectoryEncoder`] to encode an ifd directory.
+    /// Create a [`DirectoryEncoder`] to encode a non-image directory.
     ///
     /// The directory is not linked into the sequence of directories. For instance, encode Exif
     /// directories or SubIfd directories with this method.
@@ -198,7 +193,7 @@ impl<W: Write + Seek, K: TiffKind> TiffEncoder<W, K> {
         &mut self,
         width: u32,
         height: u32,
-    ) -> TiffResult<ImageEncoder<W, C, K>> {
+    ) -> TiffResult<ImageEncoder<'_, W, C, K>> {
         let encoder = Self::chain_directory(&mut self.writer, &mut self.last_ifd_chain)?;
         ImageEncoder::new(encoder, width, height, self.compression, self.predictor)
     }
@@ -249,6 +244,12 @@ pub struct DirectoryEncoder<'a, W: 'a + Write + Seek, K: TiffKind> {
 }
 
 /// The offset of an encoded directory in the file.
+///
+/// Both the `offset` and `pointer` field are a complete description of the start offset of the
+/// dictionary which is used to point to it. The struct also describes the extent covered by the
+/// encoding of the directory. The constructors [`new`][DirectoryOffset::new] allow the checked
+/// conversion. Note that even though the offsets are public do not expect their information to
+/// propagate when modified.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct DirectoryOffset<K: TiffKind> {
     /// The start of the directory as a Tiff value.
@@ -260,7 +261,9 @@ pub struct DirectoryOffset<K: TiffKind> {
     pub offset: K::OffsetType,
     /// The start of the directory as a pure offset.
     pub pointer: IfdPointer,
-    /// The offset of its sequence link field, in our private representation.
+    /// The offset of its sequence link field, in our private representation. Before exposing this
+    /// make sure that we don't want any invariants (e.g. pointer being smaller than this). The
+    /// type should be fine.
     ifd_chain: NonZeroU64,
     /// The kind of Tiff file the offset is for.
     kind: PhantomData<K>,
@@ -296,7 +299,7 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         }
 
         let entry = Self::write_value(
-            &mut self.writer,
+            self.writer,
             &DirectoryEntry {
                 data_type: <T>::FIELD_TYPE,
                 count: value.count().try_into()?,
@@ -318,6 +321,17 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         Ok(offset)
     }
 
+    /// Insert previously written key-value entries.
+    ///
+    /// It is the caller's responsibility to ensure that the data referred to by the entries is
+    /// actually (or will be) written to the file. Note that small values are necessarily inline in
+    /// the entry, the size limit depends on the Tiff kind. So do not confuse a directory from a
+    /// BigTiff in a standard tiff or the other way around.
+    pub fn extend_from(&mut self, dir: &Directory) {
+        let entries = dir.iter().map(|(tag, val)| (tag, val.clone()));
+        self.directory.extend(entries);
+    }
+
     /// Define the parent directory.
     ///
     /// Each directory has an offset based link to its successor, forming a linked list in the
@@ -334,6 +348,11 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         Ok(())
     }
 
+    /// Write the IFD to the file and return the offset it is written to.
+    ///
+    /// The offset can be used as the value, or as part of a list of values, in the entry of
+    /// another directory. If you're constructing the entry directly you'll want to use an
+    /// appropriate type variant for this such as [`Type::IFD`].
     pub fn finish_with_offsets(mut self) -> TiffResult<DirectoryOffset<K>> {
         self.finish_internal()
     }
@@ -370,14 +389,14 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
 
         if bytes.len() > in_entry_bytes {
             let offset = writer.offset();
-            writer.write_bytes(&bytes)?;
+            writer.write_bytes(bytes)?;
 
             let offset = K::convert_offset(offset)?;
             offset_bytes[..offset.bytes()].copy_from_slice(&offset.data());
         } else {
             // Note: we have indicated our native byte order in the header, hence this
             // corresponds to our byte order no matter the value type.
-            offset_bytes[..bytes.len()].copy_from_slice(&bytes);
+            offset_bytes[..bytes.len()].copy_from_slice(bytes);
         }
 
         // Undoing some hidden type. Offset is either u32 or u64. Due to the trait API being public
@@ -532,11 +551,11 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
         let rows_per_strip = {
             match compression.tag() {
                 CompressionMethod::PackBits => 1, // Each row must be packed separately. Do not compress across row boundaries
-                _ => (1_000_000 + row_bytes - 1) / row_bytes,
+                _ => 1_000_000_u64.div_ceil(row_bytes),
             }
         };
 
-        let strip_count = (u64::from(height) + rows_per_strip - 1) / rows_per_strip;
+        let strip_count = u64::from(height).div_ceil(rows_per_strip);
 
         encoder.write_tag(Tag::ImageWidth, width)?;
         encoder.write_tag(Tag::ImageLength, height)?;
@@ -705,7 +724,7 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
         self.encoder.write_tag(Tag::RowsPerStrip, value)?;
 
         let value: u64 = value as u64;
-        self.strip_count = (self.height as u64 + value - 1) / value;
+        self.strip_count = (self.height as u64).div_ceil(value);
         self.rows_per_strip = value;
 
         Ok(())
@@ -791,6 +810,71 @@ pub trait TiffKind {
     fn convert_slice(slice: &[Self::OffsetType]) -> &Self::OffsetArrayType;
 }
 
+impl<K: TiffKind> DirectoryOffset<K> {
+    /// Construct the directory pointer information from its raw offset.
+    ///
+    /// Fails in these cases:
+    ///
+    /// - if start offset is too large to be represented with the chosen TIFF format, i.e. a value
+    ///   larger than [`u32::MAX`] with a standard tiff which is only valid in a BigTiff. This
+    ///   returns [`TiffError::IntSizeError`].
+    /// - the extent of the directory would overflow the file length. This returns a
+    ///   [`TiffError::UsageError`].
+    ///
+    /// The library does *not* validate the contents or offset in any way, it just performs the
+    /// necessary math assuming the data is an accurate representation of existing content.
+    ///
+    /// # Examples
+    ///
+    /// If you have any custom way of writing a directory to a file that can not go through the
+    /// usual [`TiffEncoder::extra_directory`] then you can reconstruct the offset information as
+    /// long as you provide all the necessary data to the library. You can then use it as a parent
+    /// directory, i.e. have the library overwrite its `next` field.
+    ///
+    /// ```
+    /// use tiff::{
+    ///     encoder::{TiffEncoder, DirectoryOffset},
+    ///     Directory,
+    ///     tags::IfdPointer,
+    /// };
+    ///
+    /// # let mut file = std::io::Cursor::new(Vec::new());
+    /// let mut tiff = TiffEncoder::new(&mut file)?;
+    ///
+    /// // … some custom data writes, assume we know where a directory was written
+    /// # fn reconstruction_of_your_directory() -> Directory { Directory::from_iter([]) }
+    /// let known_offset = IfdPointer(1024);
+    /// let known_contents: Directory = reconstruction_of_your_directory();
+    ///
+    /// let reconstructed = DirectoryOffset::new(known_offset, &known_contents)?;
+    ///
+    /// // Now we can use it as if the directory was written by the `TiffEncoder` itself.
+    /// let mut chain = tiff.extra_directory()?;
+    /// chain.set_parent(&reconstructed);
+    /// chain.finish_with_offsets()?;
+    ///
+    /// # Ok::<_, tiff::TiffError>(())
+    /// ```
+    pub fn new(pointer: IfdPointer, dir: &Directory) -> TiffResult<Self> {
+        let offset = K::convert_offset(pointer.0)?;
+        let encoded = dir.encoded_len::<K>();
+        let offset_field_offset = encoded - mem::size_of_val(&offset) as u64;
+
+        let ifd_chain = pointer
+            .0
+            .checked_add(offset_field_offset)
+            .and_then(NonZeroU64::new)
+            .ok_or(TiffError::UsageError(UsageError::ZeroIfdPointer))?;
+
+        Ok(DirectoryOffset {
+            pointer,
+            offset,
+            ifd_chain,
+            kind: PhantomData,
+        })
+    }
+}
+
 /// Create a standard Tiff file.
 pub struct TiffKindStandard;
 
@@ -859,3 +943,33 @@ impl TiffKind for TiffKindBig {
         slice
     }
 }
+
+#[test]
+fn directory_offset_new_equivalent_to_writing() {
+    type K = TiffKindStandard;
+
+    let dir = Directory::from_iter(vec![
+        (
+            Tag::ImageWidth,
+            Entry::new(Type::LONG, 1, 100u32.to_ne_bytes()),
+        ),
+        (
+            Tag::ImageLength,
+            Entry::new(Type::LONG, 1, 200u32.to_ne_bytes()),
+        ),
+    ]);
+
+    let data = std::io::Cursor::new(vec![]);
+    let mut file = TiffEncoder::new(data).unwrap();
+
+    let mut as_dir_encoder = file.extra_directory().unwrap();
+    as_dir_encoder.extend_from(&dir);
+    let dir_extent = as_dir_encoder.finish_with_offsets().unwrap();
+
+    // Check we can recreate the extent had we written ourselves.
+    let synth = DirectoryOffset::<K>::new(dir_extent.pointer, &dir).unwrap();
+
+    assert_eq!(synth.pointer, dir_extent.pointer);
+    assert_eq!(synth.offset, dir_extent.offset);
+    assert_eq!(synth.ifd_chain, dir_extent.ifd_chain);
+}

src/encoder/tiff_value.rs

@@ -15,7 +15,7 @@ pub trait TiffValue {
 
     /// Access this value as an contiguous sequence of bytes.
     /// If their is no trivial representation, allocate it on the heap.
-    fn data(&self) -> Cow<[u8]>;
+    fn data(&self) -> Cow<'_, [u8]>;
 
     /// Write this value to a TiffWriter.
     /// While the default implementation will work in all cases, it may require unnecessary allocations.
@@ -34,7 +34,7 @@ impl TiffValue for [u8] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(self)
     }
 }
@@ -47,7 +47,7 @@ impl TiffValue for [i8] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i8_as_ne_bytes(self))
     }
 }
@@ -60,7 +60,7 @@ impl TiffValue for [u16] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u16_as_ne_bytes(self))
     }
 }
@@ -73,7 +73,7 @@ impl TiffValue for [i16] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i16_as_ne_bytes(self))
     }
 }
@@ -86,7 +86,7 @@ impl TiffValue for [u32] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u32_as_ne_bytes(self))
     }
 }
@@ -99,7 +99,7 @@ impl TiffValue for [i32] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i32_as_ne_bytes(self))
     }
 }
@@ -112,7 +112,7 @@ impl TiffValue for [u64] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u64_as_ne_bytes(self))
     }
 }
@@ -125,7 +125,7 @@ impl TiffValue for [i64] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i64_as_ne_bytes(self))
     }
 }
@@ -138,7 +138,7 @@ impl TiffValue for [f32] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         // We write using native endian so this should be safe
         Cow::Borrowed(bytecast::f32_as_ne_bytes(self))
     }
@@ -152,7 +152,7 @@ impl TiffValue for [f64] {
         self.len()
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         // We write using native endian so this should be safe
         Cow::Borrowed(bytecast::f64_as_ne_bytes(self))
     }
@@ -171,7 +171,7 @@ impl TiffValue for u8 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(from_ref(self))
     }
 }
@@ -189,7 +189,7 @@ impl TiffValue for i8 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i8_as_ne_bytes(from_ref(self)))
     }
 }
@@ -207,7 +207,7 @@ impl TiffValue for u16 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u16_as_ne_bytes(from_ref(self)))
     }
 }
@@ -225,7 +225,7 @@ impl TiffValue for i16 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i16_as_ne_bytes(from_ref(self)))
     }
 }
@@ -243,7 +243,7 @@ impl TiffValue for u32 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u32_as_ne_bytes(from_ref(self)))
     }
 }
@@ -261,7 +261,7 @@ impl TiffValue for i32 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i32_as_ne_bytes(from_ref(self)))
     }
 }
@@ -279,7 +279,7 @@ impl TiffValue for u64 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u64_as_ne_bytes(from_ref(self)))
     }
 }
@@ -297,7 +297,7 @@ impl TiffValue for i64 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::i64_as_ne_bytes(from_ref(self)))
     }
 }
@@ -315,7 +315,7 @@ impl TiffValue for f32 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::f32_as_ne_bytes(from_ref(self)))
     }
 }
@@ -333,7 +333,7 @@ impl TiffValue for f64 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::f64_as_ne_bytes(from_ref(self)))
     }
 }
@@ -351,7 +351,7 @@ impl TiffValue for Ifd {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u32_as_ne_bytes(from_ref(&self.0)))
     }
 }
@@ -369,7 +369,7 @@ impl TiffValue for Ifd8 {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Borrowed(bytecast::u64_as_ne_bytes(from_ref(&self.0)))
     }
 }
@@ -388,7 +388,7 @@ impl TiffValue for Rational {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Owned({
             let first_dword = bytecast::u32_as_ne_bytes(from_ref(&self.n));
             let second_dword = bytecast::u32_as_ne_bytes(from_ref(&self.d));
@@ -411,7 +411,7 @@ impl TiffValue for SRational {
         Ok(())
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Owned({
             let first_dword = bytecast::i32_as_ne_bytes(from_ref(&self.n));
             let second_dword = bytecast::i32_as_ne_bytes(from_ref(&self.d));
@@ -438,7 +438,7 @@ impl TiffValue for str {
         }
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         Cow::Owned({
             if self.is_ascii() && !self.bytes().any(|b| b == 0) {
                 let bytes: &[u8] = self.as_bytes();
@@ -450,7 +450,7 @@ impl TiffValue for str {
     }
 }
 
-impl<'a, T: TiffValue + ?Sized> TiffValue for &'a T {
+impl<T: TiffValue + ?Sized> TiffValue for &'_ T {
     const BYTE_LEN: u8 = T::BYTE_LEN;
     const FIELD_TYPE: Type = T::FIELD_TYPE;
 
@@ -462,7 +462,7 @@ impl<'a, T: TiffValue + ?Sized> TiffValue for &'a T {
         (*self).write(writer)
     }
 
-    fn data(&self) -> Cow<[u8]> {
+    fn data(&self) -> Cow<'_, [u8]> {
         T::data(self)
     }
 }
@@ -484,7 +484,7 @@ macro_rules! impl_tiff_value_for_contiguous_sequence {
                 Ok(())
             }
 
-            fn data(&self) -> Cow<[u8]> {
+            fn data(&self) -> Cow<'_, [u8]> {
                 let mut buf: Vec<u8> = Vec::with_capacity(Self::BYTE_LEN as usize * self.len());
                 for x in self {
                     buf.extend_from_slice(&x.data());

src/encoder/writer.rs

@@ -190,3 +190,58 @@ impl<W: Seek> TiffWriter<W> {
         Ok(())
     }
 }
+
+#[test]
+fn encoder_on_short_writes() {
+    struct ShortWriter<T> {
+        inner: T,
+    }
+
+    impl<T: std::io::Write> std::io::Write for ShortWriter<T> {
+        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+            let lower_bound = buf.len().min(1);
+            let lower = buf.len().saturating_sub(1).max(lower_bound);
+
+            self.inner.write(&buf[..lower])
+        }
+
+        fn flush(&mut self) -> std::io::Result<()> {
+            self.inner.flush()
+        }
+    }
+
+    impl<T: std::io::Seek> std::io::Seek for ShortWriter<T> {
+        fn seek(&mut self, pos: std::io::SeekFrom) -> std::io::Result<u64> {
+            self.inner.seek(pos)
+        }
+    }
+
+    let mut write = ShortWriter {
+        inner: std::io::Cursor::new(vec![0u8; 0]),
+    };
+
+    let imgdata = vec![42u8; 100 * 100];
+    for comp in [
+        super::Compression::Uncompressed,
+        super::Compression::Packbits,
+    ] {
+        write.inner.set_position(0);
+        write.inner.get_mut().clear();
+
+        {
+            let mut tiff_writer = super::TiffEncoder::new(&mut write)
+                .unwrap()
+                .with_compression(comp);
+
+            tiff_writer
+                .write_image::<super::Gray8>(100, 100, &imgdata)
+                .unwrap();
+        }
+
+        write.inner.set_position(0);
+        let mut tiff_reader = crate::decoder::Decoder::new(&mut write.inner).unwrap();
+        let data = tiff_reader.read_image().unwrap();
+
+        assert!(matches!(data, crate::decoder::DecodingResult::U8(v) if v == imgdata));
+    }
+}

src/error.rs

@@ -184,6 +184,12 @@ quick_error! {
         PredictorUnavailable {
             display("the requested predictor is not available")
         }
+        InsufficientOutputBufferSize { needed: usize, provided: usize } {
+            display("the borrowed output buffer is not large enough for the decoded data, needed {needed} but have {provided}")
+        }
+        ZeroIfdPointer {
+            display("the offset 0 can not point to a valid IFD")
+        }
     }
 }
 

src/tags.rs

@@ -2,7 +2,7 @@ macro_rules! tags {
     {
         // Permit arbitrary meta items, which include documentation.
         $( #[$enum_attr:meta] )*
-        $vis:vis enum $name:ident($ty:tt) $(unknown($unknown_doc:literal))* {
+        $vis:vis enum $name:ident($ty:tt) $(unknown(#[$unknown_meta:meta] $unknown_doc:ident))* {
             // Each of the `Name = Val,` permitting documentation.
             $($(#[$ident_attr:meta])* $tag:ident = $val:expr,)*
         }
@@ -13,7 +13,7 @@ macro_rules! tags {
         pub enum $name {
             $($(#[$ident_attr])* $tag,)*
             $(
-                #[doc = $unknown_doc]
+                #[$unknown_meta]
                 Unknown($ty),
             )*
         }
@@ -31,7 +31,7 @@ macro_rules! tags {
             fn __to_inner_type(&self) -> $ty {
                 match *self {
                     $( $name::$tag => $val, )*
-                    $( $name::Unknown(n) => { $unknown_doc; n }, )*
+                    $( $name::Unknown($unknown_doc) => { $unknown_doc }, )*
                 }
             }
         }
@@ -39,7 +39,7 @@ macro_rules! tags {
         tags!($name, $ty, $($unknown_doc)*);
     };
     // For u16 tags, provide direct inherent primitive conversion methods.
-    ($name:tt, u16, $($unknown_doc:literal)*) => {
+    ($name:tt, u16, $($unknown_doc:ident)*) => {
         impl $name {
             #[inline(always)]
             pub fn from_u16(val: u16) -> Option<Self> {
@@ -48,9 +48,8 @@ macro_rules! tags {
 
             $(
             #[inline(always)]
-            pub fn from_u16_exhaustive(val: u16) -> Self {
-                $unknown_doc;
-                Self::__from_inner_type(val).unwrap_or_else(|_| $name::Unknown(val))
+            pub fn from_u16_exhaustive($unknown_doc: u16) -> Self {
+                Self::__from_inner_type($unknown_doc).unwrap_or_else(|_| $name::Unknown($unknown_doc))
             }
             )*
 
@@ -68,7 +67,10 @@ macro_rules! tags {
 // Note: These tags appear in the order they are mentioned in the TIFF reference
 tags! {
 /// TIFF tags
-pub enum Tag(u16) unknown("A private or extension tag") {
+pub enum Tag(u16) unknown(
+    /// A private or extension tag
+    unknown
+) {
     // Baseline tags:
     Artist = 315,
     // grayscale images PhotometricInterpretation 1 or 3
@@ -131,6 +133,8 @@ pub enum Tag(u16) unknown("A private or extension tag") {
     ExifDirectory = 0x8769,
     // <https://web.archive.org/web/20131111073619/http://www.exif.org/Exif2-1.PDF>
     GpsDirectory = 0x8825,
+    // <https://www.color.org/technotes/ICC-Technote-ProfileEmbedding.pdf>
+    IccProfile = 34675,
     GeoKeyDirectoryTag = 34735, // (SPOT)
     GeoDoubleParamsTag = 34736, // (SPOT)
     GeoAsciiParamsTag = 34737, // (SPOT)
@@ -189,10 +193,52 @@ pub enum Type(u16) {
 }
 }
 
+impl Type {
+    pub(crate) fn byte_len(&self) -> u8 {
+        match *self {
+            Type::BYTE | Type::SBYTE | Type::ASCII | Type::UNDEFINED => 1,
+            Type::SHORT | Type::SSHORT => 2,
+            Type::LONG | Type::SLONG | Type::FLOAT | Type::IFD => 4,
+            Type::LONG8
+            | Type::SLONG8
+            | Type::DOUBLE
+            | Type::RATIONAL
+            | Type::SRATIONAL
+            | Type::IFD8 => 8,
+        }
+    }
+
+    pub(crate) fn value_bytes(&self, count: u64) -> Result<u64, crate::error::TiffError> {
+        let tag_size = u64::from(self.byte_len());
+
+        match count.checked_mul(tag_size) {
+            Some(n) => Ok(n),
+            None => Err(crate::error::TiffError::LimitsExceeded),
+        }
+    }
+
+    pub(crate) fn endian_bytes(self) -> EndianBytes {
+        match self {
+            Type::BYTE | Type::SBYTE | Type::ASCII | Type::UNDEFINED => EndianBytes::One,
+            Type::SHORT | Type::SSHORT => EndianBytes::Two,
+            Type::LONG
+            | Type::SLONG
+            | Type::FLOAT
+            | Type::IFD
+            | Type::RATIONAL
+            | Type::SRATIONAL => EndianBytes::Four,
+            Type::LONG8 | Type::SLONG8 | Type::DOUBLE | Type::IFD8 => EndianBytes::Eight,
+        }
+    }
+}
+
 tags! {
 /// See [TIFF compression tags](https://www.awaresystems.be/imaging/tiff/tifftags/compression.html)
 /// for reference.
-pub enum CompressionMethod(u16) unknown("A custom compression method") {
+pub enum CompressionMethod(u16) unknown(
+    /// A custom compression method
+    unknown
+) {
     None = 1,
     Huffman = 2,
     Fax3 = 3,
@@ -254,10 +300,89 @@ pub enum ResolutionUnit(u16) {
 }
 
 tags! {
-pub enum SampleFormat(u16) unknown("An unknown extension sample format") {
+pub enum SampleFormat(u16) unknown(
+    /// An unknown extension sample format
+    unknown
+) {
     Uint = 1,
     Int = 2,
     IEEEFP = 3,
     Void = 4,
 }
 }
+
+/// Byte order of the TIFF file.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ByteOrder {
+    /// little endian byte order
+    LittleEndian,
+    /// big endian byte order
+    BigEndian,
+}
+
+impl ByteOrder {
+    /// Get the byte order representing the running target.
+    ///
+    /// The infallibility of this method represents the fact that only little and big endian
+    /// systems are supported by the library. No mixed endian and no other weird stuff. (Note: as
+    /// of Rust 1.90 this is a tautology as Rust itself only has those two kinds).
+    pub const fn native() -> Self {
+        match () {
+            #[cfg(target_endian = "little")]
+            () => ByteOrder::LittleEndian,
+            #[cfg(target_endian = "big")]
+            () => ByteOrder::BigEndian,
+            #[cfg(not(any(target_endian = "big", target_endian = "little")))]
+            () => compile_error!("Unsupported target"),
+        }
+    }
+
+    /// Given a typed buffer, convert its contents to the specified byte order in-place.
+    ///
+    /// The buffer is assumed to represent an array of the given type. If the length of the buffer
+    /// is not divisible into an integer number of values, the behavior for the remaining bytes it
+    /// not specified.
+    pub fn convert(self, ty: Type, buffer: &mut [u8], to: ByteOrder) {
+        self.convert_endian_bytes(ty.endian_bytes(), buffer, to)
+    }
+
+    pub(crate) fn convert_endian_bytes(self, cls: EndianBytes, buffer: &mut [u8], to: ByteOrder) {
+        if self == to {
+            return;
+        }
+
+        // FIXME: at MSRV 1.89 or higher use `slice::as_chunks_mut`.
+        match cls {
+            EndianBytes::One => {
+                // No change needed
+            }
+            EndianBytes::Two => {
+                for chunk in buffer.chunks_exact_mut(2) {
+                    let chunk: &mut [u8; 2] = chunk.try_into().unwrap();
+                    *chunk = u16::from_be_bytes(*chunk).to_le_bytes();
+                }
+            }
+            EndianBytes::Four => {
+                for chunk in buffer.chunks_exact_mut(4) {
+                    let chunk: &mut [u8; 4] = chunk.try_into().unwrap();
+                    *chunk = u32::from_be_bytes(*chunk).to_le_bytes();
+                }
+            }
+            EndianBytes::Eight => {
+                for chunk in buffer.chunks_exact_mut(8) {
+                    let chunk: &mut [u8; 8] = chunk.try_into().unwrap();
+                    *chunk = u64::from_be_bytes(*chunk).to_le_bytes();
+                }
+            }
+        }
+    }
+}
+
+/// The size of individual byte-order corrected elements.
+#[derive(Clone, Copy)]
+pub(crate) enum EndianBytes {
+    One,
+    Two,
+    Four,
+    Eight,
+}

tests/decode_images.rs

@@ -4,6 +4,7 @@ use tiff::decoder::{ifd, Decoder, DecodingResult};
 use tiff::ColorType;
 
 use std::fs::File;
+use std::io::{Read, Seek};
 use std::path::PathBuf;
 
 const TEST_IMAGE_DIR: &str = "./tests/images/";
@@ -45,12 +46,12 @@ fn test_image_color_type_unsupported(file: &str, expected_type: ColorType) {
     let img_file = File::open(path).expect("Cannot find test image!");
     let mut decoder = Decoder::new(img_file).expect("Cannot create decoder");
     assert_eq!(decoder.colortype().unwrap(), expected_type);
-    assert!(match decoder.read_image() {
+    assert!(matches!(
+        decoder.read_image(),
         Err(tiff::TiffError::UnsupportedError(
             tiff::TiffUnsupportedError::UnsupportedColorType(_),
-        )) => true,
-        _ => false,
-    });
+        ))
+    ));
 }
 
 #[test]
@@ -172,7 +173,7 @@ fn test_string_tags() {
                 &s,
                 "GraphicsMagick 1.2 unreleased Q16 http://www.GraphicsMagick.org/"
             ),
-            _ => assert!(false),
+            other => unreachable!("Expected Ascii tag from file, got {other:?}"),
         };
     }
 }
@@ -231,6 +232,54 @@ fn test_tiled_rect_rgb_u8() {
     test_image_sum_u8("tiled-rect-rgb-u8.tif", ColorType::RGB(8), 62081032);
 }
 
+#[test]
+fn test_inner_access() {
+    let path = PathBuf::from(TEST_IMAGE_DIR).join("tiled-rect-rgb-u8.tif");
+    let img_file = File::open(path).expect("Cannot find test image!");
+    let mut decoder = Decoder::new(img_file).expect("Cannot create decoder");
+    assert_eq!(decoder.colortype().unwrap(), ColorType::RGB(8));
+
+    let c = decoder
+        .get_tag(tiff::tags::Tag::Compression)
+        .unwrap()
+        .into_u16()
+        .unwrap();
+    assert_eq!(c, tiff::tags::CompressionMethod::None.to_u16());
+
+    // Because the image is uncompressed, reading the first tile directly with the inner reader
+    // should yield the same result as reading it with the decoder's read_chunk method.
+    let first_offset = decoder
+        .get_tag_u32_vec(tiff::tags::Tag::TileOffsets)
+        .unwrap()
+        .into_iter()
+        .next()
+        .unwrap();
+    let first_byte_count = decoder
+        .get_tag_u32_vec(tiff::tags::Tag::TileByteCounts)
+        .unwrap()
+        .into_iter()
+        .next()
+        .unwrap();
+    decoder
+        .inner()
+        .seek(std::io::SeekFrom::Start(first_offset as u64))
+        .expect("Cannot seek to tile offset");
+    let mut buf = vec![0; first_byte_count as usize];
+    decoder
+        .inner()
+        .read_exact(&mut buf)
+        .expect("Cannot read tile data");
+    let raw_sum: u64 = buf.into_iter().map(<u64>::from).sum();
+
+    match decoder.read_chunk(0).unwrap() {
+        DecodingResult::U8(chunk) => {
+            let sum: u64 = chunk.into_iter().map(<u64>::from).sum();
+            assert_eq!(sum, raw_sum);
+        }
+        _ => panic!("Wrong bit depth"),
+    }
+}
+
 /* #[test]
 fn test_tiled_jpeg_rgb_u8() {
     test_image_sum_u8("tiled-jpeg-rgb-u8.tif", ColorType::RGB(8), 93031606);
@@ -292,6 +341,11 @@ fn test_tiled_incremental() {
 
 #[test]
 fn test_planar_rgb_u8() {
+    test_image_sum_u8("planar-rgb-u8.tif", ColorType::RGB(8), 15417630);
+}
+
+#[test]
+fn test_read_planar_bands() {
     // gdal_translate tiled-rgb-u8.tif planar-rgb-u8.tif -co INTERLEAVE=BAND -co COMPRESS=LZW -co PROFILE=BASELINE
     let file = "planar-rgb-u8.tif";
     let expected_type = ColorType::RGB(8);
@@ -328,8 +382,6 @@ fn test_planar_rgb_u8() {
         }
         _ => panic!("Wrong bit depth"),
     }
-
-    test_image_sum_u8(file, ColorType::RGB(8), 15417630);
 }
 
 #[test]
@@ -348,7 +400,7 @@ fn test_div_zero() {
 
     match err {
         TiffError::FormatError(TiffFormatError::StripTileTagConflict) => {}
-        unexpected => panic!("Unexpected error {}", unexpected),
+        unexpected => panic!("Unexpected error {unexpected}"),
     }
 }
 
@@ -366,7 +418,7 @@ fn test_too_many_value_bytes() {
 
     match error {
         tiff::TiffError::LimitsExceeded => {}
-        unexpected => panic!("Unexpected error {}", unexpected),
+        unexpected => panic!("Unexpected error {unexpected}"),
     }
 }
 
@@ -497,7 +549,7 @@ fn timeout() {
 
     match error {
         TiffError::FormatError(TiffFormatError::CycleInOffsets) => {}
-        e => panic!("Unexpected error {:?}", e),
+        e => panic!("Unexpected error {e:?}"),
     }
 }
 
@@ -522,3 +574,113 @@ fn test_zstd_compression() {
     // gdal_translate -co COMPRESS=ZSTD -co ZSTD_LEVEL=20 int16.tif int16_zstd.tif
     test_image_sum_i16("int16_zstd.tif", ColorType::Gray(16), 354396);
 }
+
+fn test_image_bytes(
+    file: &str,
+    expected: &[(ColorType, u32)],
+    // Represent all samples as little endian, ensuring check sums on all platforms.
+    normalize_byte_order: fn(&mut [u8]),
+) {
+    let path = PathBuf::from(TEST_IMAGE_DIR).join(file);
+    let img_file = File::open(path).expect("Cannot find test image!");
+    let mut decoder = Decoder::new(img_file).expect("Cannot create decoder");
+
+    let mut buffer = vec![0u8; 0];
+    for (idx, &(expected_type, expected_crc)) in expected.iter().enumerate() {
+        if idx > 0 {
+            decoder
+                .next_image()
+                .expect("mismatched number of directories");
+        }
+
+        assert_eq!(decoder.colortype().unwrap(), expected_type);
+        let layout = decoder
+            .image_buffer_layout()
+            .expect("Cannot describe buffer layout");
+
+        buffer.resize(layout.len, 0u8);
+        decoder.read_image_bytes(&mut buffer).unwrap();
+        normalize_byte_order(&mut buffer);
+
+        // Well almost a crc..
+        assert_eq!(crc32fast::hash(&buffer), expected_crc);
+    }
+}
+
+fn byte_order_u16(bytes: &mut [u8]) {
+    for chunk in bytes.chunks_exact_mut(2) {
+        let n = u16::from_ne_bytes(chunk.try_into().unwrap());
+        chunk.copy_from_slice(&n.to_le_bytes());
+    }
+}
+
+fn byte_order_u32(bytes: &mut [u8]) {
+    for chunk in bytes.chunks_exact_mut(4) {
+        let n = u32::from_ne_bytes(chunk.try_into().unwrap());
+        chunk.copy_from_slice(&n.to_le_bytes());
+    }
+}
+
+fn byte_order_u64(bytes: &mut [u8]) {
+    for chunk in bytes.chunks_exact_mut(8) {
+        let n = u64::from_ne_bytes(chunk.try_into().unwrap());
+        chunk.copy_from_slice(&n.to_le_bytes());
+    }
+}
+
+#[test]
+fn bytes_cmyk_3c_8b() {
+    test_image_bytes(
+        "cmyk-3c-8b.tiff",
+        &[(ColorType::CMYK(8), 2935032230)],
+        |_| (),
+    );
+}
+
+#[test]
+fn bytes_gray_16b() {
+    test_image_bytes(
+        "minisblack-1c-16b.tiff",
+        &[(ColorType::Gray(16), 3524597615)],
+        byte_order_u16,
+    );
+}
+
+#[test]
+fn bytes_gray_32b() {
+    test_image_bytes(
+        "gradient-1c-32b.tiff",
+        &[(ColorType::Gray(32), 2257036530)],
+        byte_order_u32,
+    );
+}
+
+#[test]
+fn bytes_gray_u64() {
+    test_image_bytes(
+        "gradient-1c-64b.tiff",
+        &[(ColorType::Gray(64), 2156547113)],
+        byte_order_u64,
+    );
+}
+
+#[test]
+fn bytes_gray_f32() {
+    test_image_bytes(
+        "gradient-1c-32b-float.tiff",
+        &[(ColorType::Gray(32), 3232356730)],
+        byte_order_u32,
+    );
+}
+
+#[test]
+#[cfg(feature = "fax")]
+fn test_fax4() {
+    test_image_sum_u8("fax4.tiff", ColorType::Gray(1), 7802706);
+}
+
+#[test]
+#[cfg(feature = "fax")]
+fn test_fax4_white_is_min() {
+    test_image_sum_u8("imagemagick_group4.tiff", ColorType::Gray(1), 3742820);
+}

tests/encode_images.rs

@@ -621,7 +621,7 @@ fn test_rows_per_strip() {
             let img2 = [i; 2 * 100];
             match decoder.read_chunk(i as u32).unwrap() {
                 DecodingResult::U8(data) => assert_eq!(&img2[..], &data[..]),
-                other => panic!("Incorrect strip type {:?}", other),
+                other => panic!("Incorrect strip type {other:?}"),
             }
         }
     }
@@ -652,8 +652,6 @@ fn test_auxiliary_directory() {
         encoder.write_tag(Tag::ExifDirectory, exif.offset).unwrap();
     }
 
-    drop(tiff);
-
     data.set_position(0);
     let mut decoder = Decoder::new(&mut data).unwrap();
 

tests/encode_images_with_compression.rs

@@ -116,7 +116,7 @@ fn encode_decode_with_compression(compression: Compression) {
         assert_eq!(
             match decoder.read_image() {
                 Ok(DecodingResult::U16(image_data)) => image_data,
-                unexpected => panic!("Descoding RGB failed: {:?}", unexpected),
+                unexpected => panic!("Descoding RGB failed: {unexpected:?}"),
             },
             image_rgb.reference_data()
         );
@@ -126,7 +126,7 @@ fn encode_decode_with_compression(compression: Compression) {
         assert_eq!(
             match decoder.read_image() {
                 Ok(DecodingResult::U8(image_data)) => image_data,
-                unexpected => panic!("Decoding grayscale failed: {:?}", unexpected),
+                unexpected => panic!("Decoding grayscale failed: {unexpected:?}"),
             },
             image_grayscale.reference_data()
         );

tests/predict.rs

@@ -1,7 +1,7 @@
 extern crate tiff;
 
 use tiff::decoder::{Decoder, DecodingResult};
-use tiff::encoder::{colortype, Compression, Predictor, TiffEncoder};
+use tiff::encoder::{colortype, Predictor, TiffEncoder};
 use tiff::ColorType;
 
 use std::fs::File;