INTRO(3T)                                               INTRO(3T)

NAME
       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),  and  an
       experimental  LZ-style algorithm known as Deflate (32946).
       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 Signif-
       icant  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 MaxSam-
       pleValue 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).

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 uint32 ttile_t;             tile 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
       TIFFPrintDirectory     print.3t         print description of the current directory
       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
       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
       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
       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
       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 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_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.

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

       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.

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
       should  do  more  validity  checking of a directory's con-
       tents.

                         October 15, 1995                       1