001/* 002 * $RCSfile: TIFFTag.java,v $ 003 * 004 * 005 * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. 006 * 007 * Redistribution and use in source and binary forms, with or without 008 * modification, are permitted provided that the following conditions 009 * are met: 010 * 011 * - Redistribution of source code must retain the above copyright 012 * notice, this list of conditions and the following disclaimer. 013 * 014 * - Redistribution in binary form must reproduce the above copyright 015 * notice, this list of conditions and the following disclaimer in 016 * the documentation and/or other materials provided with the 017 * distribution. 018 * 019 * Neither the name of Sun Microsystems, Inc. or the names of 020 * contributors may be used to endorse or promote products derived 021 * from this software without specific prior written permission. 022 * 023 * This software is provided "AS IS," without a warranty of any 024 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND 025 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 026 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY 027 * EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL 028 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF 029 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS 030 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR 031 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, 032 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND 033 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR 034 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE 035 * POSSIBILITY OF SUCH DAMAGES. 036 * 037 * You acknowledge that this software is not designed or intended for 038 * use in the design, construction, operation or maintenance of any 039 * nuclear facility. 040 * 041 * $Revision: 1.4 $ 042 * $Date: 2006/04/11 22:10:35 $ 043 * $State: Exp $ 044 */ 045package com.github.jaiimageio.plugins.tiff; 046 047import java.util.HashMap; 048import java.util.Map; 049 050/** 051 * A class defining the notion of a TIFF tag. A TIFF tag is a key 052 * that may appear in an Image File Directory (IFD). In the IFD 053 * each tag has some data associated with it, which may consist of zero 054 * or more values of a given data type. The combination of a tag and a 055 * value is known as an IFD Entry or TIFF Field. 056 * 057 * <p> The actual tag values used in the root IFD of a standard ("baseline") 058 * tiff stream are defined in the {@link BaselineTIFFTagSet 059 * <code>BaselineTIFFTagSet</code>} class. 060 * 061 * @see BaselineTIFFTagSet 062 * @see TIFFField 063 * @see TIFFTagSet 064 */ 065public class TIFFTag { 066 067 // TIFF 6.0 + Adobe PageMaker(R) 6.0 TIFF Technical Notes 1 IFD data type 068 069 /** Flag for 8 bit unsigned integers. */ 070 public static final int TIFF_BYTE = 1; 071 072 /** Flag for null-terminated ASCII strings. */ 073 public static final int TIFF_ASCII = 2; 074 075 /** Flag for 16 bit unsigned integers. */ 076 public static final int TIFF_SHORT = 3; 077 078 /** Flag for 32 bit unsigned integers. */ 079 public static final int TIFF_LONG = 4; 080 081 /** Flag for pairs of 32 bit unsigned integers. */ 082 public static final int TIFF_RATIONAL = 5; 083 084 /** Flag for 8 bit signed integers. */ 085 public static final int TIFF_SBYTE = 6; 086 087 /** Flag for 8 bit uninterpreted bytes. */ 088 public static final int TIFF_UNDEFINED = 7; 089 090 /** Flag for 16 bit signed integers. */ 091 public static final int TIFF_SSHORT = 8; 092 093 /** Flag for 32 bit signed integers. */ 094 public static final int TIFF_SLONG = 9; 095 096 /** Flag for pairs of 32 bit signed integers. */ 097 public static final int TIFF_SRATIONAL = 10; 098 099 /** Flag for 32 bit IEEE floats. */ 100 public static final int TIFF_FLOAT = 11; 101 102 /** Flag for 64 bit IEEE doubles. */ 103 public static final int TIFF_DOUBLE = 12; 104 105 /** 106 * Flag for IFD pointer defined in TIFF Tech Note 1 in 107 * TIFF Specification Supplement 1. 108 */ 109 public static final int TIFF_IFD_POINTER = 13; 110 111 /** 112 * The numerically smallest constant representing a TIFF data type. 113 */ 114 public static final int MIN_DATATYPE = TIFF_BYTE; 115 116 /** 117 * The numerically largest constant representing a TIFF data type. 118 */ 119 public static final int MAX_DATATYPE = TIFF_IFD_POINTER; 120 121 private static final int[] sizeOfType = { 122 0, // 0 = n/a 123 1, // 1 = byte 124 1, // 2 = ascii 125 2, // 3 = short 126 4, // 4 = long 127 8, // 5 = rational 128 1, // 6 = sbyte 129 1, // 7 = undefined 130 2, // 8 = sshort 131 4, // 9 = slong 132 8, // 10 = srational 133 4, // 11 = float 134 8, // 12 = double 135 4, // 13 = IFD_POINTER 136 }; 137 138 // Other tags 139 140 // Tech notes: http://partners.adobe.com/asn/developer/pdfs/tn/TIFFPM6.pdf 141 142// // Tech note 1: TIFF Trees 143// // Adds additional data type 13 = "IFD" (like LONG) 144// public static final int TAG_SUB_IFDS = 330; // IFD or LONG) 145 146// // Tech note 2: Clipping Path 147// public static final int TAG_CLIP_PATH = 343; // BYTE 148// public static final int TAG_X_CLIP_PATH_UNITS = 344; // DWORD 149// public static final int TAG_Y_CLIP_PATH_UNITS = 345; // DWORD 150 151// // Tech note 3: Indexed Images 152// public static final int TAG_INDEXED = 346; // SHORT 153 154// // Tech note 4: ICC L*a*b* 155// // New PhotometricInterpretation = 9 156 157// // Adobe 158 159// // PageMaker stuff 160// public static final int TAG_IMAGE_ID = 32781; // ASCII 161// public static final int TAG_OPI_PROXY = 351; // SHORT 162 163// // Photoshop stuff 164// public static final int TAG_IMAGE_SOURCE_DATA = 37724; // UNDEFINED 165// // 34377 - Image Resource Blocks 166 167// // GeoTIFF 168// public static final int TAG_MODEL_PIXEL_SCALE = 33550; 169// public static final int TAG_MODEL_TRANSFORMATION = 34264; 170// public static final int TAG_MODEL_TIEPOINT = 33922; 171// public static final int TAG_GEO_KEY_DIRECTORY = 34735; 172// public static final int TAG_GEO_DOUBLE_PARAMS = 34736; 173// public static final int TAG_GEO_ASCII_PARAMS = 34737; 174// public static final int TAG_INTERGRAPH_MATRIX = 33920; 175 176// // 33918 - Intergraph 177// // See http://remotesensing.org/lists/libtiff_archive/msg00557.html 178 179// // Helios ICC profile tagging 180 181// // 34841 - HELIOS ICC profile reference (ASCII) 182 183// // eiSTream Annotation Specification , Version 1.00.06 184// // Formerly Wang? 185 186// // 32932 - eiStream Annotation Data (BYTE/any) 187// // 32934 - ??? 188 189 int number; 190 191 String name; 192 193 int dataTypes; 194 195 TIFFTagSet tagSet = null; 196 197 // Mnemonic names for integral enumerated constants 198 Map valueNames = null; 199 200 /** 201 * Constructs a <code>TIFFTag</code> with a given name, tag number, set 202 * of legal data types, and <code>TIFFTagSet</code> to which it refers. 203 * The <code>tagSet</code> parameter will generally be 204 * non-<code>null</code> only if this <code>TIFFTag</code> corresponds 205 * to a pointer to a TIFF IFD. In this case <code>tagSet</code> will 206 * represent the set of <code>TIFFTag</code>s which appear in the IFD 207 * pointed to. A <code>TIFFTag</code> represents an IFD pointer if and 208 * only if <code>tagSet</code> is non-<code>null</code> or the data 209 * type <code>TIFF_IFD_POINTER</code> is legal. 210 * 211 * <p> If there are mnemonic names to be associated with the legal 212 * data values for the tag, {@link #addValueName(int, String) 213 * <code>addValueName()</code>} should be called on the new instance 214 * for each name.</p> 215 * 216 * <p> See the documentation for {@link #getDataTypes() 217 * <code>getDataTypes()</code>} for an explanation of how the set 218 * of data types is to be converted into a bit mask.</p> 219 * 220 * @param name the name of the tag; may be <code>null</code>. 221 * @param number the number used to represent the tag. 222 * @param dataTypes a bit mask indicating the set of legal data 223 * types for this tag. 224 * @param tagSet the <code>TIFFTagSet</code> to which this tag 225 * belongs; may be <code>null</code>. 226 */ 227 public TIFFTag(String name, int number, int dataTypes, TIFFTagSet tagSet) { 228 this.name = name; 229 this.number = number; 230 this.dataTypes = dataTypes; 231 this.tagSet = tagSet; 232 } 233 234 /** 235 * Constructs a <code>TIFFTag</code> with a given name, tag 236 * number, and set of legal data types. The tag will have no 237 * associated <code>TIFFTagSet</code>. 238 * 239 * @param name the name of the tag; may be <code>null</code>. 240 * @param number the number used to represent the tag. 241 * @param dataTypes a bit mask indicating the set of legal data 242 * types for this tag. 243 * 244 * @see #TIFFTag(String, int, int, TIFFTagSet) 245 */ 246 public TIFFTag(String name, int number, int dataTypes) { 247 this(name, number, dataTypes, null); 248 } 249 250 /** 251 * Returns the number of bytes used to store a value of the given 252 * data type. 253 * 254 * @param dataType the data type to be queried. 255 * 256 * @return the number of bytes used to store the given data type. 257 * 258 * @throws IllegalArgumentException if <code>datatype</code> is 259 * less than <code>MIN_DATATYPE</code> or greater than 260 * <code>MAX_DATATYPE</code>. 261 */ 262 public static int getSizeOfType(int dataType) { 263 if (dataType < MIN_DATATYPE ||dataType > MAX_DATATYPE) { 264 throw new IllegalArgumentException("dataType out of range!"); 265 } 266 267 return sizeOfType[dataType]; 268 } 269 270 /** 271 * Returns the name of the tag, as it will appear in image metadata. 272 * 273 * @return the tag name, as a <code>String</code>. 274 */ 275 public String getName() { 276 return name; 277 } 278 279 /** 280 * Returns the integer used to represent the tag. 281 * 282 * @return the tag number, as an <code>int</code>. 283 */ 284 public int getNumber() { 285 return number; 286 } 287 288 /** 289 * Returns a bit mask indicating the set of data types that may 290 * be used to store the data associated with the tag. 291 * For example, a tag that can store both SHORT and LONG values 292 * would return a value of: 293 * 294 * <pre> 295 * (1 << TIFFTag.TIFF_SHORT) | (1 << TIFFTag.TIFF_LONG) 296 * </pre> 297 * 298 * @return an <code>int</code> containing a bitmask encoding the 299 * set of valid data types. 300 */ 301 public int getDataTypes() { 302 return dataTypes; 303 } 304 305 /** 306 * Returns <code>true</code> if the given data type 307 * may be used for the data associated with this tag. 308 * 309 * @param dataType the data type to be queried, one of 310 * <code>TIFF_BYTE</code>, <code>TIFF_SHORT</code>, etc. 311 * 312 * @return a <code>boolean</code> indicating whether the given 313 * data type may be used with this tag. 314 * 315 * @throws IllegalArgumentException if <code>datatype</code> is 316 * less than <code>MIN_DATATYPE</code> or greater than 317 * <code>MAX_DATATYPE</code>. 318 */ 319 public boolean isDataTypeOK(int dataType) { 320 if (dataType < MIN_DATATYPE || dataType > MAX_DATATYPE) { 321 throw new IllegalArgumentException("datatype not in range!"); 322 } 323 return (dataTypes & (1 << dataType)) != 0; 324 } 325 326 /** 327 * Returns the <code>TIFFTagSet</code> of which this tag is a part. 328 * 329 * @return the containing <code>TIFFTagSet</code>. 330 */ 331 public TIFFTagSet getTagSet() { 332 return tagSet; 333 } 334 335 /** 336 * Returns <code>true</code> if this tag is used to point to an IFD 337 * structure containing additional tags. This condition will be 338 * satisfied if and only if either 339 * <code>getTagSet() != null</code> or 340 * <code>isDataTypeOK(TIFF_IFD_POINTER) == true</code>. 341 * 342 * <p>Many TIFF extensions use this mechanism in order to limit the 343 * number of new tags that may appear in the root IFD.</p> 344 * 345 * @return <code>true</code> if this tag points to an IFD. 346 */ 347 public boolean isIFDPointer() { 348 return tagSet != null || ((dataTypes & (1 << TIFF_IFD_POINTER)) != 0); 349 } 350 351 /** 352 * Returns <code>true</code> if there are mnemonic names associated with 353 * the set of legal values for the data associated with this tag. 354 * 355 * @return <code>true</code> if mnemonic value names are available. 356 */ 357 public boolean hasValueNames() { 358 return valueNames != null; 359 } 360 361 /** 362 * Adds a mnemonic name for a particular value that this tag's 363 * data may take on. 364 * 365 * @param value the data value. 366 * @param name the name to associate with the value. 367 */ 368 protected void addValueName(int value, String name) { 369 if (valueNames == null) { 370 valueNames = new HashMap(); 371 } 372 valueNames.put(new Integer(value), name); 373 } 374 375 /** 376 * Returns the mnemonic name associated with a particular value 377 * that this tag's data may take on, or <code>null</code> if 378 * no name is present. 379 * 380 * @param value the data value. 381 * 382 * @return the mnemonic name associated with the value, as a 383 * <code>String</code>. 384 */ 385 public String getValueName(int value) { 386 if (valueNames == null) { 387 return null; 388 } 389 return (String)valueNames.get(new Integer(value)); 390 } 391 392}