DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

libtiff(3)




INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)


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  suitable
     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 compres-
     sion (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 pro-
     gram  (32809) (decompression only), NeXT's 2-bit compression
     algorithm (32766) (decompression only), an experimental  LZ-
     style  algorithm known as Deflate (32946), and an experimen-
     tal 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  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 commun-
     ication with clients of the library  and  one  for  internal
     data structures and parsing of the TIFF format.  The follow-
     ing 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

libtiff          Last change: November 24, 2004                 1

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

          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 SamplesPerPixel 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 res-
     tricts 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 presumed.


LIST OF ROUTINES

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

     Name                     Description
     TIFFCheckpointDirectory  writes the current state of the directory
     TIFFCheckTile            very x,y,z,sample is within image
     TIFFCIELabToRGBInit      initialize CIE L*a*b* 1976 to RGB conversion state
     TIFFCIELabToXYZ          perform CIE L*a*b* 1976 to CIE XYZ conversion
     TIFFClientOpen           open a file for reading or writing
     TIFFClose                close an open file
     TIFFComputeStrip         return strip containing y,sample
     TIFFComputeTile          return tile containing x,y,z,sample
     TIFFCurrentDirectory     return index of current directory
     TIFFCurrentRow           return index of current scanline
     TIFFCurrentStrip         return index of current strip
     TIFFCurrentTile          return index of current tile
     TIFFDataWidth            return the size of TIFF data types
     TIFFError                library error handler
     TIFFFdOpen               open a file for reading or writing
     TIFFFileName             return name of open file
     TIFFFileno               return open file descriptor
     TIFFFindCODEC            find standard codec for the specific scheme
     TIFFFlush                flush all pending writes
     TIFFFlushData            flush pending data writes
     TIFFGetBitRevTable       return bit reversal table
     TIFFGetField             return tag value in current directory
     TIFFGetFieldDefaulted    return tag value in current directory
     TIFFGetMode              return open file mode

libtiff          Last change: November 24, 2004                 2

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

     TIFFGetVersion           return library version string
     TIFFIsCODECConfigured    check, whether we have working codec
     TIFFIsMSB2LSB            return true if image data is being returned
                              with bit 0 as the most significant bit
     TIFFIsTiled              return true if image data is tiled
     TIFFIsByteSwapped        return true if image data is byte-swapped
     TIFFNumberOfStrips       return number of strips in an image
     TIFFNumberOfTiles        return number of tiles in an image
     TIFFOpen                 open a file for reading or writing
     TIFFPrintDirectory       print description of the current directory
     TIFFReadBufferSetup      specify i/o buffer for reading
     TIFFReadDirectory        read the next directory
     TIFFReadEncodedStrip     read and decode a strip of data
     TIFFReadEncodedTile      read and decode a tile of data
     TIFFReadRawStrip         read a raw strip of data
     TIFFReadRawTile          read a raw tile of data
     TIFFReadRGBAImage        read an image into a fixed format raster
     TIFFReadScanline         read and decode a row of data
     TIFFReadTile             read and decode a tile of data
     TIFFRegisterCODEC        override standard codec for the specific scheme
     TIFFReverseBits          reverse bits in an array of bytes
     TIFFRGBAImageBegin       setup decoder state for TIFFRGBAImageGet
     TIFFRGBAImageEnd         release TIFFRGBAImage decoder state
     TIFFRGBAImageGet         read and decode an image
     TIFFRGBAImageOK          is image readable by TIFFRGBAImageGet
     TIFFScanlineSize         return size of a scanline
     TIFFSetDirectory         set the current directory
     TIFFSetSubDirectory      set the current directory
     TIFFSetErrorHandler      set error handler function
     TIFFSetField             set a tag's value in the current directory
     TIFFSetWarningHandler    set warning handler function
     TIFFStripSize            returns size of a strip
     TIFFRawStripSize         returns the number of bytes in a raw strip
     TIFFSwabShort            swap bytes of short
     TIFFSwabLong             swap bytes of long
     TIFFSwabArrayOfShort     swap bytes of an array of shorts
     TIFFSwabArrayOfLong      swap bytes of an array of longs
     TIFFTileRowSize          return size of a row in a tile
     TIFFTileSize             return size of a tile
     TIFFUnRegisterCODEC      unregisters the codec
     TIFFVGetField            return tag value in current directory
     TIFFVGetFieldDefaulted   return tag value in current directory
     TIFFVSetField            set a tag's value in the current directory
     TIFFVStripSize           returns the number of bytes in a strip
     TIFFWarning              library warning handler
     TIFFWriteDirectory       write the current directory
     TIFFWriteEncodedStrip    compress and write a strip of data
     TIFFWriteEncodedTile     compress and write a tile of data
     TIFFWriteRawStrip        write a raw strip of data
     TIFFWriteRawTile         write a raw tile of data
     TIFFWriteScanline        write a scanline of data
     TIFFWriteTile            compress and write a tile of data

libtiff          Last change: November 24, 2004                 3

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

     TIFFXYZToRGB             perform CIE XYZ to RGB conversion
     TIFFYCbCrToRGBInit       initialize YCbCr to RGB conversion state
     TIFFYCbCrtoRGB           perform YCbCr to RGB conversion

     Auxiliary functions:
     _TIFFfree                free memory buffer
     _TIFFmalloc              dynamically allocate memory buffer
     _TIFFmemcmp              compare contents of the memory buffers
     _TIFFmemcpy              copy contents of the one buffer to another
     _TIFFmemset              fill memory buffer with a constant byte
     _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.

     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

libtiff          Last change: November 24, 2004                 4

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

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

libtiff          Last change: November 24, 2004                 5

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)


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 functions
     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.   Possible
          values (independent bits that can be combined by or'ing
          them together) are:  FAXMODE_CLASSIC (enable  old-style
          format  in  which  the RTC is written at the end of the
          last     strip),     FAXMODE_NORTC     (opposite     of
          FAXMODE_CLASSIC;     also    called    FAXMODE_CLASSF),
          FAXMODE_NOEOL (do not write EOL codes at the  start  of
          each   row  of  data),  FAXMODE_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 ras-
          ters  (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.

     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 meta-
          data. Photoshop uses in parallel and redundantly along-
          side IPTCNEWSPHOTO information.

libtiff          Last change: November 24, 2004                 6

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

     TIFFTAG_JPEGQUALITY
          Control the compression quality level used in the base-
          line  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
          JPEGCOLORMODE_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:   JPEGTABLESMODE_QUANT
          (include  quantization tables), and JPEGTABLESMODE_HUFF
          (include Huffman encoding tables).  The  default  value
          is JPEGTABLESMODE_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 Pixar-
          Log codec when encoding and passed out from when decod-
          ing.  Possible values  are:   PIXARLOGDATAFMT_8BIT  for
          8-bit  unsigned pixels, PIXARLOGDATAFMT_8BITABGR for 8-
          bit        unsigned        ABGR-ordered         pixels,
          PIXARLOGDATAFMT_11BITLOG  for  11-bit  log-encoded  raw
          data,  PIXARLOGDATAFMT_12BITPICIO  for  12-bit   PICIO-
          compatible   data,   PIXARLOGDATAFMT_16BIT  for  16-bit
          signed samples, and  PIXARLOGDATAFMT_FLOAT  for  32-bit
          IEEE floating point samples.

     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 SGI-
          Log codec when encoding and passed out from when decod-
          ing.  Possible values  are:   SGILOGDATAFMT_FLTXYZ  for
          converting  between  LogLuv  and  32-bit  IEEE floating
          valued XYZ pixels,  SGILOGDATAFMT_16BITLUV  for  16-bit
          encoded    Luv   pixels,   SGILOGDATAFMT_32BITRAW   and
          SGILOGDATAFMT_24BITRAW  for  no  conversion  of   data,

libtiff          Last change: November 24, 2004                 7

INTRO(3TIFF)      MISC. REFERENCE MANUAL PAGES       INTRO(3TIFF)

          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 floating 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),    raw2tiff(1),   sgi2tiff(1),
     tiff2bw(1),    tiffdither(1),    tiffdump(1),     tiffcp(1),
     tiffcmp(1),  tiffgt(1),  tiffinfo(1),  tiffmedian(1), tiffs-
     plit(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 contents.

libtiff          Last change: November 24, 2004                 8


Man(1) output converted with man2html