path: root/doc/functions/libtiff.rst

libtiff
=======

Synopsis
--------

.. highlight:: c

::

    #include <tiffio.h>

.. highlight:: shell

::

    cc file.c -ltiff

Description
-----------

:program:`libtiff` is a library for reading and writing data files encoded with the
*"Tag Image File"* format, Revision 6.0 (or revision 5.0 or revision 4.0). This file format is
suitable for archiving multi-color and monochromatic image data.

The library supports several compression algorithms, as indicated by the
``Compression`` field, including:
no compression (1),
CCITT 1D Huffman compression (2),
CCITT Group 3 Facsimile compression (3),
CCITT Group 4 Facsimile compression (4),
Lempel-Ziv & Welch compression (5),
baseline JPEG compression (7),
word-aligned 1D Huffman compression (32771),
PackBits compression (32773).
In addition, several nonstandard compression algorithms are supported: the
4-bit compression algorithm used by the
*ThunderScan* program (32809) (decompression only),
NeXT's 2-bit compression algorithm (32766) (decompression only),
an experimental LZ-style algorithm known as Deflate (32946),
and an experimental CIE LogLuv compression scheme designed
for images with high dynamic range (32845 for LogL and 32845 for LogLuv).
Directory information may be in either little- or big-endian byte order; byte
swapping is automatically done by the library. Data bit ordering may be either
Most Significant Bit (``MSB``) to Least Significant Bit (``LSB``) or
LSB to MSB.
Finally, the library does not support files in which the
``BitsPerSample`` ,
``Compression`` ,
``MinSampleValue`` ,
or
``MaxSampleValue``
fields are defined differently on a per-sample basis
(in Rev. 6.0 the
``Compression``
tag is not defined on a per-sample basis, so this is immaterial).







List of routines
----------------

The following routines are part of the library. Consult specific manual pages
for details on their operation; on most systems doing :command:`man function-name`
will work.

.. list-table:: libtiff functions
    :widths: 5 20
    :header-rows: 1

    * - Name
      - Description
    * - :c:func:`TIFFCheckpointDirectory`
      - writes the current state of the directory
    * - :c:func:`TIFFCheckTile`
      - very x,y,z,sample is within image
    * - :c:func:`TIFFCIELabToRGBInit`
      - initialize CIE L*a*b* 1976 to RGB conversion state
    * - :c:func:`TIFFCIELabToXYZ`
      - perform CIE L*a*b* 1976 to CIE XYZ conversion
    * - :c:func:`TIFFClientOpen`
      - open a file for reading or writing
    * - :c:func:`TIFFClose`
      - close an open file
    * - :c:func:`TIFFComputeStrip`
      - return strip containing y,sample
    * - :c:func:`TIFFComputeTile`
      - return tile containing x,y,z,sample
    * - :c:func:`TIFFCurrentDirectory`
      - return index of current directory
    * - :c:func:`TIFFCurrentRow`
      - return index of current scanline
    * - :c:func:`TIFFCurrentStrip`
      - return index of current strip
    * - :c:func:`TIFFCurrentTile`
      - return index of current tile
    * - :c:func:`TIFFDataWidth`
      - return the size of TIFF data types
    * - :c:func:`TIFFError`
      - library error handler
    * - :c:func:`TIFFFdOpen`
      - open a file for reading or writing
    * - :c:func:`TIFFFieldDataType`
      - get data type from field information
    * - :c:func:`TIFFFieldName`
      - get field name from field information
    * - :c:func:`TIFFFieldPassCount`
      - get whether to pass a value count to Get/SetField
    * - :c:func:`TIFFFieldReadCount`
      - get number of values to be read from field
    * - :c:func:`TIFFFieldTag`
      - get tag value from field information
    * - :c:func:`TIFFFieldWithName`
      - get field information given field name
    * - :c:func:`TIFFFieldWithTag`
      - get field information given tag
    * - :c:func:`TIFFFieldWriteCount`
      - get number of values to be written to field
    * - :c:func:`TIFFFileName`
      - return name of open file
    * - :c:func:`TIFFFileno`
      - return open file descriptor
    * - :c:func:`TIFFFindCODEC`
      - find standard codec for the specific scheme
    * - :c:func:`TIFFFindField`
      - get field information given tag and data type
    * - :c:func:`TIFFFlush`
      - flush all pending writes
    * - :c:func:`TIFFFlushData`
      - flush pending data writes
    * - :c:func:`TIFFGetBitRevTable`
      - return bit reversal table
    * - :c:func:`TIFFGetField`
      - return tag value in current directory
    * - :c:func:`TIFFGetFieldDefaulted`
      - return tag value in current directory
    * - :c:func:`TIFFGetMode`
      - return open file mode
    * - :c:func:`TIFFGetVersion`
      - return library version string
    * - :c:func:`TIFFIsCODECConfigured`
      - check, whether we have working codec
    * - :c:func:`TIFFIsMSB2LSB`
      - return true if image data is being returned
    * - :c:func:``
      - with bit 0 as the most significant bit 
    * - :c:func:`TIFFIsTiled`
      - return true if image data is tiled
    * - :c:func:`TIFFIsByteSwapped`
      - return true if image data is byte-swapped
    * - :c:func:`TIFFNumberOfStrips`
      - return number of strips in an image
    * - :c:func:`TIFFNumberOfTiles`
      - return number of tiles in an image
    * - :c:func:`TIFFOpen`
      - open a file for reading or writing
    * - :c:func:`TIFFPrintDirectory`
      - print description of the current directory
    * - :c:func:`TIFFReadBufferSetup`
      - specify i/o buffer for reading
    * - :c:func:`TIFFReadDirectory`
      - read the next directory
    * - :c:func:`TIFFReadEncodedStrip`
      - read and decode a strip of data
    * - :c:func:`TIFFReadEncodedTile`
      - read and decode a tile of data
    * - :c:func:`TIFFReadRawStrip`
      - read a raw strip of data
    * - :c:func:`TIFFReadRawTile`
      - read a raw tile of data
    * - :c:func:`TIFFReadRGBAImage`
      - read an image into a fixed format raster
    * - :c:func:`TIFFReadScanline`
      - read and decode a row of data
    * - :c:func:`TIFFReadTile`
      - read and decode a tile of data
    * - :c:func:`TIFFRegisterCODEC`
      - override standard codec for the specific scheme
    * - :c:func:`TIFFReverseBits`
      - reverse bits in an array of bytes
    * - :c:func:`TIFFRGBAImageBegin`
      - setup decoder state for TIFFRGBAImageGet
    * - :c:func:`TIFFRGBAImageEnd`
      - release TIFFRGBAImage decoder state
    * - :c:func:`TIFFRGBAImageGet`
      - read and decode an image
    * - :c:func:`TIFFRGBAImageOK`
      - is image readable by TIFFRGBAImageGet
    * - :c:func:`TIFFScanlineSize`
      - return size of a scanline
    * - :c:func:`TIFFSetDirectory`
      - set the current directory
    * - :c:func:`TIFFSetSubDirectory`
      - set the current directory
    * - :c:func:`TIFFSetErrorHandler`
      - set error handler function
    * - :c:func:`TIFFSetField`
      - set a tag's value in the current directory
    * - :c:func:`TIFFSetWarningHandler`
      - set warning handler function
    * - :c:func:`TIFFStripSize`
      - returns size of a strip
    * - :c:func:`TIFFRawStripSize`
      - returns the number of bytes in a raw strip
    * - :c:func:`TIFFSwabShort`
      - swap bytes of short
    * - :c:func:`TIFFSwabLong`
      - swap bytes of long
    * - :c:func:`TIFFSwabArrayOfShort`
      - swap bytes of an array of shorts
    * - :c:func:`TIFFSwabArrayOfLong`
      - swap bytes of an array of longs
    * - :c:func:`TIFFTileRowSize`
      - return size of a row in a tile
    * - :c:func:`TIFFTileSize`
      - return size of a tile
    * - :c:func:`TIFFUnRegisterCODEC`
      - unregisters the codec
    * - :c:func:`TIFFVGetField`
      - return tag value in current directory
    * - :c:func:`TIFFVGetFieldDefaulted`
      - return tag value in current directory
    * - :c:func:`TIFFVSetField`
      - set a tag's value in the current directory
    * - :c:func:`TIFFVStripSize`
      - returns the number of bytes in a strip
    * - :c:func:`TIFFWarning`
      - library warning handler
    * - :c:func:`TIFFWriteDirectory`
      - write the current directory
    * - :c:func:`TIFFWriteEncodedStrip`
      - compress and write a strip of data
    * - :c:func:`TIFFWriteEncodedTile`
      - compress and write a tile of data
    * - :c:func:`TIFFWriteRawStrip`
      - write a raw strip of data
    * - :c:func:`TIFFWriteRawTile`
      - write a raw tile of data
    * - :c:func:`TIFFWriteScanline`
      - write a scanline of data
    * - :c:func:`TIFFWriteTile`
      - compress and write a tile of data
    * - :c:func:`TIFFXYZToRGB`
      - perform CIE XYZ to RGB conversion
    * - :c:func:`TIFFYCbCrToRGBInit`
      - initialize YCbCr to RGB conversion state
    * - :c:func:`TIFFYCbCrtoRGB`
      - perform YCbCr to RGB conversion

.. list-table:: libtiff auxillary functions
    :widths: 5 20
    :header-rows: 1

    * - Name
      - Description
    * - :c:func:`_TIFFfree`
      - free memory buffer
    * - :c:func:`_TIFFmalloc`
      - dynamically allocate memory buffer
    * - :c:func:`_TIFFmemcmp`
      - compare contents of the memory buffers
    * - :c:func:`_TIFFmemcpy`
      - copy contents of the one buffer to another
    * - :c:func:`_TIFFmemset`
      - fill memory buffer with a constant byte
    * - :c:func:`_TIFFrealloc`
      - dynamically reallocate memory buffer

Tag usage
---------

The table below lists the TIFF
tags that are recognized and handled by the library.
If no use is indicated in the table, then the library
reads and writes the tag, but does not use it internally.
Note that some tags are meaningful only when a particular
compression scheme is being used; e.g. ``Group3Options``
is only useful if ``Compression``
is set to CCITT Group 3 encoding.
Tags of this sort are considered *codec-specific*
tags and the library does not recognize them except when the
``Compression``
tag has been previously set to the relevant compression scheme.

.. list-table:: libtiff supported tags
    :widths: 10 2 2 15
    :header-rows: 1

    * - Tag name
      - Value
      - R/W
      - Library Use/Notes
    * - ``Artist``
      - 315
      - R/W
      -
    * - ``BadFaxLines``
      - 326
      - R/W
      -
    * - ``BitsPerSample``
      - 258
      - R/W
      - lots
    * - ``CellLength``
      - 265
      -
      - parsed but ignored
    * - ``CellWidth``
      - 264
      -
      - parsed but ignored
    * - ``CleanFaxData``
      - 327
      - R/W
      -
    * - ``ColorMap``
      - 320
      - R/W
      -
    * - ``ColorResponseUnit``
      - 300
      -
      - parsed but ignored
    * - ``Compression``
      - 259
      - R/W
      - choosing codec
    * - ``ConsecutiveBadFaxLines``
      - 328
      - R/W
      -
    * - ``Copyright``
      - 33432
      - R/W
      -
    * - ``DataType``
      - 32996
      - R
      - obsoleted by ``SampleFormat`` tag
    * - ``DateTime``
      - 306
      - R/W
      -
    * - ``DocumentName``
      - 269
      - R/W
      -
    * - ``DotRange``
      - 336
      - R/W
      -
    * - ``ExtraSamples``
      - 338
      - R/W
      - lots
    * - ``FaxRecvParams``
      - 34908
      - R/W
      -
    * - ``FaxSubAddress``
      - 34909
      - R/W
      -
    * - ``FaxRecvTime``
      - 34910
      - R/W
      -
    * - ``FillOrder``
      - 266
      - R/W
      - control bit order
    * - ``FreeByteCounts``
      - 289	
      -
      - parsed but ignored
    * - ``FreeOffsets``
      - 288	
      -
      - parsed but ignored
    * - ``GrayResponseCurve``
      - 291	
      -
      - parsed but ignored
    * - ``GrayResponseUnit``
      - 290	
      -
      - parsed but ignored
    * - ``Group3Options``
      - 292
      - R/W
      - used by Group 3 codec
    * - ``Group4Options``
      - 293
      - R/W
      -
    * - ``HostComputer``
      - 316
      - R/W
      -
    * - ``ImageDepth``
      - 32997
      - R/W
      - tile/strip calculations
    * - ``ImageDescription``
      - 270
      - R/W
      -
    * - ``ImageLength``
      - 257
      - R/W
      - lots
    * - ``ImageWidth``
      - 256
      - R/W
      - lots
    * - ``InkNames``
      - 333
      - R/W
      -
    * - ``InkSet``
      - 332
      - R/W
      -
    * - ``JPEGTables``
      - 347
      - R/W
      - used by JPEG codec
    * - ``Make``
      - 271
      - R/W
      -
    * - ``Matteing``
      - 32995
      - R
      - obsoleted by ExtraSamples tag
    * - ``MaxSampleValue``
      - 281
      - R/W
      -
    * - ``MinSampleValue``
      - 280
      - R/W
      -
    * - ``Model``
      - 272
      - R/W
      -
    * - ``NewSubFileType``
      - 254
      - R/W
      - called ``SubFileType`` in spec
    * - ``NumberOfInks``
      - 334
      - R/W
      -
    * - ``Orientation``
      - 274
      - R/W
      -
    * - ``PageName``
      - 285
      - R/W
      -
    * - ``PageNumber``
      - 297
      - R/W
      -
    * - ``PhotometricInterpretation``
      - 262
      - R/W
      - used by Group 3 and JPEG codecs
    * - ``PlanarConfiguration``
      - 284
      - R/W
      - data i/o
    * - ``Predictor``
      - 317
      - R/W
      - used by LZW and Deflate codecs
    * - ``PrimaryChromacities``
      - 319
      - R/W
      -
    * - ``ReferenceBlackWhite``
      - 532
      - R/W
      -
    * - ``ResolutionUnit``
      - 296
      - R/W
      - used by Group 3 codec
    * - ``RowsPerStrip``
      - 278
      - R/W
      - data i/o
    * - ``SampleFormat``
      - 339
      - R/W
      -
    * - ``SamplesPerPixel``
      - 277
      - R/W
      - lots
    * - ``SMinSampleValue``
      - 340
      - R/W
      -
    * - ``SMaxSampleValue``
      - 341
      - R/W
      -
    * - ``Software``
      - 305
      - R/W
      -
    * - ``StoNits``
      - 37439
      - R/W
      -
    * - ``StripByteCounts``
      - 279
      - R/W
      - data i/o
    * - ``StripOffsets``
      - 273
      - R/W
      - data i/o
    * - ``SubFileType``
      - 255
      - R/W
      - called ``OSubFileType`` in spec
    * - ``TargetPrinter``
      - 337
      - R/W
      -
    * - ``Thresholding``
      - 263
      - R/W
      - 
    * - ``TileByteCounts``
      - 324
      - R/W
      - data i/o
    * - ``TileDepth``
      - 32998
      - R/W
      - tile/strip calculations
    * - ``TileLength``
      - 323
      - R/W
      - data i/o
    * - ``TileOffsets``
      - 324
      - R/W
      - data i/o
    * - ``TileWidth``
      - 322
      - R/W
      - data i/o
    * - ``TransferFunction``
      - 301
      - R/W
      -
    * - ``WhitePoint``
      - 318
      - R/W
      -
    * - ``XPosition``
      - 286
      - R/W
      -
    * - ``XResolution``
      - 282
      - R/W
      -
    * - ``YCbCrCoefficients``
      - 529
      - R/W
      - used by ``TIFFRGBAImage`` support
    * - ``YCbCrPositioning``
      - 531
      - R/W
      - tile/strip size calculations
    * - ``YCbCrSubsampling``
      - 530
      - R/W
      -
    * - ``YPosition``
      - 286
      - R/W
      -
    * - ``YResolution``
      - 283
      - R/W
      - used by Group 3 codec

"Pseudo tags"
-------------

In addition to the normal TIFF
tags the library supports a collection of 
tags whose values lie in a range outside the valid range of TIFF
tags. These tags are termed *pseudo-tags*
and are used to control various codec-specific functions within the library.
The table below summarizes the defined pseudo-tags.

.. list-table:: libtiff supported tags
    :widths: 10 2 2 15
    :header-rows: 1

    * - Tag name
      - Codec
      - R/W
      - Library Use/Notes

    * - :c:macro:`TIFFTAG_FAXMODE`
      - G3
      - R/W
      - general codec operation
    * - :c:macro:`TIFFTAG_FAXFILLFUNC`
      - G3/G4
      - R/W
      - bitmap fill function
    * - :c:macro:`TIFFTAG_JPEGQUALITY`
      - JPEG
      - R/W
      - compression quality control
    * - :c:macro:`TIFFTAG_JPEGCOLORMODE`
      - JPEG
      - R/W
      - control colorspace conversions
    * - :c:macro:`TIFFTAG_JPEGTABLESMODE`
      - JPEG
      - R/W
      - control contents of ``JPEGTables`` tag
    * - :c:macro:`TIFFTAG_ZIPQUALITY`
      - Deflate
      - R/W
      - compression quality level
    * - :c:macro:`TIFFTAG_PIXARLOGDATAFMT`
      - PixarLog
      - R/W
      - user data format
    * - :c:macro:`TIFFTAG_PIXARLOGQUALITY`
      - PixarLog
      - R/W
      - compression quality level
    * - :c:macro:`TIFFTAG_SGILOGDATAFMT`
      - SGILog
      - R/W
      - user data format

:c:macro:`TIFFTAG_FAXMODE`:

  Control the operation of the Group 3 codec.
  Possible values (independent bits that can be combined by
  or'ing them together) are:

  :c:macro:`FAXMODE_CLASSIC`:

    (enable old-style format in which the ``RTC``
    is written at the end of the last strip),

  :c:macro:`FAXMODE_NORTC`:

    (opposite of :c:macro:`FAXMODE_CLASSIC`; also called
    :c:macro:`FAXMODE_CLASSF`),

  :c:macro:`FAXMODE_NOEOL`:

    (do not write ``EOL`` codes at the start of each row of data),

  :c:macro:`FAXMODE_BYTEALIGN`:

    (align each encoded row to an 8-bit boundary),

  :c:macro:`FAXMODE_WORDALIGN`:

    (align each encoded row to an 16-bit boundary),

  The default value is dependent on the compression scheme; this
  pseudo-tag is used by the various G3 and G4 codecs to share code.

:c:macro:`TIFFTAG_FAXFILLFUNC`:

  Control the function used to convert arrays of black and white
  runs to packed bit arrays.
  This hook can be used to image decoded scanlines in multi-bit
  depth rasters (e.g. for display in colormap mode)
  or for other purposes.
  The default value is a pointer to a builtin function that images
  packed bilevel data.

:c:macro:`TIFFTAG_IPTCNEWSPHOTO`:

  Tag contains image metadata per the IPTC newsphoto spec: Headline,
  captioning, credit, etc... Used by most wire services.

:c:macro:`TIFFTAG_PHOTOSHOP`:

  Tag contains Photoshop captioning information and metadata. Photoshop
  uses in parallel and redundantly alongside :c:macro:`IPTCNEWSPHOTO` information.

:c:macro:`TIFFTAG_JPEGQUALITY`:

  Control the compression quality level used in the baseline algorithm.
  Note that quality levels are in the range 0-100 with a default value of 75.

:c:macro:`TIFFTAG_JPEGCOLORMODE`:

  Control whether or not conversion is done between
  RGB and YCbCr colorspaces.
  Possible values are:

  :c:macro:`JPEGCOLORMODE_RAW`:

    (do not convert), and

  :c:macro:`JPEGCOLORMODE_RGB`:

    (convert to/from RGB)

  The default value is :c:macro:`JPEGCOLORMODE_RAW`.

:c:macro:`TIFFTAG_JPEGTABLESMODE`:

  Control the information written in the ``JPEGTables`` tag.
  Possible values (independent bits that can be combined by
  or'ing them together) are:

  :c:macro:`JPEGTABLESMODE_QUANT`:

    (include quantization tables), and

  :c:macro:`JPEGTABLESMODE_HUFF`:

    (include Huffman encoding tables).

  The default value is :c:expr:`JPEGTABLESMODE_QUANT|JPEGTABLESMODE_HUFF`.

:c:macro:`TIFFTAG_ZIPQUALITY`:

  Control the compression technique used by the Deflate codec.
  Quality levels are in the range 1-9 with larger numbers yielding better
  compression at the cost of more computation.
  The default quality level is 6 which yields a good time-space tradeoff.

:c:macro:`TIFFTAG_PIXARLOGDATAFMT`:

  Control the format of user data passed *in*
  to the PixarLog codec when encoding and passed
  *out* from when decoding. Possible values are:

  :c:macro:`PIXARLOGDATAFMT_8BIT`:

    for 8-bit unsigned pixels,

  :c:macro:`PIXARLOGDATAFMT_8BITABGR`:

    for 8-bit unsigned ABGR-ordered pixels,

  :c:macro:`PIXARLOGDATAFMT_11BITLOG`:

    for 11-bit log-encoded raw data,

  :c:macro:`PIXARLOGDATAFMT_12BITPICIO`:

    for 12-bit PICIO-compatible data,

  :c:macro:`PIXARLOGDATAFMT_16BIT`:

    for 16-bit signed samples, and

  :c:macro:`PIXARLOGDATAFMT_FLOAT`:

    for 32-bit IEEE floating point samples.

:c:macro:`TIFFTAG_PIXARLOGQUALITY`:

  Control the compression technique used by the PixarLog codec.
  This value is treated identically to :c:macro:`TIFFTAG_ZIPQUALITY`; see the
  above description.

:c:macro:`TIFFTAG_SGILOGDATAFMT`:

  Control the format of client data passed *in*
  to the SGILog codec when encoding and passed
  *out* from when decoding.  Possible values are:

  :c:macro:`SGILOGDATAFMT_FLTXYZ`:

    for converting between LogLuv and 32-bit IEEE floating valued XYZ pixels,

  :c:macro:`SGILOGDATAFMT_16BITLUV`:

    for 16-bit encoded Luv pixels,

  :c:macro:`SGILOGDATAFMT_32BITRAW`:
  :c:macro:`SGILOGDATAFMT_24BITRAW`:

     for no conversion of data,

  :c:macro:`SGILOGDATAFMT_8BITRGB`:

    for returning 8-bit RGB data (valid only when decoding LogLuv-encoded data),

  :c:macro:`SGILOGDATAFMT_FLTY`:

    for converting between LogL and 32-bit IEEE floating valued Y pixels,

  :c:macro:`SGILOGDATAFMT_16BITL`:

    for 16-bit encoded L pixels, and

  :c:macro:`SGILOGDATAFMT_8BITGRY`:

    for returning 8-bit greyscale data
    (valid only when decoding LogL-encoded data).

Diagnostics
-----------

All error messages are directed through the :c:func:`TIFFError` routine.
By default messages are directed to ``stderr`` in the form:
``module: message\n``.
Warning messages are likewise directed through the
:c:func:`TIFFWarning` routine.

See also
--------

:doc:`TIFFtypes`,
:doc:`/tools/fax2tiff`,
:doc:`/tools/pal2rgb`,
:doc:`/tools/ppm2tiff`,
:doc:`/tools/rgb2ycbcr`,
:doc:`/tools/raw2tiff`,
:doc:`/tools/tiff2bw`,
:doc:`/tools/tiffdither`,
:doc:`/tools/tiffdump`,
:doc:`/tools/tiffcp`,
:doc:`/tools/tiffcmp`,
:doc:`/tools/tiffgt`,
:doc:`/tools/tiffinfo`,
:doc:`/tools/tiffmedian`,
:doc:`/tools/tiffsplit`,

**"Tag Image File Format Specification *Revision 6.0*"**,
an Aldus Technical Memorandum.

**"The Spirit of TIFF Class F"** ,
an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies.

Bugs
----

* The library does not support multi-sample images
  where some samples have different bits/sample.

* The library does not support random access to compressed data
  that is organized with more than one row per tile or strip.