0
# Metadata Management
1

2
Complete TIFF metadata handling including image-level and stream-level metadata with support for standard TIFF tags, EXIF, IPTC, and XMP metadata preservation and manipulation.
3

4
## Capabilities
5

6
### TIFF Image Metadata
7

8
Container for TIFF image-level metadata including all TIFF tags, EXIF data, and custom metadata fields.
9

10
```java { .api }
11
/**
12
 * TIFF image-level metadata container with standard format support
13
 */
14
class TIFFImageMetadata extends IIOMetadata {
15
    
16
    /** Scale factor used for rational values in metadata */
17
    public static final int RATIONAL_SCALE_FACTOR = 100000;
18
    
19
    /**
20
     * Create empty metadata instance
21
     */
22
    public TIFFImageMetadata();
23
    
24
    /**
25
     * Create metadata from TIFF Image File Directory (IFD)
26
     * @param ifd Directory containing TIFF tags and values
27
     */
28
    public TIFFImageMetadata(Directory ifd);
29
    
30
    /**
31
     * Create metadata from collection of entries
32
     * @param entries Collection of metadata entries
33
     */
34
    public TIFFImageMetadata(Collection<? extends Entry> entries);
35
    
36
    /**
37
     * Check if metadata is read-only
38
     * @return true if metadata cannot be modified
39
     */
40
    public boolean isReadOnly();
41
    
42
    /**
43
     * Set metadata from XML DOM tree
44
     * @param formatName metadata format name
45
     * @param root root node of DOM tree
46
     */
47
    public void setFromTree(String formatName, Node root);
48
    
49
    /**
50
     * Merge metadata from XML DOM tree
51
     * @param formatName metadata format name  
52
     * @param root root node of DOM tree to merge
53
     */
54
    public void mergeTree(String formatName, Node root);
55
    
56
    /**
57
     * Reset metadata to original state
58
     */
59
    public void reset();
60
    
61
    /**
62
     * Get TIFF field by tag number
63
     * @param tagNumber TIFF tag number (e.g., 256 for ImageWidth)
64
     * @return Object containing tag value, or null if not present
65
     */
66
    public Object getTIFFField(int tagNumber);
67
}
68
```
69

70
**Usage Examples:**
71

72
```java
73
import javax.imageio.ImageIO;
74
import javax.imageio.ImageReader;
75
import javax.imageio.metadata.IIOMetadata;
76
import com.twelvemonkeys.imageio.plugins.tiff.TIFFImageMetadata;
77
import java.io.File;
78

79
// Reading TIFF metadata
80
ImageReader reader = ImageIO.getImageReadersByFormatName("TIFF").next();
81
reader.setInput(ImageIO.createImageInputStream(new File("image.tiff")));
82

83
TIFFImageMetadata metadata = (TIFFImageMetadata) reader.getImageMetadata(0);
84

85
// Get specific TIFF tags
86
Integer width = (Integer) metadata.getTIFFField(256);      // ImageWidth
87
Integer height = (Integer) metadata.getTIFFField(257);     // ImageLength  
88
Integer compression = (Integer) metadata.getTIFFField(259); // Compression
89
String software = (String) metadata.getTIFFField(305);     // Software
90

91
System.out.println("Image: " + width + "x" + height);
92
System.out.println("Compression: " + compression);
93
System.out.println("Created with: " + software);
94

95
// Get metadata as XML tree
96
Node tree = metadata.getAsTree(TIFFImageMetadataFormat.SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME);
97

98
reader.dispose();
99

100
// Creating custom metadata for writing
101
TIFFImageMetadata customMetadata = new TIFFImageMetadata();
102

103
// Set metadata values (using XML tree manipulation)
104
IIOMetadataNode root = new IIOMetadataNode(TIFFImageMetadataFormat.SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME);
105
IIOMetadataNode softwareNode = new IIOMetadataNode("Software");
106
softwareNode.setAttribute("value", "My Application v1.0");
107
root.appendChild(softwareNode);
108

109
customMetadata.setFromTree(TIFFImageMetadataFormat.SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME, root);
110
```
111

112
### TIFF Stream Metadata
113

114
Container for TIFF stream-level metadata, primarily managing byte order configuration and global file properties.
115

116
```java { .api }
117
/**
118
 * TIFF stream-level metadata (byte order configuration)
119
 */
120
class TIFFStreamMetadata extends IIOMetadata {
121
    
122
    /** Standard stream metadata format name */
123
    public static final String SUN_NATIVE_STREAM_METADATA_FORMAT_NAME = 
124
        "com_sun_media_imageio_plugins_tiff_stream_1.0";
125
    
126
    /**
127
     * Create stream metadata with default big-endian byte order
128
     */
129
    public TIFFStreamMetadata();
130
    
131
    /**
132
     * Check if metadata is read-only (always returns false)
133
     * @return false - stream metadata is writable
134
     */
135
    public boolean isReadOnly();
136
    
137
    /**
138
     * Get metadata as XML DOM tree
139
     * @param formatName metadata format name
140
     * @return Node representing the metadata tree
141
     */
142
    public Node getAsTree(String formatName);
143
    
144
    /**
145
     * Merge metadata from XML DOM tree
146
     * @param formatName metadata format name
147
     * @param root root node of tree to merge
148
     */
149
    public void mergeTree(String formatName, Node root);
150
    
151
    /**
152
     * Reset metadata to default state
153
     */
154
    public void reset();
155
    
156
    /**
157
     * Configure stream byte order based on metadata and output stream
158
     * @param streamMetadata stream metadata containing byte order information
159
     * @param imageOutput target image output stream
160
     */
161
    public static void configureStreamByteOrder(IIOMetadata streamMetadata, ImageOutputStream imageOutput);
162
}
163
```
164

165
**Usage Examples:**
166

167
```java
168
import javax.imageio.ImageWriter;
169
import com.twelvemonkeys.imageio.plugins.tiff.TIFFStreamMetadata;
170

171
// Creating stream metadata for writing
172
ImageWriter writer = ImageIO.getImageWritersByFormatName("TIFF").next();
173
TIFFStreamMetadata streamMetadata = (TIFFStreamMetadata) writer.getDefaultStreamMetadata(null);
174

175
// Get stream metadata as XML tree
176
Node streamTree = streamMetadata.getAsTree(TIFFStreamMetadata.SUN_NATIVE_STREAM_METADATA_FORMAT_NAME);
177

178
// Use stream metadata when writing
179
writer.write(streamMetadata, new IIOImage(image, null, imageMetadata), writeParam);
180
```
181

182
### Metadata Format Descriptors
183

184
Format descriptors define the structure and validation rules for TIFF metadata in XML format.
185

186
```java { .api }
187
/**
188
 * Metadata format descriptor for TIFF image metadata
189
 */
190
class TIFFImageMetadataFormat extends IIOMetadataFormatImpl {
191
    
192
    /** Standard image metadata format name */
193
    public static final String SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME = 
194
        "com_sun_media_imageio_plugins_tiff_image_1.0";
195
    
196
    /**
197
     * Constructor for metadata format
198
     */
199
    public TIFFImageMetadataFormat();
200
    
201
    /**
202
     * Check if a node can appear for the specified image type
203
     * @param elementName name of the XML element
204
     * @param imageType image type specifier
205
     * @return true if node is valid for the image type
206
     */
207
    public boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType);
208
    
209
    /**
210
     * Get singleton instance of the format descriptor
211
     * @return singleton TIFFImageMetadataFormat instance
212
     */
213
    public static TIFFImageMetadataFormat getInstance();
214
}
215

216
/**
217
 * Metadata format descriptor for TIFF stream metadata
218
 */
219
class TIFFStreamMetadataFormat extends IIOMetadataFormatImpl {
220
    
221
    /** Standard stream metadata format name */
222
    public static final String SUN_NATIVE_STREAM_METADATA_FORMAT_NAME = 
223
        "com_sun_media_imageio_plugins_tiff_stream_1.0";
224
    
225
    /**
226
     * Get singleton instance of the format descriptor
227
     * @return singleton TIFFStreamMetadataFormat instance
228
     */
229
    public static TIFFStreamMetadataFormat getInstance();
230
}
231

232
/**
233
 * Alternative metadata format for compatibility
234
 */
235
class TIFFMedataFormat extends IIOMetadataFormatImpl {
236
    
237
    /** References the image metadata format name */
238
    public static final String SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME = 
239
        TIFFImageMetadataFormat.SUN_NATIVE_IMAGE_METADATA_FORMAT_NAME;
240
    
241
    /**
242
     * Get singleton instance of the format descriptor
243
     * @return singleton TIFFMedataFormat instance
244
     */
245
    public static TIFFMedataFormat getInstance();
246
}
247
```
248

249
## Common TIFF Tags
250

251
The plugin supports reading and writing all standard TIFF tags. Here are the most commonly used ones:
252

253
### Basic Image Information
254
- **256 (ImageWidth)**: Image width in pixels
255
- **257 (ImageLength)**: Image height in pixels
256
- **258 (BitsPerSample)**: Number of bits per color component
257
- **259 (Compression)**: Compression scheme used
258
- **262 (PhotometricInterpretation)**: Color space interpretation
259
- **273 (StripOffsets)**: Byte offsets of image data strips
260
- **277 (SamplesPerPixel)**: Number of color components
261
- **278 (RowsPerStrip)**: Number of rows per strip
262

263
### Color and Display
264
- **320 (ColorMap)**: Color palette for palette images
265
- **338 (ExtraSamples)**: Description of extra samples (alpha channel)
266
- **529 (YCbCrCoefficients)**: YCbCr color space coefficients
267
- **530 (YCbCrSubSampling)**: YCbCr subsampling factors
268

269
### Metadata and Documentation
270
- **270 (ImageDescription)**: Image description or caption
271
- **271 (Make)**: Camera/scanner manufacturer
272
- **272 (Model)**: Camera/scanner model
273
- **305 (Software)**: Software used to create the image
274
- **306 (DateTime)**: Creation date and time
275
- **315 (Artist)**: Person who created the image
276
- **33432 (Copyright)**: Copyright notice
277

278
### Resolution and Physical Properties
279
- **282 (XResolution)**: Horizontal resolution
280
- **283 (YResolution)**: Vertical resolution  
281
- **296 (ResolutionUnit)**: Resolution units (inches, centimeters)
282

283
### Advanced Features
284
- **322 (TileWidth)**: Tile width for tiled images
285
- **323 (TileLength)**: Tile height for tiled images
286
- **324 (TileOffsets)**: Byte offsets of tile data
287
- **325 (TileByteCounts)**: Byte counts for each tile
288

289
## Metadata Preservation
290

291
```java
292
// Reading image with metadata preservation
293
ImageReader reader = ImageIO.getImageReadersByFormatName("TIFF").next();
294
reader.setInput(ImageIO.createImageInputStream(new File("input.tiff")));
295

296
BufferedImage image = reader.read(0);
297
TIFFImageMetadata originalMetadata = (TIFFImageMetadata) reader.getImageMetadata(0);
298
reader.dispose();
299

300
// Writing image with preserved metadata
301
ImageWriter writer = ImageIO.getImageWritersByFormatName("TIFF").next();
302
writer.setOutput(ImageIO.createImageOutputStream(new File("output.tiff")));
303

304
writer.write(null, new IIOImage(image, null, originalMetadata), null);
305
writer.dispose();
306
```
307

308
## Extended Metadata Support
309

310
The plugin automatically handles various embedded metadata formats:
311

312
- **EXIF**: Camera settings and shooting information
313
- **IPTC**: International Press Telecommunications Council metadata
314
- **XMP**: Extensible Metadata Platform (Adobe) metadata
315
- **ICC Profiles**: Color management profiles
316
- **Custom Tags**: Application-specific metadata tags
317

318
These are automatically preserved during read/write operations and can be accessed through the standard TIFF tag interface or specialized metadata parsers.