1Graphics::TIFF(3)     User Contributed Perl Documentation    Graphics::TIFF(3)
2
3
4

NAME

6       Graphics::TIFF - Perl extension for the libtiff library
7

VERSION

9       13
10

SYNOPSIS

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
17       The following snippet can be used to read the image data from a TIFF:
18
19        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

DESCRIPTION

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

SUBROUTINES/METHODS

33   Graphics::TIFF->get_version
34       Returns an array with the LIBTIFF_VERSION_(MAJOR|MINOR|MICRO) versions:
35
36         join('.',Graphics::TIFF->get_version)
37
38   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
43   Graphics::TIFF->GetVersion
44       Returns a string with the format "LIBTIFF, Version MAJOR.MINOR.MICRO"
45
46   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
51   Graphics::TIFF->Open(filename, flags)
52       Returns a TIFF object. 'r' and 'w' are valid flags.
53
54   $tif->Close
55       Closes the tiff given TIFF object.
56
57   $tif->FileName
58       Returns the filename associated with the given TIFF object.
59
60   $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
66       Notes
67
68       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
76       Return Values
77
78       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
82   $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
89       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
99       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
109       Return Values
110
111       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
115   $tif->ReadEXIFDirectory(diroff)
116       Required before reading EXIF tags.
117
118   $tif->NumberOfDirectories
119       Returns the number of directory in the given TIFF object.
120
121   $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
126       Return Values
127
128       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
132   $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
137   $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
145       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
149       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
203   $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
208   $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
213   $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
217   $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
222   $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
227   $tif->NumberOfStrips
228       Returns the number of strips in the image.
229
230   $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
235   $tif->TileRowSize
236       Returns the number of bytes of a row of data in a tile.
237
238   $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
245   $tif->ReadEncodedStrip(strip, size)
246       Returns a buffer of up to size bytes of decompressed information.
247
248       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
254       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
261   $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
268       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
273       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
278       -1 is returned if an error was encountered. Otherwise, the value of
279       size is returned.
280
281   $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
289   $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
300       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
307   $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
313       TIFFPRINT_NONE TIFFPRINT_STRIPS TIFFPRINT_CURVES TIFFPRINT_COLORMAP
314       TIFFPRINT_JPEGQTABLES TIFFPRINT_JPEGACTABLES TIFFPRINT_JPEGDCTABLES
315

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

319   Runtime
320       The runtime dependencies are just libtiff itself. In Windows this is
321       satisfied by Alien::libtiff.
322
323   Build
324       The build dependencies are additionally the development headers for
325       libtiff and Perl.
326
327   Test
328       In addition to the above, the Perl module Image::Magick is required to
329       run some of the tests.
330

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

334       The LIBTIFF Standard Reference <http://www.libtiff.org/libtiff.html> is
335       a handy companion. The Perl bindings follow the C API very closely, and
336       the C reference documentation should be considered the canonical
337       source.
338

AUTHOR

340       Jeffrey Ratcliffe, <jffry@posteo.net>
341
343       Copyright (C) 2017--2021 by Jeffrey Ratcliffe
344
345       This library is free software; you can redistribute it and/or modify it
346       under the same terms as Perl itself, either Perl version 5.8.5 or, at
347       your option, any later version of Perl 5 you may have available.
348
349
350
351perl v5.32.1                      2021-05-27                 Graphics::TIFF(3)
Impressum