TiffEncoder Class

The container is the part of TIFF 6.0 that any reader accepts: little-endian by default, chunky samples, top-down strips, no predictor for integer samples. TiffEncoder.Compression selects no compression, Deflate (the default), LZW, PackBits, the CCITT facsimile compressions or JPEG. TiffEncoder.Predictor selects horizontal differencing for the integer samples of Deflate and LZW pages, and TiffEncoder.TileWidth and TiffEncoder.TileHeight write tiles instead of strips. Planar storage is never written.

By default (TiffPixelLayout.Auto) the sample layout follows the pixel format of the image, losslessly: Gray8/Gray16 become 8- or 16-bit BlackIsZero grayscale, La16/La32 (and A8, written as black with its alpha) the same grayscale with an alpha sample, Rgb24/Rgb48 8- or 16-bit RGB, and the other formats with alpha RGBA, the alpha with ExtraSamples = 2 (unassociated, straight alpha). Nothing is quantized and alpha is never dropped. RgbaFloat and RgbaHalf become 32-bit floating-point samples (SampleFormat = 3), every value kept, in the fewest samples that hold the page: gray when the three colors of every pixel are the same number and no ICC profile is written, and without alpha when every alpha is exactly 1. Deflate and LZW strips of floating-point samples use the floating-point predictor of TIFF Technical Note 3 (Predictor = 3). A floating-point page without ICC profile is read as linear light, so its pixels must be labeled ColorTransferFunction.Linear (the label of a new floating-point image) or described by a profile; otherwise ImageEncoder.MetadataHandling decides. The bilevel and palette layouts and JPEG compression do not store floating-point samples: ImageEncoder.FloatingPointConversion reduces them first. TiffEncoder.PixelLayout also selects a bilevel layout (one bit per pixel) and a palette layout, which store the image exactly or reject it: this encoder has no background color, no bit-depth-reduction switch and no color reduction. The only output that is not exact is the one of TiffCompression.Jpeg, which is lossy by nature and selected explicitly. CMYK data is never written.

The destination must be seekable. A TIFF directory stores the offsets of the strips it describes, so it can only be written once their compressed sizes are known; the encoder writes the pixel data first and then patches the header and the directory pointers. A non-seekable stream is rejected before anything is written. File destinations are always seekable.

One Image.Save writes a one-page document; use ImageCollection.Save to write several pages, whose sizes, pixel formats and metadata may all differ. Animated images are rejected: the pages of a document are not animation frames.

Metadata (subject to ImageEncoder.MetadataHandling): the resolution (XResolution/YResolution/ResolutionUnit), the orientation (Orientation), the ICC profile (InterColorProfile) and the XMP packet (XMP). An EXIF block and text entries are not stored (rejected by default). A profile describes the written samples: a bilevel page is grayscale and a palette page is RGB, whatever the pixel format of the image, so a profile of the other color space is metadata the page cannot store.