1INTRO(3TIFF) INTRO(3TIFF)
2
6 libtiff - introduction to libtiff, a library for reading and writing
7 TIFF files
8
10 #include <tiffio.h>
11 cc file.c -ltiff
13
15 libtiff is a library for reading and writing data files encoded with
16 the Tag Image File format, Revision 6.0 (or revision 5.0 or revision
17 4.0). This file format is suitable for archiving multi-color and
18 monochromatic image data.
19 The library supports several compression algorithms, as indicated by
21 the Compression field, including: no compression (1), CCITT 1D Huffman
22 compression (2), CCITT Group 3 Facsimile compression (3), CCITT Group 4
23 Facsimile compression (4), Lempel-Ziv & Welch compression (5), baseline
24 JPEG compression (7), word-aligned 1D Huffman compression (32771), and
25 PackBits compression (32773). In addition, several nonstandard com‐
26 pression algorithms are supported: the 4-bit compression algorithm used
27 by the ThunderScan program (32809) (decompression only), NeXT's 2-bit
28 compression algorithm (32766) (decompression only), an experimental LZ-
29 style algorithm known as Deflate (32946), and an experimental CIE
30 LogLuv compression scheme designed for images with high dynamic range
31 (32845 for LogL and 32845 for LogLuv). Directory information may be in
32 either little- or big-endian byte order-byte swapping is automatically
33 done by the library. Data bit ordering may be either Most Significant
34 Bit (MSB) to Least Significant Bit (LSB) or LSB to MSB. Finally, the
35 library does not support files in which the BitsPerSample, Compression,
36 MinSampleValue, or MaxSampleValue fields are defined differently on a
37 per-sample basis (in Rev. 6.0 the Compression tag is not defined on a
38 per-sample basis, so this is immaterial).
39
41 The library makes extensive use of C typedefs to promote portability.
42 Two sets of typedefs are used, one for communication with clients of
43 the library and one for internal data structures and parsing of the
44 TIFF format. The following typedefs are exposed to users either
45 through function definitions or through parameters passed through the
46 varargs interfaces.
47 typedef unsigned short uint16; 16-bit unsigned integer
48 typedef unsigned <thing> uint32; 32-bit unsigned integer
49 typedef unsigned int ttag_t; directory tag
50 typedef uint16 tdir_t; directory index
51 typedef uint16 tsample_t; sample number
52 typedef uint32 tstrip_t; strip number
53 typedef uint32 ttile_t; tile number
54 typedef int32 tsize_t; i/o size in bytes
55 typedef void* tdata_t; image data ref
56 typedef void* thandle_t; client data handle
57 typedef int32 toff_t; file offset
58 Note that tstrip_t, ttile_t, and tsize_t are constrained to be no more
59 than 32-bit quantities by 32-bit fields they are stored in in the TIFF
60 image. Likewise tsample_t is limited by the 16-bit field used to store
61 the SamplesPerPixel tag. tdir_t constrains the maximum number of IFDs
62 that may appear in an image and may be an arbitrary size (w/o penalty).
63 ttag_t must be either int, unsigned int, pointer, or double because the
64 library uses a varargs interface and ANSI C restricts the type of the
65 parameter before an ellipsis to be a promoted type. toff_t is defined
66 as int32 because TIFF file offsets are (unsigned) 32-bit quantities. A
67 signed value is used because some interfaces return -1 on error.
68 Finally, note that user-specified data references are passed as opaque
69 handles and only cast at the lowest layers where their type is pre‐
70 sumed.
71
73 The following routines are part of the library. Consult specific manual
74 pages for details on their operation; on most systems doing ``man func‐
75 tion-name'' will work.
76 Name Description
78 TIFFCheckpointDirectory writes the current state of the directory
79 TIFFCheckTile very x,y,z,sample is within image
80 TIFFCIELabToRGBInit initialize CIE L*a*b* 1976 to RGB conversion state
81 TIFFCIELabToXYZ perform CIE L*a*b* 1976 to CIE XYZ conversion
82 TIFFClientOpen open a file for reading or writing
83 TIFFClose close an open file
84 TIFFComputeStrip return strip containing y,sample
85 TIFFComputeTile return tile containing x,y,z,sample
86 TIFFCurrentDirectory return index of current directory
87 TIFFCurrentRow return index of current scanline
88 TIFFCurrentStrip return index of current strip
89 TIFFCurrentTile return index of current tile
90 TIFFDataWidth return the size of TIFF data types
91 TIFFError library error handler
92 TIFFFdOpen open a file for reading or writing
93 TIFFFileName return name of open file
94 TIFFFileno return open file descriptor
95 TIFFFindCODEC find standard codec for the specific scheme
96 TIFFFlush flush all pending writes
97 TIFFFlushData flush pending data writes
98 TIFFGetBitRevTable return bit reversal table
99 TIFFGetField return tag value in current directory
100 TIFFGetFieldDefaulted return tag value in current directory
101 TIFFGetMode return open file mode
102 TIFFGetVersion return library version string
103 TIFFIsCODECConfigured check, whether we have working codec
104 TIFFIsMSB2LSB return true if image data is being returned
105 with bit 0 as the most significant bit
106 TIFFIsTiled return true if image data is tiled
107 TIFFIsByteSwapped return true if image data is byte-swapped
108 TIFFNumberOfStrips return number of strips in an image
109 TIFFNumberOfTiles return number of tiles in an image
110 TIFFOpen open a file for reading or writing
111 TIFFPrintDirectory print description of the current directory
112 TIFFReadBufferSetup specify i/o buffer for reading
113 TIFFReadDirectory read the next directory
114 TIFFReadEncodedStrip read and decode a strip of data
115 TIFFReadEncodedTile read and decode a tile of data
116 TIFFReadRawStrip read a raw strip of data
117 TIFFReadRawTile read a raw tile of data
118 TIFFReadRGBAImage read an image into a fixed format raster
119 TIFFReadScanline read and decode a row of data
120 TIFFReadTile read and decode a tile of data
121 TIFFRegisterCODEC override standard codec for the specific scheme
122 TIFFReverseBits reverse bits in an array of bytes
123 TIFFRGBAImageBegin setup decoder state for TIFFRGBAImageGet
124 TIFFRGBAImageEnd release TIFFRGBAImage decoder state
125 TIFFRGBAImageGet read and decode an image
126 TIFFRGBAImageOK is image readable by TIFFRGBAImageGet
127 TIFFScanlineSize return size of a scanline
128 TIFFSetDirectory set the current directory
129 TIFFSetSubDirectory set the current directory
130 TIFFSetErrorHandler set error handler function
131 TIFFSetField set a tag's value in the current directory
132 TIFFSetWarningHandler set warning handler function
133 TIFFStripSize returns size of a strip
134 TIFFRawStripSize returns the number of bytes in a raw strip
135 TIFFSwabShort swap bytes of short
136 TIFFSwabLong swap bytes of long
137 TIFFSwabArrayOfShort swap bytes of an array of shorts
138 TIFFSwabArrayOfLong swap bytes of an array of longs
139 TIFFTileRowSize return size of a row in a tile
140 TIFFTileSize return size of a tile
141 TIFFUnRegisterCODEC unregisters the codec
142 TIFFVGetField return tag value in current directory
143 TIFFVGetFieldDefaulted return tag value in current directory
144 TIFFVSetField set a tag's value in the current directory
145 TIFFVStripSize returns the number of bytes in a strip
146 TIFFWarning library warning handler
147 TIFFWriteDirectory write the current directory
148 TIFFWriteEncodedStrip compress and write a strip of data
149 TIFFWriteEncodedTile compress and write a tile of data
150 TIFFWriteRawStrip write a raw strip of data
151 TIFFWriteRawTile write a raw tile of data
152 TIFFWriteScanline write a scanline of data
153 TIFFWriteTile compress and write a tile of data
154 TIFFXYZToRGB perform CIE XYZ to RGB conversion
155 TIFFYCbCrToRGBInit initialize YCbCr to RGB conversion state
156 TIFFYCbCrtoRGB perform YCbCr to RGB conversion
157 Auxiliary functions:
159 _TIFFfree free memory buffer
160 _TIFFmalloc dynamically allocate memory buffer
161 _TIFFmemcmp compare contents of the memory buffers
162 _TIFFmemcpy copy contents of the one buffer to another
163 _TIFFmemset fill memory buffer with a constant byte
164 _TIFFrealloc dynamically reallocate memory buffer
165
168 The table below lists the TIFF tags that are recognized and handled by
169 the library. If no use is indicated in the table, then the library
170 reads and writes the tag, but does not use it internally. Note that
171 some tags are meaningful only when a particular compression scheme is
172 being used; e.g. Group3Options is only useful if Compression is set to
173 CCITT Group 3 encoding. Tags of this sort are considered codec-spe‐
174 cific tags and the library does not recognize them except when the Com‐
175 pression tag has been previously set to the relevant compression
176 scheme.
177 Tag Name Value R/W Library Use/Notes
179 Artist 315 R/W
180 BadFaxLines 326 R/W
181 BitsPerSample 258 R/W lots
182 CellLength 265 parsed but ignored
183 CellWidth 264 parsed but ignored
184 CleanFaxData 327 R/W
185 ColorMap 320 R/W
186 ColorResponseUnit 300 parsed but ignored
187 Compression 259 R/W choosing codec
188 ConsecutiveBadFaxLines 328 R/W
189 Copyright 33432 R/W
190 DataType 32996 R obsoleted by SampleFormat tag
191 DateTime 306 R/W
192 DocumentName 269 R/W
193 DotRange 336 R/W
194 ExtraSamples 338 R/W lots
195 FaxRecvParams 34908 R/W
196 FaxSubAddress 34909 R/W
197 FaxRecvTime 34910 R/W
198 FillOrder 266 R/W control bit order
199 FreeByteCounts 289 parsed but ignored
200 FreeOffsets 288 parsed but ignored
201 GrayResponseCurve 291 parsed but ignored
202 GrayResponseUnit 290 parsed but ignored
203 Group3Options 292 R/W used by Group 3 codec
204 Group4Options 293 R/W
205 HostComputer 316 R/W
206 ImageDepth 32997 R/W tile/strip calculations
207 ImageDescription 270 R/W
208 ImageLength 257 R/W lots
209 ImageWidth 256 R/W lots
210 InkNames 333 R/W
211 InkSet 332 R/W
212 JPEGTables 347 R/W used by JPEG codec
213 Make 271 R/W
214 Matteing 32995 R obsoleted by ExtraSamples tag
215 MaxSampleValue 281 R/W
216 MinSampleValue 280 R/W
217 Model 272 R/W
218 NewSubFileType 254 R/W called SubFileType in spec
219 NumberOfInks 334 R/W
220 Orientation 274 R/W
221 PageName 285 R/W
222 PageNumber 297 R/W
223 PhotometricInterpretation 262 R/Wused by Group 3 and JPEG codecs
224 PlanarConfiguration 284 R/W data i/o
225 Predictor 317 R/W used by LZW and Deflate codecs
226 PrimaryChromacities 319 R/W
227 ReferenceBlackWhite 532 R/W
228 ResolutionUnit 296 R/W used by Group 3 codec
229 RowsPerStrip 278 R/W data i/o
230 SampleFormat 339 R/W
231 SamplesPerPixel 277 R/W lots
232 SMinSampleValue 340 R/W
233 SMaxSampleValue 341 R/W
234 Software 305 R/W
235 StoNits 37439 R/W
236 StripByteCounts 279 R/W data i/o
237 StripOffsets 273 R/W data i/o
238 SubFileType 255 R/W called OSubFileType in spec
239 TargetPrinter 337 R/W
240 Thresholding 263 R/W
241 TileByteCounts 324 R/W data i/o
242 TileDepth 32998 R/W tile/strip calculations
243 TileLength 323 R/W data i/o
244 TileOffsets 324 R/W data i/o
245 TileWidth 322 R/W data i/o
246 TransferFunction 301 R/W
247 WhitePoint 318 R/W
248 XPosition 286 R/W
249 XResolution 282 R/W
250 YCbCrCoefficients 529 R/W used by TIFFRGBAImage support
251 YCbCrPositioning 531 R/W tile/strip size calulcations
252 YCbCrSubsampling 530 R/W
253 YPosition 286 R/W
254 YResolution 283 R/W used by Group 3 codec
255
257 In addition to the normal TIFF tags the library supports a collection
258 of tags whose values lie in a range outside the valid range of TIFF
259 tags. These tags are termed pseud-tags and are used to control various
260 codec-specific functions within the library. The table below summa‐
261 rizes the defined pseudo-tags.
262 Tag Name Codec R/W Library Use/Notes
264 TIFFTAG_FAXMODE G3 R/W general codec operation
265 TIFFTAG_FAXFILLFUNC G3/G4 R/W bitmap fill function
266 TIFFTAG_JPEGQUALITY JPEG R/W compression quality control
267 TIFFTAG_JPEGCOLORMODE JPEG R/W control colorspace conversions
268 TIFFTAG_JPEGTABLESMODE JPEG R/W control contents of JPEGTables tag
269 TIFFTAG_ZIPQUALITY Deflate R/Wcompression quality level
270 TIFFTAG_PIXARLOGDATAFMT PixarLog R/Wuser data format
271 TIFFTAG_PIXARLOGQUALITY PixarLog R/Wcompression quality level
272 TIFFTAG_SGILOGDATAFMT SGILog R/W user data format
273 TIFFTAG_FAXMODE
275 Control the operation of the Group 3 codec. Possible values
276 (independent bits that can be combined by or'ing them together)
277 are: FAXMODE_CLASSIC (enable old-style format in which the RTC
278 is written at the end of the last strip), FAXMODE_NORTC (oppo‐
279 site of FAXMODE_CLASSIC; also called FAXMODE_CLASSF), FAX‐
280 MODE_NOEOL (do not write EOL codes at the start of each row of
281 data), FAXMODE_BYTEALIGN (align each encoded row to an 8-bit
282 boundary), FAXMODE_WORDALIGN (align each encoded row to an
283 16-bit boundary), The default value is dependent on the compres‐
284 sion scheme; this pseudo-tag is used by the various G3 and G4
285 codecs to share code.
286 TIFFTAG_FAXFILLFUNC
288 Control the function used to convert arrays of black and white
289 runs to packed bit arrays. This hook can be used to image
290 decoded scanlines in multi-bit depth rasters (e.g. for display
291 in colormap mode) or for other purposes. The default value is a
292 pointer to a builtin function that images packed bilevel data.
293 TIFFTAG_IPTCNEWSPHOTO
295 Tag contaings image metadata per the IPTC newsphoto spec: Head‐
296 line, captioning, credit, etc... Used by most wire services.
297 TIFFTAG_PHOTOSHOP
299 Tag contains Photoshop captioning information and metadata. Pho‐
300 toshop uses in parallel and redundantly alongside IPTCNEWSPHOTO
301 information.
302 TIFFTAG_JPEGQUALITY
304 Control the compression quality level used in the baseline algo‐
305 rithm. Note that quality levels are in the range 0-100 with a
306 default value of 75.
307 TIFFTAG_JPEGCOLORMODE
309 Control whether or not conversion is done between RGB and YCbCr
310 colorspaces. Possible values are: JPEGCOLORMODE_RAW (do not
311 convert), and JPEGCOLORMODE_RGB (convert to/from RGB) The
312 default value is JPEGCOLORMODE_RAW.
313 TIFFTAG_JPEGTABLESMODE
315 Control the information written in the JPEGTables tag. Possible
316 values (independent bits that can be combined by or'ing them
317 together) are: JPEGTABLESMODE_QUANT (include quantization
318 tables), and JPEGTABLESMODE_HUFF (include Huffman encoding
319 tables). The default value is JPEGTABLESMODE_QUANT|JPEGTA‐
320 BLESMODE_HUFF.
321 TIFFTAG_ZIPQUALITY
323 Control the compression technique used by the Deflate codec.
324 Quality levels are in the range 1-9 with larger numbers yielding
325 better compression at the cost of more computation. The default
326 quality level is 6 which yields a good time-space tradeoff.
327 TIFFTAG_PIXARLOGDATAFMT
329 Control the format of user data passed in to the PixarLog codec
330 when encoding and passed out from when decoding. Possible val‐
331 ues are: PIXARLOGDATAFMT_8BIT for 8-bit unsigned pixels, PIXAR‐
332 LOGDATAFMT_8BITABGR for 8-bit unsigned ABGR-ordered pixels,
333 PIXARLOGDATAFMT_11BITLOG for 11-bit log-encoded raw data, PIXAR‐
334 LOGDATAFMT_12BITPICIO for 12-bit PICIO-compatible data, PIXAR‐
335 LOGDATAFMT_16BIT for 16-bit signed samples, and PIXARLOG‐
336 DATAFMT_FLOAT for 32-bit IEEE floating point samples.
337 TIFFTAG_PIXARLOGQUALITY
339 Control the compression technique used by the PixarLog codec.
340 This value is treated identically to TIFFTAG_ZIPQUALITY; see the
341 above description.
342 TIFFTAG_SGILOGDATAFMT
344 Control the format of client data passed in to the SGILog codec
345 when encoding and passed out from when decoding. Possible val‐
346 ues are: SGILOGDATAFMT_FLTXYZ for converting between LogLuv and
347 32-bit IEEE floating valued XYZ pixels, SGILOGDATAFMT_16BITLUV
348 for 16-bit encoded Luv pixels, SGILOGDATAFMT_32BITRAW and
349 SGILOGDATAFMT_24BITRAW for no conversion of data, SGILOG‐
350 DATAFMT_8BITRGB for returning 8-bit RGB data (valid only when
351 decoding LogLuv-encoded data), SGILOGDATAFMT_FLTY for converting
352 between LogL and 32-bit IEEE floating valued Y pixels, SGILOG‐
353 DATAFMT_16BITL for 16-bit encoded L pixels, and SGILOG‐
354 DATAFMT_8BITGRY for returning 8-bit greyscale data (valid only
355 when decoding LogL-encoded data).
356
358 All error messages are directed through the TIFFError routine. By
359 default messages are directed to stderr in the form: module: message\n.
360 Warning messages are likewise directed through the TIFFWarning routine.
361
363 fax2tiff(1), gif2tiff(1), pal2rgb(1), ppm2tiff(1), rgb2ycbcr(1),
364 ras2tiff(1), raw2tiff(1), sgi2tiff(1), tiff2bw(1), tiffdither(1), tiff‐
365 dump(1), tiffcp(1), tiffcmp(1), tiffgt(1), tiffinfo(1), tiffmedian(1),
366 tiffsplit(1), tiffsv(1).
367 Tag Image File Format Specification — Revision 6.0, an Aldus Technical
369 Memorandum.
370 The Spirit of TIFF Class F, an appendix to the TIFF 5.0 specification
372 prepared by Cygnet Technologies.
373 Libtiff library home page: http://www.remotesensing.org/libtiff/
375
377 The library does not support multi-sample images where some samples
378 have different bits/sample.
379 The library does not support random access to compressed data that is
381 organized with more than one row per tile or strip.
382libtiff November 2, 2005 INTRO(3TIFF)