Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

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

       #include	<tiffio.h>

       cc file.c -ltiff

       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), and
       PackBits	compression (32773).  In addition,  several  nonstandard  com-
       pression	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).

       The  library  makes extensive use of C typedefs to promote portability.
       Two sets	of typedefs are	used, one for communication  with  clients  of
       the  library  and  one  for internal 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  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 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. Fi-
       nally, note that	user-specified data references are  passed  as	opaque
       handles	and  only  cast	 at the	lowest layers where their type is pre-

       The following routines are part of the library. Consult specific	manual
       pages for details on their operation; on	most systems doing ``man func-
       tion-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
       TIFFFieldDataType	get data type from field information
       TIFFFieldName		get field name from field information
       TIFFFieldPassCount	get whether to pass a value count to Get/SetField
       TIFFFieldReadCount	get number of values to	be read	from field
       TIFFFieldTag		get tag	value from field information
       TIFFFieldWithName	get field information given field name
       TIFFFieldWithTag		get field information given tag
       TIFFFieldWriteCount	get number of values to	be written to field
       TIFFFileName		return name of open file
       TIFFFileno		return open file descriptor
       TIFFFindCODEC		find standard codec for	the specific scheme
       TIFFFindField		get field information given tag	and data type
       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
       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
       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

       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-spe-
       cific tags and the library does not recognize them except when the Com-
       pression	 tag  has  been	 previously  set  to  the relevant compression

       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/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 calculations
       YCbCrSubsampling	       530    R/W
       YPosition	       286    R/W
       YResolution	       283    R/W  used	by Group 3 codec

       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	 vari-
       ous  codec-specific functions within the	library.  The table below sum-
       marizes 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

	      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	(oppo-
	      site  of	FAXMODE_CLASSIC;  also	called	FAXMODE_CLASSF),  FAX-
	      MODE_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 compres-
	      sion  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 de-
	      coded 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.

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

	      Tag contains Photoshop captioning	information and	metadata. Pho-
	      toshop uses in parallel and redundantly alongside	 IPTCNEWSPHOTO

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

	      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 de-
	      fault value is JPEGCOLORMODE_RAW.

	      Control the information written in the JPEGTables	tag.  Possible
	      values (independent bits that can	be combined by or'ing them to-
	      gether) are: JPEGTABLESMODE_QUANT	(include quantization tables),
	      and  JPEGTABLESMODE_HUFF (include	Huffman	encoding tables).  The

	      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.

	      Control  the format of user data passed in to the	PixarLog codec
	      when encoding and	passed out from	when decoding.	Possible  val-
	      ues  are:	PIXARLOGDATAFMT_8BIT for 8-bit unsigned	pixels,	PIXAR-
	      LOGDATAFMT_8BITABGR  for	8-bit  unsigned	 ABGR-ordered  pixels,
	      PIXARLOGDATAFMT_11BITLOG for 11-bit log-encoded raw data,	PIXAR-
	      LOGDATAFMT_12BITPICIO for	12-bit PICIO-compatible	 data,	PIXAR-
	      LOGDATAFMT_16BIT	 for  16-bit  signed  samples,	and  PIXARLOG-
	      DATAFMT_FLOAT for	32-bit IEEE floating point samples.

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

	      Control the format of client data	passed in to the SGILog	 codec
	      when  encoding and passed	out from when decoding.	 Possible val-
	      ues 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,  SGILOG-
	      DATAFMT_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,  SGILOG-
	      DATAFMT_16BITL   for   16-bit  encoded  L	 pixels,  and  SGILOG-
	      DATAFMT_8BITGRY for returning 8-bit greyscale data  (valid  only
	      when decoding LogL-encoded data).

       All  error messages are directed	through	the TIFFError routine.	By de-
       fault messages are directed to stderr in	the form:  module:  message\n.
       Warning messages	are likewise directed through the TIFFWarning routine.

       fax2tiff(1),   gif2tiff(1),   pal2rgb(1),   ppm2tiff(1),	 rgb2ycbcr(1),
       ras2tiff(1), raw2tiff(1), sgi2tiff(1), tiff2bw(1), tiffdither(1), tiff-
       dump(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

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

       Libtiff library home page:

       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.

libtiff			       November	2, 2005			  INTRO(3TIFF)


Want to link to this manual page? Use this URL:

home | help