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^® supports LibTIFF version 4.1.0. For copyright information on the LibTIFF library, see the libtiffcopyright.txt file.

Creation

Syntax

obj = Tiff(filename)

obj = Tiff(filename,mode)

Description

example

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

example

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

Input Arguments

expand all

`filename` — Name of file
character vector | string scalar

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

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

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

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

`ImageWidth`	`Compression`
`ImageLength`	`PlanarConfiguration`
`BitsPerSample`	`Photometric`
`SamplesPerPixel`

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.

`Compression` — Scheme to compress image data
structure

Scheme to compress image data, stored in 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, stored in 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, stored in a structure with these fields.

Field Name Description

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 ensures that a zero nibble precedes an EOL sequence by 1 byte. For example, `xxxx-0000 0000-0001`.

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

`InkSet` — Separated image ink set
structure

Separated image ink set, stored in 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 `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, stored in 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 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);

`Orientation` — Visual orientation of image data
structure

Visual orientation of the image data, stored in 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 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);

`Photometric` — Color space of image data
structure

Color space of image data, stored in 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, stored in 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, stored in 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, the following 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, stored in 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, and ComplexIEEEFP.

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

`SGILogDataFmt` — `SGIL` codec data format
structure

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

Field Name	Description
`Float`	Single precision samples.
`Bits8`	`uint8` 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
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, stored in 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 multiimage (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, stored in 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 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` — Thresholding technique
structure

Thresholding technique, stored in a structure with these fields.

Field Name
`BiLevel`
`HalfTone`
`ErrorDiffuse`

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

`YCbCrPositioning` — Position of chrominance samples
structure

Position of chrominance samples relative to luminance samples, stored in 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.

expand all

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

collapse all

Create New TIFF File Using Tiff object

Open Live Script

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.

close(t);

Write Tiff Image with Color and Alpha Channel Data

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

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

Open Live Script

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,'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);

Documentation

Tiff

Description

Creation

Syntax

Description

Input Arguments

`filename` — Name of file
character vector | string scalar

`mode` — File access type
`'r'` (default) | `'w'` | `'w8'` | `'a'` | `'r+'`

Properties

`Compression` — Scheme to compress image data
structure

`ExtraSamples` — Extra channel description
structure

`Group3Options` — Group 3 Fax compression options
structure

`InkSet` — Separated image ink set
structure

`JPEGColorMode` — Color mode
structure

`Orientation` — Visual orientation of image data
structure

`Photometric` — Color space of image data
structure

`PlanarConfiguration` — Storage configuration
structure

`ResolutionUnit` — Resolution units
structure

`SampleFormat` — Pixel sample format
structure

`SGILogDataFmt` — `SGIL` codec data format
structure

`SubFileType` — Type of image
structure

`TagID` — TIFF tag IDs
structure

`Thresholding` — Thresholding technique
structure

`YCbCrPositioning` — Position of chrominance samples
structure

Object Functions

Read Image

Write Image

Set or Get Tags

Change Image File Directory (IFD)

Get Tile, Strip, or Library Information

Examples

Create New TIFF File Using Tiff object

Write Tiff Image with Color and Alpha Channel Data

Create YCbCr/JPEG image from RGB data

See Also

Topics

MATLAB Documentation

Support

Documentation

Tiff

Description

Creation

Syntax

Description

Input Arguments

filename — Name of file character vector | string scalar

mode — File access type 'r' (default) | 'w' | 'w8' | 'a' | 'r+'

Properties

Compression — Scheme to compress image data structure

ExtraSamples — Extra channel description structure

Group3Options — Group 3 Fax compression options structure

InkSet — Separated image ink set structure

JPEGColorMode — Color mode structure

Orientation — Visual orientation of image data structure

Photometric — Color space of image data structure

PlanarConfiguration — Storage configuration structure

ResolutionUnit — Resolution units structure

SampleFormat — Pixel sample format structure

SGILogDataFmt — SGIL codec data format structure

SubFileType — Type of image structure

TagID — TIFF tag IDs structure

Thresholding — Thresholding technique structure

YCbCrPositioning — Position of chrominance samples structure

Object Functions

Read Image

Write Image

Set or Get Tags

Change Image File Directory (IFD)

Get Tile, Strip, or Library Information

Examples

Create New TIFF File Using Tiff object

Write Tiff Image with Color and Alpha Channel Data

Create YCbCr/JPEG image from RGB data

See Also

Topics

MATLAB Documentation

Support

`filename` — Name of file
character vector | string scalar

`mode` — File access type
`'r'` (default) | `'w'` | `'w8'` | `'a'` | `'r+'`

`Compression` — Scheme to compress image data
structure

`ExtraSamples` — Extra channel description
structure

`Group3Options` — Group 3 Fax compression options
structure

`InkSet` — Separated image ink set
structure

`JPEGColorMode` — Color mode
structure

`Orientation` — Visual orientation of image data
structure

`Photometric` — Color space of image data
structure

`PlanarConfiguration` — Storage configuration
structure

`ResolutionUnit` — Resolution units
structure

`SampleFormat` — Pixel sample format
structure

`SGILogDataFmt` — `SGIL` codec data format
structure

`SubFileType` — Type of image
structure

`TagID` — TIFF tag IDs
structure

`Thresholding` — Thresholding technique
structure

`YCbCrPositioning` — Position of chrominance samples
structure