.\" $Id: libtiff.3tiff,v 1.4 2012-07-29 15:45:30 tgl Exp $

.\"

.\" Copyright (c) 1988-1997 Sam Leffler

.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.

.\"

.\" Permission to use, copy, modify, distribute, and sell this software and 

.\" its documentation for any purpose is hereby granted without fee, provided

.\" that (i) the above copyright notices and this permission notice appear in

.\" all copies of the software and related documentation, and (ii) the names of

.\" Sam Leffler and Silicon Graphics may not be used in any advertising or

.\" publicity relating to the software without the specific, prior written

.\" permission of Sam Leffler and Silicon Graphics.

.\" 

.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 

.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 

.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  

.\" 

.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR

.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,

.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,

.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 

.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

.\" OF THIS SOFTWARE.

.\"

.if n .po 0

.TH INTRO 3TIFF "November 2, 2005" "libtiff"

.SH NAME

libtiff \- introduction to

.IR libtiff ,

a library for reading and writing

.SM TIFF

files

.SH SYNOPSIS

.B "#include <tiffio.h>"</tiffio.h>

.sp

cc file.c

.B -ltiff

.SH DESCRIPTION

.I libtiff

is a library for reading and writing data files encoded with the

.I "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.

.PP

The library supports several compression algorithms, as indicated by the

.I Compression

field, including:

no compression (1),

.SM CCITT

1D Huffman compression (2),

.SM CCITT

Group 3 Facsimile compression (3),

.SM 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 compression algorithms are supported: the

4-bit compression algorithm used by the

.I 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 (\c

.SM MSB\c

) to Least Significant Bit (\c

.SM LSB\c

) or

.SM LSB

to

.SM MSB.

Finally, the library does not support files in which the

.IR BitsPerSample ,

.IR Compression ,

.IR MinSampleValue ,

or

.IR MaxSampleValue

fields are defined differently on a per-sample basis

(in Rev. 6.0 the

.I Compression

tag is not defined on a per-sample basis, so this is immaterial).

.SH "DATA TYPES"

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

.SM TIFF

format.

The following typedefs are exposed to users either through function

definitions or through parameters passed through the varargs interfaces.

.in +.5i

.sp 5p

.ta +\w'typedef unsigned <\fIthing\fP> uint32;    'u

.nf

typedef unsigned short uint16;	16-bit unsigned integer

typedef unsigned <\fIthing\fP> uint32;	32-bit unsigned integer

.sp 5p

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

.fi

.sp 5p

.in -.5i

Note that

.IR tstrip_t ,

.IR ttile_t ,

and

.I tsize_t

are constrained to be no more than 32-bit quantities by 32-bit fields they are

stored in in the

.SM TIFF

image.

Likewise

.I tsample_t

is limited by the 16-bit field used to store the

.I SamplesPerPixel

tag.

.I tdir_t

constrains the maximum number of

.SM IFDs

that may appear in an image and may be an arbitrary size (w/o penalty). 

.I ttag_t

must be either int, unsigned int, pointer, or double because the library uses

a varargs interface and

.SM "ANSI C"

restricts the type of the parameter before an ellipsis to be a promoted type.

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

.SH "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.

.sp

.nf

.ta \w'TIFFCheckpointDirectory'u+2n

\fIName\fP	\fIDescription\fP

.sp 5p

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

.sp

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

.fi

.SH "TAG USAGE"

The table below lists the

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

.I Group3Options

is only useful if 

.I Compression

is set to

.SM CCITT

Group 3 encoding.

Tags of this sort are considered

.I codec-specific

tags and the library does not recognize them except when the

.I Compression

tag has been previously set to the relevant compression scheme.

.sp

.nf

.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Value'u+2n +\w'R/W'u+2n

\fITag Name\fP	\fIValue\fP	\fIR/W\fP	\fILibrary Use/Notes\fP

.sp 5p

.nf

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 calulcations

YCbCrSubsampling	530	R/W

YPosition	286	R/W

YResolution	283	R/W	used by Group 3 codec

.SH "PSEUDO TAGS"

In addition to the normal

.SM TIFF

tags the library supports a collection of 

tags whose values lie in a range outside the valid range of 

.SM TIFF

tags.

These tags are termed

.I pseud-tags

and are used to control various codec-specific functions within the library.

The table below summarizes the defined pseudo-tags.

.sp

.nf

.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Codec'u+2n +\w'R/W'u+2n

\fITag Name\fP	\fICodec\fP	\fIR/W\fP	\fILibrary Use/Notes\fP

.sp 5p

.nf

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 \fIJPEGTables\fP tag

TIFFTAG_ZIPQUALITY	Deflate	R/W	compression quality level

TIFFTAG_PIXARLOGDATAFMT	PixarLog	R/W	user data format

TIFFTAG_PIXARLOGQUALITY	PixarLog	R/W	compression quality level

TIFFTAG_SGILOGDATAFMT	SGILog	R/W	user data format

.fi

.TP

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

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

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

.TP

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

.TP

.B TIFFTAG_IPTCNEWSPHOTO

Tag contaings image metadata per the IPTC newsphoto spec: Headline, 

captioning, credit, etc... Used by most wire services. 

.TP

.B TIFFTAG_PHOTOSHOP

Tag contains Photoshop captioning information and metadata. Photoshop 

uses in parallel and redundantly alongside IPTCNEWSPHOTO information. 

.TP

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

.TP

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

.TP

.B TIFFTAG_JPEGTABLESMODE

Control the information written in the 

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

.TP

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

.TP

.B TIFFTAG_PIXARLOGDATAFMT

Control the format of user data passed

.I in

to the PixarLog codec when encoding and passed

.I out

from when decoding.

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.

.TP

.B TIFFTAG_PIXARLOGQUALITY

Control the compression technique used by the PixarLog codec.

This value is treated identically to TIFFTAG_ZIPQUALITY; see the

above description.

.TP

.B TIFFTAG_SGILOGDATAFMT

Control the format of client data passed 

.I in

to the SGILog codec when encoding and passed

.I out

from when decoding.

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,

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

.SH DIAGNOSTICS

All error messages are directed through the

.IR TIFFError

routine.

By default messages are directed to

.B stderr

in the form:

.IR "module: message\en."

Warning messages are likewise directed through the

.IR TIFFWarning

routine.

.SH "SEE ALSO"

.BR fax2tiff (1),

.BR gif2tiff (1),

.BR pal2rgb (1),

.BR ppm2tiff (1),

.BR rgb2ycbcr (1),

.BR ras2tiff (1),

.BR raw2tiff (1),

.BR sgi2tiff (1),

.BR tiff2bw (1),

.BR tiffdither (1),

.BR tiffdump (1),

.BR tiffcp (1),

.BR tiffcmp (1),

.BR tiffgt (1),

.BR tiffinfo (1),

.BR tiffmedian (1),

.BR tiffsplit (1),

.BR tiffsv (1).

.PP

.BR "Tag Image File Format Specification \(em Revision 6.0" ,

an Aldus Technical Memorandum.

.PP

.BR "The Spirit of TIFF Class F" ,

an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies.

.PP

Libtiff library home page:

.BR http://www.remotesensing.org/libtiff/

.SH BUGS

The library does not support multi-sample images

where some samples have different bits/sample.

.PP

The library does not support random access to compressed data

that is organized with more than one row per tile or strip.