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.6.0.
Creation
Description
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
andTileHeight
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,
|
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,
|
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 R2009bR2024a: 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.
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)