Tiff

MATLAB Gateway to LibTIFF library routines

Description

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^® uses LibTIFF version 4.7.0.

Creation

Syntax

obj = Tiff(filename)

obj = Tiff(filename,mode)

Description

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

filename — Name of file

string scalar | character vector

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

Example: "myfile.tif"

mode — File access type

"r" (default) | "w" | "w8" | "a" | "r+"

File access type, specified as one of these values.

Parameter	Description
"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 image file directory (IFD) in the file for writing subsequent data. This IFD has all the default values specified in TIFF Revision 6.0.

Properties

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 RGB color space.

t = Tiff("myfile.tif","w");
setTag(t,"Photometric",Tiff.Photometric.RGB)

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

• ImageLength

• ImageWidth

• Photometric

Depending on the type of data in the image, you may also be required to set other tags. These tags commonly include:

• Compression

• BitsPerSample

• SamplesPerPixel

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

• Stripped layout — Set the RowsPerStrip tag.

• Tiled layout — Set the TileWidth and TileHeight tags.

Compression — Scheme to compress image data

structure

Scheme to compress image data, returned as a structure with these fields.

Field Name
None
CCITTRLE (Read-only)
CCITTFax3
CCITTFax4
LZW
OJPEG
JPEG
AdobeDeflate
...

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)

ExtraSamples — Extra channel description

structure

Extra channel description, returned as a structure with these fields.

Field Name	Description
Unspecified	Unspecified data
AssociatedAlpha	Associated alpha (premultiplied)
UnassociatedAlpha	Unassociated 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)

Group3Options — Group 3 Fax compression options

structure

Group 3 Fax compression options, returned as a structure with these fields.

Field Name	Description
Encoding2D	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.
Uncompressed	Bit 1 is 1. This value specifies an uncompressed mode when encoding.
FillBits	Bit 2 is 1. Add fill bits as necessary before the EOL codes, such that EOL always ends on a byte boundary. This convention 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 three bits.

Example: setTag(t,"Group3Options",Tiff.Group3Options.Uncompressed)

InkSet — Separated image ink set

structure

Separated image ink set, returned as a structure with these fields.

Field Name	Description
CMYK	Order 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.
MultiInk	Any ordering other than CMYK. Consult the TIFF specification for the 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)

JPEGColorMode — Color mode

structure

Color mode, returned as a structure with these fields.

Field Name	Description
Raw (default)	Keep input as separate Y, Cb, and Cr matrices.
RGB	Convert RGB input to YCbCr.

Do not use this property to read YCbCr images 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)

Orientation — Visual orientation of image data

structure

Visual orientation of the image data, returned as a structure with these fields.

Field Name
TopLeft
TopRight
BottomRight
BottomLeft
LeftTop
RightTop
RightBottom
LeftBottom

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 tag is for informational purposes only and does not affect how MATLAB reads or writes the image data.

Example: setTag(t,"Orientation",Tiff.Orientation.TopLeft)

Photometric — Color space of image data

structure

Color space of image data, returned as a structure with these fields.

Field Name
MinIsWhite
MinIsBlack
RGB
Palette
Mask
Separated (CMYK)
YCbCr
CIELab
ICCLab
ITULab
LogL
LogLUV
CFA
LinearRaw

Example: setTag(t,"Photometric",Tiff.Photometric.RGB)

PlanarConfiguration — Storage configuration

structure

Storage configuration of the image component values, returned as a structure with these fields.

Field Name	Description
Chunky	Store 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.
Separate	Store 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)

ResolutionUnit — Resolution units

structure

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

Field Name	Description
None	Default value.
Inch	Assign unit inches for values contained in XResolution and YResolution tags.
Centimeter	Assign unit centimeters for values contained in XResolution and YResolution tags.

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

setTag(t,"ResolutionUnit",Tiff.ResolutionUnit.Inch)
setTag(t,"XResolution",300)
setTag(t,"YResolution",300)

Example: setTag(t,"ResolutionUnit",Tiff.ResolutionUnit.Inch)

SampleFormat — Pixel sample format

structure

Pixel sample format, returned as a structure with these fields.

Field Name	Description
UInt (default)	Unsigned integer data
Int	Two's complement signed integer data
IEEEFP	IEEE floating-point data

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

Example: setTag(t,"SampleFormat",Tiff.SampleFormat.IEEEFP)

SGILogDataFmt — SGIL codec data format

structure

SGIL codec data format, returned as a structure with these fields.

Field Name	Description
Float	Single-precision samples
Bits8	uint8 samples (read-only)

Setting the SGILogDataFmt tag 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 LogLuv or LogL TIFF image object.

Use this 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 3 is a LogLuv image
setTag(tiffobj,"SGILogDataFmt",Tiff.SGILogDataFmt.Float)
imdata = read(tiffobj);

Example: setTag(t,"SGILogDataFmt",Tiff.SGILogDataFmt.Float)

SubFileType — Type of image

structure

Type of the image, returned as a structure with these fields.

Field Name	Description
Default	Default value for single image file or first image.
ReducedImage	The image is a single image of a multi-image (or multipage) file.
Page	Unassociated alpha data.
Mask	The 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)

TagID — TIFF tag IDs

structure

TIFF tag IDs that MATLAB supports, returned as a structure with these fields.

Field Name	Value
SubFileType	254
ImageWidth	256
ImageLength	257
BitsPerSample	258
Compression	259
Photometric	262
Thresholding	263
FillOrder	266
...	...

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 use 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 — Thresholding technique

structure

Thresholding technique, returned as a structure with these fields.

Field Name
BiLevel
HalfTone
ErrorDiffuse

This property describes which algorithm to use when converting pixels from grayscale to black and white.

Example: setTag(t,"Thresholding",Tiff.Thresholding.HalfTone)

YCbCrPositioning — Position of chrominance samples

structure

Position of chrominance samples relative to luminance samples, returned as a structure with these fields.

Field Name	Description
Centered	Specify for compatibility with industry standards, such as PostScript® Level 2.
Cosited	Specify 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.

Read Image

read	Read entire TIFF image
readEncodedStrip	Read data from specified strip
readEncodedTile	Read data from specified tile
readRGBAImage	Read image using RGBA interface
readRGBAStrip	Read strip data using RGBA interface
readRGBATile	Read tile data using RGBA interface
close	Close Tiff object

Write Image

write	Write entire image
writeEncodedStrip	Write data to specified strip
writeEncodedTile	Write data to specified tile
close	Close Tiff object

Set or Get Tags

getTag	Value of specified tag
setTag	Set value of tag
Tiff.getTagNames	List of recognized TIFF tags

Change Image File Directory (IFD)

currentDirectory	Return index of current IFD
lastDirectory	Determine if current IFD is last in file
nextDirectory	Make next IFD the current IFD
setDirectory	Make specified IFD the current IFD
setSubDirectory	Make subIFD the current IFD
rewriteDirectory	Write modified metadata to existing IFD
writeDirectory	Create new IFD and make it current IFD

Get Tile, Strip, or Library Information

isTiled	Determine if image is tiled
computeTile	Index number of tile containing specified coordinates
numberOfTiles	Total number of tiles in image
computeStrip	Index number of strip containing specified coordinate
numberOfStrips	Total number of strips in image
getVersion	LibTIFF library version

Examples

Create New TIFF File Using Tiff Object

Create a new file called myfile.tif.

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

Close the Tiff object.

close(t)

Write Tiff Image with Color and Alpha Channel Data

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

Create an array, 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.

setTag(t,"Photometric",Tiff.Photometric.RGB)
setTag(t,"Compression",Tiff.Compression.None)
setTag(t,"BitsPerSample",8)
setTag(t,"SamplesPerPixel",4)
setTag(t,"SampleFormat",Tiff.SampleFormat.UInt)
setTag(t,"ExtraSamples",Tiff.ExtraSamples.Unspecified)
setTag(t,"ImageLength",numrows)
setTag(t,"ImageWidth",numcols)
setTag(t,"TileLength",32)
setTag(t,"TileWidth",32)
setTag(t,"PlanarConfiguration",Tiff.PlanarConfiguration.Chunky)

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

write(t,data)
close(t)

Create YCbCr/JPEG Image from RGB Data

Write RGB image data to a TIFF file as a 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,"Photometric",Tiff.Photometric.YCbCr)
setTag(t,"Compression",Tiff.Compression.JPEG)
setTag(t,"YCbCrSubSampling",[2 2])
setTag(t,"BitsPerSample",8)
setTag(t,"SamplesPerPixel",3)
setTag(t,"SampleFormat",Tiff.SampleFormat.UInt)
setTag(t,"ImageLength",size(rgb,1))
setTag(t,"ImageWidth",size(rgb,2))
setTag(t,"TileLength",32)
setTag(t,"TileWidth",32)
setTag(t,"PlanarConfiguration",Tiff.PlanarConfiguration.Chunky)
setTag(t,"JPEGColorMode",Tiff.JPEGColorMode.RGB)
setTag(t,"JPEGQuality",75)

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

write(t,rgb)
close(t)

Version History

Introduced in R2009b

R2024b: LibTIFF library upgraded to version 4.7.0

The LibTIFF library is upgraded to version 4.7.0.

R2024a: LibTIFF library upgraded to version 4.6.0

The LibTIFF library is upgraded to version 4.6.0.

R2023b: LibTIFF library upgraded to version 4.5.0

The LibTIFF library is upgraded to version 4.5.0.

R2022b: LibTIFF library upgraded to version 4.4.0

The LibTIFF library is upgraded to version 4.4.0.

R2021b: LibTIFF library upgraded to version 4.2.0

The LibTIFF library is upgraded to version 4.2.0.

R2020b: Read images from Aperio SVS and TIFF files containing JPEG 2000 compression

You can read Aperio SVS microscopy image files and TIFF image files with JPEG 2000 compression.

R2020b: LibTIFF library upgraded to version 4.1.0

The LibTIFF library is upgraded to version 4.1.0.

R2020a: Read and write values of Rational Polynomial Coefficients tag

You can read and write the values of the Rational Polynomial Coefficient (RPC) tag using the RPCCoefficientTag property of the Tiff object. For more information, see table 6 in Exporting to Images.

R2019b: LibTIFF library upgraded to version 4.0.10

The LibTIFF library is upgraded to version 4.0.10.

R2019b: Tiff object for writing certain TIFF files is not recommended

Writing TIFF images with certain combinations of photometric configuration and the number of samples per pixel is not recommended. The value of SamplesPerPixel must be equal to the sum of Photometric color channels and the value of ExtraSamples specified in the Tiff object.