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_t; 16-bit unsigned integer
48 typedef unsigned <thing> uint32_t; 32-bit unsigned integer
49 typedef unsigned int ttag_t; directory tag
50 typedef uint16_t tdir_t; directory index
51 typedef uint16_t tsample_t; sample number
52 typedef uint32_t tstrip_t; strip number
53 typedef uint32_t ttile_t; tile number
54 typedef int32_t 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_t 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_t because TIFF file offsets are (unsigned) 32-bit quantities.
67 A signed value is used because some interfaces return -1 on error. Fi‐
68 nally, 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 TIFFFieldDataType get data type from field information
94 TIFFFieldName get field name from field information
95 TIFFFieldPassCount get whether to pass a value count to Get/SetField
96 TIFFFieldReadCount get number of values to be read from field
97 TIFFFieldTag get tag value from field information
98 TIFFFieldWithName get field information given field name
99 TIFFFieldWithTag get field information given tag
100 TIFFFieldWriteCount get number of values to be written to field
101 TIFFFileName return name of open file
102 TIFFFileno return open file descriptor
103 TIFFFindCODEC find standard codec for the specific scheme
104 TIFFFindField get field information given tag and data type
105 TIFFFlush flush all pending writes
106 TIFFFlushData flush pending data writes
107 TIFFGetBitRevTable return bit reversal table
108 TIFFGetField return tag value in current directory
109 TIFFGetFieldDefaulted return tag value in current directory
110 TIFFGetMode return open file mode
111 TIFFGetVersion return library version string
112 TIFFIsCODECConfigured check, whether we have working codec
113 TIFFIsMSB2LSB return true if image data is being returned
114 with bit 0 as the most significant bit
115 TIFFIsTiled return true if image data is tiled
116 TIFFIsByteSwapped return true if image data is byte-swapped
117 TIFFNumberOfStrips return number of strips in an image
118 TIFFNumberOfTiles return number of tiles in an image
119 TIFFOpen open a file for reading or writing
120 TIFFPrintDirectory print description of the current directory
121 TIFFReadBufferSetup specify i/o buffer for reading
122 TIFFReadDirectory read the next directory
123 TIFFReadEncodedStrip read and decode a strip of data
124 TIFFReadEncodedTile read and decode a tile of data
125 TIFFReadRawStrip read a raw strip of data
126 TIFFReadRawTile read a raw tile of data
127 TIFFReadRGBAImage read an image into a fixed format raster
128 TIFFReadScanline read and decode a row of data
129 TIFFReadTile read and decode a tile of data
130 TIFFRegisterCODEC override standard codec for the specific scheme
131 TIFFReverseBits reverse bits in an array of bytes
132 TIFFRGBAImageBegin setup decoder state for TIFFRGBAImageGet
133 TIFFRGBAImageEnd release TIFFRGBAImage decoder state
134 TIFFRGBAImageGet read and decode an image
135 TIFFRGBAImageOK is image readable by TIFFRGBAImageGet
136 TIFFScanlineSize return size of a scanline
137 TIFFSetDirectory set the current directory
138 TIFFSetSubDirectory set the current directory
139 TIFFSetErrorHandler set error handler function
140 TIFFSetField set a tag's value in the current directory
141 TIFFSetWarningHandler set warning handler function
142 TIFFStripSize returns size of a strip
143 TIFFRawStripSize returns the number of bytes in a raw strip
144 TIFFSwabShort swap bytes of short
145 TIFFSwabLong swap bytes of long
146 TIFFSwabArrayOfShort swap bytes of an array of shorts
147 TIFFSwabArrayOfLong swap bytes of an array of longs
148 TIFFTileRowSize return size of a row in a tile
149 TIFFTileSize return size of a tile
150 TIFFUnRegisterCODEC unregisters the codec
151 TIFFVGetField return tag value in current directory
152 TIFFVGetFieldDefaulted return tag value in current directory
153 TIFFVSetField set a tag's value in the current directory
154 TIFFVStripSize returns the number of bytes in a strip
155 TIFFWarning library warning handler
156 TIFFWriteDirectory write the current directory
157 TIFFWriteEncodedStrip compress and write a strip of data
158 TIFFWriteEncodedTile compress and write a tile of data
159 TIFFWriteRawStrip write a raw strip of data
160 TIFFWriteRawTile write a raw tile of data
161 TIFFWriteScanline write a scanline of data
162 TIFFWriteTile compress and write a tile of data
163 TIFFXYZToRGB perform CIE XYZ to RGB conversion
164 TIFFYCbCrToRGBInit initialize YCbCr to RGB conversion state
165 TIFFYCbCrtoRGB perform YCbCr to RGB conversion
166 Auxiliary functions:
168 _TIFFfree free memory buffer
169 _TIFFmalloc dynamically allocate memory buffer
170 _TIFFmemcmp compare contents of the memory buffers
171 _TIFFmemcpy copy contents of the one buffer to another
172 _TIFFmemset fill memory buffer with a constant byte
173 _TIFFrealloc dynamically reallocate memory buffer
174
177 The table below lists the TIFF tags that are recognized and handled by
178 the library. If no use is indicated in the table, then the library
179 reads and writes the tag, but does not use it internally. Note that
180 some tags are meaningful only when a particular compression scheme is
181 being used; e.g. Group3Options is only useful if Compression is set to
182 CCITT Group 3 encoding. Tags of this sort are considered codec-spe‐
183 cific tags and the library does not recognize them except when the Com‐
184 pression tag has been previously set to the relevant compression
185 scheme.
186 Tag Name Value R/W Library Use/Notes
188 Artist 315 R/W
189 BadFaxLines 326 R/W
190 BitsPerSample 258 R/W lots
191 CellLength 265 parsed but ignored
192 CellWidth 264 parsed but ignored
193 CleanFaxData 327 R/W
194 ColorMap 320 R/W
195 ColorResponseUnit 300 parsed but ignored
196 Compression 259 R/W choosing codec
197 ConsecutiveBadFaxLines 328 R/W
198 Copyright 33432 R/W
199 DataType 32996 R obsoleted by SampleFormat tag
200 DateTime 306 R/W
201 DocumentName 269 R/W
202 DotRange 336 R/W
203 ExtraSamples 338 R/W lots
204 FaxRecvParams 34908 R/W
205 FaxSubAddress 34909 R/W
206 FaxRecvTime 34910 R/W
207 FillOrder 266 R/W control bit order
208 FreeByteCounts 289 parsed but ignored
209 FreeOffsets 288 parsed but ignored
210 GrayResponseCurve 291 parsed but ignored
211 GrayResponseUnit 290 parsed but ignored
212 Group3Options 292 R/W used by Group 3 codec
213 Group4Options 293 R/W
214 HostComputer 316 R/W
215 ImageDepth 32997 R/W tile/strip calculations
216 ImageDescription 270 R/W
217 ImageLength 257 R/W lots
218 ImageWidth 256 R/W lots
219 InkNames 333 R/W
220 InkSet 332 R/W
221 JPEGTables 347 R/W used by JPEG codec
222 Make 271 R/W
223 Matteing 32995 R obsoleted by ExtraSamples tag
224 MaxSampleValue 281 R/W
225 MinSampleValue 280 R/W
226 Model 272 R/W
227 NewSubFileType 254 R/W called SubFileType in spec
228 NumberOfInks 334 R/W
229 Orientation 274 R/W
230 PageName 285 R/W
231 PageNumber 297 R/W
232 PhotometricInterpretation 262 R/Wused by Group 3 and JPEG codecs
233 PlanarConfiguration 284 R/W data i/o
234 Predictor 317 R/W used by LZW and Deflate codecs
235 PrimaryChromacities 319 R/W
236 ReferenceBlackWhite 532 R/W
237 ResolutionUnit 296 R/W used by Group 3 codec
238 RowsPerStrip 278 R/W data i/o
239 SampleFormat 339 R/W
240 SamplesPerPixel 277 R/W lots
241 SMinSampleValue 340 R/W
242 SMaxSampleValue 341 R/W
243 Software 305 R/W
244 StoNits 37439 R/W
245 StripByteCounts 279 R/W data i/o
246 StripOffsets 273 R/W data i/o
247 SubFileType 255 R/W called OSubFileType in spec
248 TargetPrinter 337 R/W
249 Thresholding 263 R/W
250 TileByteCounts 324 R/W data i/o
251 TileDepth 32998 R/W tile/strip calculations
252 TileLength 323 R/W data i/o
253 TileOffsets 324 R/W data i/o
254 TileWidth 322 R/W data i/o
255 TransferFunction 301 R/W
256 WhitePoint 318 R/W
257 XPosition 286 R/W
258 XResolution 282 R/W
259 YCbCrCoefficients 529 R/W used by TIFFRGBAImage support
260 YCbCrPositioning 531 R/W tile/strip size calculations
261 YCbCrSubsampling 530 R/W
262 YPosition 286 R/W
263 YResolution 283 R/W used by Group 3 codec
264
266 In addition to the normal TIFF tags the library supports a collection
267 of tags whose values lie in a range outside the valid range of TIFF
268 tags. These tags are termed pseudo-tags and are used to control vari‐
269 ous codec-specific functions within the library. The table below sum‐
270 marizes the defined pseudo-tags.
271 Tag Name Codec R/W Library Use/Notes
273 TIFFTAG_FAXMODE G3 R/W general codec operation
274 TIFFTAG_FAXFILLFUNC G3/G4 R/W bitmap fill function
275 TIFFTAG_JPEGQUALITY JPEG R/W compression quality control
276 TIFFTAG_JPEGCOLORMODE JPEG R/W control colorspace conversions
277 TIFFTAG_JPEGTABLESMODE JPEG R/W control contents of JPEGTables tag
278 TIFFTAG_ZIPQUALITY Deflate R/Wcompression quality level
279 TIFFTAG_PIXARLOGDATAFMT PixarLog R/Wuser data format
280 TIFFTAG_PIXARLOGQUALITY PixarLog R/Wcompression quality level
281 TIFFTAG_SGILOGDATAFMT SGILog R/W user data format
282 TIFFTAG_FAXMODE
284 Control the operation of the Group 3 codec. Possible values
285 (independent bits that can be combined by or'ing them together)
286 are: FAXMODE_CLASSIC (enable old-style format in which the RTC
287 is written at the end of the last strip), FAXMODE_NORTC (oppo‐
288 site of FAXMODE_CLASSIC; also called FAXMODE_CLASSF), FAX‐
289 MODE_NOEOL (do not write EOL codes at the start of each row of
290 data), FAXMODE_BYTEALIGN (align each encoded row to an 8-bit
291 boundary), FAXMODE_WORDALIGN (align each encoded row to an
292 16-bit boundary), The default value is dependent on the compres‐
293 sion scheme; this pseudo-tag is used by the various G3 and G4
294 codecs to share code.
295 TIFFTAG_FAXFILLFUNC
297 Control the function used to convert arrays of black and white
298 runs to packed bit arrays. This hook can be used to image de‐
299 coded scanlines in multi-bit depth rasters (e.g. for display in
300 colormap mode) or for other purposes. The default value is a
301 pointer to a builtin function that images packed bilevel data.
302 TIFFTAG_IPTCNEWSPHOTO
304 Tag contains image metadata per the IPTC newsphoto spec: Head‐
305 line, captioning, credit, etc... Used by most wire services.
306 TIFFTAG_PHOTOSHOP
308 Tag contains Photoshop captioning information and metadata. Pho‐
309 toshop uses in parallel and redundantly alongside IPTCNEWSPHOTO
310 information.
311 TIFFTAG_JPEGQUALITY
313 Control the compression quality level used in the baseline algo‐
314 rithm. Note that quality levels are in the range 0-100 with a
315 default value of 75.
316 TIFFTAG_JPEGCOLORMODE
318 Control whether or not conversion is done between RGB and YCbCr
319 colorspaces. Possible values are: JPEGCOLORMODE_RAW (do not
320 convert), and JPEGCOLORMODE_RGB (convert to/from RGB) The de‐
321 fault value is JPEGCOLORMODE_RAW.
322 TIFFTAG_JPEGTABLESMODE
324 Control the information written in the JPEGTables tag. Possible
325 values (independent bits that can be combined by or'ing them to‐
326 gether) are: JPEGTABLESMODE_QUANT (include quantization tables),
327 and JPEGTABLESMODE_HUFF (include Huffman encoding tables). The
328 default value is JPEGTABLESMODE_QUANT|JPEGTABLESMODE_HUFF.
329 TIFFTAG_ZIPQUALITY
331 Control the compression technique used by the Deflate codec.
332 Quality levels are in the range 1-9 with larger numbers yielding
333 better compression at the cost of more computation. The default
334 quality level is 6 which yields a good time-space tradeoff.
335 TIFFTAG_PIXARLOGDATAFMT
337 Control the format of user data passed in to the PixarLog codec
338 when encoding and passed out from when decoding. Possible val‐
339 ues are: PIXARLOGDATAFMT_8BIT for 8-bit unsigned pixels, PIXAR‐
340 LOGDATAFMT_8BITABGR for 8-bit unsigned ABGR-ordered pixels,
341 PIXARLOGDATAFMT_11BITLOG for 11-bit log-encoded raw data, PIXAR‐
342 LOGDATAFMT_12BITPICIO for 12-bit PICIO-compatible data, PIXAR‐
343 LOGDATAFMT_16BIT for 16-bit signed samples, and PIXARLOG‐
344 DATAFMT_FLOAT for 32-bit IEEE floating point samples.
345 TIFFTAG_PIXARLOGQUALITY
347 Control the compression technique used by the PixarLog codec.
348 This value is treated identically to TIFFTAG_ZIPQUALITY; see the
349 above description.
350 TIFFTAG_SGILOGDATAFMT
352 Control the format of client data passed in to the SGILog codec
353 when encoding and passed out from when decoding. Possible val‐
354 ues are: SGILOGDATAFMT_FLTXYZ for converting between LogLuv and
355 32-bit IEEE floating valued XYZ pixels, SGILOGDATAFMT_16BITLUV
356 for 16-bit encoded Luv pixels, SGILOGDATAFMT_32BITRAW and
357 SGILOGDATAFMT_24BITRAW for no conversion of data, SGILOG‐
358 DATAFMT_8BITRGB for returning 8-bit RGB data (valid only when
359 decoding LogLuv-encoded data), SGILOGDATAFMT_FLTY for converting
360 between LogL and 32-bit IEEE floating valued Y pixels, SGILOG‐
361 DATAFMT_16BITL for 16-bit encoded L pixels, and SGILOG‐
362 DATAFMT_8BITGRY for returning 8-bit greyscale data (valid only
363 when decoding LogL-encoded data).
364
366 All error messages are directed through the TIFFError routine. By de‐
367 fault messages are directed to stderr in the form: module: message\n.
368 Warning messages are likewise directed through the TIFFWarning routine.
369
371 fax2tiff(1), gif2tiff(1), pal2rgb(1), ppm2tiff(1), rgb2ycbcr(1),
372 ras2tiff(1), raw2tiff(1), sgi2tiff(1), tiff2bw(1), tiffdither(1), tiff‐
373 dump(1), tiffcp(1), tiffcmp(1), tiffgt(1), tiffinfo(1), tiffmedian(1),
374 tiffsplit(1), tiffsv(1).
375 Tag Image File Format Specification — Revision 6.0, an Aldus Technical
377 Memorandum.
378 The Spirit of TIFF Class F, an appendix to the TIFF 5.0 specification
380 prepared by Cygnet Technologies.
381 Libtiff library home page: http://www.simplesystems.org/libtiff/
383
385 The library does not support multi-sample images where some samples
386 have different bits/sample.
387 The library does not support random access to compressed data that is
389 organized with more than one row per tile or strip.
390libtiff November 2, 2005 INTRO(3TIFF)