Graphics::TIFF(3pm)

📦

version 21 · 11 versions

🎀 NAME 🎀

Graphics::TIFF — a Perl extension for the libtiff library. 💖 That's the whole name, bestie — it's a User Contributed Perl Documentation page (Graphics::TIFF(3pm)), and it is absolutely about TIFFs.

🌸 VERSION 🌸

21

Yes. Version 21. We're not new here. 👑

🦋 SYNOPSIS 🦋

Perl bindings for the libtiff library, periodt. This module lets you access TIFF images in a Perlish and object-oriented way — which means it frees you from all the casting and memory management you'd be doing in C, but it still stays very close in spirit to the original API. Like, it went to the same school, it just has better hair now. 💅

Here's a snippet you can use 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;

Slay. Look at that loop go. 🫶

🌈 DESCRIPTION 🌈

The Graphics::TIFF module allows a Perl developer to access TIFF images. That's it, that's the pitch. Find out more about libtiff over at http://www.libtiff.org. ✨

💫 SUBROUTINES/METHODS 💫

Okay so here's the whole menu, angel. Take your time, nobody's rushing you. 🧚

`Graphics::TIFF->get_version`

Returns an array with the LIBTIFF_VERSION_(MAJOR|MINOR|MICRO) versions:

join('.',Graphics::TIFF->get_version)

Three little numbers, all in a row. Adorable. 🎀

`Graphics::TIFF->get_version_scalar`

Returns an scalar with the LIBTIFF_VERSION_(MAJOR|MINOR|MICRO) versions combined as per the Perl version numbering — so, like, libtiff 4.0.6 gives you 4.000006. This is the one that lets you do simple version comparisons without losing your mind. Lowkey the most useful function here ngl. 💜

`Graphics::TIFF->GetVersion`

Returns a string with the format "LIBTIFF, Version MAJOR.MINOR.MICRO". For when you just want it to say the thing. 💬

`Graphics::TIFF->IsCODECConfigured(compression)`

Returns a boolean telling you whether libtiff was configured with the given compression method. Peep the possible values for the TIFFTAG_COMPRESSION tag for the valid compression methods, bestie — they're all listed down in GetField territory. 🔍

`Graphics::TIFF->Open(filename, flags)`

Returns a TIFF object. 'r' and 'w' are the valid flags. That's the door, go through it. 🚪✨

`$tif->Close`

Closes the tiff given TIFF object. Say bye to it. It had a good run. 💀

`$tif->FileName`

Returns the filename associated with the given TIFF object. It remembers its own name, we love an icon with memory. 👑

`$tif->ReadDirectory`

Reads the next directory in the specified file and makes it the current directory. Here's the tea though — applications only need to call ReadDirectory to read multiple subfiles in a single TIFF file, because the first directory in a file is automatically read when Open is called. Free win. 🎁

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 — and this is the part people miss — the construction of the ''chopped strips'' is visible to the application through the number of strips [tiles] returned by NumberOfStrips [NumberOfTiles]. So your count can go up and the file itself didn't change at all. Sneaky but wholesome. 🙈

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. And good news: 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 it 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 placing it at its 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 its 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. It outgrew the outfit, so it moved. 💅

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. If you read 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. No mess, no drama. 🧼

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. That's the prerequisite, don't skip it, it's not optional and you know it. ⚠️

`$tif->NumberOfDirectories`

Returns the number of directory in the given TIFF object. (Yes, "directory", singular, that's how the page says it. We respect the original.) 🔢

`$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 — zero-indexed, the way the universe intended. 🌌

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 one is required for accessing subdirectories linked through a SubIFD tag. Different door, same room. 🚪

`$tif->GetField(tag)`

Returns the value of a tag or pseudo-tag associated with the the current directory of the open TIFF file tif. (Quick vocab check: 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. It's a vibe, not a byte. 💭) 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

Yeah. All of them. Every single one. We do not skip tags in this house. 👑🔥

`$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. It's GetField but with a safety net. 🫶

`$tif->SetField(tag, ...)`

Sets the value of a field or pseudo-tag in the current directory associated with the open TIFF file tif. Peep GetField for the 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. So basically: tiles or strips, pick a lane. 🌈

`$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. Count 'em. 🔢

`$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). No crashing, no drama, it just clamps and carries on. 💅

`$tif->ReadEncodedStrip(strip, size)`

Returns a buffer of up to size bytes of decompressed information. That's your data, bestie — go do something with $buffer. 💖

okay so the value of strip is a “raw strip number.” Like, raw raw. That means you, the caller, have to keep it in your head whether the data lives in separate planes or not, aka PlanarConfiguration=2. And if you wanna read a whole full strip of data, your data buffer should typically be at least as big as whatever StripSize hands back. bestie, size your buffers. 💅

The library is out here doing the most to hide bit- and byte-ordering drama between the image and your native machine, converting everything to native machine order for you. Bit reversal happens if the FillOrder tag is opposite to the native machine bit order. And 16- and 32-bit samples get automatically byte-swapped if the file was written with a byte order opposite to the native machine byte order. it's giving considerate. 🫶

`$tif->WriteEncodedStrip(strip, data, size)`

Compresses size bytes of raw data from buf and writes the result to the specified strip, replacing any previously written data. heads up though: the value of strip is a “raw strip number.” Which means the caller (that's you, bestie 😭) has to take into account whether or not the data is 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. so like, not your problem, but also lowkey your problem if you're writing the reader. 🙈

The strip number must be valid according to the current settings of the ImageLength and RowsPerStrip tags. And guess what — an image may be dynamically grown by increasing the value of ImageLength prior to each call to TIFFWriteEncodedStrip. growth mindset fr fr ✨

-1 is returned if an error was encountered. Otherwise, the value of size is returned. simple as.

`$tif->ReadRawStrip(strip, size)`

Returns the contents of the specified strip. And yes, once again, 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. we been knew. 💖

`$tif->ReadTile(x, y, z, s)`

Returns the data for the tile containing the specified coordinates. The data comes back 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 — no shortcuts. Applications should call the routine TIFFTileSize to find out the size (in bytes) of a tile buffer.

Now the parameter tea ☕:

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. iconic behaviour honestly. 👑

`$tif->CurrentDirectory()`

Returns an index number of the current directory in the specified TIFF file. that's it. that's the whole thing. 🎀

`$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 controls the level of detail of the printed information, and it's a bitwise or of these values:

TIFFPRINT_NONE
TIFFPRINT_STRIPS
TIFFPRINT_CURVES
TIFFPRINT_COLORMAP
TIFFPRINT_JPEGQTABLES
TIFFPRINT_JPEGACTABLES
TIFFPRINT_JPEGDCTABLES

bitwise-or them together for the exact amount of lore you want printed. 🌈

`Graphics::TIFF::ReverseBits(data, size)`

Replaces each byte in data with the equivalent bit-reversed value. This operation is done with a lookup table, so it's speedy. slay. ⭐

🩺 DIAGNOSTICS

this section is empty in the original — no diagnostics listed, bestie. nothing to report. 💀

🌱 CONFIGURATION AND ENVIRONMENT

also empty. no environment variables live here. 🦋

🧸 DEPENDENCIES

🌸 Runtime

The runtime dependencies are just libtiff itself. On Windows this is satisfied by Alien::libtiff. one dependency, one icon. 💅

🔨 Build

The build dependencies are additionally the development headers for libtiff and Perl. so, more stuff. of course. 😭

🧪 Test

In addition to the above, the Perl module Image::Magick is required to run some of the tests. yes, some tests need the whole image manipulation queen. 👑

🚫 INCOMPATIBILITIES

empty section, no incompatibilities documented. we stay compatible. periodt. ✨

🐛 BUGS AND LIMITATIONS

nothing listed in the original. no known bugs, no known limitations. living the dream fr fr. 🔥

👀 SEE ALSO

The LIBTIFF Standard Reference <http://www.libtiff.org/libtiff.html> is a handy companion. The Perl bindings follow the C API very closely, and the C reference documentation should be considered the canonical source. so if you're confused, that's where the real lore lives. iykyk. 📖

✍️ AUTHOR

Jeffrey Ratcliffe, <jffry@posteo.net>

📜 LICENSE AND COPYRIGHT

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. free software, bestie, we love to see it. 🫶

and that's the whole page, babes!! 🎀 this was perl v5.42.3, rendered on 2026-08-19, filed under Graphics::TIFF(3pm). go read some tiff files. mwah. 💖✨🌸

📦 where this page comes from

ubuntu stonking: libgraphics-tiff-perl 21-1build2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms