diff options
Diffstat (limited to 'tiff/man/libtiff.3tiff')
| -rw-r--r-- | tiff/man/libtiff.3tiff | 536 |
1 files changed, 536 insertions, 0 deletions
diff --git a/tiff/man/libtiff.3tiff b/tiff/man/libtiff.3tiff new file mode 100644 index 0000000..0d8885f --- /dev/null +++ b/tiff/man/libtiff.3tiff @@ -0,0 +1,536 @@ +.\" $Id: libtiff.3tiff,v 1.3 2005/11/02 11:07:19 dron 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 +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 +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. |