Add metadata and changelog for 0.10.3

Make fax a default feature

CHANGES.md

@@ -1,3 +1,19 @@
+# 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`).

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tiff"
-version = "0.10.2"
+version = "0.10.3"
 edition = "2021"
 resolver = "2"
 
@@ -20,6 +20,8 @@ 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 }
@@ -31,10 +33,11 @@ criterion = "0.3.1"
 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/decoder/ifd.rs

@@ -577,10 +577,10 @@ impl Entry {
             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])))
+                Ok(Byte(buf[0]))
             }),
             Type::SBYTE => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
-                Ok(SignedBig(i64::from(reader.read_i8()?)))
+                Ok(SignedByte(reader.read_i8()?))
             }),
             Type::SHORT => self.decode_offset(self.count, bo, bigtiff, limits, reader, |reader| {
                 Ok(Short(reader.read_u16()?))

src/decoder/image.rs

@@ -9,6 +9,7 @@ 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;
@@ -343,6 +344,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)),
@@ -384,7 +388,9 @@ impl Image {
         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),
@@ -452,6 +458,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),
@@ -658,6 +670,7 @@ impl Image {
             compression_method,
             *compressed_bytes,
             self.jpeg_tables.as_deref().map(|a| &**a),
+            chunk_dims,
         )?;
 
         if output_row_stride == chunk_row_bytes {
@@ -674,7 +687,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
@@ -691,7 +704,7 @@ 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 {
@@ -713,7 +726,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

@@ -475,11 +475,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) => {
@@ -512,8 +523,14 @@ 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.
@@ -547,7 +564,6 @@ fn fix_endianness(buf: &mut [u8], byte_order: ByteOrder, bit_depth: u8) {
 }
 
 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)?;

src/decoder/stream.rs

@@ -1,5 +1,4 @@
 //! All IO functionality needed for TIFF decoding
-
 use std::io::{self, BufRead, BufReader, Read, Seek, Take};
 
 /// Byte order of the TIFF file.
@@ -276,6 +275,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::*;

tests/decode_images.rs

@@ -672,3 +672,15 @@ fn bytes_gray_f32() {
         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);
+}