Main Content

Tiff

MATLAB Gateway to LibTIFF library routines

expand all in page

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.6.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.

example

Input Arguments

expand all

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

Example: "myfile.tif"

File access type, specified as one of these values.

ParameterDescription
"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

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 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.

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)

Extra channel description, returned as 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, returned as a structure with these fields.

Field NameDescription
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)

Separated image ink set, returned as 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 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)

Color mode, returned as 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 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)

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)

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)

Storage configuration of the image component values, returned as 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, returned as 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, 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)

Pixel sample format, returned as 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, or ComplexIEEEFP.

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

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

Field NameDescription
FloatSingle-precision samples
Bits8uint8 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)

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

Field NameDescription
DefaultDefault value for single image file or first image.
ReducedImageThe image is a single image of a multi-image (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, returned as a structure with these fields.

Field NameValue
SubFileType254
ImageWidth256
ImageLength257
BitsPerSample258
Compression259
Photometric262
Thresholding263
FillOrder266
......

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 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)

Position of chrominance samples relative to luminance samples, returned as 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

Examples

collapse all

Open Live Script

Create a new file called myfile.tif.

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

Close the Tiff object.

close(t)
Open Live Script

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)
Open Live Script

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

expand all

See Also

Functions

Topics