0
# TwelveMonkeys ImageIO TIFF Plugin
1

2
A comprehensive Java ImageIO plugin that provides robust TIFF and BigTIFF format support for reading and writing Tagged Image File Format files. This plugin extends Java's ImageIO framework with advanced TIFF capabilities including multi-page documents, extensive compression options, and comprehensive metadata handling.
3

4
## Package Information
5

6
- **Package Name**: imageio-tiff
7
- **Package Type**: maven
8
- **Group ID**: com.twelvemonkeys.imageio
9
- **Artifact ID**: imageio-tiff
10
- **Language**: Java
11
- **Installation**: Add to pom.xml dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>com.twelvemonkeys.imageio</groupId>
16
    <artifactId>imageio-tiff</artifactId>
17
    <version>3.12.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
The plugin automatically registers with Java's ImageIO service provider interface, so no explicit imports are required for basic usage:
24

25
```java
26
import javax.imageio.ImageIO;
27
import java.awt.image.BufferedImage;
28
import java.io.File;
29
```
30

31
For advanced usage with plugin-specific features:
32

33
```java
34
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageReader;
35
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageWriter;
36
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageWriteParam;
37
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageMetadata;
38
import com.twelvemonkeys.imageio.plugins.tiff.TIFFStreamMetadata;
39
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageReaderSpi;
40
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageWriterSpi;
41
import com.twelvemonkeys.imageio.plugins.tiff.BigTIFFImageReaderSpi;
42
import com.twelvemonkeys.imageio.plugins.tiff.BigTIFFImageWriterSpi;
43
```
44

45
## Basic Usage
46

47
```java
48
import javax.imageio.ImageIO;
49
import java.awt.image.BufferedImage;
50
import java.io.File;
51
import java.io.IOException;
52

53
// Reading a TIFF file (automatic plugin selection)
54
BufferedImage image = ImageIO.read(new File("example.tiff"));
55

56
// Writing a TIFF file (automatic plugin selection)
57
BufferedImage image = // ... create or load image
58
ImageIO.write(image, "TIFF", new File("output.tiff"));
59

60
// Reading multi-page TIFF
61
ImageReader reader = ImageIO.getImageReadersByFormatName("TIFF").next();
62
reader.setInput(ImageIO.createImageInputStream(new File("multipage.tiff")));
63
int numImages = reader.getNumImages(true);
64
for (int i = 0; i < numImages; i++) {
65
    BufferedImage page = reader.read(i);
66
    // Process each page
67
}
68
reader.dispose();
69
```
70

71
## Architecture
72

73
The plugin is built around several key components that integrate seamlessly with Java's ImageIO framework:
74

75
- **Service Providers**: Automatic registration via `TIFFImageReaderSpi`, `TIFFImageWriterSpi`, `BigTIFFImageReaderSpi`, and `BigTIFFImageWriterSpi`
76
- **Core Readers/Writers**: `TIFFImageReader` and `TIFFImageWriter` handle all TIFF operations with comprehensive format support
77
- **Write Parameters**: `TIFFImageWriteParam` provides extensive compression and quality configuration options
78
- **Metadata System**: `TIFFImageMetadata` and `TIFFStreamMetadata` provide complete TIFF tag and metadata access
79
- **Format Support**: Handles baseline TIFF, BigTIFF (>4GB files), and extensive compression algorithms
80

81
## Capabilities
82

83
### Image Reading and Writing
84

85
Core TIFF/BigTIFF image reading and writing functionality with comprehensive format support, compression options, and multi-page document handling.
86

87
```java { .api }
88
// Primary reader/writer classes
89
class TIFFImageReader extends ImageReader;
90
class TIFFImageWriter extends ImageWriter;
91

92
// Service provider interfaces (auto-registered)
93
class TIFFImageReaderSpi extends ImageReaderSpi;
94
class TIFFImageWriterSpi extends ImageWriterSpi;
95
class BigTIFFImageReaderSpi extends ImageReaderSpi;
96
class BigTIFFImageWriterSpi extends ImageWriterSpi;
97
```
98

99
[Image Operations](./image-operations.md)
100

101
### Compression Configuration
102

103
Advanced compression settings and write parameters for optimizing TIFF output with support for 9 different compression algorithms including lossless and lossy options.
104

105
```java { .api }
106
class TIFFImageWriteParam extends ImageWriteParam {
107
    // Available compression types (string constants for setCompressionType()):
108
    // "None", "CCITT RLE", "CCITT T.4", "CCITT T.6", 
109
    // "LZW", "JPEG", "ZLib", "PackBits", "Deflate"
110
    
111
    public TIFFImageWriteParam();
112
    public float[] getCompressionQualityValues();
113
    public String[] getCompressionQualityDescriptions();
114
}
115
```
116

117
[Compression](./compression.md)
118

119
### Metadata Management
120

121
Complete TIFF metadata handling including image-level and stream-level metadata with support for standard TIFF tags, EXIF, IPTC, and XMP metadata.
122

123
```java { .api }
124
class TIFFImageMetadata extends IIOMetadata {
125
    public static final int RATIONAL_SCALE_FACTOR = 100000;
126
    
127
    public TIFFImageMetadata();
128
    public TIFFImageMetadata(Directory ifd);
129
    public TIFFImageMetadata(Collection<? extends Entry> entries);
130
    public Entry getTIFFField(int tagNumber);
131
    public void reset();
132
}
133

134
class TIFFStreamMetadata extends IIOMetadata {
135
    public static final String SUN_NATIVE_STREAM_METADATA_FORMAT_NAME = "com_sun_media_imageio_plugins_tiff_stream_1.0";
136
    
137
    public TIFFStreamMetadata();
138
    public void reset();
139
    public static void configureStreamByteOrder(IIOMetadata streamMetadata, ImageOutputStream imageOutput);
140
}
141
```
142

143
[Metadata](./metadata.md)
144

145
## Types
146

147
```java { .api }
148
// Core service provider interfaces
149
abstract class ImageReaderSpi {
150
    public abstract boolean canDecodeInput(Object source);
151
    public abstract ImageReader createReaderInstance(Object extension);
152
    public abstract String getDescription(Locale locale);
153
}
154

155
abstract class ImageWriterSpi {
156
    public abstract boolean canEncodeImage(ImageTypeSpecifier type);
157
    public abstract ImageWriter createWriterInstance(Object extension);
158
    public abstract String getDescription(Locale locale);
159
}
160

161
// ImageIO base classes
162
abstract class ImageReader {
163
    public abstract int getNumImages(boolean allowSearch);
164
    public abstract int getWidth(int imageIndex);
165
    public abstract int getHeight(int imageIndex);
166
    public abstract BufferedImage read(int imageIndex, ImageReadParam param);
167
    public abstract IIOMetadata getImageMetadata(int imageIndex);
168
}
169

170
abstract class ImageWriter {
171
    public abstract void write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param);
172
    public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param);
173
    public abstract ImageWriteParam getDefaultWriteParam();
174
}
175

176
abstract class ImageWriteParam {
177
    public void setCompressionMode(int mode);
178
    public void setCompressionType(String compressionType);
179
    public void setCompressionQuality(float quality);
180
}
181

182
abstract class IIOMetadata {
183
    public abstract boolean isReadOnly();
184
    public abstract Node getAsTree(String formatName);
185
    public abstract void setFromTree(String formatName, Node root);
186
}
187
```