--- name: "Graphics::TIFF" section: "3pm" platform: "linux" package: "perl-graphics-tiff" version: "21-4" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Graphics::TIFF" --- # Graphics::TIFF(3pm) Perl extension for the libtiff library ## NAME Graphics::TIFF - Perl extension for the libtiff library ## VERSION 21 ## SYNOPSIS Perl bindings for the libtiff library. This module allows you to access TIFF images in a Perlish and object-oriented way, freeing you from the casting and memory management in C, yet remaining very close in spirit to original API. The following snippet can be used to read the image data from a TIFF: ``` use Graphics::TIFF ':all'; my $tif = Graphics::TIFF->Open( 'test.tif', 'r' ); my $stripsize = $tif->StripSize; for my $stripnum ( 0 .. $tif->NumberOfStrips - 1 ) { my $buffer = $tif->ReadEncodedStrip( $stripnum, $stripsize ); # do something with $buffer } $tif->Close; ``` ## DESCRIPTION The Graphics::TIFF module allows a Perl developer to access TIFF images. Find out more about libtiff at \. ## SUBROUTINES/METHODS ### Graphics::TIFF-\>get\_version Returns an array with the LIBTIFF\_VERSION\_(MAJOR\|MINOR\|MICRO) versions: ``` join('.',Graphics::TIFF->get_version) ``` ### Graphics::TIFF-\>get\_version\_scalar Returns an scalar with the LIBTIFF\_VERSION\_(MAJOR\|MINOR\|MICRO) versions combined as per the Perl version numbering, i.e. libtiff 4.0.6 gives 4.000006. This allows simple version comparisons. ### Graphics::TIFF-\>GetVersion Returns a string with the format "LIBTIFF, Version MAJOR.MINOR.MICRO" ### Graphics::TIFF-\>IsCODECConfigured(compression) Returns a boolean if libtiff was configured with the given compression method. See the possible values for the TIFFTAG\_COMPRESSION tag for valid compression methods. ### Graphics::TIFF-\>Open(filename, flags) Returns a TIFF object. 'r' and 'w' are valid flags. ### $tif-\>Close Closes the tiff given TIFF object. ### $tif-\>FileName Returns the filename associated with the given TIFF object. ### $tif-\>ReadDirectory Read the next directory in the specified file and make it the current directory. Applications only need to call ReadDirectory to read multiple subfiles in a single TIFF file - the first directory in a file is automatically read when Open is called. *Notes* If the library is compiled with STRIPCHOP\_SUPPORT enabled, then images that have a single uncompressed strip or tile of data are automatically treated as if they were made up of multiple strips or tiles of approximately 8 kilobytes each. This operation is done only in-memory; it does not alter the contents of the file. However, the construction of the ''chopped strips'' is visible to the application through the number of strips \[tiles\] returned by NumberOfStrips \[NumberOfTiles\]. *Return Values* If the next directory was successfully read, 1 is returned. Otherwise, 0 is returned if an error was encountered, or if there are no more directories to be read. ### $tif-\>WriteDirectory WriteDirectory will write the contents of the current directory to the file and setup to create a new subfile in the same file. Applications only need to call WriteDirectory when writing multiple subfiles to a single TIFF file. WriteDirectory is automatically called by Close and Flush to write a modified directory if the file is open for writing. The RewriteDirectory function operates similarly to WriteDirectory, but can be called with directories previously read or written that already have an established location in the file. It will rewrite the directory, but instead of place it at it's old location (as TIFFWriteDirectory would) it will place them at the end of the file, correcting the pointer from the preceding directory or file header to point to it's new location. This is particularly important in cases where the size of the directory and pointed to data has grown, so it won't fit in the space available at the old location. The CheckpointDirectory writes the current state of the tiff directory into the file to make what is currently in the file readable. Unlike WriteDirectory, CheckpointDirectory does not free up the directory data structures in memory, so they can be updated (as strips/tiles are written) and written again. Reading such a partial file you will at worst get a tiff read error for the first strip/tile encountered that is incomplete, but you will at least get all the valid data in the file before that. When the file is complete, just use WriteDirectory as usual to finish it off cleanly. *Return Values* 1 is returned when the contents are successfully written to the file. Otherwise, 0 is returned if an error was encountered when writing the directory contents. ### $tif-\>ReadEXIFDirectory(diroff) Required before reading EXIF tags. ### $tif-\>NumberOfDirectories Returns the number of directory in the given TIFF object. ### $tif-\>SetDirectory(dirnum) Changes the current directory and reads its contents with ReadDirectory. The parameter dirnum specifies the subfile/directory as an integer number, with the first directory numbered zero. *Return Values* On successful return 1 is returned. Otherwise, 0 is returned if dirnum or diroff specifies a non-existent directory, or if an error was encountered while reading the directory's contents. ### $tif-\>SetSubDirectory(diroff) Acts like SetDirectory, except the directory is specified as a file offset instead of an index; this is required for accessing subdirectories linked through a SubIFD tag. ### $tif-\>GetField(tag) Returns the value of a tag or pseudo-tag associated with the the current directory of the open TIFF file tif. (A pseudo-tag is a parameter that is used to control the operation of the TIFF library but whose value is not read or written to the underlying file.) The file must have been previously opened with Open. The type and number of values returned is dependent on the tag being requested. The tags understood by libtiff are shown below. Consult the TIFF specification for information on the meaning of each tag and their possible values. TIFFTAG\_ARTIST TIFFTAG\_BADFAXLINES TIFFTAG\_BITSPERSAMPLE TIFFTAG\_CLEANFAXDATA TIFFTAG\_COLORMAP TIFFTAG\_COMPRESSION (COMPRESSION\_NONE COMPRESSION\_CCITTRLE COMPRESSION\_CCITTFAX3 COMPRESSION\_CCITT\_T4 COMPRESSION\_CCITTFAX4 COMPRESSION\_CCITT\_T6 COMPRESSION\_LZW COMPRESSION\_OJPEG COMPRESSION\_JPEG COMPRESSION\_T85 COMPRESSION\_T43 COMPRESSION\_NEXT COMPRESSION\_CCITTRLEW COMPRESSION\_PACKBITS COMPRESSION\_THUNDERSCAN COMPRESSION\_IT8CTPAD COMPRESSION\_IT8LW COMPRESSION\_IT8MP COMPRESSION\_IT8BL COMPRESSION\_PIXARFILM COMPRESSION\_PIXARLOG COMPRESSION\_DEFLATE COMPRESSION\_ADOBE\_DEFLATE COMPRESSION\_DCS COMPRESSION\_JBIG COMPRESSION\_SGILOG COMPRESSION\_SGILOG24 COMPRESSION\_JP2000 COMPRESSION\_LZMA) TIFFTAG\_CONSECUTIVEBADFAXLINES TIFFTAG\_COPYRIGHT TIFFTAG\_DATATYPE TIFFTAG\_DATETIME TIFFTAG\_DOCUMENTNAME TIFFTAG\_DOTRANGE TIFFTAG\_EXTRASAMPLES (EXTRASAMPLE\_UNSPECIFIED EXTRASAMPLE\_ASSOCALPHA EXTRASAMPLE\_UNASSALPHA) TIFFTAG\_FAXMODE TIFFTAG\_FAXFILLFUNC TIFFTAG\_FILLORDER (FILLORDER\_MSB2LSB FILLORDER\_LSB2MSB) TIFFTAG\_GROUP3OPTIONS (GROUP3OPT\_2DENCODING GROUP3OPT\_UNCOMPRESSED GROUP3OPT\_FILLBITS) TIFFTAG\_GROUP4OPTIONS (GROUP4OPT\_UNCOMPRESSED) TIFFTAG\_HALFTONEHINTS TIFFTAG\_HOSTCOMPUTER TIFFTAG\_IMAGEDEPTH TIFFTAG\_IMAGEDESCRIPTION TIFFTAG\_IMAGELENGTH TIFFTAG\_IMAGEWIDTH TIFFTAG\_INKNAMES TIFFTAG\_INKSET (INKSET\_CMYK INKSET\_MULTIINK) TIFFTAG\_JPEGTABLES TIFFTAG\_JPEGQUALITY TIFFTAG\_JPEGCOLORMODE (JPEGCOLORMODE\_RAW JPEGCOLORMODE\_RGB) TIFFTAG\_JPEGPROC (JPEGPROC\_BASELINE JPEGPROC\_LOSSLESS) TIFFTAG\_JPEGTABLESMODE (JPEGTABLESMODE\_QUANT JPEGTABLESMODE\_HUFF) TIFFTAG\_MAKE TIFFTAG\_MATTEING TIFFTAG\_MAXSAMPLEVALUE TIFFTAG\_MINSAMPLEVALUE TIFFTAG\_MODEL TIFFTAG\_ORIENTATION (ORIENTATION\_TOPLEFT ORIENTATION\_TOPRIGHT ORIENTATION\_BOTRIGHT ORIENTATION\_BOTLEFT ORIENTATION\_LEFTTOP ORIENTATION\_RIGHTTOP ORIENTATION\_RIGHTBOT ORIENTATION\_LEFTBOT) TIFFTAG\_OSUBFILETYPE (OFILETYPE\_IMAGE OFILETYPE\_REDUCEDIMAGE OFILETYPE\_PAGE) TIFFTAG\_PAGENAME TIFFTAG\_PAGENUMBER TIFFTAG\_PHOTOMETRIC (PHOTOMETRIC\_MINISWHITE PHOTOMETRIC\_MINISBLACK PHOTOMETRIC\_RGB PHOTOMETRIC\_PALETTE PHOTOMETRIC\_MASK PHOTOMETRIC\_SEPARATED PHOTOMETRIC\_YCBCR PHOTOMETRIC\_CIELAB PHOTOMETRIC\_ICCLAB PHOTOMETRIC\_ITULAB PHOTOMETRIC\_LOGL PHOTOMETRIC\_LOGLUV) TIFFTAG\_PLANARCONFIG (PLANARCONFIG\_CONTIG PLANARCONFIG\_SEPARATE) TIFFTAG\_PREDICTOR (PREDICTOR\_NONE PREDICTOR\_HORIZONTAL PREDICTOR\_FLOATINGPOINT) TIFFTAG\_PRIMARYCHROMATICITIES TIFFTAG\_REFERENCEBLACKWHITE TIFFTAG\_RESOLUTIONUNIT (RESUNIT\_NONE RESUNIT\_INCH RESUNIT\_CENTIMETER) TIFFTAG\_ROWSPERSTRIP TIFFTAG\_SAMPLEFORMAT (SAMPLEFORMAT\_UINT SAMPLEFORMAT\_INT SAMPLEFORMAT\_IEEEFP SAMPLEFORMAT\_VOID SAMPLEFORMAT\_COMPLEXINT SAMPLEFORMAT\_COMPLEXIEEEFP) TIFFTAG\_SAMPLESPERPIXEL TIFFTAG\_SMAXSAMPLEVALUE TIFFTAG\_SMINSAMPLEVALUE TIFFTAG\_SOFTWARE TIFFTAG\_STONITS TIFFTAG\_STRIPBYTECOUNTS TIFFTAG\_STRIPOFFSETS TIFFTAG\_SUBFILETYPE (FILETYPE\_REDUCEDIMAGE FILETYPE\_PAGE FILETYPE\_MASK) TIFFTAG\_SUBIFD TIFFTAG\_TARGETPRINTER TIFFTAG\_THRESHHOLDING TIFFTAG\_TILEBYTECOUNTS TIFFTAG\_TILEDEPTH TIFFTAG\_TILELENGTH TIFFTAG\_TILEOFFSETS TIFFTAG\_TILEWIDTH TIFFTAG\_TRANSFERFUNCTION TIFFTAG\_WHITEPOINT TIFFTAG\_XPOSITION TIFFTAG\_XRESOLUTION TIFFTAG\_YCBCRCOEFFICIENTS TIFFTAG\_YCBCRPOSITIONING TIFFTAG\_YCBCRSUBSAMPLING TIFFTAG\_YPOSITION TIFFTAG\_YRESOLUTION TIFFTAG\_ICCPROFILE ### $tif-\>GetFieldDefaulted(tag) Identical to GetField, except that if a tag is not defined in the current directory and it has a default value, then the default value is returned. ### $tif-\>SetField(tag, ...) Sets the value of a field or pseudo-tag in the current directory associated with the open TIFF file tif. Set GetField for Possible values for# tag. ### $tif-\>IsTiled Returns a non-zero value if the image data has a tiled organisation. Zero is returned if the image data is organised in strips. ### $tif-\>ScanlineSize Returns the size in bytes of a row of data as it would be returned in a call to ReadScanline, or as it would be expected in a call to WriteScanline. ### $tif-\>StripSize Returns the equivalent size for a strip of data as it would be returned in a call to ReadEncodedStrip or as it would be expected in a call to WriteEncodedStrip. ### $tif-\>NumberOfStrips Returns the number of strips in the image. ### $tif-\>TileSize Returns the equivalent size for a tile of data as it would be returned in a call to ReadTile or as it would be expected in a call to WriteTile. ### $tif-\>TileRowSize Returns the number of bytes of a row of data in a tile. ### $tif-\>ComputeStrip(row, sample) Returns the strip that contains the specified coordinates. A valid strip is always returned; out-of-range coordinate values are clamped to the bounds of the image. The row parameter is always used in calculating a strip. The sample parameter is used only if data are organised in separate planes (PlanarConfiguration=2). ### $tif-\>ReadEncodedStrip(strip, size) Returns a buffer of up to size bytes of decompressed information. The value of strip is a \`\`raw strip number.'' That is, the caller must take into account whether or not the data are organised in separate planes (PlanarConfiguration=2). To read a full strip of data the data buffer should typically be at least as large as the number returned by StripSize. The library attempts to hide bit- and byte-ordering differences between the image and the native machine by converting data to the native machine order. Bit reversal is done if the FillOrder tag is opposite to the native machine bit order. 16- and 32-bit samples are automatically byte-swapped if the file was written with a byte order opposite to the native machine byte order. ### $tif-\>WriteEncodedStrip(strip, data, size) Compress size bytes of raw data from buf and write the result to the specified strip; replacing any previously written data. Note that the value of strip is a \`\`raw strip number.'' That is, the caller must take into account whether or not the data are organised in separate places (PlanarConfiguration=2). The library writes encoded data using the native machine byte order. Correctly implemented TIFF readers are expected to do any necessary byte-swapping to correctly process image data with BitsPerSample greater than 8. The strip number must be valid according to the current settings of the ImageLength and RowsPerStrip tags. An image may be dynamically grown by increasing the value of ImageLength prior to each call to TIFFWriteEncodedStrip. \-1 is returned if an error was encountered. Otherwise, the value of size is returned. ### $tif-\>ReadRawStrip(strip, size) Returns the contents of the specified strip. Note that the value of strip is a ''raw strip number.'' That is, the caller must take into account whether or not the data is organised in separate planes (PlanarConfiguration=2). To read a full strip of data the data buffer should typically be at least as large as the number returned by StripSize. ### $tif-\>ReadTile(x, y, z, s) Returns the data for the tile containing the specified coordinates. The data is returned decompressed and, typically, in the native byte- and bit-ordering, but are otherwise packed (see further below). The buffer must be large enough to hold an entire tile of data. Applications should call the routine TIFFTileSize to find out the size (in bytes) of a tile buffer. The x and y parameters are always used by ReadTile. The z parameter is used if the image is deeper than 1 slice (ImageDepth\>1). The sample parameter is used only if data are organised in separate planes (PlanarConfiguration=2). The library attempts to hide bit- and byte-ordering differences between the image and the native machine by converting data to the native machine order. Bit reversal is done if the FillOrder tag is opposite to the native machine bit order. 16- and 32-bit samples are automatically byte-swapped if the file was written with a byte order opposite to the native machine byte order. ### $tif-\>CurrentDirectory() Return an index number of the current directory in the specified TIFF file. ### $tif-\>PrintDirectory(file, flags) Prints a description of the current directory in the specified TIFF file to the standard I/O output stream fd. The flags parameter is used to control the level of detail of the printed information, and is a bitwise or of the following values: TIFFPRINT\_NONE TIFFPRINT\_STRIPS TIFFPRINT\_CURVES TIFFPRINT\_COLORMAP TIFFPRINT\_JPEGQTABLES TIFFPRINT\_JPEGACTABLES TIFFPRINT\_JPEGDCTABLES ### Graphics::TIFF::ReverseBits(data, size) Replaces each byte in data with the equivalent bit-reversed value. This operation is done with a lookup table. ## DIAGNOSTICS ## CONFIGURATION AND ENVIRONMENT ## DEPENDENCIES ### Runtime The runtime dependencies are just libtiff itself. In Windows this is satisfied by Alien::libtiff. ### Build The build dependencies are additionally the development headers for libtiff and Perl. ### Test In addition to the above, the Perl module Image::Magick is required to run some of the tests. ## INCOMPATIBILITIES ## BUGS AND LIMITATIONS ## SEE ALSO The LIBTIFF Standard Reference \ is a handy companion. The Perl bindings follow the C API very closely, and the C reference documentation should be considered the canonical source. ## AUTHOR Jeffrey Ratcliffe, \ ## LICENSE AND COPYRIGHT Copyright (C) 2017--2024 by Jeffrey Ratcliffe This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.