Make read_image_to_buffer read out all planes

Fix debug condition of ValueBuffer

.github/workflows/rust.yml

@@ -9,14 +9,14 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        rust: ["1.74.0", stable, beta, nightly]
+        rust: ["1.85.0", stable, beta, nightly]
     steps:
     - uses: actions/checkout@v2
 
     - uses: dtolnay/rust-toolchain@nightly
-      if: ${{ matrix.rust == '1.74.0' }}
+      if: ${{ matrix.rust == '1.85.0' }}
     - name: Generate Cargo.lock with minimal-version dependencies
-      if: ${{ matrix.rust == '1.74.0' }}
+      if: ${{ matrix.rust == '1.85.0' }}
       run: cargo -Zminimal-versions generate-lockfile
 
     - uses: dtolnay/rust-toolchain@v1
@@ -29,7 +29,7 @@ jobs:
     - name: build
       run: cargo build -v
     - name: test
-      if: ${{ matrix.rust != '1.74.0' }}
+      if: ${{ matrix.rust != '1.85.0' }}
       run: cargo test -v && cargo doc -v
 
   features:

CHANGES.md

@@ -1,4 +1,35 @@
-# Version 0.10.4 (unreleased)
+# Version 0.11.1
+
+Fixes:
+- The enumeration types in `tags` are now all marked with a representation of
+  their underlying TIFF type (e.g. `repr(u16)`) and variants are explicitly
+  assigned their corresponding values. That is you may _read_ the raw
+  discriminant and interpret that as the value—except for `Unknown` variants.
+- The variants `RationalBig` and `SRationalBig` of `decoder::ifd::Value` are
+  deprecated as they have no corresponding TIFF type and were not constructed
+  during decoding.
+
+Additions:
+- Types in `tags` now generally implement `TiffValue` and can be handed to the
+  `DirectoryEncoder::write_tag` method. Unlike primitive types they do _not_
+  always implement the trait for slices of themselves.
+- Added `tags::ValueBuffer`, a byte-based buffer for tags with a runtime value
+  type and count.
+- Added `IfdDecoder::find_tag_{buf,bytes}` to read tag values into a
+  `ValueBuffer` or byte slice respectively without interpreting them
+  immediately within the Rust type system.
+- Added `DirectoryEncoder::write_{data,tag}_buf` that takes a `ValueBuffer`
+  instead of a statically typed argument.
+- Added `DirectoryEncoder::write_entry{,_buf,_bytes}` that encode their
+  argument into the file and return an `Entry` for later use, without
+  immediately adding a tag-entry pair to the directory.
+- The `TiffValue` trait is now implemented for several builtin `tags::*` types
+  or slices of them as appropriate for their use as values of their intended
+  TIFF tag.
+- The `TiffValue` trait is now implemented for `[T; N]` for all types that
+  implement it for slices.
+
+# Version 0.11.0
 
 - `Directory` now implements `FromIterator<(Tag, Value)>`.
 
@@ -10,6 +41,45 @@ Changes:
   as unspecified relation.  Previously, these may have been interpreted as
   alpha by the total sample count (e.g. RgbA if 4 samples under a photometric
   interpretation of RGB).
+- The decoder handles planar data, current limited to non-subsampled channels.
+  The `Decoder::read_image` method return planes one-after-another depending on
+  the size of the buffer that was passed.
+- `Decoder::read_image_to_buffer` now takes `&mut DecodingResult` and resizes
+  it according to the required layout. Previously, a borrowed `DecodingBuffer`
+  was passed which can be replaced by calling `as_bytes_mut` and
+  `read_image_bytes`.
+- Several methods of tags are now `const`. Note that does not guarantee any
+  particular value when calling these methods.
+
+Fixes:
+- Fix a bug in the uncompressed encoder that could lead to short writes, i.e.
+  data silently dropped when the underlying writer did not accept all data in a
+  single write call.
+- Encoding YCbCr data now writes the `ChromaSubsampling` tag as `(1, 1)` to
+  indicate no subsampling, instead of leaving it at its default of `(2, 2)`.
+- The decoder will reject subsampled YCbCr data as there is no upsampling
+  routine, except for JPEG compressed images where the JPEG decoders handles
+  this. Since the buffer in that case indicates a full-sized plane for all
+  color samples any future support for the tag will upsample all planes (at
+  least within this major version).
+
+Additions:
+- Added support for the `CieLab` color type.
+- Added `DecodingResult::resize_to` to create a buffer with a matching sample
+  type and dimensions.
+- Added `ByteOrder::native` to access the platform's native endianness.
+- Added `ByteOrder::convert` to change the byte-order of values in a byte
+  buffer, depending on their `Type` as described at runtime.
+- Added `DirectoryOffset::new` to encode a directory whose offset is known to
+  the caller but that has not been written through the encoder itself.
+- Added `Encoder::extra_samples` to encode images with more samples than their
+  color's trait implementation would otherwise suggest.
+- Added `DirectoryEncoder::extend_from` to encode multiple tag entries from a
+  directory whose values were written to the file by means outside the
+  encoder's control.
+- Added `Decoder::read_coding_unit_bytes` to retrieve data of corresponding
+  coordinates from potentially planar data, which is encoded in multiple chunks
+  of the file.
 
 # Version 0.10.3
 

Cargo.toml

@@ -1,11 +1,11 @@
 [package]
 name = "tiff"
-version = "0.10.3"
+version = "0.11.1"
 edition = "2021"
 resolver = "2"
 
 # note: when changed, also update test runner in `.github/workflows/rust.yml`
-rust-version = "1.74.0"
+rust-version = "1.85.0"
 
 license = "MIT"
 description = "TIFF decoding and encoding library in pure Rust"
@@ -14,7 +14,7 @@ authors = ["The image-rs Developers"]
 repository = "https://github.com/image-rs/image-tiff"
 categories = ["multimedia::images", "multimedia::encoding"]
 
-exclude = ["tests/images/*", "tests/fuzz_images/*"]
+exclude = ["tests/images/*", "tests/fuzz_images/*", "tests/**/*.tif"]
 
 [dependencies]
 half = { version = "2.4.1" }

src/decoder/ifd.rs

@@ -6,12 +6,12 @@ use std::mem;
 use std::str;
 
 use super::stream::{ByteOrder, EndianReader};
-use crate::tags::{IfdPointer, Tag, Type};
+use crate::tags::{IfdPointer, Tag, Type, ValueBuffer};
 use crate::{TiffError, TiffFormatError, TiffResult};
 
 use self::Value::{
-    Ascii, Byte, Double, Float, Ifd, IfdBig, List, Rational, RationalBig, SRational, SRationalBig,
-    Short, Signed, SignedBig, SignedByte, SignedShort, Unsigned, UnsignedBig,
+    Ascii, Byte, Double, Float, Ifd, IfdBig, List, Rational, SRational, Short, Signed, SignedBig,
+    SignedByte, SignedShort, Unsigned, UnsignedBig,
 };
 
 #[allow(unused_qualifications)]
@@ -30,8 +30,16 @@ pub enum Value {
     Double(f64),
     List(Vec<Value>),
     Rational(u32, u32),
+    #[deprecated(
+        note = "Not implemented in BigTIFF with a standard tag value",
+        since = "0.11.1"
+    )]
     RationalBig(u64, u64),
     SRational(i32, i32),
+    #[deprecated(
+        note = "Not implemented in BigTIFF with a standard tag value",
+        since = "0.11.1"
+    )]
     SRationalBig(i64, i64),
     Ascii(String),
     Ifd(u32),
@@ -170,7 +178,8 @@ impl Value {
             Unsigned(val) => Ok(vec![val]),
             UnsignedBig(val) => Ok(vec![u32::try_from(val)?]),
             Rational(numerator, denominator) => Ok(vec![numerator, denominator]),
-            RationalBig(numerator, denominator) => {
+            #[expect(deprecated)]
+            Value::RationalBig(numerator, denominator) => {
                 Ok(vec![u32::try_from(numerator)?, u32::try_from(denominator)?])
             }
             Ifd(val) => Ok(vec![val]),
@@ -220,7 +229,8 @@ impl Value {
                             new_vec.push(numerator);
                             new_vec.push(denominator);
                         }
-                        SRationalBig(numerator, denominator) => {
+                        #[expect(deprecated)]
+                        Value::SRationalBig(numerator, denominator) => {
                             new_vec.push(i32::try_from(numerator)?);
                             new_vec.push(i32::try_from(denominator)?);
                         }
@@ -234,7 +244,8 @@ impl Value {
             Signed(val) => Ok(vec![val]),
             SignedBig(val) => Ok(vec![i32::try_from(val)?]),
             SRational(numerator, denominator) => Ok(vec![numerator, denominator]),
-            SRationalBig(numerator, denominator) => {
+            #[expect(deprecated)]
+            Value::SRationalBig(numerator, denominator) => {
                 Ok(vec![i32::try_from(numerator)?, i32::try_from(denominator)?])
             }
             _ => Err(TiffError::FormatError(TiffFormatError::InvalidTypeForTag)),
@@ -283,7 +294,8 @@ impl Value {
             Unsigned(val) => Ok(vec![val.into()]),
             UnsignedBig(val) => Ok(vec![val]),
             Rational(numerator, denominator) => Ok(vec![numerator.into(), denominator.into()]),
-            RationalBig(numerator, denominator) => Ok(vec![numerator, denominator]),
+            #[expect(deprecated)]
+            Value::RationalBig(numerator, denominator) => Ok(vec![numerator, denominator]),
             Ifd(val) => Ok(vec![val.into()]),
             IfdBig(val) => Ok(vec![val]),
             Ascii(val) => Ok(val.chars().map(u32::from).map(u64::from).collect()),
@@ -301,7 +313,8 @@ impl Value {
                             new_vec.push(numerator.into());
                             new_vec.push(denominator.into());
                         }
-                        SRationalBig(numerator, denominator) => {
+                        #[expect(deprecated)]
+                        Value::SRationalBig(numerator, denominator) => {
                             new_vec.push(numerator);
                             new_vec.push(denominator);
                         }
@@ -315,7 +328,8 @@ impl Value {
             Signed(val) => Ok(vec![val.into()]),
             SignedBig(val) => Ok(vec![val]),
             SRational(numerator, denominator) => Ok(vec![numerator.into(), denominator.into()]),
-            SRationalBig(numerator, denominator) => Ok(vec![numerator, denominator]),
+            #[expect(deprecated)]
+            Value::SRationalBig(numerator, denominator) => Ok(vec![numerator, denominator]),
             _ => Err(TiffError::FormatError(TiffFormatError::InvalidTypeForTag)),
         }
     }
@@ -565,7 +579,7 @@ 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)?;
+        self.set_reader_offset_relative(bigtiff, reader, 0)?;
 
         match self.type_ {
             Type::BYTE | Type::UNDEFINED => {
@@ -723,6 +737,113 @@ impl Entry {
         Ok(List(v))
     }
 
+    pub(crate) fn buffered_value<R: Read + Seek>(
+        &self,
+        buf: &mut ValueBuffer,
+        limits: &super::Limits,
+        bigtiff: bool,
+        reader: &mut EndianReader<R>,
+    ) -> TiffResult<()> {
+        if self.count == 0 {
+            buf.assume_type(self.type_, 0, reader.byte_order);
+            return Ok(());
+        }
+
+        let value_bytes = self.buffer_with_capacity(buf, limits)?;
+
+        // Case 1: the value fits in the offset field.
+        if value_bytes <= 4 || bigtiff && value_bytes <= 8 {
+            let src = &self.offset[..value_bytes];
+            buf.raw_bytes_mut()[..value_bytes].copy_from_slice(src);
+            buf.assume_type(self.type_, self.count, reader.byte_order);
+
+            return Ok(());
+        }
+
+        // Case 2: the value is stored in the reader at an offset.
+        self.set_reader_offset_relative(bigtiff, reader, 0)?;
+
+        // In case of an error we set the type and endianess.
+        buf.assume_type(self.type_, 0, reader.byte_order);
+        let target = &mut buf.raw_bytes_mut()[..value_bytes];
+        // FIXME: if the read fails we have already grown to full size, which is not great.
+        reader.inner().read_exact(target)?;
+        buf.assume_type(self.type_, self.count, reader.byte_order);
+
+        Ok(())
+    }
+
+    pub(crate) fn raw_value_at<R: Read + Seek>(
+        &self,
+        buf: &mut [u8],
+        bigtiff: bool,
+        reader: &mut EndianReader<R>,
+        at: u64,
+    ) -> TiffResult<usize> {
+        if self.count == 0 {
+            return Ok(0);
+        }
+
+        // We have no limits to handle, we do not allocate.
+        let value_bytes = self.type_.value_bytes(self.count)?;
+
+        // No bytes to fill into the buffer.
+        if at >= value_bytes {
+            return Ok(0);
+        }
+
+        // Case 1: the value fits in the offset field.
+        if value_bytes <= 4 || bigtiff && value_bytes <= 8 {
+            // `at < value_bytes` and `value_bytes <= 8` so casting is mathematical
+            let src = &self.offset[..value_bytes as usize][at as usize..];
+            let len = src.len().min(buf.len());
+            buf[..len].copy_from_slice(&src[..len]);
+            return Ok(value_bytes as usize);
+        }
+
+        // Case 2: the value is stored in the reader at an offset. We will find the offset
+        // encoded in the entry, apply the relative start position and seek there.
+        self.set_reader_offset_relative(bigtiff, reader, at)?;
+
+        let remainder = value_bytes - at;
+        let len = usize::try_from(remainder)
+            .unwrap_or(usize::MAX)
+            .min(buf.len());
+
+        let target = &mut buf[..len];
+        reader.inner().read_exact(target)?;
+
+        // Design note: in a previous draft we would consume the rest of the bytes of this value
+        // here (into a stack buffer if need be) to verify the stream itself. But in the end we
+        // have `Seek` so we better verify this by seeking over the rest of the bytes, finding if
+        // the stream continues that far. Even that is maybe bad if we wanted to provide a
+        // async-adaptor that `WouldBlock` errors to fill back a read window then the seek is
+        // poison to that, too.
+
+        // So a really simple choice: The caller is responsible for handling the fact that this did
+        // not verify the whole value. Attempt a 1-byte read at the end of the value instead?
+        Ok(len)
+    }
+
+    // Returns `Ok(bytes)` if our value's bytes through type and count fit into `usize` and are
+    // within the limits. Extends the buffer to that many bytes.
+    fn buffer_with_capacity(
+        &self,
+        buf: &mut ValueBuffer,
+        limits: &super::Limits,
+    ) -> TiffResult<usize> {
+        let bytes = self.type_.value_bytes(self.count())?;
+
+        let allowed_length = usize::try_from(bytes)
+            .ok()
+            .filter(|&n| n <= limits.decoding_buffer_size)
+            .ok_or(TiffError::LimitsExceeded)?;
+
+        buf.prepare_length(allowed_length);
+
+        Ok(allowed_length)
+    }
+
     fn vec_with_capacity(
         value_count: u64,
         limits: &super::Limits,
@@ -736,21 +857,32 @@ impl Entry {
         Ok(Vec::with_capacity(value_count))
     }
 
-    fn set_reader_offset<R>(
+    /// Seek to an offset within a value stored in the offset defined by this entry.
+    fn set_reader_offset_relative<R>(
         &self,
-        bo: ByteOrder,
         bigtiff: bool,
         reader: &mut EndianReader<R>,
+        at: u64,
     ) -> TiffResult<()>
     where
         R: Read + Seek,
     {
+        let bo = reader.byte_order;
+
         let offset = if bigtiff {
             self.offset_field_reader(bo).read_u64()?
         } else {
             self.offset_field_reader(bo).read_u32()?.into()
         };
 
+        // FIXME: `at` should be within `self.type_.value_bytes(self.count)` and that itself should
+        // be within the bounds of the stream. But we do not check this eagerly so this below will
+        // fail sometimes differently for exotic streams, depending on the method by which we read
+        // (at once or through multiple raw into-byte-slice reads).
+        let offset = offset.checked_add(at).ok_or(TiffError::FormatError(
+            TiffFormatError::InconsistentSizesEncountered,
+        ))?;
+
         reader.goto_offset(offset)?;
 
         Ok(())

src/decoder/image.rs

@@ -85,6 +85,7 @@ pub(crate) struct Image {
     pub tile_attributes: Option<TileAttributes>,
     pub chunk_offsets: Vec<u64>,
     pub chunk_bytes: Vec<u64>,
+    pub chroma_subsampling: (u16, u16),
 }
 
 /// Describes how to read a tile-aligned portion of the image.
@@ -95,6 +96,19 @@ pub(crate) struct ReadoutLayout {
     pub planar_config: PlanarConfiguration,
 
     /// The sample interpretation (interpret with planar_config).
+    ///
+    /// FIXME: we should not require this here. The ability to turn out the raw bytes from the
+    /// sample arrays is very different from turning out interpretable color. Firstly we can always
+    /// readout `Multiband` but currently only use that ColorType in special circumstances (it must
+    /// not overlap cases where actually want to use a ColorType).
+    ///
+    /// And then we have CIE Lab, which uses a tuple of `(u8, i8, i8)`, that is still filterable
+    /// but still not represented by any of our `DecoderResult` variants. Other color variants
+    /// depend on extra tags (YCbCrCoefficients/0x0211) and we don't have a good side channel to
+    /// tag the output with all that TIFF specific information, so arguably we should process and
+    /// apply those to the data so it becomes a self-contained representation.
+    ///
+    /// This should be computed at a higher level, in `Decoder`, instead.
     pub color: ColorType,
     /// The number of bytes from one row to another.
     pub minimum_row_stride: usize,
@@ -262,6 +276,25 @@ impl Image {
             .transpose()?
             .unwrap_or(PlanarConfiguration::Chunky);
 
+        let ycbcr_subsampling = tag_reader.find_tag_uint_vec::<u16>(Tag::ChromaSubsampling)?;
+
+        let chroma_subsampling = if let Some(subsamples) = &ycbcr_subsampling {
+            let [a, b] = subsamples.as_slice() else {
+                return Err(TiffError::FormatError(TiffFormatError::InvalidCountForTag(
+                    Tag::ChromaSubsampling,
+                    subsamples.len(),
+                )));
+            };
+
+            // ImageWidth and ImageLength are constrained to be integer multiples of
+            // YCbCrSubsampleHoriz and YCbCrSubsampleVert respectively. TileWidth and TileLength
+            // have the same constraints. RowsPerStrip must be an integer multiple of
+            // YCbCrSubsampleVert.
+            (*a, *b)
+        } else {
+            (2, 2)
+        };
+
         let planes = match planar_config {
             PlanarConfiguration::Chunky => 1,
             PlanarConfiguration::Planar => samples,
@@ -373,6 +406,7 @@ impl Image {
             tile_attributes,
             chunk_offsets,
             chunk_bytes,
+            chroma_subsampling,
         })
     }
 
@@ -435,15 +469,60 @@ impl Image {
                     }),
                 }
             }
-            // TODO: this is bad we should not fail at this point
-            PhotometricInterpretation::RGBPalette
-            | PhotometricInterpretation::TransparencyMask
-            | PhotometricInterpretation::CIELab => Err(TiffError::UnsupportedError(
+            // ```
+            // struct IccLab /* Interpretation 9* {
+            //     pub L: u8, // SampleFormat::Uint
+            //     pub a: u8, // SampleFormat::Uint, defined as TiffLab::a + 128
+            //     pub b: u8, // SampleFormat::Uint, defined as TiffLab::b + 128
+            // }
+            // ```
+            PhotometricInterpretation::IccLab => match self.photometric_samples {
+                3 if matches!(self.sample_format, SampleFormat::Uint) => {
+                    Ok(ColorType::Lab(self.bits_per_sample))
+                }
+                _ => Err(TiffError::UnsupportedError(
+                    TiffUnsupportedError::InterpretationWithBits(
+                        self.photometric_interpretation,
+                        vec![self.bits_per_sample; self.samples as usize],
+                    ),
+                )),
+            },
+            // Unsupported due to inherently heterogeneous sample types. This is represented as:
+            // ```
+            // struct TiffLab /* Interpretation 8* {
+            //     pub L: u8, // SampleFormat::Uint
+            //     pub a: i8, // SampleFormat::Int
+            //     pub b: i8, // SampleFormat::Int
+            // }
+            // ```
+            PhotometricInterpretation::CIELab => Err(TiffError::UnsupportedError(
                 TiffUnsupportedError::InterpretationWithBits(
-                    self.photometric_interpretation,
+                    PhotometricInterpretation::CIELab,
                     vec![self.bits_per_sample; self.samples as usize],
                 ),
             )),
+            // Unsupported due to extra unfiltering and conversion steps. We need to find the
+            // Decode tag (SRATIONAL; 2 * SamplesPerPixel) and apply the following conversion:
+            //
+            // L* = Decode[0] + Lsample x (Decode[1] - Decode[0]) / (2^n -1)
+            // …
+            //
+            // So we'll have a larger depth in the output and either worry about reducing fractions
+            // or turn everything into floats. That's a lot of decisions.
+            PhotometricInterpretation::ItuLab => Err(TiffError::UnsupportedError(
+                TiffUnsupportedError::InterpretationWithBits(
+                    PhotometricInterpretation::CIELab,
+                    vec![self.bits_per_sample; self.samples as usize],
+                ),
+            )),
+            PhotometricInterpretation::RGBPalette | PhotometricInterpretation::TransparencyMask => {
+                Err(TiffError::UnsupportedError(
+                    TiffUnsupportedError::InterpretationWithBits(
+                        self.photometric_interpretation,
+                        vec![self.bits_per_sample; self.samples as usize],
+                    ),
+                ))
+            }
         }
     }
 
@@ -657,6 +736,23 @@ impl Image {
             ));
         }
 
+        // Only this color type interprets the tag, which is defined with a default of (2, 2)
+        if matches!(color, ColorType::YCbCr(_)) && self.chroma_subsampling != (1, 1) {
+            // The JPEG library does upsampling for us and defines its buffers correctly
+            // (presumably). All other compression schemes are not supported..
+            //
+            // NOTE: as explained in <fa225e820b96bef35f01bf4685654beeb4a8df0c> we may be better
+            // off supporting this tag by consistently upsampling, not by adjusting the buffer
+            // size. At least as a default this makes more sense and is much more permissive in
+            // case the compression stream disagrees with the tags (we would not have enough / or
+            // the wrong buffer layout if we only asked for subsampled planes in a planar layout).
+            if !matches!(self.compression_method, CompressionMethod::ModernJPEG) {
+                return Err(TiffError::UnsupportedError(
+                    TiffUnsupportedError::ChromaSubsampling,
+                ));
+            }
+        }
+
         Ok(ReadoutLayout {
             planar_config: self.planar_config,
             color,

src/decoder/mod.rs

@@ -5,7 +5,7 @@ use std::num::NonZeroUsize;
 
 use crate::tags::{
     CompressionMethod, IfdPointer, PhotometricInterpretation, PlanarConfiguration, Predictor,
-    SampleFormat, Tag, Type,
+    SampleFormat, Tag, Type, ValueBuffer,
 };
 use crate::{
     bytecast, ColorType, Directory, TiffError, TiffFormatError, TiffResult, TiffUnsupportedError,
@@ -860,6 +860,7 @@ impl<R: Read + Seek> Decoder<R> {
                 tile_attributes: None,
                 chunk_offsets: Vec::new(),
                 chunk_bytes: Vec::new(),
+                chroma_subsampling: (2, 2),
             },
         };
         decoder.next_image()?;
@@ -1277,7 +1278,7 @@ impl<R: Read + Seek> Decoder<R> {
     ///
     /// It will re-allocate the buffer into the correct type and size, within the decoder's
     /// configured limits, and then pass it to the underlying method. This is essentially a
-    /// type-safe wrapper around the raw [`Self::read_chunk_to_bytes`] method.
+    /// type-safe wrapper around the raw [`Self::read_chunk_bytes`] method.
     ///
     /// Note that for planar images each chunk contains only one sample of the underlying data.
     pub fn read_chunk_to_buffer(
@@ -1395,14 +1396,16 @@ impl<R: Read + Seek> Decoder<R> {
     /// # 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`.
+    /// the first sample's plane. This will be fixed in a future major version of `tiff`. To read
+    /// multiple planes, [`Self::read_image_to_buffer`] can be used instead.
     ///
     /// # Intent to deprecate
     ///
-    /// Use `DecodingResult::resize_to` and `read_image_bytes` instead where possible, preserving
-    /// the buffer across multiple calls. This old method will likely keep its bugged planar
-    /// behavior until it is fully replaced, to ensure that existing code will not run into
-    /// unexpectedly large allocations that will error on limits instead.
+    /// Use [`Self::read_image_to_buffer`] or a combination of [`DecodingResult::resize_to`] and
+    /// [`Self::read_image_bytes`] instead where possible, preserving the buffer across multiple
+    /// calls. This old method will likely keep its bugged planar behavior until it is fully
+    /// replaced, to ensure that existing code will not run into unexpectedly large allocations
+    /// that will error on limits instead.
     pub fn read_image(&mut self) -> TiffResult<DecodingResult> {
         let readout = self.image().readout_for_image()?;
 
@@ -1421,6 +1424,30 @@ impl<R: Read + Seek> Decoder<R> {
     /// configured limits, and then pass it to the underlying method. This is essentially a
     /// type-safe wrapper around the raw [`Self::read_image_bytes`] method.
     ///
+    /// ## Planar behavior
+    ///
+    /// If the image is stored as a planar configuration, an attempt is made to resize the buffer
+    /// to hold all planes. If that does not fit then only the first plane is read. Check the
+    /// buffer size against [`BufferLayoutPreference::complete_len`] to ensure that all planes were
+    /// read:
+    ///
+    /// ```
+    /// use tiff::decoder::{Decoder, DecodingResult};
+    /// let mut result = DecodingResult::U8(vec![]);
+    ///
+    /// let mut reader = /* */
+    /// # Decoder::new(std::io::Cursor::new(include_bytes!(concat!(
+    /// #   env!("CARGO_MANIFEST_DIR"), "/tests/images/tiled-gray-i1.tif"
+    /// # )))).unwrap();
+    /// let layout = reader.read_image_to_buffer(&mut result)?;
+    ///
+    /// if result.as_buffer(0).as_bytes().len() < layout.complete_len {
+    ///    println!("Only the first plane was read");
+    /// }
+    ///
+    /// # Ok::<_, tiff::TiffError>(())
+    /// ```
+    ///
     /// # Examples
     ///
     /// ```
@@ -1442,12 +1469,20 @@ impl<R: Read + Seek> Decoder<R> {
         result: &mut DecodingResult,
     ) -> TiffResult<BufferLayoutPreference> {
         let readout = self.image().readout_for_image()?;
-
         let planes = readout.to_plane_layout()?;
-        let layout = BufferLayoutPreference::from_planes(&planes);
 
-        let extent = readout.result_extent_for_planes(0..1)?;
+        let num_planes = if planes.total_bytes <= self.value_reader.limits.decoding_buffer_size {
+            planes.plane_offsets.len() as u16
+        } else {
+            1
+        };
+
+        let layout = BufferLayoutPreference::from_planes(&planes);
+        let extent = readout.result_extent_for_planes(0..num_planes)?;
+        // Compatibility: if this extent is too large our configured limits we will fall back to
+        // reading only the first plane.
         result.resize_to_extent(extent, &self.value_reader.limits)?;
+
         self.read_image_bytes(result.as_buffer(0).as_bytes_mut())?;
 
         Ok(layout)
@@ -1716,12 +1751,41 @@ impl<R: Seek + Read> ValueReader<R> {
 }
 
 impl IfdDecoder<'_> {
+    /// Retrieve the IFD entry for a given tag, if it exists.
+    ///
+    /// The entry contains the metadata of the value, that is its type and count from which we can
+    /// calculate a total byte size.
+    pub fn find_entry(&self, tag: Tag) -> Option<ifd::Entry> {
+        self.inner.ifd.get(tag).cloned()
+    }
+
     /// Tries to retrieve a tag.
     /// Return `Ok(None)` if the tag is not present.
     pub fn find_tag(&mut self, tag: Tag) -> TiffResult<Option<ifd::Value>> {
         self.inner.find_tag(tag)
     }
 
+    /// Retrieve a tag and reproduce its bytes into the provided buffer.
+    ///
+    /// The buffer is unmodified if the tag is not present.
+    pub fn find_tag_buf(
+        &mut self,
+        tag: Tag,
+        buf: &mut ValueBuffer,
+    ) -> TiffResult<Option<ifd::Entry>> {
+        self.inner.find_tag_buf(tag, buf)
+    }
+
+    /// Read bytes of a tag's value into a byte buffer.
+    pub fn find_tag_bytes(
+        &mut self,
+        tag: Tag,
+        buf: &mut [u8],
+        offset: u64,
+    ) -> TiffResult<Option<usize>> {
+        self.inner.find_tag_raw(tag, buf, offset)
+    }
+
     /// Tries to retrieve a tag and convert it to the desired unsigned type.
     pub fn find_tag_unsigned<T: TryFrom<u64>>(&mut self, tag: Tag) -> TiffResult<Option<T>> {
         self.find_tag(tag)?
@@ -1835,3 +1899,70 @@ impl<'l> IfdDecoder<'l> {
             })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::Decoder;
+    use crate::{
+        bytecast,
+        tags::{ByteOrder, Tag, ValueBuffer},
+    };
+
+    #[test]
+    fn equivalence_of_tag_readers() {
+        let file = std::fs::File::open(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/tests/images/int8_rgb.tif"
+        ))
+        .unwrap();
+
+        let mut decoder = Decoder::new(file).unwrap();
+        let file_bo = decoder.byte_order();
+        let mut ifd = decoder.image_ifd();
+
+        {
+            let value = ifd
+                .find_tag(Tag::BitsPerSample)
+                .unwrap()
+                .expect("must have BitsPerSample");
+
+            let samples = value.into_u16_vec().unwrap();
+            assert_eq!(samples.as_slice(), [8, 8, 8]);
+        }
+
+        {
+            let mut value = ValueBuffer::from_value(&[0u16; 4]);
+            let _entry = ifd
+                .find_tag_buf(Tag::BitsPerSample, &mut value)
+                .unwrap()
+                .expect("must have BitsPerSample");
+
+            value.set_byte_order(ByteOrder::native());
+            assert_eq!(value.as_bytes(), bytecast::u16_as_ne_bytes(&[8, 8, 8]));
+        }
+
+        {
+            let mut by_bytes = [0u16; 4];
+            let entry = ifd
+                .find_entry(Tag::BitsPerSample)
+                .expect("must have BitsPerSample");
+
+            let byte_len = ifd
+                .find_tag_bytes(
+                    Tag::BitsPerSample,
+                    bytecast::u16_as_ne_mut_bytes(&mut by_bytes),
+                    0,
+                )
+                .unwrap()
+                .expect("must have BitsPerSample");
+            assert_eq!(byte_len, 3 * std::mem::size_of::<u16>());
+
+            file_bo.convert(
+                entry.field_type(),
+                bytecast::u16_as_ne_mut_bytes(&mut by_bytes[..3]),
+                ByteOrder::native(),
+            );
+            assert_eq!(&by_bytes[..3], &[8, 8, 8]);
+        }
+    }
+}

src/decoder/tag_reader.rs

@@ -1,7 +1,9 @@
 use std::io::{Read, Seek};
 
-use crate::{tags::Tag, Directory};
-use crate::{TiffError, TiffFormatError, TiffResult};
+use crate::{
+    tags::{Tag, ValueBuffer},
+    Directory, TiffError, TiffFormatError, TiffResult,
+};
 
 use super::ifd::{Entry, Value};
 use super::ValueReader;
@@ -14,12 +16,25 @@ pub(crate) struct TagReader<'lt, R: EntryDecoder + ?Sized> {
 pub(crate) trait EntryDecoder {
     /// Turn an entry into a value by fetching the required bytes in the stream.
     fn entry_val(&mut self, entry: &Entry) -> TiffResult<Value>;
+    /// Fill a  `ValueBuffer` by fetching the required bytes.
+    fn entry_buf(&mut self, entry: &Entry, _: &mut ValueBuffer) -> TiffResult<()>;
+    /// Fill the prefix of the buffer and return the actual bytes. Start interpreting the inner
+    /// value at `offset`.
+    fn entry_raw(&mut self, entry: &Entry, _: &mut [u8], offset: u64) -> TiffResult<usize>;
 }
 
 impl<R: Seek + Read> EntryDecoder for ValueReader<R> {
     fn entry_val(&mut self, entry: &Entry) -> TiffResult<Value> {
         entry.val(&self.limits, self.bigtiff, &mut self.reader)
     }
+
+    fn entry_buf(&mut self, entry: &Entry, buf: &mut ValueBuffer) -> TiffResult<()> {
+        entry.buffered_value(buf, &self.limits, self.bigtiff, &mut self.reader)
+    }
+
+    fn entry_raw(&mut self, entry: &Entry, buf: &mut [u8], offset: u64) -> TiffResult<usize> {
+        entry.raw_value_at(buf, self.bigtiff, &mut self.reader, offset)
+    }
 }
 
 impl<'a, R: EntryDecoder + ?Sized> TagReader<'a, R> {
@@ -32,6 +47,39 @@ impl<'a, R: EntryDecoder + ?Sized> TagReader<'a, R> {
         self.decoder.entry_val(&entry).map(Some)
     }
 
+    /// Find a tag and fill the provided buffer with its raw data.
+    ///
+    /// Returns the entry of the tag if found. This signals that the buffer was overwritten.
+    /// Otherwise the buffer is preserved as-is.
+    pub(crate) fn find_tag_buf(
+        &mut self,
+        tag: Tag,
+        buf: &mut ValueBuffer,
+    ) -> TiffResult<Option<Entry>> {
+        let entry = match self.ifd.get(tag) {
+            None => return Ok(None),
+            Some(entry) => entry.clone(),
+        };
+
+        self.decoder.entry_buf(&entry, buf)?;
+        Ok(Some(entry))
+    }
+
+    pub(crate) fn find_tag_raw(
+        &mut self,
+        tag: Tag,
+        buf: &mut [u8],
+        at: u64,
+    ) -> TiffResult<Option<usize>> {
+        let entry = match self.ifd.get(tag) {
+            None => return Ok(None),
+            Some(entry) => entry.clone(),
+        };
+
+        let len = self.decoder.entry_raw(&entry, buf, at)?;
+        Ok(Some(len))
+    }
+
     pub(crate) fn require_tag(&mut self, tag: Tag) -> TiffResult<Value> {
         match self.find_tag(tag)? {
             Some(val) => Ok(val),

src/encoder/mod.rs

@@ -11,7 +11,10 @@ use std::{
 use crate::{
     decoder::ifd::Entry,
     error::{TiffResult, UsageError},
-    tags::{CompressionMethod, ExtraSamples, IfdPointer, ResolutionUnit, SampleFormat, Tag, Type},
+    tags::{
+        ByteOrder, CompressionMethod, ExtraSamples, IfdPointer, PhotometricInterpretation,
+        ResolutionUnit, SampleFormat, Tag, Type, ValueBuffer,
+    },
     Directory, TiffError, TiffFormatError,
 };
 
@@ -298,12 +301,12 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
             value.write(&mut writer)?;
         }
 
-        let entry = Self::write_value(
+        let entry = Self::write_entry_inner(
             self.writer,
-            &DirectoryEntry {
+            DirectoryEntry {
                 data_type: <T>::FIELD_TYPE,
                 count: value.count().try_into()?,
-                data: bytes,
+                data: bytes.into(),
             },
         )?;
 
@@ -312,15 +315,114 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         Ok(())
     }
 
+    /// Write a tag-value pair with prepared byte data.
+    ///
+    /// Note that the library will _not_ attempt to verify that the data type or the count of the
+    /// buffered value is permissible for the given tag. The data will be associated with the tag
+    /// exactly as-is.
+    ///
+    /// An error is returned if the byte order of the presented value does not match the byte order
+    /// of the underlying file (i.e. the [native byte order](`crate::tags::ByteOrder::native`)).
+    pub fn write_tag_buf(&mut self, tag: Tag, value: &ValueBuffer) -> TiffResult<()> {
+        let entry = self.write_entry_buf(value)?;
+        self.directory.extend([(tag, entry)]);
+
+        Ok(())
+    }
+
     /// Write some data to the tiff file, the offset of the data is returned.
     ///
-    /// This could be used to write tiff strips.
+    /// This could be used to write tiff strips. All of the data will be written into the file as a
+    /// slice of bytes. It can not be used as an entry in a directory directly, where very short
+    /// values are instead represented in the offset field directly. Use [`Self::write_entry`]
+    /// instead.
     pub fn write_data<T: TiffValue>(&mut self, value: T) -> TiffResult<u64> {
         let offset = self.writer.offset();
         value.write(self.writer)?;
         Ok(offset)
     }
 
+    /// Write some data directly to the tiff file, the offset of the data is returned.
+    ///
+    /// All of the data will be written into the file as a slice of bytes. It can not be used as an
+    /// entry in a directory directly, where very short values are instead represented in the
+    /// offset field directly. Use [`Self::write_entry_buf`] instead.
+    ///
+    /// An error is returned if the byte order of the presented value does not match the byte order
+    /// of the underlying file (i.e. the [native byte order](`crate::tags::ByteOrder::native`)).
+    pub fn write_data_buf(&mut self, value: &ValueBuffer) -> TiffResult<u64> {
+        self.check_value_byteorder(value)?;
+        let offset = self.writer.offset();
+        self.writer.write_bytes(value.as_bytes())?;
+        Ok(offset)
+    }
+
+    /// Write a directory value into the file.
+    ///
+    /// Returns an [`Entry`]. If the value is short enough it will *not* be written in the file but
+    /// stored in the entry's offset field.
+    pub fn write_entry<T: TiffValue>(&mut self, value: T) -> TiffResult<Entry> {
+        Self::write_entry_inner(
+            self.writer,
+            DirectoryEntry {
+                data_type: T::FIELD_TYPE,
+                count: K::convert_offset(value.count() as u64)?,
+                // FIXME: not optimal we always allocate here. But the only other method we have
+                // available is `T::write(&mut TiffWriter<W>)` and we must pass that into
+                // `write_entry_inner` but then have a combinatorial explosion of instantiations
+                // which is absurd.
+                data: value.data(),
+            },
+        )
+    }
+
+    /// Write a directory value into the file.
+    ///
+    /// An error is returned if the byte order of the presented value does not match the byte order
+    /// of the underlying file (i.e. the [native byte order](`crate::tags::ByteOrder::native`)).
+    ///
+    /// Returns an [`Entry`]. If the value is short enough it will *not* be written in the file but
+    /// stored in the entry's offset field.
+    pub fn write_entry_buf(&mut self, value: &ValueBuffer) -> TiffResult<Entry> {
+        self.check_value_byteorder(value)?;
+
+        Self::write_entry_inner(
+            self.writer,
+            DirectoryEntry {
+                data_type: value.data_type(),
+                count: K::convert_offset(value.count())?,
+                data: value.as_bytes().into(),
+            },
+        )
+    }
+
+    /// Write a directory entry by its byte data.
+    ///
+    /// The data must be pre-formatted to the byte order expected by the file.
+    ///
+    /// Returns an [`Entry`]. If the value is short enough it will *not* be written in the file but
+    /// stored in the entry's offset field.
+    pub fn write_entry_bytes(&mut self, ty: Type, data: &[u8]) -> TiffResult<Entry> {
+        if data.len() % usize::from(ty.byte_len()) != 0 {
+            return Err(TiffError::UsageError(UsageError::MismatchedEntryLength {
+                ty,
+                found: data.len(),
+            }));
+        }
+
+        let count = data.len() / usize::from(ty.byte_len());
+        let count = u64::try_from(count)?;
+
+        Self::write_entry_inner(
+            self.writer,
+            DirectoryEntry {
+                data_type: ty,
+                count: K::convert_offset(count)?,
+                data: data.into(),
+            },
+        )
+    }
+
     /// Insert previously written key-value entries.
     ///
     /// It is the caller's responsibility to ensure that the data referred to by the entries is
@@ -374,17 +476,21 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         Ok(offset)
     }
 
-    fn write_value(
+    // Does it really make sense that this would be a (potentially) compressible write? For actual
+    // directory values their size must match the data written so there's going to be a silent
+    // problem if that actually occurs.
+    fn write_entry_inner(
         writer: &mut TiffWriter<W>,
-        value: &DirectoryEntry<K::OffsetType>,
+        value: DirectoryEntry<K::OffsetType>,
     ) -> TiffResult<Entry> {
-        let &DirectoryEntry {
+        let DirectoryEntry {
             data: ref bytes,
             ref count,
             data_type,
         } = value;
 
         let in_entry_bytes = mem::size_of::<K::OffsetType>();
+
         let mut offset_bytes = [0; 8];
 
         if bytes.len() > in_entry_bytes {
@@ -403,6 +509,7 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         // and some oversight, we can not clone the `count: K::OffsetType` and thus not convert it.
         // Instead, write it to a buffer...
         let mut count_bytes = [0; 8];
+        debug_assert!(in_entry_bytes == 4 || in_entry_bytes == 8);
         // Nominally Cow but we only expect `Cow::Borrowed`.
         count_bytes[..count.bytes()].copy_from_slice(&count.data());
 
@@ -416,6 +523,15 @@ impl<'a, W: 'a + Write + Seek, K: TiffKind> DirectoryEncoder<'a, W, K> {
         })
     }
 
+    fn check_value_byteorder(&self, value: &ValueBuffer) -> TiffResult<()> {
+        // FIXME: we should enable writing files with any chosen byte order.
+        if value.byte_order() != ByteOrder::native() {
+            Err(TiffError::UsageError(UsageError::ByteOrderMismatch))
+        } else {
+            Ok(())
+        }
+    }
+
     /// Provides the number of bytes written by the underlying TiffWriter during the last call.
     fn last_written(&self) -> u64 {
         self.writer.last_written()
@@ -565,6 +681,12 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
 
         encoder.write_tag(Tag::PhotometricInterpretation, <T>::TIFF_VALUE.to_u16())?;
 
+        if matches!(<T>::TIFF_VALUE, PhotometricInterpretation::YCbCr) {
+            // The default for this tag is 2,2 for subsampling but we do not support such a
+            // transformation. Instead all samples must be provided.
+            encoder.write_tag(Tag::ChromaSubsampling, &[1u16, 1u16][..])?;
+        }
+
         encoder.write_tag(Tag::RowsPerStrip, u32::try_from(rows_per_strip)?)?;
 
         encoder.write_tag(
@@ -573,7 +695,7 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
         )?;
         encoder.write_tag(Tag::XResolution, Rational { n: 1, d: 1 })?;
         encoder.write_tag(Tag::YResolution, Rational { n: 1, d: 1 })?;
-        encoder.write_tag(Tag::ResolutionUnit, ResolutionUnit::None.to_u16())?;
+        encoder.write_tag(Tag::ResolutionUnit, ResolutionUnit::None)?;
 
         Ok(ImageEncoder {
             encoder,
@@ -757,7 +879,7 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
         } else {
             let mut sample_format: Vec<_> = <T>::BITS_PER_SAMPLE.to_vec();
             let replicated =
-                core::iter::repeat(<T>::BITS_PER_SAMPLE[0]).take(self.extra_samples.len());
+                core::iter::repeat_n(<T>::BITS_PER_SAMPLE[0], self.extra_samples.len());
             sample_format.extend(replicated);
 
             self.encoder
@@ -779,7 +901,7 @@ impl<'a, W: 'a + Write + Seek, T: ColorType, K: TiffKind> ImageEncoder<'a, W, T,
             // extra samples and not provided via a slice used for samples themselves.
             .unwrap_or(SampleFormat::Void.to_u16());
 
-        sample_format.extend(core::iter::repeat(extra_format).take(self.extra_samples.len()));
+        sample_format.extend(core::iter::repeat_n(extra_format, self.extra_samples.len()));
 
         self.encoder
             .write_tag(Tag::SampleFormat, &sample_format[..])?;
@@ -815,10 +937,10 @@ impl<'a, W: Write + Seek, C: ColorType, K: TiffKind> Drop for ImageEncoder<'a, W
     }
 }
 
-struct DirectoryEntry<S> {
+struct DirectoryEntry<'data, S> {
     data_type: Type,
     count: S,
-    data: Vec<u8>,
+    data: std::borrow::Cow<'data, [u8]>,
 }
 
 /// Trait to abstract over Tiff/BigTiff differences.

src/encoder/tiff_value.rs

@@ -1,14 +1,27 @@
 use std::{borrow::Cow, io::Write, slice::from_ref};
 
-use crate::{bytecast, tags::Type, TiffError, TiffFormatError, TiffResult};
+use crate::{bytecast, tags, tags::Type, TiffError, TiffFormatError, TiffResult};
 
 use super::writer::TiffWriter;
 
 /// Trait for types that can be encoded in a tiff file
+#[diagnostic::on_unimplemented(
+    message = "the type `{Self}` does not implement `TiffValue`",
+    note = "the trait is implemented for primitive types (`u8`, `i16`, `f32`, etc.)",
+    note = "the trait is implemented for shared references to values",
+    note = "the trait is implemented for slices, pass them by reference (e.g. `&[u8]`)",
+    note = "the trait is implemented for arrays if it is implemented for a slice",
+    note = "values in a `Vec` or `Box` should be dereferenced, e.g. `&vec[..]`"
+)]
 pub trait TiffValue {
     const BYTE_LEN: u8;
     const FIELD_TYPE: Type;
+
+    // FIXME: If we want this to mean 'count' in the sense of `Entry` it should return `u32` or
+    // `u64`, probably the latter with `convert_offset` taking care of the check against `u32::MAX`
+    // for classic tiff.
     fn count(&self) -> usize;
+
     fn bytes(&self) -> usize {
         self.count() * usize::from(Self::BYTE_LEN)
     }
@@ -450,6 +463,136 @@ impl TiffValue for str {
     }
 }
 
+// FIXME: held up on reading the discriminant for all but the unknown variant.
+//
+// It needs to have `repr(u16)` to have a defined layout and then we may read the tag from its
+// value representation by casting a u16 pointer to a pointer to the enum type.
+//     unsafe { *<*const _>::from(self).cast::<u16>() }
+// But that is quite unsafe and needs careful review to maintain the safety requirements. Maybe we
+// could get `bytemuck` to add a trait for this (it has `TransparentWrapper`) with a derive for
+// enum types that have an explicit repr.
+//
+// This would allow returning borrowed data in more cases. For all types without an unknown, in all
+// cases including as slices, and for all types with and unknown variant when we have a single
+// value (either returning a borrowed discriminant or a borrowed value within `Unknown`).
+impl TiffValue for tags::CompressionMethod {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        1
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        let bytes = self.to_u16().to_ne_bytes();
+        Cow::Owned(bytes.to_vec())
+    }
+}
+
+impl TiffValue for tags::PhotometricInterpretation {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        1
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        self.to_u16().to_ne_bytes().to_vec().into()
+    }
+}
+
+impl TiffValue for tags::PlanarConfiguration {
+    const BYTE_LEN: u8 = 2;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        1
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        self.to_u16().to_ne_bytes().to_vec().into()
+    }
+}
+
+impl TiffValue for tags::Predictor {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        1
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        self.to_u16().to_ne_bytes().to_vec().into()
+    }
+}
+
+impl TiffValue for tags::ResolutionUnit {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        1
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        self.to_u16().to_ne_bytes().to_vec().into()
+    }
+}
+
+/// This is implemented for slices as the `SampleFormat` tag takes a count of `N`.
+///
+/// Use `core::slice::from_ref` if you really need to write a single element.
+///
+/// See: <https://web.archive.org/web/20191120220815/https://www.awaresystems.be/imaging/tiff/tifftags/sampleformat.html>
+impl TiffValue for [tags::SampleFormat] {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        self.len()
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        let mut buf: Vec<u8> = Vec::with_capacity(self.len() * 2);
+        for x in self {
+            buf.extend_from_slice(&x.to_u16().to_ne_bytes());
+        }
+        Cow::Owned(buf)
+    }
+}
+
+/// This is implemented for slices as the `ExtraSamples` tag takes a count of `N`.
+///
+/// Use `core::slice::from_ref` if you really need to write a single element.
+///
+/// See: <https://web.archive.org/web/20191120220815/https://www.awaresystems.be/imaging/tiff/tifftags/extrasamples.html>
+impl TiffValue for [tags::ExtraSamples] {
+    const BYTE_LEN: u8 = <u16 as TiffValue>::BYTE_LEN;
+    const FIELD_TYPE: Type = Type::SHORT;
+
+    fn count(&self) -> usize {
+        self.len()
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        let mut buf: Vec<u8> = Vec::with_capacity(self.len() * 2);
+        for x in self {
+            buf.extend_from_slice(&x.to_u16().to_ne_bytes());
+        }
+        Cow::Owned(buf)
+    }
+}
+
+// If you pass `&Vec<_>` then you'd get at first sight the  complaint:
+//
+//  `Vec<T>` does not implement `TiffValue`
+//
+// and a list of implementations of `TiffValue` that are quite unrelated. That is not very helpful.
+// We do not *want* `Vec` to implement the trait as an owning type, instead you should pass a
+// reference to a slice. The error message is further customized in the diagnostics of the trait.
+#[diagnostic::do_not_recommend]
 impl<T: TiffValue + ?Sized> TiffValue for &'_ T {
     const BYTE_LEN: u8 = T::BYTE_LEN;
     const FIELD_TYPE: Type = T::FIELD_TYPE;
@@ -467,6 +610,27 @@ impl<T: TiffValue + ?Sized> TiffValue for &'_ T {
     }
 }
 
+/// An array is treated like a slice of the same length.
+impl<T, const N: usize> TiffValue for [T; N]
+where
+    [T]: TiffValue,
+{
+    const BYTE_LEN: u8 = <[T]>::BYTE_LEN;
+    const FIELD_TYPE: Type = <[T]>::FIELD_TYPE;
+
+    fn count(&self) -> usize {
+        self.as_slice().count()
+    }
+
+    fn write<W: Write>(&self, writer: &mut TiffWriter<W>) -> TiffResult<()> {
+        self.as_slice().write(writer)
+    }
+
+    fn data(&self) -> Cow<'_, [u8]> {
+        self.as_slice().data()
+    }
+}
+
 macro_rules! impl_tiff_value_for_contiguous_sequence {
     ($inner_type:ty; $bytes:expr; $field_type:expr) => {
         impl $crate::encoder::TiffValue for [$inner_type] {

src/error.rs

@@ -5,6 +5,7 @@ use std::string;
 use quick_error::quick_error;
 
 use crate::decoder::ChunkType;
+use crate::tags::Type;
 use crate::tags::{
     CompressionMethod, PhotometricInterpretation, PlanarConfiguration, SampleFormat, Tag,
 };
@@ -90,6 +91,9 @@ quick_error! {
         InvalidTypeForTag {
             display("tag has invalid type")
         }
+        InvalidCountForTag(tag: Tag, len: usize) {
+            display("tag `{tag:?}` with incorrect number of elements ({len}) encountered")
+        }
         StripTileTagConflict {
             display("file should contain either (StripByteCounts and StripOffsets) or (TileByteCounts and TileOffsets), other combination was found")
         }
@@ -156,6 +160,9 @@ quick_error! {
         UnsupportedInterpretation(interpretation: PhotometricInterpretation) {
             display("unsupported photometric interpretation \"{interpretation:?}\"")
         }
+        ChromaSubsampling {
+            display("chroma subsampling of YCbCr color is unsupported")
+        }
         MisalignedTileBoundaries {
             display("tile rows are not aligned to byte boundaries")
         }
@@ -202,6 +209,12 @@ quick_error! {
         ReconfiguredAfterImageWrite {
             display("attempted to reconfigure the encoder after image writing has started")
         }
+        ByteOrderMismatch {
+            display("attempted to use data with a byte order that does not match the required one")
+        }
+        MismatchedEntryLength {ty: Type, found: usize } {
+            display("the length of data is not a multiple of the size of the type {ty:?}, found {found}")
+        }
     }
 }
 

src/lib.rs

@@ -44,6 +44,9 @@ pub enum ColorType {
     /// Pixel is YCbCr
     YCbCr(u8),
 
+    /// Pixel is CIE L*a*b* (ICC LAb)
+    Lab(u8),
+
     /// Pixel has multiple bands/channels
     Multiband { bit_depth: u8, num_samples: u16 },
 }
@@ -58,6 +61,7 @@ impl ColorType {
             | ColorType::CMYK(b)
             | ColorType::CMYKA(b)
             | ColorType::YCbCr(b)
+            | ColorType::Lab(b)
             | ColorType::Multiband { bit_depth: b, .. } => b,
         }
     }
@@ -72,6 +76,7 @@ impl ColorType {
             ColorType::CMYK(_) => 4,
             ColorType::CMYKA(_) => 5,
             ColorType::YCbCr(_) => 3,
+            ColorType::Lab(_) => 3,
             ColorType::Multiband { num_samples, .. } => num_samples,
         }
     }

src/tags.rs

@@ -1,3 +1,5 @@
+use crate::encoder::TiffValue;
+
 macro_rules! tags {
     {
         // Permit arbitrary meta items, which include documentation.
@@ -10,8 +12,9 @@ macro_rules! tags {
         $( #[$enum_attr] )*
         #[derive(Clone, Copy, PartialEq, Eq, Debug, Hash)]
         #[non_exhaustive]
+        #[repr($ty)]
         pub enum $name {
-            $($(#[$ident_attr])* $tag,)*
+            $($(#[$ident_attr])* $tag = $val,)*
             $(
                 #[$unknown_meta]
                 Unknown($ty),
@@ -20,7 +23,7 @@ macro_rules! tags {
 
         impl $name {
             #[inline(always)]
-            fn __from_inner_type(n: $ty) -> Result<Self, $ty> {
+            const fn __from_inner_type(n: $ty) -> Result<Self, $ty> {
                 match n {
                     $( $val => Ok($name::$tag), )*
                     n => Err(n),
@@ -28,7 +31,7 @@ macro_rules! tags {
             }
 
             #[inline(always)]
-            fn __to_inner_type(&self) -> $ty {
+            const fn __to_inner_type(&self) -> $ty {
                 match *self {
                     $( $name::$tag => $val, )*
                     $( $name::Unknown($unknown_doc) => { $unknown_doc }, )*
@@ -42,19 +45,25 @@ macro_rules! tags {
     ($name:tt, u16, $($unknown_doc:ident)*) => {
         impl $name {
             #[inline(always)]
-            pub fn from_u16(val: u16) -> Option<Self> {
-                Self::__from_inner_type(val).ok()
+            pub const fn from_u16(val: u16) -> Option<Self> {
+                match Self::__from_inner_type(val) {
+                    Ok(v) => Some(v),
+                    Err(_) => None,
+                }
             }
 
             $(
             #[inline(always)]
-            pub fn from_u16_exhaustive($unknown_doc: u16) -> Self {
-                Self::__from_inner_type($unknown_doc).unwrap_or_else(|_| $name::Unknown($unknown_doc))
+            pub const fn from_u16_exhaustive($unknown_doc: u16) -> Self {
+                match Self::__from_inner_type($unknown_doc) {
+                    Ok(v) => v,
+                    Err(_) => $name::Unknown($unknown_doc),
+                }
             }
             )*
 
             #[inline(always)]
-            pub fn to_u16(&self) -> u16 {
+            pub const fn to_u16(&self) -> u16 {
                 Self::__to_inner_type(self)
             }
         }
@@ -122,6 +131,11 @@ pub enum Tag(u16) unknown(
     SMaxSampleValue = 341, // TODO add support
     // JPEG
     JPEGTables = 347,
+    // Subsampling
+    #[doc(alias = "YCbCrSubsampling")]
+    ChromaSubsampling = 530, // TODO add support
+    #[doc(alias = "YCbCrPositioning")]
+    ChromaPositioning = 531, // TODO add support
     // GeoTIFF
     ModelPixelScaleTag = 33550, // (SoftDesk)
     ModelTransformationTag = 34264, // (JPL Carto Group)
@@ -266,6 +280,8 @@ pub enum PhotometricInterpretation(u16) {
     CMYK = 5,
     YCbCr = 6,
     CIELab = 8,
+    IccLab = 9,
+    ItuLab = 10,
 }
 }
 
@@ -322,6 +338,124 @@ pub enum ExtraSamples(u16) {
 }
 }
 
+/// A value represented as in-memory bytes with flexible byteorder.
+pub struct ValueBuffer {
+    /// The raw bytes of the value.
+    bytes: Vec<u8>,
+
+    /// The type of the value.
+    ty: Type,
+
+    /// The number of items, as `bytes` may be oversized while holding bytes that are initialized
+    /// but not used by any value.
+    count: u64,
+
+    /// The byte order of the value.
+    byte_order: ByteOrder,
+}
+
+impl ValueBuffer {
+    /// A value with a count of zero.
+    ///
+    /// The byte order is set to the native byte order of the platform.
+    pub fn empty(ty: Type) -> Self {
+        ValueBuffer {
+            bytes: vec![],
+            ty,
+            count: 0,
+            byte_order: ByteOrder::native(),
+        }
+    }
+
+    /// Create a value with native byte order from in-memory data.
+    pub fn from_value<T: TiffValue>(value: &T) -> Self {
+        ValueBuffer {
+            bytes: value.data().into_owned(),
+            ty: <T as TiffValue>::FIELD_TYPE,
+            count: value.count() as u64,
+            byte_order: ByteOrder::native(),
+        }
+    }
+
+    pub fn byte_order(&self) -> ByteOrder {
+        self.byte_order
+    }
+
+    pub fn data_type(&self) -> Type {
+        self.ty
+    }
+
+    /// The count of items in the value.
+    pub fn count(&self) -> u64 {
+        debug_assert!({
+            self.ty
+                .value_bytes(self.count)
+                .is_ok_and(|n| n <= self.bytes.len() as u64)
+        });
+
+        self.count
+    }
+
+    /// View the underlying raw bytes of this value.
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.bytes[..self.assumed_len_from_count()]
+    }
+
+    /// View the underlying mutable raw bytes of this value.
+    pub fn as_bytes_mut(&mut self) -> &mut [u8] {
+        let len = self.assumed_len_from_count();
+        &mut self.bytes[..len]
+    }
+
+    /// Change the byte order of the value representation.
+    pub fn set_byte_order(&mut self, byte_order: ByteOrder) {
+        let len = self.assumed_len_from_count();
+
+        self.byte_order
+            .convert(self.ty, &mut self.bytes[..len], byte_order);
+
+        self.byte_order = byte_order;
+    }
+
+    /// Prepare the internal for a value `to_len` bytes long.
+    ///
+    /// Shrinks the allocation if it is far too large or extends it if it is too small. In either
+    /// case ensures that at least `to_len` bytes are initialized for [`Self::raw_bytes_mut`].
+    pub(crate) fn prepare_length(&mut self, to_len: usize) {
+        if to_len > self.bytes.len() {
+            self.bytes.resize(to_len, 0);
+        }
+
+        if self.bytes.len() < to_len / 2 {
+            self.bytes.truncate(to_len);
+            self.bytes.shrink_to_fit();
+        }
+    }
+
+    /// Internal method to change the type and count while re-interpreting the byte buffer.
+    ///
+    /// Should only be called after writing bytes to the internal buffer prepared with
+    /// `Self::prepare_length`.
+    pub(crate) fn assume_type(&mut self, ty: Type, count: u64, bo: ByteOrder) {
+        debug_assert!({
+            ty.value_bytes(count)
+                .is_ok_and(|n| n <= self.bytes.len() as u64)
+        });
+
+        self.byte_order = bo;
+        self.ty = ty;
+        self.count = count;
+    }
+
+    pub(crate) fn raw_bytes_mut(&mut self) -> &mut [u8] {
+        &mut self.bytes
+    }
+
+    fn assumed_len_from_count(&self) -> usize {
+        usize::from(self.ty.byte_len()) * self.count as usize
+    }
+}
+
 /// Byte order of the TIFF file.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum ByteOrder {

tests/decode_planes.rs

@@ -1,4 +1,4 @@
-use tiff::decoder::{Decoder, TiffCodingUnit};
+use tiff::decoder::{Decoder, DecodingResult, Limits, TiffCodingUnit};
 
 use std::fs::File;
 use std::path::PathBuf;
@@ -74,3 +74,50 @@ fn read_first_coding_unit() {
         }
     }
 }
+
+#[test]
+fn read_planes_by_limits() {
+    let path = PathBuf::from(TEST_IMAGE_DIR).join("planar-rgb-u8.tif");
+    let file = File::open(path).unwrap();
+    let io = std::io::BufReader::new(file);
+
+    let mut limits = Limits::default();
+    let mut buffer = DecodingResult::U8(vec![]);
+
+    // Make room for 1 plane.
+    let mut tif = Decoder::new(io).unwrap();
+    tif = tif.with_limits({
+        limits.decoding_buffer_size = 374 * 499;
+        limits.clone()
+    });
+
+    tif.read_image_to_buffer(&mut buffer).unwrap();
+    assert_eq!(buffer.as_buffer(0).byte_len(), 374 * 499);
+
+    // Make room for 2 planes.
+    tif = tif.with_limits({
+        limits.decoding_buffer_size = 374 * 499 * 2;
+        limits.clone()
+    });
+
+    tif.read_image_to_buffer(&mut buffer).unwrap();
+    assert_eq!(buffer.as_buffer(0).byte_len(), 374 * 499);
+
+    // Make room for 3 planes.
+    tif = tif.with_limits({
+        limits.decoding_buffer_size = 374 * 499 * 3;
+        limits.clone()
+    });
+
+    tif.read_image_to_buffer(&mut buffer).unwrap();
+    assert_eq!(buffer.as_buffer(0).byte_len(), 374 * 499 * 3);
+
+    // Make room for 4 planes?
+    tif = tif.with_limits({
+        limits.decoding_buffer_size = 374 * 499 * 4;
+        limits.clone()
+    });
+
+    tif.read_image_to_buffer(&mut buffer).unwrap();
+    assert_eq!(buffer.as_buffer(0).byte_len(), 374 * 499 * 3);
+}