1Graphics::TIFF(3) User Contributed Perl Documentation Graphics::TIFF(3)
2
6 Graphics::TIFF - Perl extension for the libtiff library
7
9 18
10
12 Perl bindings for the libtiff library. This module allows you to
13 access TIFF images in a Perlish and object-oriented way, freeing you
14 from the casting and memory management in C, yet remaining very close
15 in spirit to original API.
16 The following snippet can be used to read the image data from a TIFF:
18 use Graphics::TIFF ':all';
20 my $tif = Graphics::TIFF->Open( 'test.tif', 'r' );
21 my $stripsize = $tif->StripSize;
22 for my $stripnum ( 0 .. $tif->NumberOfStrips - 1 ) {
23 my $buffer = $tif->ReadEncodedStrip( $stripnum, $stripsize );
24 # do something with $buffer
25 }
26 $tif->Close;
27
29 The Graphics::TIFF module allows a Perl developer to access TIFF
30 images. Find out more about libtiff at <http://www.libtiff.org>.
31
33 Graphics::TIFF->get_version
34 Returns an array with the LIBTIFF_VERSION_(MAJOR|MINOR|MICRO) versions:
35 join('.',Graphics::TIFF->get_version)
37 Graphics::TIFF->get_version_scalar
39 Returns an scalar with the LIBTIFF_VERSION_(MAJOR|MINOR|MICRO) versions
40 combined as per the Perl version numbering, i.e. libtiff 4.0.6 gives
41 4.000006. This allows simple version comparisons.
42 Graphics::TIFF->GetVersion
44 Returns a string with the format "LIBTIFF, Version MAJOR.MINOR.MICRO"
45 Graphics::TIFF->IsCODECConfigured(compression)
47 Returns a boolean if libtiff was configured with the given compression
48 method. See the possible values for the TIFFTAG_COMPRESSION tag for
49 valid compression methods.
50 Graphics::TIFF->Open(filename, flags)
52 Returns a TIFF object. 'r' and 'w' are valid flags.
53 $tif->Close
55 Closes the tiff given TIFF object.
56 $tif->FileName
58 Returns the filename associated with the given TIFF object.
59 $tif->ReadDirectory
61 Read the next directory in the specified file and make it the current
62 directory. Applications only need to call ReadDirectory to read
63 multiple subfiles in a single TIFF file - the first directory in a file
64 is automatically read when Open is called.
65 Notes
67 If the library is compiled with STRIPCHOP_SUPPORT enabled, then images
69 that have a single uncompressed strip or tile of data are automatically
70 treated as if they were made up of multiple strips or tiles of
71 approximately 8 kilobytes each. This operation is done only in-memory;
72 it does not alter the contents of the file. However, the construction
73 of the ''chopped strips'' is visible to the application through the
74 number of strips [tiles] returned by NumberOfStrips [NumberOfTiles].
75 Return Values
77 If the next directory was successfully read, 1 is returned. Otherwise,
79 0 is returned if an error was encountered, or if there are no more
80 directories to be read.
81 $tif->WriteDirectory
83 WriteDirectory will write the contents of the current directory to the
84 file and setup to create a new subfile in the same file. Applications
85 only need to call WriteDirectory when writing multiple subfiles to a
86 single TIFF file. WriteDirectory is automatically called by Close and
87 Flush to write a modified directory if the file is open for writing.
88 The RewriteDirectory function operates similarly to WriteDirectory, but
90 can be called with directories previously read or written that already
91 have an established location in the file. It will rewrite the
92 directory, but instead of place it at it's old location (as
93 TIFFWriteDirectory would) it will place them at the end of the file,
94 correcting the pointer from the preceding directory or file header to
95 point to it's new location. This is particularly important in cases
96 where the size of the directory and pointed to data has grown, so it
97 won't fit in the space available at the old location.
98 The CheckpointDirectory writes the current state of the tiff directory
100 into the file to make what is currently in the file readable. Unlike
101 WriteDirectory, CheckpointDirectory does not free up the directory data
102 structures in memory, so they can be updated (as strips/tiles are
103 written) and written again. Reading such a partial file you will at
104 worst get a tiff read error for the first strip/tile encountered that
105 is incomplete, but you will at least get all the valid data in the file
106 before that. When the file is complete, just use WriteDirectory as
107 usual to finish it off cleanly.
108 Return Values
110 1 is returned when the contents are successfully written to the file.
112 Otherwise, 0 is returned if an error was encountered when writing the
113 directory contents.
114 $tif->ReadEXIFDirectory(diroff)
116 Required before reading EXIF tags.
117 $tif->NumberOfDirectories
119 Returns the number of directory in the given TIFF object.
120 $tif->SetDirectory(dirnum)
122 Changes the current directory and reads its contents with
123 ReadDirectory. The parameter dirnum specifies the subfile/directory as
124 an integer number, with the first directory numbered zero.
125 Return Values
127 On successful return 1 is returned. Otherwise, 0 is returned if dirnum
129 or diroff specifies a non-existent directory, or if an error was
130 encountered while reading the directory's contents.
131 $tif->SetSubDirectory(diroff)
133 Acts like SetDirectory, except the directory is specified as a file
134 offset instead of an index; this is required for accessing
135 subdirectories linked through a SubIFD tag.
136 $tif->GetField(tag)
138 Returns the value of a tag or pseudo-tag associated with the the
139 current directory of the open TIFF file tif. (A pseudo-tag is a
140 parameter that is used to control the operation of the TIFF library but
141 whose value is not read or written to the underlying file.) The file
142 must have been previously opened with Open. The type and number of
143 values returned is dependent on the tag being requested.
144 The tags understood by libtiff are shown below. Consult the TIFF
146 specification for information on the meaning of each tag and their
147 possible values.
148 TIFFTAG_ARTIST TIFFTAG_BADFAXLINES TIFFTAG_BITSPERSAMPLE
150 TIFFTAG_CLEANFAXDATA TIFFTAG_COLORMAP TIFFTAG_COMPRESSION
151 (COMPRESSION_NONE COMPRESSION_CCITTRLE COMPRESSION_CCITTFAX3
152 COMPRESSION_CCITT_T4 COMPRESSION_CCITTFAX4 COMPRESSION_CCITT_T6
153 COMPRESSION_LZW COMPRESSION_OJPEG COMPRESSION_JPEG COMPRESSION_T85
154 COMPRESSION_T43 COMPRESSION_NEXT COMPRESSION_CCITTRLEW
155 COMPRESSION_PACKBITS COMPRESSION_THUNDERSCAN COMPRESSION_IT8CTPAD
156 COMPRESSION_IT8LW COMPRESSION_IT8MP COMPRESSION_IT8BL
157 COMPRESSION_PIXARFILM COMPRESSION_PIXARLOG COMPRESSION_DEFLATE
158 COMPRESSION_ADOBE_DEFLATE COMPRESSION_DCS COMPRESSION_JBIG
159 COMPRESSION_SGILOG COMPRESSION_SGILOG24 COMPRESSION_JP2000
160 COMPRESSION_LZMA) TIFFTAG_CONSECUTIVEBADFAXLINES TIFFTAG_COPYRIGHT
161 TIFFTAG_DATATYPE TIFFTAG_DATETIME TIFFTAG_DOCUMENTNAME TIFFTAG_DOTRANGE
162 TIFFTAG_EXTRASAMPLES (EXTRASAMPLE_UNSPECIFIED EXTRASAMPLE_ASSOCALPHA
163 EXTRASAMPLE_UNASSALPHA) TIFFTAG_FAXMODE TIFFTAG_FAXFILLFUNC
164 TIFFTAG_FILLORDER (FILLORDER_MSB2LSB FILLORDER_LSB2MSB)
165 TIFFTAG_GROUP3OPTIONS (GROUP3OPT_2DENCODING GROUP3OPT_UNCOMPRESSED
166 GROUP3OPT_FILLBITS) TIFFTAG_GROUP4OPTIONS (GROUP4OPT_UNCOMPRESSED)
167 TIFFTAG_HALFTONEHINTS TIFFTAG_HOSTCOMPUTER TIFFTAG_IMAGEDEPTH
168 TIFFTAG_IMAGEDESCRIPTION TIFFTAG_IMAGELENGTH TIFFTAG_IMAGEWIDTH
169 TIFFTAG_INKNAMES TIFFTAG_INKSET (INKSET_CMYK INKSET_MULTIINK)
170 TIFFTAG_JPEGTABLES TIFFTAG_JPEGQUALITY TIFFTAG_JPEGCOLORMODE
171 (JPEGCOLORMODE_RAW JPEGCOLORMODE_RGB) TIFFTAG_JPEGPROC
172 (JPEGPROC_BASELINE JPEGPROC_LOSSLESS) TIFFTAG_JPEGTABLESMODE
173 (JPEGTABLESMODE_QUANT JPEGTABLESMODE_HUFF) TIFFTAG_MAKE
174 TIFFTAG_MATTEING TIFFTAG_MAXSAMPLEVALUE TIFFTAG_MINSAMPLEVALUE
175 TIFFTAG_MODEL TIFFTAG_ORIENTATION (ORIENTATION_TOPLEFT
176 ORIENTATION_TOPRIGHT ORIENTATION_BOTRIGHT ORIENTATION_BOTLEFT
177 ORIENTATION_LEFTTOP ORIENTATION_RIGHTTOP ORIENTATION_RIGHTBOT
178 ORIENTATION_LEFTBOT) TIFFTAG_OSUBFILETYPE (OFILETYPE_IMAGE
179 OFILETYPE_REDUCEDIMAGE OFILETYPE_PAGE) TIFFTAG_PAGENAME
180 TIFFTAG_PAGENUMBER TIFFTAG_PHOTOMETRIC (PHOTOMETRIC_MINISWHITE
181 PHOTOMETRIC_MINISBLACK PHOTOMETRIC_RGB PHOTOMETRIC_PALETTE
182 PHOTOMETRIC_MASK PHOTOMETRIC_SEPARATED PHOTOMETRIC_YCBCR
183 PHOTOMETRIC_CIELAB PHOTOMETRIC_ICCLAB PHOTOMETRIC_ITULAB
184 PHOTOMETRIC_LOGL PHOTOMETRIC_LOGLUV) TIFFTAG_PLANARCONFIG
185 (PLANARCONFIG_CONTIG PLANARCONFIG_SEPARATE) TIFFTAG_PREDICTOR
186 (PREDICTOR_NONE PREDICTOR_HORIZONTAL PREDICTOR_FLOATINGPOINT)
187 TIFFTAG_PRIMARYCHROMATICITIES TIFFTAG_REFERENCEBLACKWHITE
188 TIFFTAG_RESOLUTIONUNIT (RESUNIT_NONE RESUNIT_INCH RESUNIT_CENTIMETER)
189 TIFFTAG_ROWSPERSTRIP TIFFTAG_SAMPLEFORMAT (SAMPLEFORMAT_UINT
190 SAMPLEFORMAT_INT SAMPLEFORMAT_IEEEFP SAMPLEFORMAT_VOID
191 SAMPLEFORMAT_COMPLEXINT SAMPLEFORMAT_COMPLEXIEEEFP)
192 TIFFTAG_SAMPLESPERPIXEL TIFFTAG_SMAXSAMPLEVALUE TIFFTAG_SMINSAMPLEVALUE
193 TIFFTAG_SOFTWARE TIFFTAG_STONITS TIFFTAG_STRIPBYTECOUNTS
194 TIFFTAG_STRIPOFFSETS TIFFTAG_SUBFILETYPE (FILETYPE_REDUCEDIMAGE
195 FILETYPE_PAGE FILETYPE_MASK) TIFFTAG_SUBIFD TIFFTAG_TARGETPRINTER
196 TIFFTAG_THRESHHOLDING TIFFTAG_TILEBYTECOUNTS TIFFTAG_TILEDEPTH
197 TIFFTAG_TILELENGTH TIFFTAG_TILEOFFSETS TIFFTAG_TILEWIDTH
198 TIFFTAG_TRANSFERFUNCTION TIFFTAG_WHITEPOINT TIFFTAG_XPOSITION
199 TIFFTAG_XRESOLUTION TIFFTAG_YCBCRCOEFFICIENTS TIFFTAG_YCBCRPOSITIONING
200 TIFFTAG_YCBCRSUBSAMPLING TIFFTAG_YPOSITION TIFFTAG_YRESOLUTION
201 TIFFTAG_ICCPROFILE
202 $tif->GetFieldDefaulted(tag)
204 Identical to GetField, except that if a tag is not defined in the
205 current directory and it has a default value, then the default value is
206 returned.
207 $tif->SetField(tag, ...)
209 Sets the value of a field or pseudo-tag in the current directory
210 associated with the open TIFF file tif. Set GetField for Possible
211 values for# tag.
212 $tif->IsTiled
214 Returns a non-zero value if the image data has a tiled organisation.
215 Zero is returned if the image data is organised in strips.
216 $tif->ScanlineSize
218 Returns the size in bytes of a row of data as it would be returned in a
219 call to ReadScanline, or as it would be expected in a call to
220 WriteScanline.
221 $tif->StripSize
223 Returns the equivalent size for a strip of data as it would be returned
224 in a call to ReadEncodedStrip or as it would be expected in a call to
225 WriteEncodedStrip.
226 $tif->NumberOfStrips
228 Returns the number of strips in the image.
229 $tif->TileSize
231 Returns the equivalent size for a tile of data as it would be returned
232 in a call to ReadTile or as it would be expected in a call to
233 WriteTile.
234 $tif->TileRowSize
236 Returns the number of bytes of a row of data in a tile.
237 $tif->ComputeStrip(row, sample)
239 Returns the strip that contains the specified coordinates. A valid
240 strip is always returned; out-of-range coordinate values are clamped to
241 the bounds of the image. The row parameter is always used in
242 calculating a strip. The sample parameter is used only if data are
243 organised in separate planes (PlanarConfiguration=2).
244 $tif->ReadEncodedStrip(strip, size)
246 Returns a buffer of up to size bytes of decompressed information.
247 The value of strip is a ``raw strip number.'' That is, the caller must
249 take into account whether or not the data are organised in separate
250 planes (PlanarConfiguration=2). To read a full strip of data the data
251 buffer should typically be at least as large as the number returned by
252 StripSize.
253 The library attempts to hide bit- and byte-ordering differences between
255 the image and the native machine by converting data to the native
256 machine order. Bit reversal is done if the FillOrder tag is opposite
257 to the native machine bit order. 16- and 32-bit samples are
258 automatically byte-swapped if the file was written with a byte order
259 opposite to the native machine byte order.
260 $tif->WriteEncodedStrip(strip, data, size)
262 Compress size bytes of raw data from buf and write the result to the
263 specified strip; replacing any previously written data. Note that the
264 value of strip is a ``raw strip number.'' That is, the caller must take
265 into account whether or not the data are organised in separate places
266 (PlanarConfiguration=2).
267 The library writes encoded data using the native machine byte order.
269 Correctly implemented TIFF readers are expected to do any necessary
270 byte-swapping to correctly process image data with BitsPerSample
271 greater than 8.
272 The strip number must be valid according to the current settings of the
274 ImageLength and RowsPerStrip tags. An image may be dynamically grown by
275 increasing the value of ImageLength prior to each call to
276 TIFFWriteEncodedStrip.
277 -1 is returned if an error was encountered. Otherwise, the value of
279 size is returned.
280 $tif->ReadRawStrip(strip, size)
282 Returns the contents of the specified strip. Note that the value of
283 strip is a ''raw strip number.'' That is, the caller must take into
284 account whether or not the data is organised in separate planes
285 (PlanarConfiguration=2). To read a full strip of data the data buffer
286 should typically be at least as large as the number returned by
287 StripSize.
288 $tif->ReadTile(x, y, z, s)
290 Returns the data for the tile containing the specified coordinates. The
291 data is returned decompressed and, typically, in the native byte- and
292 bit-ordering, but are otherwise packed (see further below). The buffer
293 must be large enough to hold an entire tile of data. Applications
294 should call the routine TIFFTileSize to find out the size (in bytes) of
295 a tile buffer. The x and y parameters are always used by ReadTile. The
296 z parameter is used if the image is deeper than 1 slice (ImageDepth>1).
297 The sample parameter is used only if data are organised in separate
298 planes (PlanarConfiguration=2).
299 The library attempts to hide bit- and byte-ordering differences between
301 the image and the native machine by converting data to the native
302 machine order. Bit reversal is done if the FillOrder tag is opposite to
303 the native machine bit order. 16- and 32-bit samples are automatically
304 byte-swapped if the file was written with a byte order opposite to the
305 native machine byte order.
306 $tif->PrintDirectory(file, flags)
308 Prints a description of the current directory in the specified TIFF
309 file to the standard I/O output stream fd. The flags parameter is used
310 to control the level of detail of the printed information, and is a
311 bitwise or of the following values:
312 TIFFPRINT_NONE TIFFPRINT_STRIPS TIFFPRINT_CURVES TIFFPRINT_COLORMAP
314 TIFFPRINT_JPEGQTABLES TIFFPRINT_JPEGACTABLES TIFFPRINT_JPEGDCTABLES
315 Graphics::TIFF::ReverseBits(data, size)
317 Replaces each byte in data with the equivalent bit-reversed value. This
318 operation is done with a lookup table.
319
323 Runtime
324 The runtime dependencies are just libtiff itself. In Windows this is
325 satisfied by Alien::libtiff.
326 Build
328 The build dependencies are additionally the development headers for
329 libtiff and Perl.
330 Test
332 In addition to the above, the Perl module Image::Magick is required to
333 run some of the tests.
334
338 The LIBTIFF Standard Reference <http://www.libtiff.org/libtiff.html> is
339 a handy companion. The Perl bindings follow the C API very closely, and
340 the C reference documentation should be considered the canonical
341 source.
342
344 Jeffrey Ratcliffe, <jffry@posteo.net>
345
347 Copyright (C) 2017--2021 by Jeffrey Ratcliffe
348 This library is free software; you can redistribute it and/or modify it
350 under the same terms as Perl itself, either Perl version 5.8.5 or, at
351 your option, any later version of Perl 5 you may have available.
352perl v5.34.0 2021-11-01 Graphics::TIFF(3)