Main Content


MATLAB Gateway to LibTIFF library routines


A Tiff object represents a connection to a Tagged Image File Format (TIFF) file and provides access to many of the functions of the LibTIFF library. Tiff offers more capabilities than the imread and imwrite functions, such as reading subimages, writing tiles and strips of image data, and modifying individual TIFF tags.

In most cases, the syntax of the Tiff object function is similar to the syntax of the corresponding LibTIFF library function. To fully understand the capabilities of the Tiff object, refer to the LibTIFF API and the TIFF specification and technical notes. View this documentation at LibTIFF - TIFF Library and Utilities.

MATLAB® supports LibTIFF version 4.4.0.




obj = Tiff(filename) creates a Tiff object for read access to the TIFF file filename.


obj = Tiff(filename,mode) creates a Tiff object with the type of access to the TIFF file specified by mode.

Input Arguments

expand all

Name of file, specified as a character vector or string scalar.

Example: 'myfile.tif'

File access type, specified as one of these values.

'r'Open file for reading (default).
'w'Open file for writing; discard existing contents.
'w8'Open file for writing a BigTIFF file; discard existing contents.
'a'Open or create file for writing; append data to end of file.
'r+'Open (do not create) file for reading and writing.

When you open a TIFF file for writing or appending, the Tiff object automatically creates an IFD in the file for writing subsequent data. This IFD has all the default values specified in TIFF Revision 6.0.


expand all

TIFF files consist of image file directories (IFDs) that contain image data and associated tags. The tags contain image related information, such as the image width, the image height, and the number of samples. Each TIFF property is a structure that provides values for a tag. Set the tag values using the setTag function. For instance, create a file and specify the JPEG compression.

t = Tiff('myfile.tif','w');

When you create a file, before writing data to the file, you must set these tags:


Depending on the layout of the image, you must set these additional tags:

  • Stripped layout — Set the RowsPerStrip tag.

  • Tiled layout — Set the TileWidth and TileHeight tags.

Scheme to compress image data, stored in a structure with these fields.

Field Name
CCITTRLE (Read-only)

To see a full list of values that MATLAB supports for the Compression tag, type Tiff.Compression in the command window.

Example: setTag(t,'Compression',Tiff.Compression.JPEG);

Extra channel description, stored in a structure with these fields.

Field NameDescription
UnspecifiedUnspecified data
AssociatedAlphaAssociated alpha (premultiplied)
UnassociatedAlphaUnassociated alpha data

If extra channels exist in addition to the usual colorimetric channels, then the ExtraSamples tag is required. For an example usage, see Write Tiff Image with Color and Alpha Channel Data.

Example: setTag(t,'ExtraSamples',Tiff.ExtraSamples.AssociatedAlpha)

Group 3 Fax compression options, stored in a structure with these fields.

Field NameDescription

Bit 0 is 1.

This value specifies two-dimensional coding. If more than one strip is specified, each strip must begin with a one-dimensionally coded line. That is, RowsPerStrip must be a multiple of parameter K, as documented in the CCITT specification.


Bit 1 is 1.

This value specifies an uncompressed mode when encoding.


Bit 2 is 1.

Add fill bits as necessary before the EOL codes, such that EOL always ends on a byte boundary. This ensures that a zero nibble precedes an EOL sequence by 1 byte. For example, xxxx-0000 0000-0001.

This property also is referred to as Fax3 or T4Options. The value of the property is a bit mask controlled by the first 3 bits.

Example: setTag(t,'Group3Options',Tiff.Group3Options.Uncompressed);

Separated image ink set, stored in a structure with these fields.

Field NameDescription
CMYKOrder of components: cyan, magenta, yellow, black. Usually, a value of 0 represents 0% ink coverage and a value of 255 represents 100% ink coverage for that component, but consult the TIFF specification for DotRange. When you specify CMYK, do not set the InkNames tag.
MultiInkAny ordering other than CMYK. Consult the TIFF specification for InkNames field for a description of the inks used.

In the context of this property, separated refers to the photometric interpretation (not the planar configuration).

Example: setTag(t,'InkSet',Tiff.InkSet.CMYK);

Color mode, stored in a structure with these fields.

Field NameDescription
Raw (default)Keep input as separate Y, Cb, and Cr matrices.
RGBConvert RGB input to YCbCr.

Do not use this property to read YCbCr imagery as RGB. Instead use the RGBA interface provided by the readRGBAImage, readRGBAStrip, and readRGBATile functions.

For an example, see Create YCbCr/JPEG Image from RGB Data.

Example: setTag(t,'JPEGColorMode',Tiff.JPEGColorMode.RGB);

Visual orientation of the image data, stored in a structure with these fields.

Field Name

The Orientation property describes the image orientation with respect to rows and columns. For instance, when Orientation is set to TopLeft, then the first row represents the top of the image, and the first column represents the left side. The value specified in the Orientation is for informational purposes only, and it does not affect how MATLAB reads or writes the image data.

Example: setTag(t,'Orientation',Tiff.Orientation.TopLeft);

Color space of image data, stored in a structure with these fields.

Field Name
Separated (CMYK)

Example: setTag(t,'Photometric',Tiff.Photometric.RGB);

Storage configuration of the image component values, stored in a structure with these fields.

Field NameDescription
ChunkyStore component values for each pixel contiguously. For example, in the case of RGB data, store the first three pixels in the file as RGBRGBRGB. Almost all TIFF images have contiguous planar configurations.
SeparateStore component values for each pixel separately. For example, in the case of RGB data, the red component is stored separately in the file from the green and blue components.

Example: setTag(t,'PlanarConfiguration',Tiff.PlanarConfiguration.Chunky);

Resolution units to interpret the values contained in XResolution and YResolution tags, stored in a structure with these fields.

Field NameDescription
NoneDefault value.
InchAssign unit inches for values contained in XResolution and YResolution tags.
CentimeterAssign unit centimeters for values contained in XResolution and YResolution tags.

For example, the following code sets the value of the image resolution in X and Y directions to 300 pixels per inch:


Example: setTag(t,'ResolutionUnit',Tiff.ResolutionUnit.Inch);

Pixel sample format, stored in a structure with these fields.

Field NameDescription
UInt (default)Unsigned integer data
IntTwo's complement signed integer data
IEEEFPIEEE floating point data

MATLAB does not support the formats Void, ComplexInt, and ComplexIEEEFP.

Example: setTag(t,'SampleFormat',Tiff.SampleFormat.IEEEFP);

SGIL codec data format, stored in a structure with these fields.

Field NameDescription
FloatSingle precision samples.
Bits8uint8 samples (read-only).

Setting the SGILogDataFmt to Float or Bits8 implies a SamplesPerPixel value of 3 for LogLuv images and a value of 1 for LogL images.

You can set the SGILogDataFmt tag only once per instance for a LogL/LogLuv TIFF image object.

Use the following code to create a Tiff object, set the SGIL data format, and then read the image data.

tiffobj = Tiff('example.tif','r');
setDirectory(tiffobj,3); % image three is a LogLuv image
imdata = read(tiffobj);

Example: setTag(t,'SGILogDataFmt',Tiff.SGILogDataFmt.Float);

Type of the image, stored in a structure with these fields.

Field NameDescription
DefaultDefault value for single image file or first image.
ReducedImageThe image is a single image of a multiimage (or multipage) file.
PageUnassociated alpha data.
MaskThe image is a transparency mask for another image in the file. The photometric interpretation value must be Photometric.Mask.

Example: setTag(t,'SubFileType',Tiff.SubFileType.Mask);

TIFF tag IDs that MATLAB supports, stored in a structure with these fields.

Field NameValue

For a complete list of tag names and their corresponding tag IDs, type Tiff.TagID in the Command Window.

Use this property to specify a tag when you are using the setTag function. For example, Tiff.TagID.ImageWidth returns the ID of the ImageWidth tag. To get a list of all supported tags, use the Tiff.getTagNames function.

Example: setTag(t,Tiff.TagID.ImageWidth,300);

Thresholding technique, stored in a structure with these fields.

Field Name

Use this tag to specify which algorithm to use when converting pixels from grayscale to black and white.

Example: setTag(t,'Thresholding',Tiff.Thresholding.HalfTone);

Position of chrominance samples relative to luminance samples, stored in a structure with these fields.

Field NameDescription
CenteredSpecify for compatibility with industry standards, such as PostScript® Level 2.
CositedSpecify for compatibility with most digital video standards, such as CCIR Recommendation 601-1.

Example: setTag(t,'YCbCrPositioning',Tiff.YCbCrPositioning.Centered);

Object Functions

A TIFF file is made up of one or more image file directories (IFDs). An IFD contains image data and its associated metadata. IFDs can contain subIFDs, which also contain image data and metadata. When you open a TIFF file for reading, the Tiff object makes the first IFD in the file the current IFD. The Tiff object functions operate on the current IFD.

expand all

readRead entire TIFF image
readEncodedStripRead data from specified strip
readEncodedTileRead data from specified tile
readRGBAImageRead image using RGBA interface
readRGBAStripRead strip data using RGBA interface
readRGBATileRead tile data using RGBA interface
closeClose Tiff object
writeWrite entire image
writeEncodedStripWrite data to specified strip
writeEncodedTileWrite data to specified tile
closeClose Tiff object
getTagValue of specified tag
setTagSet value of tag
Tiff.getTagNamesList of recognized TIFF tags
currentDirectoryReturn index of current IFD
lastDirectoryDetermine if current IFD is last in file
nextDirectoryMake next IFD the current IFD
setDirectoryMake specified IFD the current IFD
setSubDirectoryMake subIFD the current IFD
rewriteDirectoryWrite modified metadata to existing IFD
writeDirectoryCreate new IFD and make it current IFD
isTiledDetermine if image is tiled
computeTileIndex number of tile containing specified coordinates
numberOfTilesTotal number of tiles in image
computeStripIndex number of strip containing specified coordinate
numberOfStripsTotal number of strips in image
getVersionLibTIFF library version


collapse all

Create a new file called myfile.tif. To run this example, you must have write access to the folder.

t = Tiff('myfile.tif','w');

Close the Tiff object.


For a dataset with color and alpha channels, set the Tiff tags and then write the data to a file.

Create an array of data, data, that contains color channels and an alpha channel.

rgb = imread('example.tif');
numrows = size(rgb,1);
numcols = size(rgb,2);
alpha = 255*ones([numrows numcols], 'uint8');
data = cat(3,rgb,alpha);

Create a Tiff object.

t = Tiff('myfile.tif','w');

Set the Tiff tags and specify the value of the ExtraSamples tag because the data contains the alpha channel in addition to the color channels.


Write the data to the TIFF file and close the Tiff object.


Write RGB image data to a TIFF file as an YCbCr/JPEG image.

Get RGB data.

rgb = imread('example.tif');

Create a Tiff object, t, and set the tags. Specify that the input data is RGB using the JPEGColorMode tag.

t = Tiff('myfile.tif','w');
setTag(t,'YCbCrSubSampling',[2 2]);

Write the data to the TIFF file and close the Tiff object.


Version History

Introduced in R2009b

expand all