C Library Functions libtiff(3)
NAME
libtiff - introduction to libtiff, a library for reading and
writing TIF files
SYNOPSIS
#include
cc [ flag ...] -I/usr/sfw/include file [ library ... ]
-L/usr/sfw/lib -R/usr/sfw/lib -ltiff
DESCRIPTION
libtiff is a library for reading and writing data files
encoded with the Tag Image File format, Revision 4.0 or
later. The TIF file format is suitable for archiving mul-
ticolor and monochromatic image data.
EXTENDED DESCRIPTION
The libtiff library supports several compression algorithms,
as indicated by the Compression field, including:
]o No compression (1)
]o CIT 1D Huffman compression (2)
]o CIT Group 3 Facsimile compression (3)
]o CIT Group 4 Facsimile compression (4)
]o Lempel-Ziv & Welch compression (5)
]o Baseline JPEG compression (7)
]o Word-aligned 1D Huffman compression (32771)
]o PackBits compression (32773)
In addition, several nonstandard compression algorithms are
supported:
]o 4-bit compression algorithm used by the ThunderScan
program (32809) (decompression only)
]o NeXT's 2-bit compression algorithm (32766) (decompres-
sion only)
]o Experimental LZ-style algorithm known as Deflate
(32946)
]o Experimental CIE LogLuv compression scheme designed for
images with high dynamic range (32845 for LogL and
SunOS 5.11 Last change: 06 Apr 2004 1
C Library Functions libtiff(3)
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.
The library does not support files in which the BitsPerSam-
ple, Compression, MinSampleValue, or MaxSampleValue fields
are defined differently on a per-sample basis. In Revision
6.0, the Compression tag is not defined on a per-sample
basis, so this is immaterial.
Data Types
The libtiff 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 inter-
nal data structures and parsing of the TIF format. The fol-
lowing typedefs are exposed to users either through function
definitions or through parameters passed through the varargs
interfaces.
]o typedef unsigned short uint16; - 16-bit unsigned
integer
]o typedef unsigned uint32; - 32-bit unsigned
integer
]o typedef unsigned int ttagt; - directory tag
]o typedef uint16 tdirt; - directory index
]o typedef uint16 tsamplet; - sample number
]o typedef uint32 tstript; - strip number
]o typedef uint32 ttilet; - tile number
]o typedef int32 tsizet; - i/o size in bytes
]o typedef void* tdatat; - image data ref
]o typedef void* thandlet; - client data handle
]o typedef int32 tofft; - file offset
tstript, ttilet, and tsizet are limited to 32-bit quanti-
ties because they are stored in 32-bit fields in the TIF
SunOS 5.11 Last change: 06 Apr 2004 2
C Library Functions libtiff(3)
image. Similarly, tsamplet is limited by the 16-bit field
used to store the SamplesPerPixel tag. tdirt constrains the
maximum number of IFDs that may appear in an image and may
be an arbitrary size without penalty.
ttagt must be 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 pro-
moted type.
tofft is defined as int32 because TIF file offsets are
unsigned 32-bit quantities. A signed value is used because
some interfaces return -1 on error.
User-specified data references are passed as opaque handles
and only cast at the lowest layers where their type is
presumed.
Library Routines
The following routines are part of the libtiff library.
Consult specific reference pages for details on their opera-
tion. The reference page names listed below are for systems
where the full function names cannot be encoded in the file
system. On most systems, the command man function-name will
work.
TIFfree Release allocated
memory. See
TIFmemory(3tiff).
TIFmalloc Dynamically allocate
memory. See
TIFmemory(3tiff).
TIFmemcmp Compare allocated
memory. See
TIFmemory(3tiff).
TIFmemcpy Copy allocated
memory to another
memory location. See
TIFmemory(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 3
C Library Functions libtiff(3)
TIFmemset Set allocated memory
to known value. See
TIFmemory(3tiff).
TIFrealloc Dynamically reallo-
cate memory. See
TIFmemory(3tiff).
TIFbuffer Specify i/o buffer
for reading or writ-
ing. See
TIFbuffer(3tiff).
TIFCheckTile Every x,y,z,sample
is within image. See
TIFtile(3tiff).
TIFClientOpen Open a file for
reading or writing.
See TIFOpen(3tiff).
TIFClose Close an open file.
See
TIFClose(3tiff).
TIFcodec Work with codecs.
See
TIFcodec(3tiff).
TIFComputeStrip Return strip con-
taining
x,y,z,sample. See
TIFstrip(3tiff).
TIFComputeTile Return tile contain-
ing y,sample. See
SunOS 5.11 Last change: 06 Apr 2004 4
C Library Functions libtiff(3)
TIFtile(3tiff).
TIFCurrentDirectory Return index of
current directory.
See
TIFquery(3tiff).
TIFCurrentRow Return index of
current scanline.
See
TIFquery(3tiff).
TIFCurrentStrip Return index of
current strip. See
TIFquery(3tiff).
TIFCurrentTile Return index of
current tile. See
TIFquery(3tiff).
TIFDefaultStripSize Return size of a
strip. See
TIFstrip(3tiff).
TIFDefaultTileSize Return size of a
tile. See
TIFtile(3tiff).
TIFError Library error
handler. See
TIFError(3tiff).
TIFdOpen Open a file for
reading or writing.
See TIFOpen(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 5
C Library Functions libtiff(3)
TIFileName Return name of open
file. See
TIFquery(3tiff).
TIFileno Return open file
descriptor. See
TIFquery(3tiff).
TIFindCODEC Find a codec. See
TIFcodec(3tiff).
TIFlush Flush all pending
writes. See
TIFlush(3tiff).
TIFlushData Flush pending data
writes. See
TIFlush(3tiff).
TIFGetBitRevTable Return bit reversal
table. See
TIFswab(3tiff).
TIFGetField Return tag value in
current directory.
See
TIFGetField(3tiff).
TIFGetFieldDefaulted Return tag value in
current directory.
See
TIFGetField(3tiff).
TIFGetMode Return open file
mode. See
TIFquery(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 6
C Library Functions libtiff(3)
TIFGetVersion Return library ver-
sion string. See
TIFquery(3tiff).
TIFIsByteSwapped Return true if image
data is byte-
swapped. See
TIFquery(3tiff).
TIFIsMSB2LSB Return true if image
data is returned
with bit 0 as the
most significant
bit. See
TIFquery(3tiff).
TIFIsTiled Return true if image
data is tiled. See
TIFquery(3tiff).
TIFIsUpSampled Return true if image
data is up-sampled.
See
TIFquery(3tiff).
TIFLastDirectory Return a non-zero
value if the current
directory is the
last directory in
the file. See
TIFquery(3tiff).
TIFmemory Manage memory. See
TIFmemory(3tiff).
TIFNumberOfStrips Return number of
strips in an image.
See
SunOS 5.11 Last change: 06 Apr 2004 7
C Library Functions libtiff(3)
TIFstrip(3tiff).
TIFNumberOfTiles Return number of
tiles in an image.
See TIFtile(3tiff).
TIFOpen Open a file for
reading or writing.
See TIFOpen(3tiff).
TIFPrintDirectory Print description of
the current direc-
tory. See
TIFPrintDirectory(3tiff).
TIFquery Return information
about image. See
TIFquery(3tiff).
TIFRasterScanlineSize Return size of a
raster scanline. See
TIFsize(3tiff).
TIFReadBufferSetup Specify i/o buffer
for reading. See
TIFbuffer(3tiff).
TIFReadDirectory Read the next direc-
tory. See
TIFReadDirectory(3tiff).
TIFReadEncodedStrip Read and decode a
strip of data. See
TIFReadEncodedStrip(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 8
C Library Functions libtiff(3)
TIFReadEncodedTile Read and decode a
tile of data. See
TIFReadEncodedTile(3tiff).
TIFReadRawStrip Read a raw strip of
data. See
TIFReadRawStrip(3tiff).
TIFReadRawTile Read a raw tile of
data. See
TIFReadRawTile(3tiff).
TIFReadRGBAImage Read an image into a
fixed format raster.
See
TIFReadRGBAImage(3tiff).
TIFReadRGBAStrip Read an image strip
into a fixed format
raster. See
TIFReadRGBAStrip(3tiff).
TIFReadRGBATile Read an image tile
into a fixed format
raster. See
TIFReadRGBATile(3tiff).
TIFReadScanline Read and decode a
row of data. See
TIFReadScanline(3tiff).
TIFReadTile Read and decode a
tile of data. See
TIFReadTile(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 9
C Library Functions libtiff(3)
TIFRegisterCODEC Register a codec.
See
TIFcodec(3tiff).
TIFReverseBits Reverse bits in an
array of bytes. See
TIFswab(3tiff).
TIFRGBAImage Read and decode an
image into a raster.
See
TIFRGBAImage(3tiff).
TIFRGBAImageBegin Set up decoder state
for TIF-
FRGBAImageGet. See
TIFRGBAImage(3tiff).
TIFRGBAImageEnd Release TIFRGBAIm-
age decoder state.
See
TIFRGBAImage(3tiff).
TIFRGBAImageGet Read and decode an
image. See
TIFRGBAImage(3tiff).
TIFRGBAImageOK Determine whether
image is readable by
TIFRGBAImageGet.
See
TIFRGBAImage(3tiff).
TIFScanlineSize Return size of a
scanline. See
TIFsize(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 10
C Library Functions libtiff(3)
TIFSetDirectory Set the current
directory. See
TIFSetDirectory(3tiff).
TIFSetSubDirectory Set the current
directory. See
TIFSetDirectory(3tiff).
TIFSetErrorHandler Set error handler
function. See
TIFError(3tiff).
TIFSetField Set tag value in the
current directory.
See
TIFSetField(3tiff).
TIFSetWarningHandler Set warning handler
function. See
TIFWarning(3tiff).
TIFsize Return the size. See
TIFsize(3tiff).
TIFstrip Work with strips.
See
TIFstrip(3tiff).
TIFStripSize Return size of a
strip. See
TIFstrip(3tiff).
TIFswab Swap bytes. See
TIFswab(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 11
C Library Functions libtiff(3)
TIFSwabShort Swap bytes of short.
See TIFswab(3tiff).
TIFSwabLong Swap bytes of long.
See TIFswab(3tiff).
TIFSwabArrayOfShort Swap bytes of an
array of shorts. See
TIFswab(3tiff).
TIFSwabArrayOfLong Swap bytes of an
array of longs. See
TIFswab(3tiff).
TIFtile Return tile informa-
tion. See
TIFtile(3tiff).
TIFTileRowSize Return size of a row
in a tile. See
TIFtile(3tiff).
TIFTileSize Return size of a
tile. See
TIFtile(3tiff).
TIFUnregisterCODEC Unregister a codec.
See
TIFcodec(3tiff).
TIFVGetField Return tag value in
current directory.
See
TIFGetField(3tiff).
SunOS 5.11 Last change: 06 Apr 2004 12
C Library Functions libtiff(3)
TIFVGetFieldDefaulted Return tag value in
current directory.
See
TIFGetField(3tiff).
TIFVSetField Set tag value in
current directory.
See
TIFSetField(3tiff).
TIFVStripSize Return size of a
strip. See
TIFstrip(3tiff).
TIFVTileSize Return size of a
tile. See
TIFtile(3tiff).
TIFWarning Library warning
handler. See
TIFWarning(3tiff).
TIFWriteBufferSetup Specify i/o buffer
for writing. See
TIFbuffer(3tiff).
TIFWriteDirectory Write the current
directory. See
TIFWriteDirectory(3tiff).
TIFWriteEncodedStrip Compress and write a
strip of data. See
TIFWriteEncodedStrip(3tiff).
TIFWriteEncodedTile Compress and write a
tile of data. See
SunOS 5.11 Last change: 06 Apr 2004 13
C Library Functions libtiff(3)
TIFWriteEncodedTile(3tiff).
TIFWriteRawStrip Write a raw strip of
data. See
TIFWriteRawStrip(3tiff).
TIFWriteRawTile Write a raw tile of
data. See
TIFWriteRawTile(3tiff).
TIFWriteScanline Write a scanline of
data. See
TIFWriteScanline(3tiff).
TIFWriteTile Compress and write a
tile of data. See
TIFWriteTile(3tiff).
Tag Usage
The table below lists the TIF tags that are recognized and
supported by the libtiff library. If no use is indicated in
the table, then the library reads and writes the tag, but
does not use the tag internally. Note that some tags are
meaningful only when a particular compression scheme is
used. For example, Group3Options is only useful if Compres-
sion is set to CIT 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 pre-
viously set to the relevant compression scheme.
SunOS 5.11 Last change: 06 Apr 2004 14
C Library Functions libtiff(3)
SunOS 5.11 Last change: 06 Apr 2004 15
C Library Functions libtiff(3)
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.
SunOS 5.11 Last change: 06 Apr 2004 16
C Library Functions libtiff(3)
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.
SunOS 5.11 Last change: 06 Apr 2004 17
C Library Functions libtiff(3)
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
SunOS 5.11 Last change: 06 Apr 2004 18
C Library Functions libtiff(3)
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 TIFRGBAImage 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 TIF tags, the libtiff library
supports a collection of tags whose values lie in a range
outside the valid range of TIF tags. These tags are termed
pseudo-tags and are used to control various codec-specific
functions within the library. The table below summarizes the
defined pseudo-tags.
SunOS 5.11 Last change: 06 Apr 2004 19
C Library Functions libtiff(3)
TAG NAME CODEC R/W LIBRARY USE / NOTES
TIFTAGFAXMODE G3 R/W General codec operation.
TIFTAGFAXFILFUNC G3/G4 R/W Bitmap fill function.
TIFTAGJPEGQUALITY JPEG R/W Compression quality control.
TIFTAGJPEGCOLORMODE JPEG R/W Control colorspace conversions.
TIFTAGJPEGTABLESMODE JPEG R/W Control contents of JPEGTables tag.
TIFTAGZIPQUALITY Deflate R/W Compression quality level.
TIFTAGPIXARLOGDATAFMT PixarLog R/W User data format.
TIFTAGPIXARLOGQUALITY PixarLog R/W Compression quality level.
TIFTAGSGILOGDATAFMT SGILog R/W User data format.
TIFTAGFAXMODE
Controls the operation of the Group 3 codec. Possible values
(independent bits that can be combined by or'ing them
together) are:
FAXMODEBYTEALIGN Align each encoded row to an 8-bit
boundary.
FAXMODECLASIC Enable old-style format in which the
RTC is written at the end of the
last strip.
FAXMODENOEOL Do not write EOL codes at the start
of each row of data.
FAXMODENORTC, also callOppFoAsXiMtOeDEofCLFASXSMFODECLASIC.
FAXMODEWORDALIGN Align each encoded row to a 16-bit
boundary.
SunOS 5.11 Last change: 06 Apr 2004 20
C Library Functions libtiff(3)
The default value depends on the compression scheme. This
pseudo-tag is used by the various G3 and G4 codecs to share
code.
TIFTAGFAXFILFUNC
Controls 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 (for
example, for display in colormap mode) or for other pur-
poses. The default value is a pointer to a builtin function
that images packed bilevel data.
TIFTAGIPTCNEWSPHOTO
Contains image metadata per the IPTC newsphoto specifica-
tion: Headline, captioning, credit, and so on. Used by most
wire services.
TIFTAGPHOTOSHOP
Contains Photoshop captioning information and metadata. Pho-
toshop uses in parallel and redundantly alongside IPTCNEWS-
PHOTO information.
TIFTAGJPEGQUALITY
Controls 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.
TIFTAGJPEGCOLORMODE
Controls whether or not conversion is done between RGB and
YCbCr colorspaces. Possible values are: JPEGCOLORMODERAW
(do not convert), and JPEGCOLORMODERGB (convert to/from
RGB). The default value is JPEGCOLORMODERAW.
TIFTAGJPEGTABLESMODE
Controls the information written in the JPEGTables tag. Pos-
sible values (independent bits that can be combined by
or'ing them together) are: JPEGTABLESMODEQUANT (include
quantization tables), and JPEGTABLESMODEHUF (include Huff-
man encoding tables).
TIFTAGZIPQUALITY
Controls 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 com-
putation. The default quality level is 6 which yields a good
time-space tradeoff.
TIFTAGPIXARLOGDATAFMT
Controls the format of user data passed to the PixarLog
codec when encoding and passed from the PixarLog codec when
decoding. Possible values are:
SunOS 5.11 Last change: 06 Apr 2004 21
C Library Functions libtiff(3)
]o PIXARLOGDATAFMT8BIT for 8-bit unsigned pixels
]o PIXARLOGDATAFMT8BITABGR for 8-bit unsigned ABGR-
orderedpixels
]o PIXARLOGDATAFMT11BITLOG for 11-bit log-encoded raw
data
]o PIXARLOGDATAFMT12BITPICIO for 12-bit PICIO-compatible
data
]o PIXARLOGDATAFMT16BIT for 16-bit signed samples
]o PIXARLOGDATAFMTFLOAT for 32-bit IE floating point
samples
TIFTAGPIXARLOGQUALITY
Controls the compression technique used by the PixarLog
codec. This value is treated identically to
TIFTAGZIPQUALITY.
TIFTAGSGILOGDATAFMT
Controls the format of client data passed to the SGILog
codec when encoding and passed from the SGILog codec when
decoding. Possible values are:
]o SGILOGDATAFMTFLTXYZ for converting between LogLuv and
32-bit IE floating valued XYZ pixels
]o SGILOGDATAFMT16BITLUV for 16-bit encoded Luv pixels
]o SGILOGDATAFMT32BITRAW and SGILOGDATAFMT24BITRAW for
no conversion of data
]o SGILOGDATAFMT8BITRGB for returning 8-bit RGB data
(valid only when decoding LogLuv-encoded data)
]o SGILOGDATAFMTFLTY for converting between LogL and 32-
bit IE floating valued Y pixels
]o SGILOGDATAFMT16BITL for 16-bit encoded L pixels
]o SGILOGDATAFMT8BITGRY for returning 8-bit greyscale
data (valid only when decoding LogL-encoded data)
Diagnostics
All error messages are directed through the TIFError rou-
tine. By default, messages are directed to stderr in the
form: module: message\n. Warning messages are likewise
directed through the TIFWarning routine.
SunOS 5.11 Last change: 06 Apr 2004 22
C Library Functions libtiff(3)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWTiff
Interface stability Uncommitted
SEE ALSO
fax2tiff(1), gif2tiff(1), pal2rgb(1), ppm2tiff(1),
ras2tiff(1), rgb2ycbcr(1), sgi2tiff(1), tiff2bw(1),
tiffcmp(1), tiffcp(1), tiffdither(1), tiffdump(1),
tiffgt(1), tiffinfo(1), tiffmedian(1), tiffsplit(1),
tiffsv(1), attributes(5)
Tag Image File Format Specification Revision 6.0, an Aldus
Technical Memorandum.
The Spirit of TIF Class F an appendix to the TIF 5.0
specification prepared by Cygnet Technologies.
NOTES
The libtiff library does not support multisample 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.
This man page was originally written by Sam Leffler. Updated
by Breda McColgan, Sun Microsystems Inc., 2004.
SunOS 5.11 Last change: 06 Apr 2004 23
|
