- Timestamp:
- 2011-06-01T12:33:42+12:00 (13 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
main/trunk/greenstone2/perllib/cpan/Image/ExifTool/README
r16842 r24107 4 4 Description: ExifTool support modules documentation 5 5 6 The ExifTool support modules are loaded by ExifTool to interpret various formats7 of meta information.6 The ExifTool support modules are loaded by ExifTool to allow processing of 7 various meta information formats. 8 8 9 9 The tables in these files are used as lookups based on the tag ID values. The … … 11 11 with EXIF tables, or the tag name if the ID is ASCII as with XMP tables). In 12 12 the case of a BinaryData table, the IDs are numerical and specify offsets into 13 the binary data block. The corresponding hash value provides information about 14 the tag (explained later). 15 16 Twenty-one special keys (PROCESS_PROC, WRITE_PROC, CHECK_PROC, GROUPS, FORMAT, 17 FIRST_ENTRY, TAG_PREFIX, PRINT_CONV, DID_TAG_ID, WRITABLE, NOTES, IS_OFFSET, 18 EXTRACT_UNKNOWN, NAMESPACE, PREFERRED, PARENT, PRIORITY, WRITE_GROUP, LANG_INFO, 19 VARS and DATAMEMBER) are used to provide additional information about a table. 20 The special keys have names that are all capitalized to avoid possible conflicts 21 with tag keys. Below is an explanation of the meaning of each special key: 13 the binary data block (floating point IDs allow multiple tags for the same 14 offset, with the integer part being used for the offset). The corresponding 15 hash value provides information about the tag (explained later). 16 17 Twenty-five special keys (TABLE_NAME, SHORT_NAME, PROCESS_PROC, WRITE_PROC, 18 CHECK_PROC, GROUPS, FORMAT, FIRST_ENTRY, TAG_PREFIX, PRINT_CONV, WRITABLE, 19 TABLE_DESC, NOTES, IS_OFFSET, IS_SUBDIR, EXTRACT_UNKNOWN, NAMESPACE, PREFERRED, 20 SRC_TABLE, PRIORITY, WRITE_GROUP, LANG_INFO, VARS, DATAMEMBER and SET_GROUP1) 21 are used to provide additional information about a table. The special keys have 22 names that are all capitalized to avoid possible conflicts with tag keys. Below 23 is an explanation of the meaning of each special key: 24 25 TABLE_NAME : Name of this table (set by GetTagTable()). 26 27 SHORT_NAME : Table name with leading "Image::ExifTool::" removed. 22 28 23 29 PROCESS_PROC : Reference to a function used to process the directory for this … … 56 62 reference, 2) value reference, and returns undefined (and possibly modifies 57 63 the input value) if successful, or an error message if there was a format 58 problem. 64 problem. May set ExifTool CHECK_WARN datamember for success with a warning. 59 65 60 66 GROUPS : A hash lookup for the default group names for all entries in this … … 64 70 FORMAT : Specifies the default tag Format and corresponding pointer increment 65 71 for entries in a BinaryData table, and defaults to 'int8u' if not specified. 66 The possible values of FORMAT are: 72 Format names starting with 'var_' cause subsequent tag ID's in BinaryData 73 tables to be incremented according to the size of the data (not including the 74 terminator). The possible values of FORMAT are: 67 75 68 76 int8s - Signed 8-bit integer (EXIF 'SBYTE') … … 70 78 int16s - Signed 16-bit integer (EXIF 'SSHORT') 71 79 int16u - Unsigned 16-bit integer (EXIF 'SHORT') 80 int16uRev - Unsigned 16-bit integer, reversed byte order 72 81 int32s - Signed 32-bit integer (EXIF 'SLONG') 73 82 int32u - Unsigned 32-bit integer (EXIF 'LONG') … … 86 95 extended - 80-bit extended floating float 87 96 ifd - Unsigned 32-bit integer sub-IFD pointer (EXIF 'IFD') 88 ifd 8- Unsigned 64-bit integer sub-IFD pointer (BigTIFF 'IFD8')97 ifd64 - Unsigned 64-bit integer sub-IFD pointer (BigTIFF 'IFD8') 89 98 string - Series of 8-bit ASCII characters (EXIF 'ASCII') 99 pstring - Pascal string [BinaryData tables only] 90 100 undef - Undefined-format binary data (EXIF 'UNDEFINED') 91 101 binary - Binary data 102 var_string - variable-length null-terminated ASCII string [BinaryData] 103 var_ustring - variable-length null-terminated UCS-2 string [BinaryData] 104 var_pstring - variable-length Pascal string [BinaryData] 105 var_pstr32 - variable-length Pascal string /w 32-bit len [BinaryData] 106 var_int16u - variable-length undef data with int6u count [BinaryData] 92 107 93 108 FIRST_ENTRY : Specifies the index for the first tag entry in a binary table. … … 97 112 TAG_PREFIX : Prefix for names of unknown tags. 98 113 99 PRINT_CONV : Default print conversion tags where PrintConv isn't specified. 100 101 DID_TAG_ID : Used by GetTagID() as a flag to indicate that TagID's have been 102 defined for all tags in this table. This may be set in the table definition 103 to prevent GetTagID() from assigning TagID's. 114 PRINT_CONV : Default print conversion for tags where PrintConv isn't 115 specified. PrintConv may be set to undef for individual tags to disable print 116 conversion when PRINT_CONV is defined for a table. 104 117 105 118 WRITABLE : Indicates that all tags in this table are writable. This is the … … 107 120 for SubDirectory tags which are not made Writable. 108 121 122 TABLE_DESC : Short description for this table. Plain text only. Used only 123 for XML tag database output. 124 109 125 NOTES : Notes to introduce the table in the TagNames documentation. Pod 110 126 formatting codes B<> and C<> may be used in this text. 111 127 112 IS_OFFSET : Reference to list of TagID's representing offsets for binary 113 data tables only. Not used for EXIF tables. 128 IS_OFFSET : Reference to list of sorted TagID's representing offsets for 129 writable binary data tables only. Not used for EXIF tables. 130 131 IS_SUBDIR : BinaryData tables only. A reference to a list of sorted tag ID's 132 representing subdirectories. Required for writable subdirectories only. 114 133 115 134 EXTRACT_UNKNOWN : Used in PDF tables to specify a directory where all unknown 116 tags should be extracted. 135 tags should be extracted. Set to 0 to extract only unknown numbered tags for 136 which the unnumbered tag is known. 117 137 118 138 NAMESPACE : Namespace prefix for tags in the XMP table. If this isn't a … … 120 140 this, the NAMESPACE value is a reference to either a list or a hash, where the 121 141 first element (or hash key) is the namespace prefix and and the second element 122 (or hash value) is the URI. 142 (or hash value) is the URI. This is undef for XMP tables in which tags have 143 variable namespaces, and in this case each tag must have a Namespace entry. 123 144 124 145 PREFERRED : Set to true if the tags in this table should always be added when … … 128 149 directories for tags which are already being creating in the preferred group. 129 150 130 PARENT : Used internally to store the parent table name of a user-defined tag131 ta ble so the appropriate module can be loaded as required.151 SRC_TABLE : Used internally to store the source table name of a user-defined 152 tag table so the appropriate module can be loaded as required. 132 153 133 154 PRIORITY : Default Priority for all tags in this table. … … 138 159 language-specific tag information hash. The routine takes two arguments: a 139 160 reference to the non-specific tagInfo hash, and the language code. Used only 140 in tables which support tag name language extensions (ie. MIE and XMP). 161 in tables with writable tags which support tag name language extensions (ie. 162 MIE and XMP). 141 163 142 164 VARS : Hash used to store additional parameters. Individual modules may use … … 144 166 have been defined, and may be used by any module: 145 167 146 INDEX - Use "Index" instead of "Tag ID" for column heading in tag name docs. 147 148 NO_ID - Avoid printing "Tag ID" column in tag name documentation. 149 150 DATAMEMBER : BinaryData tables only. A reference to a list of tag ID's which 151 must be extracted as data members when writing. 168 ID_LABEL Label to use instead of "Tag ID" for column heading in tag 169 name documentation. When this is set, numerical TagID's are 170 not converted to hexadecimal notation. Unless otherwise set, 171 an ID_LABEL of "Index" is assumed for tables which use 172 ProcessBinaryData. 173 174 NO_ID Avoid printing "Tag ID" column in tag name documentation. 175 176 CAPTURE Used by PDF module to name dictionaries to capture when 177 writing. 178 179 MINOR_ERRORS [EXIF tables only] Flag to make errors in this IFD minor, or 180 to downgrade already minor errors to warnings while writing. 181 (Errors in MakerNote IFD's are already classified as minor.) 182 Note that for certain types errors, the response is to delete 183 the entire IFD from the image. 184 185 NUMBERS_LAST Sort numerical tags after character tags in documentation. 186 187 DATAMEMBER : BinaryData tables only. A reference to a list of sorted tag ID's 188 which must be extracted as data members when writing. Must also list "var_" 189 format tags and tags with Hook so offsets are properly calculated if the table 190 is writable. 191 192 SET_GROUP1 : [EXIF tables only] Flag to set group1 name to the directory name 193 for all tags in the table. 152 194 153 195 The remaining entries in a tag table are the tag IDs with their associated … … 161 203 162 204 Name : The tag name. Tag names need not be unique. If they aren't 163 unique, duplicate tags overwrite values of previous tags 164 unless the Duplicates option is set or the new tag has lower 165 Priority. With Duplicates set, to allow multiple tags with 166 the same name to exist in the tag information hash, the key of 167 the previous tag is changed to the form "TagName (N)", where N 168 starts at 1 and increments for subsequent duplicate tags. A 169 tag name should start with an uppercase letter, and contain 170 only the charcters in the set [A-Za-z0-9_-]. 205 unique, then duplicate tags will hide the values of previous 206 tags when extracting information unless the Duplicates option 207 is set or the new tag has lower Priority. With Duplicates 208 set, to allow multiple tags with the same name to exist in the 209 tag information hash, the key of the previous tag is changed 210 to the form "TagName (N)", where N starts at 1 and increments 211 for subsequent duplicate tags. A tag name should start with 212 an uppercase letter, and contain only the charcters in the set 213 [A-Za-z0-9_-]. If not given, the Name is taken from the tag 214 ID with the first character changed to upper case. 171 215 172 216 Description : A more readable description of tag name. If a tag doesn't … … 181 225 or EXIF table, this gives the format that is used to convert 182 226 the binary data, and is one of the FORMAT types specified 183 above. For BinaryData tables, the format may have a size in 184 trailing brackets which is a perl expression to be evaluated. 185 The expression may access any of the previous table entries 186 through a %val hash, or the data size via $size. For example, 227 above. If not specified, the Format of an EXIF entry is taken 228 from the EXIF information, and the Format of a BinaryData 229 entry is taken from the FORMAT specified for the table (or 230 int8u if FORMAT is not specified). Must be specified for 231 Writable tags where the value must be converted for a 232 Condition. For BinaryData tables, the format may have a size 233 in trailing brackets which is a Perl expression to be 234 evaluated. The expression may access any of the previous table 235 entries through a %val hash (read-only tables), the data size 236 via $size, or the ExifTool object via $self. For example, 187 237 'string[$val{3}]' defines a string with length given by the 188 table entry with tag index '3'. If not specified, the format 189 of an EXIF entry is taken from the EXIF information, and the 190 format of a BinaryData entry is taken from the FORMAT 191 specified for the table (or int8u if FORMAT is not specified). 238 table entry with tag index '3'. An initial "var_" may be 239 added to the Format name of any BinaryData tag with a size in 240 brackets. In this case, subsequent offsets are adjusted by 241 the total size minus the size of the base Format (ie. 242 "var_int16u[10]" causes subsequent offsets to be incremented 243 by sizeof(int16u) * 9). Note that all "var_" Format tags must 244 have corresponding DATAMEMBER entries. 192 245 193 246 Count : Used when writing EXIF information to specify the number … … 199 252 count written to the file will be different. 200 253 254 FixCount : Flag set to determine correct count from offsets in IFD. This 255 is necessary for some Kodak tags which write an incorrect 256 Count value. 257 201 258 Flags : Flags to specify characteristics for this tag. May be a 202 259 simple scalar flag name, a reference to a list of flag names, … … 207 264 available flag names are: 208 265 209 'Avoid' - avoid creating this tag if possible. 266 'AutoSplit' - [List tags only] Similar to ListSplit option, 267 but applied automatically to individual tags. Value specifies 268 pattern for split, or 1 for default pattern ',?\\s+'. 269 270 'Avoid' - avoid creating this tag if possible. This is only 271 effective if another tag exists with the same name. 210 272 211 273 'Binary' - set to 1 for binary data. This has the same effect 212 274 as setting ValueConv to '\$val', but it it a bit cleaner and 213 275 avoids dummy ValueConvInv entries for writable tags. Has no 214 effect if ValueConv is defined for the tag. 276 effect if ValueConv is defined for the tag. Some values may 277 be treated as binary data even if this flag is not set. 278 279 'BlockExtract' - set for writable directories in EXIF 280 information which are extracted by default. Otherwise 281 writable directories are only extracted as a block if 282 specified explicitly. 215 283 216 284 'DataMember' - name of exiftool data member associated with … … 218 286 writing information. Necessary only if the value of the tag 219 287 affects other written information. Currently only used for 220 tags in EXIF tables. 288 tags in EXIF tables where it triggers the execution of the 289 RawConv to convert and stores the value as an ExifTool data 290 member when writing. 221 291 222 292 'DataTag' - associated tag name containing data for offset or … … 231 301 Casio PrintIM information). 232 302 303 'Flat' - [flattened XMP structure tags only] must be set for 304 all pre-defined flattened tags (including user-defined 305 flattened tags). This flag is reset to 0 internally after all 306 associated flattened tags in the structure have been 307 generated. 308 309 'Flattened' - [reserved] used internally to mark Struct tags 310 which have been processed to generate flattened equivalents. 311 312 'GotGroups' - [reserved] flag used internally to indicate that 313 the Groups hash has been initialized for this tag. 314 315 'Hidden' - set to hide tag from the TagName documentation. 316 Also suppresses verbose output of a BinaryData tag. 317 233 318 'IsOffset' - flag set if the tag represents an offset to some 234 319 data, and causes value will be adjusted to an absolute file 235 320 offset. If set to 2, the offset base of the parent directory 236 321 is used even if the base changes for the current directory 237 (only some maker notes are this messed up). 238 239 'List' - indicates that duplicate entries of this tag are 240 allowed, and will be accumulated in a list. Note that for XMP 241 information, 3 different types of lists are supported and the 242 List value specifies the type: 'Bag', 'Seq' or 'Alt'. 322 (only some maker notes are this messed up). Set to 3 if 323 absolute file offsets are used. May be set to an expression 324 to be evaluated. Expression may access $val and $exifTool, 325 and is evaluated only when reading. 326 327 'List' - flag indicating that duplicate entries of this tag 328 are allowed, and will be accumulated in a list. Note that for 329 XMP information, 3 different types of lists are supported and 330 the List value specifies the type: 'Bag', 'Seq' or 'Alt'. As 331 well, a value of '1' is used internally in XMP to allow list 332 behaviour for a flattened tag which is itself not a list 333 element (ie. a member of list of structures). Note that in 334 ExifTool an XMP lang-alt tag (Writable="lang-alt") is NOT a 335 List-type tag (unless it is a list of lang-alt lists, which is 336 uncommon). 243 337 244 338 'MakerNotes' - set if this tag is maker note data. 245 339 340 'MakerPreview' - set in the PreviewImageStart tag information 341 if the preview must be stored inside the maker notes. 342 343 'Mandatory' - set for mandatory tags. Used only by TagInfoXML 344 and documentation purposes. Mandatory tags may be added 345 automatically by ExifTool. 346 347 'NestedHtmlDump' - flag set if value for this tag is also 348 dumped when processing the SubDirectory. This flag is implied 349 if the MakerNotes flag is set. Set to 2 if the dump should 350 only be underlined if nested inside other maker notes. 351 246 352 'NotIFD' - set for 'MakerNotes' tags only if the data is not 247 in standard EXIF IFD format. 248 353 in standard EXIF IFD format. (Note: All SubDirectory tags in 354 the MakerNotes table are 'MakerNotes' type by default.) 355 249 356 'OffsetPair' - set if the tag represents half of an offset/ 250 357 byte count pair. Data for these tags must be handled … … 252 359 253 360 'Permanent' - flag indicates that a tag is permanent, and 254 can't be added or deleted from the file. By default, all 361 can't be added or deleted from the file, although a new value 362 may be written if the tag already exists. By default, all 255 363 MakerNotes tags are permanent unless otherwise specified. 256 364 257 365 'PrintHex' - specifies that unknown PrintConv values should 258 be printed in hex (ie. 'Unknown (0x0)') 366 be printed in hex (ie. 'Unknown (0x01)'). Also causes 367 numerical tag values to be printed in hex in the HTML tag name 368 documentation. 369 370 'PrintString' - flag set to force PrintConv values to be 371 printed as strings in the documentation. 259 372 260 373 'Priority' - gives the priority of this tag while reading. If … … 265 378 special feature is that Priority 0 tags are automatically 266 379 incremented to Priority 1 if they exist in the IFD of the full 267 resolution image (as determined by SubFileType). 380 resolution image (as determined by SubfileType). If not 381 defined, the priority defaults to 1 for all tags except except 382 tags in IFD1 of JPEG images which default to priority 0. 268 383 269 384 'Protected' - bit mask to protect tags from writing: … … 273 388 directly by the user. 274 389 390 'PutFirst' - [EXIF only] flag to place this value before IFD0 391 when writing (ie. immediately after TIFF header). Only used 392 for main IFD's (IFD0, IFD1, etc) and IFD's where SubIFD flag 393 is set to 2 (currently only ExifIFD). 394 395 'Resource' - [XMP only] flag to write value as an rdf:resource 396 in an empty element instead of as a normal string. 397 275 398 'SeparateTable' - set to list PrintConv values in a separate 276 399 table in the HTML documentation. Value is 1 for a table name 277 400 of 'Module TagName', or 'TAG' for 'Module TAG', or 'MODULE 278 TAG' to fully specify the table name. 401 TAG' to fully specify the table name. The table may have a 402 'Notes' entry for a description of the table. 279 403 280 404 'SetResourceName' - [Photoshop tags only] set to 1 to append … … 285 409 provided. 286 410 411 'StructType' - [reserved] used internally by XMP writer for 412 flattened structure tags as a flag to indicate that one or 413 more enclosing structures has a TYPE field. 414 415 'SubDoc' - [Composite tags only] set to cause this composite 416 tag to also be generated for each sub-document. To achieve 417 this, 'Main:' and 'Doc#:' prefixes are added to all Require'd 418 and Desire'd tag names which don't already start with 'Main:' 419 or 'Doc#:', and the composite tag is built once for each of 420 the main document and all sub-documents. 421 287 422 'SubIFD' - used in writing to determine that the tag specifies 288 423 an offset to a sub-IFD. When this flag is set, the Group1 289 name gives the name of the IFD. 424 name gives the name of the IFD. Must be set if and only if 425 the tag has a SubDirectory Start of '$val' (this is validated 426 by BuildTagLookup). Set to 2 for standard EXIF SubIFD's where 427 the PutFirst flag is valid. 290 428 291 429 'Unknown' - this is an unknown tag (only extracted when the 292 430 Unknown option is set). 431 432 'WrongBase' - ['IsOffset' tags only] An expression using $self 433 that is evaluated to generate a base shift for 'IsOffset' tags 434 which use a different base than the rest of the tags. 293 435 294 436 RawConv : Used to convert the Raw value at extraction time (while the … … 296 438 which are done later only if the value is requested). May be 297 439 a scalar expression using $val (the Raw tag value), $self (the 298 current ExifTool object) and $tag (the tag name), or a code 299 reference with $val and $self as arguments. For Composite 300 tags, $val is a reference to a hash of component tag names, 440 current ExifTool object), $tag (the tag key) and $tagInfo 441 (reference to the tag information hash) or a code reference 442 with $val and $self as arguments. For Composite tags, $val is 443 a reference to a hash of source ("derived from") tag names, 301 444 and @val may be used to access the Raw values of these tags. 302 The returned value may be a scalar which is used as the new 303 Raw value, a scalar reference to a binary data value, a hash 304 reference for Composite tags, an ARRAY reference for a list of 305 values, or undefined to indicate that the tag should be 306 ignored. Also, RawConv may generate Warning or Error tags, 307 while ValueConv and PrintConv may not. Note: RawConv should 308 only be used if necessary (in general, only if the tag may be 309 ignored). It is preferable to use ValueConv instead of 310 RawConv because ValueConv is only executed if the tag value is 311 requested, while RawConv is executed for all extracted tags. 445 If RawConv is specified for a Composite tag, then ValueConv 446 and PrintConv evals will no longer have access to the source 447 @val and @prt values. The returned value may be a scalar 448 which is used as the new Raw value, a scalar reference to a 449 binary data value, a hash reference for Composite tags, an 450 ARRAY reference for a list of values, or undefined to indicate 451 that the tag should be ignored. Also, RawConv may generate 452 Warning or Error tags, while ValueConv and PrintConv may not. 453 Note: RawConv should only be used if necessary (in general, 454 only if the conversion may return undef to ignore the tag) 455 because ValueConv is more efficient since it is only executed 456 if the tag value is requested, while RawConv is executed for 457 all extracted tags. 312 458 313 459 ValueConv : Used to convert the Raw value to a useable form. May be a hash … … 319 465 list. If a hash reference is used and the Raw value doesn't 320 466 appear as one of the keys, then the converted value is set to 321 "Unknown (X)", where X is the Raw value (unless a special 322 'BITMASK' key exists, in which case the hash referenced by 323 'BITMASK' is used to decode individual value bits). In an 467 "Unknown (X)", where X is the Raw value (unless either of the 468 special keys exist: 'BITMASK', a reference to a hash used to 469 decode individual value bits; or 'OTHER', a reference to a 470 subroutine used to convert unknown values. The subroutine 471 takes 3 arguments: the value, a flag which is set for the 472 inverse conversion, and a reference to the PrintConv hash, and 473 returns the converted value or undef on error. The lookup 474 hash may also contain a 'Notes' entry which is used for 475 documentation if the SeparateTable flag is set). In an 324 476 expression, $self is a reference to the current ExifTool 325 object, $val is the Raw value, and $tag is the tag name. The477 object, $val is the Raw value, and $tag is the tag key. The 326 478 subroutine takes 2 arguments: the Raw value and a reference to 327 479 the current ExifTool object. The expression or subroutine is … … 333 485 to cyclical dependencies so they should be avoided). When 334 486 evaluated, the expression or subroutine returns a scalar for 335 the converted value, or a scalar reference to a binary data 336 value (see the 'Binary' flag). The return value should always 337 be defined -- use RawConv instead to return undef if it is 338 necessary to test the value for validity, otherwise an undef 339 tag may hide a previously defined value when the Duplicates 340 option is not enabled. Composite tags which Require or Desire 341 other tags may access the ValueConv, PrintConv and Raw values 342 of these tags through the elements of the @val, @prt and @raw 343 lists respectively (only if there was no RawConv or returned a 344 hash reference). For these tags, $val may be used in an 345 expression to represent $val[0], and the first argument passed 346 for a code reference is a reference to @val. If ValueConv is 347 not specified, the Raw value is not converted. 487 the converted value, a SCALAR reference to a binary data value 488 (see the 'Binary' flag), or an ARRAY reference for a list of 489 values. The return value should always be defined -- use 490 RawConv instead to return undef if it is necessary to test the 491 value for validity, otherwise an undef tag may hide a 492 previously defined value when the Duplicates option is not 493 enabled. If this isn't possible (as with Composite tags where 494 the converted values of the source tags are needed), set the 495 Priority to 0 to avoid taking priority over a valid tag. 496 Composite tags which Require or Desire other tags may access 497 the ValueConv, PrintConv and Raw values of these tags through 498 the elements of the @val, @prt and @raw lists respectively 499 (only if there was no RawConv or it returned a hash 500 reference). For these tags, $val may be used in an expression 501 to represent $val[0], and the first argument passed for a code 502 reference is a reference to @val. If ValueConv is not 503 specified, the Raw value is not converted. 348 504 349 505 PrintConv : This entry is similar to ValueConv above, except that it is … … 375 531 that DataMember tags may NOT be used in the inverse 376 532 conversions because these conversions are done before the 377 input file is parsed. Instead, a Condition or RawConvInv must 378 be used. 533 input file is parsed. Instead, a Condition or RawConvInv must 534 be used. May return undef on conversion error and call warn() 535 to issue a warning. If warn() is not called, a generic 536 warning is generated when undef is returned. An empty warning 537 ("\n") may be issued to suppress warning messages when undef 538 is returned. If a scalar, the expression may use the 539 variables $val, $self and $wantGroup. If a code ref, the 540 routine is passed 2 arguments: $val and $self. Note that this 541 conversion is not applied for deleted tags (ie. $val is 542 undef). 379 543 380 544 PrintConvInv : The inverse of PrintConv. Only necessary if for Writable tags 381 when PrintConv is specified (unless WriteAlso is used). 545 when PrintConv is specified (unless WriteAlso is used). See 546 ValueConvInv above for more details. 547 548 PrintConvColumns : Number of columns for PrintConv lookup in HTML docs. 549 Default is 1 if not specified. 550 551 DelValue : Raw value to be used when deleting a permanent tag. (Note all 552 MakerNotes tags are permanent.) If not specified, an attempt 553 is made to convert an empty string for the raw value. 554 555 Relist : [Only if ValueConv or PrintConv is a list ref] Reference to a 556 list of original value indices used to reorganize values. Each 557 entry in the list may be a scalar index, or a reference to a 558 list of indices to join values. (Currently values may be 559 joined, but the order of writable values must not be changed 560 until this ability is added to the writer.) 561 562 Mask : [BinaryData tags only] Bitmask for this value. (Multiple tags 563 may have the same index by using floating point indices. An 564 unknown tag will only be generated for a certain TagID if 565 there is no integral TagID for that tag.) When Mask is used, 566 PrintHex=1 is implied unless otherwise defined. 382 567 383 568 Condition : If given, specifies scalar which is evaluated as a Perl … … 386 571 first list entry with a true condition is taken. If no 387 572 condition exists, then a 'true' condition is assumed. The 388 expression may use $self to access the ExifTool object, and 389 $oldVal to access the previous Raw value of the tag (if it 390 exists). The first 48 bytes of the raw data value are 391 accessible through the reference $valPt for EXIF and Jpeg2000 392 tags only. EXIF tags may also reference the format string and 393 value count through $format and $count. Note that if the 394 value is writable and $valPt is used, the tag must have a 395 Format (unless 'undef' or 'string'), and a Count (unless 1 or 396 length of the 'undef' or 'string'), so the raw data may be 397 generated for evaluating the Condition. 573 expression may use $self to access the ExifTool object. The 574 first 128 bytes of the raw data value are accessible through 575 the reference $valPt for EXIF, Jpeg2000 and BinaryData tags 576 only (note that for BinaryData tags, the raw data of $$valPt 577 is always 'undef' type, and may not be used when writing 578 except for SubDirectory tags). EXIF tags may also reference 579 the format string and value count through $format and $count. 580 Note that if the value is writable and $valPt is used, the tag 581 must have a Format (unless 'undef' or 'string'), and a Count 582 (unless 1 or length of the 'undef' or 'string'), so the raw 583 data may be generated for evaluating the Condition. When 584 writing, $valPt, $format and $count refer to the new value, 585 except for MakerNotes tags where $format and $count refer to 586 the old tag if it existed. 398 587 399 588 Require : [Composite tags only] A hash reference specifying the tags … … 436 625 information, this flag is only defined if the SubDirectory is 437 626 writable as a block, or if the SubDirectory can not be edited 438 (in which case Writable is set to 0). 627 (in which case Writable is set to 0). If non-zero, the 628 SubDirectory is also extracted as a block, so the Binary and 629 Protected flags should usually set as well. There is 630 currently no way to specify a write format for a SubDirectory 631 that is not writable as a block (the default is 'int32u' for 632 IFD-type SubDirectories, and 'undef' for all others). 439 633 440 634 WriteAlso : Used for writable tag to specify other tags to write when this … … 442 636 are the names of the tags to write, and the values are 443 637 evaluated to obtain the ValueConv values of each tag (or undef 444 to delete the tag). In the eval, $val may be used as the Raw 445 value of the parent tag. This will write Protected tags that 446 aren't directly writable (Protected bit 0x02 set). 638 to delete the tag). In the eval, $val is the Raw value of the 639 parent tag (which may be undef if the tag is being deleted), 640 and the %opts hash may be accessed to modify SetNewValue 641 options for each tag. By default, Type is set to "ValueConv" 642 and the Protected option has bit 0x02 set to allow writing of 643 Protected tags that aren't directly writable. The AddValue 644 and DelValue options from the parent tag are also defined, but 645 no other options are set by default. Previous new values of 646 WriteAlso tags have already been removed prior to the eval if 647 the Replace option was used for the parent tag. If an empty 648 warning is issued ("\n"), the target tag is not written and no 649 error is reported. 447 650 448 651 WriteCheck : If given, specifies a scalar which is evaluated as a Perl … … 451 654 the value to be written, $self is the ExifTool object, and 452 655 $tagInfo is the tag information hash reference. It returns an 453 error string or undef if the value is good. 656 error string, or undef if the value is good. If the error 657 string is empty, the tag is not written and no warnings are 658 issued, but WriteAlso is still evaluated if it exists. 659 660 DelCheck : Similar to WriteCheck, but called when the tag is deleted. The 661 expression may access $self, $tagInfo and $wantGroup. Returns 662 error string, or undef on success, and may set $val to 663 something other than undef. May return empty string ('') to 664 suppress warning messages but not delete tag (ie. when 665 deleting only associated tags). 454 666 455 667 WriteCondition: [Writable EXIF tags only] Specifies a condition to be 456 668 evaluated before the tag can be written to a specific file. 457 669 The condition may use $self to reference the ExifTool object, 458 and returns true if it is OK for writing. Unlike WriteCheck670 and returns true if it is OK for writing. Unlike WriteCheck 459 671 which is done only once when the new value is set, this 460 condition is evaluated before the information is written in 461 each file. 462 463 WriteGroup : [Required for writable EXIF tags] Specifies the IFD where the 464 information gets written by default. 672 condition is evaluated just before the tags of the specific 673 SubDirectory are written. 674 675 WriteGroup : [Writable EXIF tags only] Specifies the IFD where the 676 information gets written by default. Must be defined for 677 writable EXIF tags if WRITE_GROUP is not specified in table. 678 679 IsOverwriting : [Writable EXIF tags only] Specifies reference to subroutine 680 which determines if tag should be overwritten. Arguments are: 681 0) ExifTool object ref, 1) new value hash ref, 2) old value, 682 3) new value reference. 683 684 AllowGroup : [Writable tags only] Regular expression string (case 685 insensitive) to match group names which are allowed when 686 writing this tag. Only needed if tag can be written to 687 groups other than the normal groups for this tag (very rare). 465 688 466 689 OffsetPair : Used in EXIF table to specify the tagID for the corresponding … … 470 693 associated with offset/length tags. 471 694 472 Struct : [XMP tags only] Used by XMP writer code to specify name of XMP 473 structure so the PropertyPath can be determined. 695 FixFormat : [Writable EXIF SubIFD SubDirectory's only] Used to specify a 696 format for writing an IFD pointer other than 'int32u'. 697 698 ChangeBase : [EXIF tags in JPEG images only] Eval used to return new base 699 for the offset for this tag only. Eval may use $dirStart and 700 $dataPos. Note this is geared to the quirky Leica preview 701 image offset, and is only used if the preview is outside the 702 APP1 EXIF segment. 703 704 Struct : [XMP tags only] Reference to structure hash for structured XMP 705 tags. See "STRUCTURES" section below for more details. (For 706 backward compatibility, this may be a name to an entry in 707 %Image::ExifTool::UserDefined::xmpStruct, but this use is 708 deprecated.) Flattened tags are automatically generated for 709 each field in the structure. Note that Struct tags can NOT 710 have ValueConv/PrintConv entries, because values that are HASH 711 references are are also used by Composite tags, which use the 712 the Conv entries to generate the composite value. 713 714 Namespace : [XMP tags only] Gives standard XMP namespace prefix to use for 715 this tag. If not defined, the tag table NAMESPACE is used. 474 716 475 717 Units : [MIE tags only] Reference to a list of valid units strings. 476 718 The default units are the first item in the list. 477 719 478 TagID : [reserved] This entry is used internally by GetTagID() to 479 cache tag ID numbers for speed. 720 Hook : [BinaryData tags only] Expression to be evaluated when 721 extracting tag to allow dynamic Format, etc for BinaryData 722 tags. May access $self, and assign a new value to $format to 723 dynamically set the tag format, and/or increment $varSize to 724 add a byte offset to subsequent tags. 725 726 TagID : [reserved] Used internally to save the table key for this tag. 727 Note: For XMP tables this corresponds to the XMP property 728 name, but the table key may have a full XMP namespace prefix 729 added. 730 731 NewTagID : [reserved] Used internally to save new ID of tag in Composite 732 table if it is different that the original TagID (happens if 733 there was a conflict with an existing entry in the table) 734 735 Index : [reserved] Used internally to save the index of tagInfo items 736 which are in a conditional list. 480 737 481 738 Table : [reserved] Reference to parent tag table. 482 739 483 740 PropertyPath : [reserved] Used internally by XMP writer to save property path 484 name. 741 name. Also used in structure field information hashes, but 742 for these the full property path is not stored. 743 744 SrcTagInfo : [reserved] Used internally by XMP module to store reference to 745 default language tagInfo hash for alternate-language tags. 746 747 RootTagInfo : [reserved] Used internally to store a reference to the tag 748 information hash of the top-level structure for flattened 749 structure tags. 485 750 486 751 Module : [reserved] Used internally to store module name for writable … … 488 753 489 754 LangCode : [reserved] Used internally to indicate language code for 490 alternate language tags (MIE and XMP only) 755 alternate language tags (ie. 'fr'). Only used with formats 756 which support alternate languages (ie. XMP, MIE, etc). 491 757 492 758 SubDirectory { If it exists, this specifies the start of a new subdirectory. … … 514 780 same as the current directory, which is normally the case. 515 781 May use $start to represent the subdirectory start location 516 relative to the current base. If this is defined, the 517 automatic validation of base offsets is disabled for maker 518 notes directories. 519 520 EntryBased : Flag indicating that the offsets are based on the indidual 782 relative to the current base, and $base for the value of the 783 current base. If this is defined, the automatic validation of 784 base offsets is disabled for maker notes directories. The 785 IFD is flagged as using relative offsets when writing if 786 '$start' is used in this expression. 787 788 EntryBased : Flag indicating that the offsets are based on the individual 521 789 directory entry position, so offsets are incremented by 12 522 790 times the corresponding entry index. … … 526 794 tag value ($val) is used as-is. If MaxSubdirs is specified, 527 795 then one subdirectory is parsed for each value found up to the 528 maximum number specified. 796 maximum number specified. Ignored when writing. 529 797 530 798 ByteOrder : Specifies byte ordering if different than than the rest of the … … 538 806 the expression: $val (value of the tag), $dirData (reference 539 807 to directory data), $subdirStart (offset to subdirectory 540 start) and $size (size of subdirectory). 808 start) and $size (size of subdirectory). Returns true if 809 subirectory is valid. 541 810 542 811 ProcessProc: If given, specifies processing procedure used to decode this 543 812 subdirectory data. This overrides the default procedure 544 813 specified by PROCESS_PROC in the tag table. 814 815 WriteProc: If given, specifies processing procedure used to write this 816 subdirectory data. This overrides the default procedure 817 specified by WRITE_PROC in the tag table. 545 818 546 819 DirName : Name of this subdirectory. If not specified, the name is … … 551 824 FixBase : Flag set if base offsets should be fixed. Used to add a 552 825 constant to maker notes offsets to fix damage done by some 553 image editing utilities. (maker notes only) 826 image editing utilities. (maker notes only) Set to 2 for 827 unknown maker notes to be a bit more flexible in adjusting 828 the base offset. 829 830 AutoFix : Flag set to patch GE makernote offset quirks and apply FixBase 831 without warnings when writing. 554 832 555 833 FixOffsets : Expression to evaluate for each value pointer to patch … … 557 835 following variables: $valuePtr, $valEnd, $size, $tagID and 558 836 $wFlag. May return undef when writing to ignore the entry. 837 838 RelativeBase:[EXIF directories only] Flag to adjust all offsets relative 839 to the start of the IFD when writing. 840 841 Multi : [EXIF directories only] Flag to allow multiple linked IFD's. 842 1 is assumed if DirName is IFD0 or SubIFD unless otherwise 843 defined. 844 845 Magic : [TiffIFD directories only] Magic number used in TIFF-like 846 header. 559 847 } 560 848 849 STRUCTURES 850 851 Structure hashes are very similar to tag tables in that their keys are structure 852 field ID's and their values are structure field information hashes. The special 853 keys in structure hashes are: 854 855 NAMESPACE : Same as in tag tables, but may be set to undef for a 856 variable-namespace structure which holds any top-level tag. This 857 is mandatory for built-in tags, but optional for user-defined 858 tags (where it defaults to the NAMESPACE of the tag table). 859 860 STRUCT_NAME : Name of structure (used in warning messages). 861 862 TYPE : rdf:type resource for structure. 863 864 NOTES : Notes for documentation. 865 866 GROUPS : Same as in tag table, but only the family 2 group name is used, 867 as the default for the flattened tags. 868 869 The contained structure field information hashes are similar to tag information 870 hashes, except that only the following elements are used: 871 872 Raw/Value/PrintConv (and their inverses), TagID (optional), Groups, List, 873 Writable, Struct, Namespace, LangCode, PropertyPath. 874 875 But note that for PropertyPath, only the element of the path corresponding to 876 the specific field is stored (including any necessary list properties). The 877 full property path is obtained by walking the structure tree. 878 879 Flattened tags corresponding to each field in a structure are automatically 880 generated (using an on-demand approach to avoid spending time generating them 881 unless necessary). Pre-defined flattened tags are allowed, and are used when it 882 is necessary to change the Name or Description of a flattened tag. The 883 flattened tag information hash entries are copied from the corresponding 884 structure field definitions, even for pre-defined flattened tags. The exception 885 that the List tag is generated automatically unless explicity set to 0 in a 886 pre-defined flattened tag. 887 561 888 --------------------------------------------------------------------------------
Note:
See TracChangeset
for help on using the changeset viewer.
