libtiff  -  introduction to libtiff, a library for reading
       and writing TIFF files


SYNOPSIS

       #include <tiffio.h>
       cc file.c -ltiff


DESCRIPTION

       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  suit­
       able  for  archiving  multi-color  and monochromatic image
       data.

       The library supports several  compression  algorithms,  as
       indicated by the Compression field, including: no compres­
       sion (1), CCITT 1D Huffman compression (2), CCITT Group  3
       Facsimile  compression  (3),  CCITT Group 4 Facsimile com­
       pression (4), Lempel-Ziv & Welch compression (5), baseline
       JPEG  compression (7), word-aligned 1D Huffman compression
       (32771), and 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 com­
       pression algorithm (32766) (decompression only), an exper­
       imental  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  lit­
       tle-  or  big-endian byte order-byte swapping is automati­
       cally 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  sup­
       port  files  in which the BitsPerSample, Compression, Min­
       SampleValue, or MaxSampleValue fields are defined  differ­
       ently  on  a per-sample basis (in Rev. 6.0 the Compression
       tag is not defined on a per-sample basis, so this is imma­
       terial).


DATA TYPES

       The  library  makes extensive use of C typedefs to promote
       portability.  Two sets of typedefs are used, one for  com­
       munication  with clients of the library and one for inter­
       nal data structures and parsing of the TIFF  format.   The
       following  typedefs  are  exposed  to users either through
       function definitions or through parameters passed  through
       the varargs interfaces.
            typedef unsigned short uint16;      16-bit unsigned integer
            typedef unsigned <thing> uint32;    32-bit unsigned integer
            typedef unsigned int ttag_t;        directory tag
            typedef uint16 tdir_t;              directory index
            typedef uint16 tsample_t;           sample number
            typedef uint32 tstrip_t;            strip number

            typedef int32 tsize_t;              i/o size in bytes
            typedef void* tdata_t;              image data ref
            typedef void* thandle_t;            client data handle
            typedef int32 toff_t;               file offset
       Note  that  tstrip_t, ttile_t, and tsize_t are constrained
       to be no more than 32-bit quantities by 32-bit fields they
       are  stored  in  in the TIFF image.  Likewise tsample_t is
       limited by the 16-bit field used to store the  SamplesPer­
       Pixel  tag.   tdir_t constrains the maximum number of IFDs
       that may appear in an image and may be an  arbitrary  size
       (w/o  penalty).   ttag_t must be either int, unsigned int,
       pointer, or double because  the  library  uses  a  varargs
       interface  and  ANSI C restricts the type of the parameter
       before an ellipsis to  be  a  promoted  type.   toff_t  is
       defined  as int32 because TIFF file offsets are (unsigned)
       32-bit quantities.  A signed value is  used  because  some
       interfaces  return  -1 on error.  Finally, note that user-
       specified data references are passed as opaque handles and
       only  cast  at  the lowest layers where their type is pre­
       sumed.


LIST OF ROUTINES

       The following routines are part of the  library.   Consult
       specific manual pages for details on their operation.  The
       manual page names listed below are for systems  where  the
       full  function names can not be encoded in the filesystem;
       on most systems doing ``man function-name'' will work.
       Name                   Appears on Page  Description
       TIFFCheckTile          tile.3t          very x,y,z,sample is within image
       TIFFClientOpen         open.3t          open a file for reading or writing
       TIFFClose              close.3t         close an open file
       TIFFComputeStrip       strip.3t         return strip containing y,sample
       TIFFComputeTile        tile.3t          return tile containing x,y,z,sample
       TIFFCurrentDirectory   query.3t         return index of current directory
       TIFFCurrentRow         query.3t         return index of current scanline
       TIFFCurrentStrip       query.3t         return index of current strip
       TIFFCurrentTile        query.3t         return index of current tile
       TIFFError              error.3t         library error handler
       TIFFFdOpen             open.3t          open a file for reading or writing
       TIFFFileName           query.3t         return name of open file
       TIFFFileno             query.3t         return open file descriptor
       TIFFFlush              flush.3t         flush all pending writes
       TIFFFlushData          flush.3t         flush pending data writes
       TIFFGetBitRevTable     swab.3t          return bit reversal table
       TIFFGetField           getfield.3t      return tag value in current directory
       TIFFGetFieldDefaulted  getfield.3t      return tag value in current directory
       TIFFGetMode            query.3t         return open file mode
       TIFFGetVersion         query.3t         return library version string
       TIFFIsTiled            query.3t         return true if image data is tiled
       TIFFIsByteSwapped      query.3t         return true if image data is byte-swapped
       TIFFNumberOfStrips     strip.3t         return number of strips in an image
       TIFFNumberOfTiles      tile.3t          return number of tiles in an image
       TIFFOpen               open.3t          open a file for reading or writing

       TIFFReadBufferSetup    rdbuf.3t         specify i/o buffer for reading
       TIFFReadDirectory      readdir.3t       read the next directory
       TIFFReadEncodedStrip   rdestrip.3t      read and decode a strip of data
       TIFFReadEncodedTile    rdetile.3t       read and decode a tile of data
       TIFFReadRawStrip       rdrstrip.3t      read a raw strip of data
       TIFFReadRawTile        rdrtile.3t       read a raw tile of data
       TIFFReadRGBAImage      rdimage.3t       read an image into a fixed format raster
       TIFFReadScanline       readline.3t      read and decode a row of data
       TIFFReadTile           readtile.3t      read and decode a tile of data
       TIFFReverseBits        swab.3t          reverse bits in an array of bytes
       TIFFRGBAImageBegin     rgbaimage.3t     setup decoder state for TIFFRGBAImageGet
       TIFFRGBAImageEnd       rgbaimage.3t     release TIFFRGBAImage decoder state
       TIFFRGBAImageGet       rgbaimage.3t     read and decode an image
       TIFFRGBAImageOK        rgbaimage.3t     is image readable by TIFFRGBAImageGet
       TIFFScanlineSize       size.3t          return size of a scanline
       TIFFSetDirectory       setdir.3t        set the current directory
       TIFFSetSubDirectory    setdir.3t        set the current directory
       TIFFSetErrorHandler    error.3t         set error handler function
       TIFFSetField           setfield.3t      set a tag's value in the current directory
       TIFFSetWarningHandler  error.3t         set warning handler function
       TIFFStripSize          size.3t          return size of a strip
       TIFFSwabShort          swab.3t          swap bytes of short
       TIFFSwabLong           swab.3t          swap bytes of long
       TIFFSwabArrayOfShort   swab.3t          swap bytes of an array of shorts
       TIFFSwabArrayOfLong    swab.3t          swap bytes of an array of longs
       TIFFTileRowSize        size.3t          return size of a row in a tile
       TIFFTileSize           size.3t          return size of a tile
       TIFFVGetField          getfield.3t      return tag value in current directory
       TIFFVGetFieldDefaulted getfield.3t      return tag value in current directory
       TIFFVSetField          setfield.3t      set a tag's value in the current directory
       TIFFWarning            warning.3t       library warning handler
       TIFFWriteDirectory     writedir.3t      write the current directory
       TIFFWriteEncodedStrip  wrestrip.3t      compress and write a strip of data
       TIFFWriteEncodedTile   wretile.3t       compress and write a tile of data
       TIFFWriteRawStrip      wrrstrip.3t      write a raw strip of data
       TIFFWriteRawTile       wrrtile.3t       write a raw tile of data
       TIFFWriteScanline      writeline.3t     write a scanline of data
       TIFFWriteTile          wrrtile.3t       compress and write a tile of data


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  consid­
       ered  codec-specific  tags and the library does not recog­
       nize them except when the Compression tag has been  previ­
       ously set to the relevant compression scheme.
       Tag Name                Value  R/W  Library Use/Notes
       Artist                  315    R/W
       BadFaxLines             326    R/W

       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
       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/Wused 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

       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 calulcations
       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 pseud-
       tags and are used to control various codec-specific  func­
       tions  within the library.  The table below summarizes the
       defined pseudo-tags.
       Tag Name                Codec  R/W  Library Use/Notes
       TIFFTAG_FAXMODE         G3     R/W  general codec operation
       TIFFTAG_FAXFILLFUNC     G3/G4  R/W  bitmap fill function
       TIFFTAG_JPEGQUALITY     JPEG   R/W  compression quality control
       TIFFTAG_JPEGCOLORMODE   JPEG   R/W  control colorspace conversions
       TIFFTAG_JPEGTABLESMODE  JPEG   R/W  control contents of JPEGTables tag
       TIFFTAG_ZIPQUALITY      Deflate     R/Wcompression quality level
       TIFFTAG_PIXARLOGDATAFMT PixarLog    R/Wuser data format
       TIFFTAG_PIXARLOGQUALITY PixarLog    R/Wcompression quality level
       TIFFTAG_SGILOGDATAFMT   SGILog R/W  user data format

       TIFFTAG_FAXMODE
              Control the operation of the Group 3 codec.  Possi­
              ble  values  (independent bits that can be combined
              by  or'ing  them  together)  are:   FAXMODE_CLASSIC
              (enable  old-style format in which the RTC is writ­
              ten at the end of the  last  strip),  FAXMODE_NORTC
              (opposite  of  FAXMODE_CLASSIC;  also  called  FAX­
              MODE_CLASSF), FAXMODE_NOEOL (do not write EOL codes
              at   the   start   of   each  row  of  data),  FAX­
              MODE_BYTEALIGN (align each encoded row to an  8-bit
              boundary),  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.

              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  col­
              ormap  mode)  or  for  other purposes.  The default
              value is a  pointer  to  a  builtin  function  that
              images packed bilevel data.

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

       TIFFTAG_PHOTOSHOP
              Tag  contains  Photoshop captioning information and
              metadata. Photoshop uses  in  parallel  and  redun­
              dantly alongside IPTCNEWSPHOTO information.

       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.

       TIFFTAG_JPEGCOLORMODE
              Control  whether  or not conversion is done between
              RGB and YCbCr colorspaces.   Possible  values  are:
              JPEGCOLORMODE_RAW  (do not convert), and JPEGCOLOR­
              MODE_RGB (convert to/from RGB) The default value is
              JPEGCOLORMODE_RAW.

       TIFFTAG_JPEGTABLESMODE
              Control  the  information written in the JPEGTables
              tag.  Possible values (independent bits that can be
              combined  by  or'ing  them  together)  are: JPEGTA­
              BLESMODE_QUANT (include quantization  tables),  and
              JPEGTABLESMODE_HUFF   (include   Huffman   encoding
              tables).    The   default    value    is    JPEGTA­
              BLESMODE_QUANT|JPEGTABLESMODE_HUFF.

       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.

       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:  PIXARLOG­
              DATAFMT_8BIT  for  8-bit unsigned pixels, PIXARLOG­
              DATAFMT_8BITABGR for  8-bit  unsigned  ABGR-ordered
              pixels,  PIXARLOGDATAFMT_11BITLOG  for  11-bit log-

              12-bit PICIO-compatible data, PIXARLOGDATAFMT_16BIT
              for   16-bit   signed   samples,   and    PIXARLOG­
              DATAFMT_FLOAT  for  32-bit IEEE floating point sam­
              ples.

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

       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:    SGILOG­
              DATAFMT_FLTXYZ  for  converting  between LogLuv and
              32-bit IEEE floating  valued  XYZ  pixels,  SGILOG­
              DATAFMT_16BITLUV  for  16-bit  encoded  Luv pixels,
              SGILOGDATAFMT_32BITRAW  and  SGILOGDATAFMT_24BITRAW
              for  no  conversion  of data, SGILOGDATAFMT_8BITRGB
              for returning  8-bit  RGB  data  (valid  only  when
              decoding  LogLuv-encoded  data), SGILOGDATAFMT_FLTY
              for converting between LogL and 32-bit IEEE  float­
              ing   valued  Y  pixels,  SGILOGDATAFMT_16BITL  for
              16-bit encoded L pixels, and  SGILOGDATAFMT_8BITGRY
              for returning 8-bit greyscale data (valid only when
              decoding LogL-encoded data).


DIAGNOSTICS

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


SEE ALSO

       fax2tiff(1),    gif2tiff(1),    pal2rgb(1),   ppm2tiff(1),
       rgb2ycbcr(1),   ras2tiff(1),   sgi2tiff(1),    tiff2bw(1),
       tiffdither(1),    tiffdump(1),    tiffcp(1),   tiffcmp(1),
       tiffgt(1),   tiffinfo(1),   tiffmedian(1),   tiffsplit(1),
       tiffsv(1),

       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.  The library discards unknown  tags.   The  library

       tents.


Man(1) output converted with man2html