0
# Image Operations
1

2
Core TIFF and BigTIFF image reading and writing functionality with comprehensive format support, multi-page document handling, and advanced features like tiled images and extensive color space support.
3

4
## Capabilities
5

6
### TIFF Image Reading
7

8
Reads TIFF and BigTIFF files with comprehensive format support including multi-page documents, various compression algorithms, and advanced features like tiled images.
9

10
```java { .api }
11
/**
12
 * Main TIFF/BigTIFF image reader with comprehensive format support
13
 */
14
class TIFFImageReader extends ImageReader {
15
    /**
16
     * Get the number of images in the TIFF file
17
     * @param allowSearch whether to search the entire file if necessary
18
     * @return number of images/pages in the file
19
     */
20
    public int getNumImages(boolean allowSearch);
21
    
22
    /**
23
     * Get the width of the specified image
24
     * @param imageIndex zero-based image index
25
     * @return image width in pixels
26
     */
27
    public int getWidth(int imageIndex);
28
    
29
    /**
30
     * Get the height of the specified image  
31
     * @param imageIndex zero-based image index
32
     * @return image height in pixels
33
     */
34
    public int getHeight(int imageIndex);
35
    
36
    /**
37
     * Get the raw image type specifier for the image
38
     * @param imageIndex zero-based image index
39
     * @return ImageTypeSpecifier representing the raw image format
40
     */
41
    public ImageTypeSpecifier getRawImageType(int imageIndex);
42
    
43
    /**
44
     * Get all supported image types for reading
45
     * @param imageIndex zero-based image index
46
     * @return Iterator of supported ImageTypeSpecifier objects
47
     */
48
    public Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex);
49
    
50
    /**
51
     * Read the specified image as a BufferedImage
52
     * @param imageIndex zero-based image index
53
     * @param param read parameters (can be null)
54
     * @return BufferedImage containing the image data
55
     */
56
    public BufferedImage read(int imageIndex, ImageReadParam param);
57
    
58
    /**
59
     * Check if raster reading is supported (always returns true)
60
     * @return true - raster reading is supported
61
     */
62
    public boolean canReadRaster();
63
    
64
    /**
65
     * Read the specified image as a Raster
66
     * @param imageIndex zero-based image index  
67
     * @param param read parameters (can be null)
68
     * @return Raster containing the raw image data
69
     */
70
    public Raster readRaster(int imageIndex, ImageReadParam param);
71
    
72
    /**
73
     * Check if the image uses tiling
74
     * @param imageIndex zero-based image index
75
     * @return true if the image is tiled
76
     */
77
    public boolean isImageTiled(int imageIndex);
78
    
79
    /**
80
     * Get tile width for tiled images
81
     * @param imageIndex zero-based image index
82
     * @return tile width in pixels
83
     */
84
    public int getTileWidth(int imageIndex);
85
    
86
    /**
87
     * Get tile height for tiled images
88
     * @param imageIndex zero-based image index
89
     * @return tile height in pixels
90
     */
91
    public int getTileHeight(int imageIndex);
92
    
93
    /**
94
     * Read a specific tile as BufferedImage
95
     * @param imageIndex zero-based image index
96
     * @param tileX tile X coordinate
97
     * @param tileY tile Y coordinate
98
     * @return BufferedImage containing the tile data
99
     */
100
    public BufferedImage readTile(int imageIndex, int tileX, int tileY);
101
    
102
    /**
103
     * Read a specific tile as Raster
104
     * @param imageIndex zero-based image index
105
     * @param tileX tile X coordinate
106
     * @param tileY tile Y coordinate
107
     * @return Raster containing the tile data
108
     */
109
    public Raster readTileRaster(int imageIndex, int tileX, int tileY);
110
    
111
    /**
112
     * Get TIFF-specific image metadata
113
     * @param imageIndex zero-based image index
114
     * @return TIFFImageMetadata containing TIFF tags and metadata
115
     */
116
    public IIOMetadata getImageMetadata(int imageIndex);
117
    
118
    /**
119
     * Get TIFF-specific stream metadata
120
     * @return TIFFStreamMetadata containing stream-level metadata
121
     */
122
    public IIOMetadata getStreamMetadata();
123
}
124
```
125

126
**Usage Examples:**
127

128
```java
129
import javax.imageio.ImageIO;
130
import javax.imageio.ImageReader;
131
import java.awt.image.BufferedImage;
132
import java.io.File;
133

134
// Reading a single TIFF image
135
BufferedImage image = ImageIO.read(new File("example.tiff"));
136

137
// Reading multi-page TIFF with explicit reader
138
ImageReader reader = ImageIO.getImageReadersByFormatName("TIFF").next();
139
reader.setInput(ImageIO.createImageInputStream(new File("multipage.tiff")));
140

141
int numImages = reader.getNumImages(true);
142
System.out.println("Found " + numImages + " pages");
143

144
for (int i = 0; i < numImages; i++) {
145
    BufferedImage page = reader.read(i);
146
    System.out.println("Page " + i + ": " + page.getWidth() + "x" + page.getHeight());
147
}
148

149
reader.dispose();
150

151
// Reading tiled TIFF
152
reader = ImageIO.getImageReadersByFormatName("TIFF").next();
153
reader.setInput(ImageIO.createImageInputStream(new File("tiled.tiff")));
154

155
if (reader.isImageTiled(0)) {
156
    int tileWidth = reader.getTileWidth(0);
157
    int tileHeight = reader.getTileHeight(0);
158
    BufferedImage firstTile = reader.readTile(0, 0, 0);
159
}
160

161
reader.dispose();
162
```
163

164
### TIFF Image Writing
165

166
Writes TIFF and BigTIFF files with support for various compression algorithms, multi-page documents, and comprehensive metadata preservation.
167

168
```java { .api }
169
/**
170
 * Main TIFF/BigTIFF image writer with multi-page support
171
 */
172
class TIFFImageWriter extends ImageWriter {
173
    /**
174
     * Set the output destination for writing
175
     * @param output ImageOutputStream, File, or other supported output
176
     */
177
    public void setOutput(Object output);
178
    
179
    /**
180
     * Write a single image with optional metadata
181
     * @param streamMetadata stream-level metadata (can be null)
182
     * @param image IIOImage containing image data and metadata
183
     * @param param write parameters for compression settings
184
     */
185
    public void write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param);
186
    
187
    /**
188
     * Get default image metadata for the specified image type
189
     * @param imageType image type specifier
190
     * @param param write parameters
191
     * @return default TIFFImageMetadata instance
192
     */
193
    public IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param);
194
    
195
    /**
196
     * Convert metadata from another format to TIFF format
197
     * @param inData input metadata
198
     * @param imageType target image type
199
     * @param param write parameters
200
     * @return converted TIFFImageMetadata
201
     */
202
    public IIOMetadata convertImageMetadata(IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param);
203
    
204
    /**
205
     * Get default stream metadata
206
     * @param param write parameters
207
     * @return default TIFFStreamMetadata instance
208
     */
209
    public IIOMetadata getDefaultStreamMetadata(ImageWriteParam param);
210
    
211
    /**
212
     * Convert stream metadata to TIFF format
213
     * @param inData input stream metadata
214
     * @param param write parameters
215
     * @return converted TIFFStreamMetadata
216
     */
217
    public IIOMetadata convertStreamMetadata(IIOMetadata inData, ImageWriteParam param);
218
    
219
    /**
220
     * Get default write parameters (returns TIFFImageWriteParam)
221
     * @return TIFFImageWriteParam with default settings
222
     */
223
    public ImageWriteParam getDefaultWriteParam();
224
    
225
    /**
226
     * Check if sequence writing is supported (always returns true)
227
     * @return true - multi-page writing is supported
228
     */
229
    public boolean canWriteSequence();
230
    
231
    /**
232
     * Prepare for writing a multi-page document
233
     * @param streamMetadata stream metadata for the document
234
     */
235
    public void prepareWriteSequence(IIOMetadata streamMetadata);
236
    
237
    /**
238
     * Write a page to the multi-page sequence
239
     * @param image IIOImage containing page data and metadata
240
     * @param param write parameters
241
     */
242
    public void writeToSequence(IIOImage image, ImageWriteParam param);
243
    
244
    /**
245
     * Finish writing the multi-page document
246
     */
247
    public void endWriteSequence();
248
}
249
```
250

251
**Usage Examples:**
252

253
```java
254
import javax.imageio.ImageIO;
255
import javax.imageio.ImageWriter;
256
import javax.imageio.IIOImage;
257
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageWriteParam;
258
import java.awt.image.BufferedImage;
259
import java.io.File;
260

261
// Writing a single TIFF image
262
BufferedImage image = // ... create or load image
263
ImageIO.write(image, "TIFF", new File("output.tiff"));
264

265
// Writing with compression
266
ImageWriter writer = ImageIO.getImageWritersByFormatName("TIFF").next();
267
writer.setOutput(ImageIO.createImageOutputStream(new File("compressed.tiff")));
268

269
TIFFImageWriteParam writeParam = (TIFFImageWriteParam) writer.getDefaultWriteParam();
270
writeParam.setCompressionMode(ImageWriteParam.MODE_EXPLICIT);
271
writeParam.setCompressionType("LZW");
272

273
writer.write(null, new IIOImage(image, null, null), writeParam);
274
writer.dispose();
275

276
// Writing multi-page TIFF
277
writer = ImageIO.getImageWritersByFormatName("TIFF").next();
278
writer.setOutput(ImageIO.createImageOutputStream(new File("multipage.tiff")));
279

280
writer.prepareWriteSequence(null);
281

282
BufferedImage[] pages = // ... array of images
283
for (BufferedImage page : pages) {
284
    writer.writeToSequence(new IIOImage(page, null, null), writeParam);
285
}
286

287
writer.endWriteSequence();
288
writer.dispose();
289
```
290

291
### Service Provider Registration
292

293
The plugin automatically registers service providers with Java's ImageIO framework, enabling automatic format detection and plugin selection.
294

295
```java { .api }
296
/**
297
 * Standard TIFF image reading service provider
298
 */
299
class TIFFImageReaderSpi extends ImageReaderSpi {
300
    public TIFFImageReaderSpi();
301
    
302
    /**
303
     * Test if the input source contains TIFF format data
304
     * @param source input source (ImageInputStream, File, etc.)
305
     * @return true if source contains TIFF data
306
     */
307
    public boolean canDecodeInput(Object source);
308
    
309
    /**
310
     * Create a new TIFFImageReader instance
311
     * @param extension optional extension object
312
     * @return new TIFFImageReader instance
313
     */
314
    public ImageReader createReaderInstance(Object extension);
315
    
316
    /**
317
     * Get human-readable description of the provider
318
     * @param locale locale for localization
319
     * @return description string
320
     */
321
    public String getDescription(Locale locale);
322
}
323

324
/**
325
 * Standard TIFF image writing service provider
326
 */
327
class TIFFImageWriterSpi extends ImageWriterSpi {
328
    public TIFFImageWriterSpi();
329
    
330
    /**
331
     * Test if the image type can be encoded to TIFF
332
     * @param type image type specifier
333
     * @return true if type can be encoded
334
     */
335
    public boolean canEncodeImage(ImageTypeSpecifier type);
336
    
337
    /**
338
     * Create a new TIFFImageWriter instance
339
     * @param extension optional extension object  
340
     * @return new TIFFImageWriter instance
341
     */
342
    public ImageWriter createWriterInstance(Object extension);
343
    
344
    /**
345
     * Get human-readable description of the provider
346
     * @param locale locale for localization
347
     * @return description string
348
     */
349
    public String getDescription(Locale locale);
350
}
351

352
/**
353
 * BigTIFF format reading service provider (for files >4GB)
354
 */
355
class BigTIFFImageReaderSpi extends ImageReaderSpi {
356
    public BigTIFFImageReaderSpi();
357
    
358
    /**
359
     * Test if the input source contains BigTIFF format data
360
     * @param source input source
361
     * @return true if source contains BigTIFF data
362
     */
363
    public boolean canDecodeInput(Object source);
364
    
365
    /**
366
     * Create a new TIFFImageReader instance for BigTIFF
367
     * @param extension optional extension object
368
     * @return new TIFFImageReader instance
369
     */
370
    public ImageReader createReaderInstance(Object extension);
371
    
372
    /**
373
     * Get human-readable description of the provider
374
     * @param locale locale for localization
375
     * @return description string
376
     */
377
    public String getDescription(Locale locale);
378
}
379

380
/**
381
 * BigTIFF format writing service provider
382
 */
383
class BigTIFFImageWriterSpi extends ImageWriterSpi {
384
    public BigTIFFImageWriterSpi();
385
    
386
    /**
387
     * Test if the image type can be encoded to BigTIFF
388
     * @param type image type specifier
389
     * @return true if type can be encoded
390
     */
391
    public boolean canEncodeImage(ImageTypeSpecifier type);
392
    
393
    /**
394
     * Create a new TIFFImageWriter instance for BigTIFF
395
     * @param extension optional extension object
396
     * @return new TIFFImageWriter instance
397
     */
398
    public ImageWriter createWriterInstance(Object extension);
399
    
400
    /**
401
     * Get human-readable description of the provider
402
     * @param locale locale for localization
403
     * @return description string
404
     */
405
    public String getDescription(Locale locale);
406
}
407
```
408

409
## Supported Image Formats
410

411
The plugin supports a comprehensive range of TIFF image types and formats:
412

413
- **Bi-level**: 1-bit black and white images
414
- **Grayscale**: 1-16 bits per pixel grayscale images
415
- **Palette**: Color-mapped images with up to 256 colors
416
- **RGB**: 8-16 bits per component RGB images
417
- **RGBA**: RGB with alpha channel support
418
- **CMYK**: 8-16 bits per component CMYK images
419
- **YCbCr**: YUV color space images
420
- **CIE L*a*b**: CIE Lab color space images
421

422
## Advanced Features
423

424
- **Multi-page documents**: Support for multiple images in a single TIFF file
425
- **Tiled images**: Efficient access to large images through tiling
426
- **BigTIFF support**: Files larger than 4GB with 64-bit addressing
427
- **ICC color profiles**: Embedded color management support
428
- **Extensive metadata**: TIFF tags, EXIF, IPTC, and XMP metadata preservation
429
- **Alpha channels**: Full transparency support
430
- **Planar configuration**: Support for both interleaved and planar color arrangements