.\" $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>"

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