Debian Codegraph @

lib/Image/ExifTool/README

raw
1 --------------------------------------------------------------------------------
2 File: Image/ExifTool/README
3
4 Description: ExifTool support modules documentation
5
6 Note: This documentation is a reference to be used by developers when
7 adding new tags to ExifTool.
8
9 The ExifTool support modules are loaded by ExifTool to allow processing of
10 various meta information formats.
11
12 The tables in these files are used as lookups based on the tag ID values. The
13 hash keys are the tag IDs (in decimal or hexadecimal if the ID is numerical as
14 with EXIF tables, or the tag name if the ID is ASCII as with XMP tables). In
15 the case of a BinaryData table, the IDs are numerical and specify offsets into
16 the binary data block (floating point IDs allow multiple tags for the same
17 offset, with the integer part being used for the offset). The corresponding
18 hash value provides information about the tag (explained later).
19
20 Twenty-eight special keys (TABLE_NAME, SHORT_NAME, PROCESS_PROC, WRITE_PROC,
21 CHECK_PROC, INIT_TABLE, GROUPS, FORMAT, FIRST_ENTRY, TAG_PREFIX, PRINT_CONV,
22 WRITABLE, TABLE_DESC, NOTES, IS_OFFSET, IS_SUBDIR, EXTRACT_UNKNOWN, NAMESPACE,
23 PREFERRED, PERMANENT, SRC_TABLE, PRIORITY, AVOID, WRITE_GROUP, LANG_INFO, VARS,
24 DATAMEMBER and SET_GROUP1) are used to provide additional information about a
25 table. The special keys have names that are all capitalized to avoid possible
26 conflicts with tag keys. Below is an explanation of the meaning of each special
27 key:
28
29 TABLE_NAME : Name of this table (set automatically by GetTagTable()).
30
31 SHORT_NAME : Table name with leading "Image::ExifTool::" removed.
32
33 PROCESS_PROC : Reference to a function used to process the directory for this
34 table. If PROCESS_PROC is not given, \&Image::ExifTool::Exif::ProcessExif is
35 assumed (except for QuickTime atoms for which
36 \&Image::ExifTool::QuickTime::ProcessMOV is the default). If PROCESS_PROC is
37 set to 0, the tags are not added to the lookup. The process proc returns 1 on
38 success or 0 on failure, and takes 3 arguments: 0) reference to the ExifTool
39 object, 1) reference to a directory information hash (with the following
40 entries:), 2) reference to the tag table hash.
41
42 Name - Tag name for this SubDirectory entry (for verbose messages)
43 Base - Base offset for pointers from start of file
44 DataPt - Reference to data block containing directory (may be undef)
45 DataPos - Position of data block within file (relative to Base)
46 DataLen - Length of data block in bytes
47 DirStart - Offset to start of directory from start of data block
48 DirLen - Length of directory data within block
49 DirName - Name of this directory
50 OutFile - Output file or scalar reference
51 Parent - Name of parent directory
52 RAF - Reference to File::RandomAccess object if available
53 NewDataPos - File position of new data (write proc only)
54 Fixup - Reference to hash of offset fixups (used in EXIF writing only)
55 FixBase - Flag set to attempt to fix base offsets
56 FixOffsets - Evaluated for each value pointer to patch maker note offsets
57 LastIFD - Used by WriteExif() to return offset of last IFD written
58 ImageData - Used by WriteExif() to avoid buffering large image data blocks
59 NoRefTest - Flag to bypass "referenced by previous directory" test
60
61 WRITE_PROC : Function reference or name for writing this directory. The
62 function returns the new directory data or undefined on error. It takes the
63 same arguments as the process proc above except that the second argument
64 (reference to directory information hash) is optional, and if specified gives
65 information about the source directory for tags to be copied to the output.
66
67 CHECK_PROC : Reference to a function which validates Raw values for writing.
68 The function takes 3-4 arguments: 0) ExifTool object reference, 1) tagInfo
69 reference, 2) value reference, and 3) [optional] conversion type. It returns
70 undefined (and possibly modifies the input value) if successful, or an error
71 message if there was a format problem. May set ExifTool CHECK_WARN datamember
72 for success with a warning.
73
74 INIT_TABLE : Routine called to do any necessary initialization before the
75 first time the table is loaded. Argument is a reference to the table.
76
77 GROUPS : A hash lookup for the default group names for all entries in this
78 table. If not specified, the default Group 0 and 1 names will be set
79 automatically according to the name of the module, and the default Group 2
80 name will be set to 'Other'.
81
82 FORMAT : Specifies the default tag Format, and corresponding pointer increment
83 for entries in a BinaryData table. Defaults to 'int8u' for BinaryData tables
84 if not specified. The possible values of FORMAT are:
85
86 int8s - Signed 8-bit integer (EXIF 'SBYTE')
87 int8u - Unsigned 8-bit integer (EXIF 'BYTE')
88 int16s - Signed 16-bit integer (EXIF 'SSHORT')
89 int16u - Unsigned 16-bit integer (EXIF 'SHORT')
90 int16uRev - Unsigned 16-bit integer, reversed byte order
91 int32s - Signed 32-bit integer (EXIF 'SLONG')
92 int32u - Unsigned 32-bit integer (EXIF 'LONG')
93 int64s - Signed 64-bit integer (BigTIFF 'SLONG8')
94 int64u - Unsigned 64-bit integer (BigTIFF 'LONG8')
95 rational32s - Rational consisting of 2 int16s values
96 rational32u - Rational consisting of 2 int16u values
97 rational64s - Rational consisting of 2 int32s values (EXIF 'SRATIONAL')
98 rational64u - Rational consisting of 2 int32u values (EXIF 'RATIONAL')
99 fixed16s - Signed 16-bit fixed point value
100 fixed16u - Unsigned 16-bit fixed point value
101 fixed32s - Signed 32-bit fixed point value
102 fixed32u - Unsigned 32-bit fixed point value
103 float - 32-bit IEEE floating point value (EXIF 'FLOAT')
104 double - 64-bit IEEE floating point value (EXIF 'DOUBLE')
105 extended - 80-bit extended floating float
106 ifd - Unsigned 32-bit integer sub-IFD pointer (EXIF 'IFD')
107 ifd64 - Unsigned 64-bit integer sub-IFD pointer (BigTIFF 'IFD8')
108 string - Series of 8-bit characters (EXIF 'ASCII')
109 undef - Undefined-format binary data (EXIF 'UNDEFINED')
110 binary - Binary data (same as 'undef')
111
112 Additionally, the following variable-length Format types may be used in
113 individual tag information hashes of a BinaryData table. The 'var_' formats
114 cause subsequent tag indices to be incremented according to the size of the
115 data, not including the terminator. See "Format" below for more details.
116
117 pstring - Pascal string (1-byte length followed by ASCII string)
118 var_string - variable-length null-terminated ASCII string
119 var_ustring - variable-length null-terminated UCS-2 string
120 var_pstring - variable-length Pascal string
121 var_pstr32 - variable-length Pascal string /w 32-bit len
122 var_ustr32 - variable-length UCS-2 string /w 32-bit len
123 var_int16u - variable-length undef data with int6u count
124 var_ue7 - variable-length 7-bit-at-a-time integer (BPG)
125
126 And the following format codes are used for string values in XMP metadata.
127 (See the XMP specification for more details.)
128
129 boolean - "True" or "False"
130 date - date/time string
131 integer - integer as a string
132 lang-alt - list of alternate-language strings
133 rational - "N/D" where N=numerator, D=Denominator
134 real - floating point value as a string
135 string - unformatted string
136 struct - structure
137
138 FIRST_ENTRY : Specifies the index for the first tag entry in a binary table.
139 This value is only used if the Unknown option is set to 2 or higher, and
140 allows the binary data to be scanned for unknown tag entries.
141
142 TAG_PREFIX : Prefix for names of unknown tags.
143
144 PRINT_CONV : Default print conversion for tags where PrintConv isn't
145 specified. PrintConv may be set to undef for individual tags to disable print
146 conversion when PRINT_CONV is defined for a table.
147
148 WRITABLE : Indicates that all tags in this table are writable. This is the
149 same as setting the Writable flag for each individual tag in the table, except
150 for SubDirectory tags which are not made Writable.
151
152 TABLE_DESC : Short description for this table. Plain text only. Used only
153 for XML tag database output.
154
155 NOTES : Notes to introduce the table in the TagNames documentation. Pod
156 formatting codes B<>, C<> and L<> may be used in this text.
157
158 IS_OFFSET : Writable BinaryData tables only. Reference to list of sorted
159 TagID's representing offsets.
160
161 IS_SUBDIR : Writable BinaryData tables only. A reference to a list of sorted
162 tag ID's representing subdirectories.
163
164 EXTRACT_UNKNOWN : Used in PDF tables to specify a directory where all unknown
165 tags should be extracted. Set to 0 to extract only unknown numbered tags for
166 which the unnumbered tag is known.
167
168 NAMESPACE : Namespace prefix for tags in the XMP table. If this isn't a
169 standard namespace defined in %Image::ExifTool::XMP::nsURI, then the URI must
170 be defined as well (however, this is not recommended for pre-defined
171 namespaces because then non-standard namespace prefixes won't be recognized).
172 To define the URI, the NAMESPACE value is a reference to a hash where the key
173 is the namespace prefix and and the value is the URI (alternatively, a
174 reference to a 2-element array containing the prefix and URI is also allowed
175 for backward compatibility). The NAMESPACE value may be undef for XMP tables
176 where tags have variable namespaces (in this case each tag must have a
177 Namespace entry).
178
179 PREFERRED : Set if the tags in this table should always be added when writing
180 information. Higher number are higher precedence. Overrides the order
181 specified by SetNewGroups(). When this feature is used, it may also be
182 desirable to specify a preferred group when calling InitWriteDirs() to write
183 these tags -- this avoids creating other directories for tags which are
184 already being creating in the preferred group.
185
186 PERMANENT : Tags in this table are Permanent, and can't be deleted. Maker
187 notes tags are Permanent by default, without the need to set this property.
188
189 SRC_TABLE : Used internally to store the source table name of a user-defined
190 tag table so the appropriate module can be loaded as required.
191
192 PRIORITY : Default Priority for all tags in this table.
193
194 AVOID : Flag set to Avoid writing all tags in this table.
195
196 WRITE_GROUP : Default WriteGroup for all tags in the table.
197
198 LANG_INFO : Code reference to a routine which returns a reference to a
199 language-specific tag information hash. The routine takes two arguments: a
200 reference to the non-specific tagInfo hash, and the language code. Used only
201 in tables with writable tags which support tag name language extensions (eg.
202 MIE and XMP).
203
204 VARS : Hash used to store additional parameters. Individual modules may use
205 this to store any parameters they want. The following additional parameters
206 have been defined, and may be used by any module:
207
208 ID_LABEL Label to use instead of "Tag ID" for column heading in tag
209 name documentation. When this is set, numerical TagID's are
210 not converted to hexadecimal notation. Unless otherwise set,
211 an ID_LABEL of "Index" is assumed for tables which use
212 ProcessBinaryData or set the IS_BINARY flag.
213
214 ID_FMT Format for tag ID's in the documentation. Setting is 'hex' to
215 print tag ID in hexadecimal (with 4 hex digits or more), 'dec'
216 to leave as decimal, 'str' to use a quoted string, or 'none'
217 to drop the "Tag ID" column entirely. Any setting other than
218 'hex' prevents hex-looking strings from being converted when
219 importing an XML file for language translations in
220 BuildLangModules().
221
222 NO_LOOKUP Do not add tags to TagLookup.pm lookup tables.
223
224 CAPTURE Used by PDF module to name dictionaries to capture when
225 writing.
226
227 MINOR_ERRORS [EXIF tables only] Flag to make errors in this IFD minor, or
228 to downgrade already minor errors to warnings while writing.
229 (Errors in MakerNote IFD's are already classified as minor.)
230 Note that for certain types errors, the response is to delete
231 the entire IFD from the image.
232
233 ALPHA_FIRST Sort alphabetical tags before numerical in documentation.
234
235 LONG_TAGS Suppress "Long tags" warning when generating documentation.
236 Value is the number of long tag names to expect.
237
238 SORT_PROC Reference to sort procedure for sorting tag ID's in the
239 documentation. Takes two arguments and returns -1, 0 or 1
240 if the first argument is less than, equal to, or greater than
241 the second argument.
242
243 ENTRY_SIZE Used by ProcessPhaseOne to specify size of IFD entry
244
245 MAP_FORMAT Lookup to map unknown format numbers (eg. Panasonic CameraIFD)
246
247 START_INDEX [QuickTime tables only] Initial index for indices shown in
248 Verbose output. Indices are not show otherwise.
249
250 ATOM_COUNT [QuickTime tables only] Maximum number of atoms contained in
251 within this atom. Currently used only for Canon CNTH atom,
252 which contains garbage after the first contained atom.
253
254 NIKON_OFFSETS [Nikon Encrypted tables only] Pointer to int32u NumberOffsets
255 for offset-type encrypted Nikon directories. When set,
256 directory and decryption lengths are calculated automatically.
257
258 ALLOW_REPROCESS Flag to allow reprocessing of another directory at this
259 same location in the file, bypassing recursion avoidance test.
260
261 IS_BINARY Set if this is a binary table and should show an Index in the
262 first column instead of a Tag ID.
263
264 DATAMEMBER : BinaryData tables only. A reference to a list of sorted tag ID's
265 which must be extracted as data members when writing. Must also list "var_"
266 format tags and tags with Hook so offsets are properly calculated if the table
267 is writable.
268
269 SET_GROUP1 : [EXIF tables only] Flag to set group1 name to the directory name
270 for all tags in the table.
271
272 The remaining entries in a tag table are the tag IDs with their associated
273 information. The information may exist in one of three forms: 1) A simple
274 scalar which is the name of the tag, 2) A reference to a hash of information
275 describing this tag, or 3) a reference to a list of hashes which contain
276 Condition expressions allowing the appropriate hash to be selected to suit the
277 conditions. The following is a description of possible hash entries. All
278 entries are optional, except for the tag Name which is required if the tag ID is
279 numerical, and generated automatically otherwise.
280
281 Name : The tag name. Tag names need not be unique. If they aren't
282 unique, then duplicate tags will hide the values of previous
283 tags when extracting information unless the Duplicates option
284 is set or the new tag has lower Priority. With Duplicates
285 set, to allow multiple tags with the same name to exist in the
286 tag information hash, the key of the previous tag is changed
287 to the form "TagName (N)", where N starts at 1 and increments
288 for subsequent duplicate tags. A tag name should start with
289 an uppercase letter, and contain only the characters in the
290 set [A-Za-z0-9_-]. If not given, the Name is taken from the
291 tag ID with the first character changed to upper case.
292
293 Description : A more readable description of tag name. If a tag doesn't
294 specify a Description, then the tag Name is used instead, with
295 spaces inserted between the words.
296
297 Notes : Notes for this tag in the HTML TagNames documentation.
298
299 Groups : Hash lookup for group names for this tag. If not specified,
300 defaults to the GROUPS specified in the table definition.
301
302 Format : Only valid for BinaryData, EXIF and IPTC tables. For a Binary
303 or EXIF table, this gives the format that is used to convert
304 the binary data, and is one of the FORMAT types specified
305 above. If not specified, the Format of an EXIF entry is taken
306 from the EXIF information, and the Format of a BinaryData
307 entry is taken from the FORMAT specified for the table (or
308 int8u if FORMAT is not specified). Must be specified for
309 Writable tags where the value must be converted for a
310 Condition. For BinaryData tables, the format may have a size
311 in trailing brackets which is a Perl expression to be
312 evaluated. The expression may access any of the previous
313 table entries through a %val hash (read-only tags), the data
314 size via $size, or the ExifTool object via $self. For
315 example, 'string[$val{3}]' defines a string with length given
316 by the table entry with tag index '3' (which may be a Hidden
317 tag). An initial "var_" may be added to the Format name of any
318 BinaryData tag with a size in brackets. In this case,
319 subsequent offsets are adjusted by the value length minus the
320 size of the default table FORMAT (eg. "var_int16u[10]" causes
321 subsequent offsets to be incremented by sizeof(int16u) * 10 -
322 sizeof(int8u) if the default table FORMAT is "int8u"). Note
323 that all "var_" Format tags (as well as tags with values used
324 within "var_" Format expressions) must have corresponding
325 DATAMEMBER entries.
326
327 Count : Used when writing EXIF information to specify the number
328 values to write, or the number of characters in a fixed-length
329 string. A value of -1 indicates that the count is variable
330 and should be determined by the number of values provided.
331 Defaults to 1 if not specified for non-string formats. Note
332 that this count corresponds to the specified Format, so if a
333 different-sized Writable format is defined, the actual count
334 written to the file will be different.
335
336 FixCount : Flag set to determine correct count from offsets in IFD. This
337 is necessary for some Kodak tags which write an incorrect
338 Count value.
339
340 Flags : Flags to specify characteristics for this tag. May be a
341 simple scalar flag name, a reference to a list of flag names,
342 or a reference to a hash of flag/value pairs. If not a hash
343 reference, the flag value is set to 1. Flags are expanded for
344 faster access at run time into members of the tagInfo hash,
345 and may be written directly as members if desired. The
346 available flag names are:
347
348 'AutoSplit' - [List tags only] Similar to ListSplit option,
349 but applied automatically to individual tags. Value specifies
350 pattern for split, or 1 for default pattern ',?\\s+'.
351
352 'Avoid' - avoid creating this tag when writing if possible.
353 This is only effective if another tag exists with the same
354 name. Setting this flag also sets the default Priority to 0
355 for this tag.
356
357 'Binary' - set to 1 for binary data. This has the same effect
358 as setting ValueConv to '\$val', but it it a bit cleaner and
359 avoids dummy ValueConvInv entries for writable tags. Has no
360 effect if ValueConv is defined for the tag. Some values may
361 be treated as binary data even if this flag is not set.
362
363 'BlockExtract' - set for writable directories in EXIF
364 information which are extracted by default. Otherwise
365 writable directories are only extracted as a block if
366 specified explicitly. Also used for Jpeg2000 and QuickTime
367 XMP-like tags to extract as a block with a name other than
368 'XMP'.
369
370 'ConvertBinary' - true to apply ValueConv and/or PrintConv to
371 Binary values (ie. SCALAR references). (By default, these
372 conversions are not done for Binary values.)
373
374 'DataMember' - name of exiftool data member associated with
375 this tag if it should be stored as a special data member when
376 writing information. Necessary only if the value of the tag
377 affects other written information. Currently only used for
378 tags in EXIF tables where it triggers the execution of the
379 RawConv to convert and store the value as an ExifTool data
380 member when writing.
381
382 'DataTag' - associated tag name containing data for offset or
383 byte count tags.
384
385 'DelGroup' - set if deleting this tag is the same as deleting
386 the group of the same name.
387
388 'Drop' - [IFD-format and PhaseOne makernote tags only] set to
389 1 for tags that should be excluded when rebuilding maker notes
390 when copying all tags. Set to a number larger than 1 to drop
391 only if data is larger than this size. Works for SubDirectory
392 tags too.
393
394 'EntryBased' - set to 1 if the offset for this value is based
395 on the IFD entry position. This allows individual values to
396 be entry-based even though some others aren't (as with the
397 Casio PrintIM information).
398
399 'Flat' - [flattened XMP structure tags only] must be set for
400 all pre-defined flattened tags (including user-defined
401 flattened tags). This flag is reset to 0 internally after all
402 associated flattened tags in the structure have been
403 generated.
404
405 'Flattened' - [reserved] used internally to mark Struct tags
406 which have been processed to generate flattened equivalents.
407
408 'NotFlat' - [XMP tags only] Flag indicates that this tag ID
409 does not represent a flattened tag. Used to avoid a conflict
410 if the tag ID would be the same as a generated ID for a
411 flattened tag. The result is that the flattened tag will not
412 be accessible.
413
414 'Hidden' - set to hide tag from the TagName documentation and
415 -list* command output. Also suppresses verbose output of a
416 BinaryData tag. A Hidden tag should also be marked as Unknown
417 or the RawConv should return undef so the tag is not normally
418 seen by the user. Set to 2 to bypass BuildTagLookup() warning
419 about violating these guidelines, or 0 to avoid being hidden
420 automaticallly when added at runtime with AddTagToTable().
421 Finally, setting to '' disables inclusion of the PrintConv
422 lookup in the documentation (for dynamically-added lookups,
423 eg. DICOM).
424
425 'IsComposite' - flag set for Composite tags
426
427 'IsImageData' - flag set if this is an image data offset to
428 be included in ImageDataHash calculation. Must have an
429 OffsetPair entry which is the ID of the corresponding size.
430
431 'IsOffset' - flag set if the tag represents an offset to some
432 data, and causes value will be adjusted to an absolute file
433 offset. If set to 2, the offset base of the parent directory
434 is used even if the base changes for the current directory
435 (only some maker notes are this messed up). Set to 3 if
436 absolute file offsets are used. May be set to an expression
437 to be evaluated. Expression may access $val and $et,
438 and is evaluated only when reading.
439
440 'iTXt' - [PNG TextualData tags only] flag to write tag as PNG
441 iTXt chunk even if it contains no special characters.
442
443 'List' - flag indicating that duplicate entries of this tag
444 are allowed, and will be accumulated in a list. Note that for
445 XMP information, 3 different types of lists are supported and
446 the List value specifies the type: 'Bag', 'Seq' or 'Alt'. As
447 well, a value of '1' is used internally in XMP to allow list
448 behaviour for a flattened tag which is itself not a list
449 element (eg. a member of list of structures). Note that in
450 ExifTool an XMP lang-alt tag (Writable="lang-alt") is NOT a
451 list-type tag (unless it is a list of lang-alt lists, which is
452 uncommon).
453
454 'IsList' - Flag to mark tag as List-type in the documentation
455 without accumulating entries from subsequent tags. Used when
456 the value for a single tag is a complete list.
457
458 'MakerNotes' - set if this tag is maker note data.
459
460 'MakerPreview' - set in the PreviewImageStart tag information
461 if the preview must be stored inside the maker notes.
462
463 'Mandatory' - set for mandatory tags. Used only by TagInfoXML
464 and for documentation purposes. Mandatory tags may be added
465 automatically by ExifTool.
466
467 'NestedHtmlDump' - flag set if value for this tag is also
468 dumped when processing the SubDirectory. This flag is implied
469 if the MakerNotes flag is set. Set to 2 if the dump should
470 only be underlined if nested inside other maker notes.
471
472 'NotIFD' - set for 'MakerNotes' SubDirectory tags only if the
473 SubDirectory is not EXIF IFD format. (Note: All SubDirectory
474 tags in the MakerNotes table are 'MakerNotes' type by
475 default.)
476
477 'OffsetPair' - set if the tag represents half of an offset/
478 byte count pair. Data for these tags must be handled
479 separately. Value is the tagID for the paired tag.
480
481 'Permanent' - flag indicates that a tag is permanent, and
482 can't be added or deleted from the file, although a new value
483 may be written if the tag already exists. By default, all
484 MakerNotes tags are permanent unless otherwise specified.
485
486 'PreservePadding' - [QuickTime only] flag to preserve the
487 original size of the QuickTime atom by padding with nulls when
488 writing with the QuickTimePad option.
489
490 'PrintHex' - specifies that unknown PrintConv values should
491 be printed in hex (eg. 'Unknown (0x1)'). Also causes
492 numerical tag values to be printed in hex in the HTML tag name
493 documentation, padded to the number of digits given by the
494 PrintHex value.
495
496 'PrintInt' - remove decimal part of tag ID in HTML tag name
497 documentation. (To avoid confusing ExifTool users because
498 the LensType decimal numbers are for internal use only.)
499
500 'PrintSort' - causes PrintConv values to be sorted by value
501 rather than key in the HTML tag name documentation.
502
503 'PrintString' - flag set to force PrintConv values to be
504 printed as strings in the documentation.
505
506 'Priority' - gives the priority of this tag while reading. If
507 set to zero, this tag will not override the value of previous
508 tags with the same name. If the priority is greater than
509 zero, this tag won't be overridden by subsequent tags unless
510 their priority is equal to or greater than this priority. A
511 special feature is that Priority 0 tags are automatically
512 incremented to Priority 1 if they exist in the IFD of the full
513 resolution image (as determined by SubfileType). If not
514 defined, the priority defaults to 1 for all tags except except
515 tags in IFD1 of JPEG images which default to priority 0.
516
517 'Protected' - bit mask to protect tags from writing:
518 Bit 0x01 indicates an 'Unsafe' tag, which is not set via
519 SetNewValuesFromFile() unless specified explicitly.
520 Bit 0x02 indicates a 'Protected' tag, which should not be set
521 directly by the user.
522
523 'PutFirst' - [EXIF only] flag to place this value before IFD0
524 when writing (ie. immediately after TIFF header). Only used
525 for values in main IFD's (IFD0, IFD1, etc) and IFD's where
526 SubIFD flag is set to 2 (currently only ExifIFD).
527
528 'RawJoin' - [List tags only] Joins raw List-type tag values
529 into a single string with a space separator, allowing
530 ValueConv and PrintConv to act on the concatenated string so
531 the tag does not exhibit list-type behaviour. When writing,
532 the inverse is performed and the value is split at whitespace.
533
534 'Resource' - [XMP only] flag to write value as an rdf:resource
535 in an empty element instead of as a normal string.
536
537 'SeparateTable' - set to list PrintConv values in a separate
538 table in the HTML documentation. Value is 1 for a table name
539 of 'Module TagName', or 'TAG' for 'Module TAG', or 'MODULE
540 TAG' to fully specify the table name. The table may have a
541 'Notes' entry for a description of the table.
542
543 'SetResourceName' - [Photoshop tags only] set to 1 to append
544 resource name to the extracted value (eg. 'VALUE/#NAME#/').
545 Also allows resource name to be appended when writing new
546 values. May be set to any value other than 1 for a default
547 resource name to use when writing if an appended name is not
548 provided.
549
550 'StructType' - [reserved] used internally by XMP writer for
551 flattened structure tags as a flag to indicate that one or
552 more enclosing structures has a TYPE field.
553
554 'SubDoc' - [Composite tags only] set to cause this Composite
555 tag to also be generated for each sub-document. To achieve
556 this, 'Main:' and 'Doc#:' prefixes are added to all Require'd
557 and Desire'd tag names which don't already start with 'Main:'
558 or 'Doc#:', and the Composite tag is built once for each of
559 the main document and all sub-documents. May be a reference
560 to a list of indices for Desire'd tags, one of which must
561 exist to generate this tag for sub-documents.
562
563 'SubIFD' - used in writing to determine that the tag specifies
564 an offset to a sub-IFD. When this flag is set, the Group1
565 name gives the name of the IFD. Must be set if and only if
566 the tag has a SubDirectory Start that references '$val' (this
567 is validated by BuildTagLookup). Set to 2 for standard EXIF
568 SubIFD's where the PutFirst flag is valid.
569
570 'Unknown' - this is an unknown tag (only extracted when the
571 Unknown option is set). This is set to 2 for Unknown tags in
572 binary tables (extracted when Unknown is 2).
573
574 'WriteNothing' - flag indicating that nothing is actually
575 written when this tag is set. It is a fake writable tag that
576 isn't actually written (eg. Geotag). Used to avoid processing
577 a file unnecessarily if nothing will actually be written.
578
579 'WritePseudo' - flag indicating that this is a writable pseudo
580 tag. If set, this tag may be written without actually writing
581 to the file (eg. FileName, FileModifyDate).
582
583 'WrongBase' - ['IsOffset' tags only] An expression using $self
584 that is evaluated to generate a base shift for 'IsOffset' tags
585 which use a different base than the rest of the tags.
586
587 RawConv : Used to convert the Raw value at extraction time (while the
588 image file is still open, unlike ValueConv and PrintConv below
589 which are done later only if the value is requested). May be
590 a scalar expression using $val (the Raw tag value), $self (the
591 current ExifTool object), $tag (the tag key), $tagInfo
592 (reference to the tag information hash), $priority (to
593 dynamically set the priority of a tag), and @grps (to
594 dynamically set the family and/or groups), or a code reference
595 with $val and $self as arguments (in which case $$self{grps}
596 may be used to set the groups). For Composite tags, $val is a
597 reference to a hash of source ("derived from") tag names, and
598 @val may be used to access the Raw values of these tags. The
599 returned value may be a scalar which is used as the new Raw
600 value, a scalar reference to a binary data value, a hash
601 reference for Composite tags, an ARRAY reference for a list of
602 values, or undefined to indicate that the tag should be
603 ignored. If RawConv is specified for a Composite tag, then
604 ValueConv and PrintConv evals will no longer have access to
605 the source @val and @prt values unless the input $val is
606 returned. RawConv may generate Warning or Error tags, while
607 ValueConv and PrintConv should not (see ValueConv note below).
608 Note: RawConv should only be used if necessary (in general,
609 only if the conversion may return undef to ignore the tag, or
610 if a Warning may be issued) because ValueConv is more
611 efficient since it is only executed if the tag value is
612 requested, while RawConv is executed for all extracted tags.
613 Note that a tag is still writable if it has a RawConv without
614 a RawConvInv (with the exception of QuickTime ItemList and
615 UserData tags, which specifically require this), but this is
616 not true for ValueConv/PrintConv.
617
618 ValueConv : Used to convert the Raw value to a useable form. May be a hash
619 reference to act as a lookup table, a scalar which is
620 evaluated as a Perl expression, a code reference to a
621 subroutine, or an ARRAY reference (in which case the value is
622 split at whitespace into a list of items and each item is
623 converted by the associated entry in the ValueConv list. A
624 special value of 'REPEAT' may be used to repeat the previous
625 conversion for all remaining elements). If a hash reference
626 is used and the Raw value doesn't appear as one of the keys,
627 then the converted value is set to "Unknown (X)", where X is
628 the Raw value (unless either of the special keys exist:
629 'BITMASK', a reference to a hash used to decode individual
630 value bits; or 'OTHER', a reference to a subroutine used to
631 convert unknown values. The OTHER subroutine takes 3
632 arguments: the value, a flag which is set for the inverse
633 conversion, and a reference to the PrintConv hash, and returns
634 the converted value or undef on error -- it may call warn() to
635 return an error message. The lookup hash may also contain a
636 'Notes' entry which is used for documentation if the
637 SeparateTable flag is set). In an expression, $self is a
638 reference to the current ExifTool object, $val is the Raw
639 value, and $tag is the tag key. The subroutine takes 2
640 arguments: the Raw value and a reference to the current
641 ExifTool object. The advanced formatting expression (if any)
642 may be accessed via the ExifTool "FMT_EXPR" member variable.
643 The expression or subroutine is evaluated if and when the tag
644 value is requested (ie. only after all extraction is
645 complete), so if necessary at this time the values of all
646 other tags are available via calls to
647 $self->GetValue("Tag","Raw"). (Note: In theory, types other
648 than "Raw" may be accessed, but they are slower and may lead
649 to cyclical dependencies so they should be avoided). When
650 evaluated, the expression or subroutine returns a scalar for
651 the converted value, a SCALAR reference to a binary data value
652 (see the 'Binary' flag), or an ARRAY reference for a list of
653 values. The return value should always be defined -- use
654 RawConv instead to return undef if it is necessary to test the
655 value for validity, otherwise an undef tag may hide a
656 previously defined value when the Duplicates option is not
657 enabled. If this isn't possible (as with Composite tags where
658 the converted values of the source tags are needed), set the
659 Priority to 0 to avoid taking priority over a valid tag. If
660 ValueConv is not specified, the Raw value is not converted.
661 Composite tags which Require or Desire other tags may access
662 the ValueConv, PrintConv and Raw values of these tags through
663 the elements of the @val, @prt and @raw lists respectively
664 (only if there was no RawConv or it returned a hash
665 reference). For these tags, $val may be used in an expression
666 to represent $val[0], and the first argument passed for a code
667 reference is a reference to @val. Note: Warnings issued by
668 these conversions are intercepted by ExifTool and saved as
669 Warning tags, but since ValueConv and PrintConv conversions
670 are done on demand, the warnings may be generated after the
671 list of extracted tags is returned, so may easily be missed.
672
673 PrintConv : This entry is similar to ValueConv above, except that it is
674 used to further convert the tag value to a human readable
675 form. It can be either a hash lookup, a scalar Perl
676 expression, a code reference or a list reference. In this
677 expression, $self, $val and $tag may be used as with
678 ValueConv, but if ValueConv was defined then $val is the
679 ValueConv value instead of the Raw value. Composite tags
680 may also use the @val, @prt and @raw lists. The returned value
681 should always be defined. Note that the print conversion is
682 only done if the PrintConv option is enabled (which it is by
683 default), and if the result of the ValueConv is not a scalar
684 reference. If it is a list reference, then the converted
685 values are joined by '; ' in the output string.
686
687 RawConvInv : The inverse of RawConv. This should only be used in very rare
688 situations when the raw value can not be predetermined.
689 Unlike the other inverse conversions which are applied in
690 SetNewValue(), this conversion is applied in WriteInfo() as
691 the file is being written. This is important because it means
692 that FILE_TYPE and any DataMember tags ocurring before this
693 tag in the file are available. Beware that if the return
694 value is not defined, the tag will be deleted unless there is
695 specific logic to avoid this (currently, only EXIF and Binary
696 data directories handle this case).
697
698 ValueConvInv : The inverse of ValueConv. Only necessary for Writable tags
699 when ValueConv is specified (except WriteAlso tags). Note
700 that DataMember tags may NOT be used in the inverse
701 conversions because these conversions are done before the
702 input file is parsed. Instead, a Condition or RawConvInv must
703 be used. May return undef on conversion error and call warn()
704 to issue a warning. If warn() is not called, a generic
705 warning is generated when undef is returned. An empty warning
706 ("\n") may be issued to suppress warning messages when undef
707 is returned. If a scalar, the expression may use the
708 variables $val, $self and $wantGroup. If a code ref, the
709 routine is passed 2 arguments: $val and $self. Note that this
710 conversion is not applied for deleted tags (ie. $val is
711 undef).
712
713 PrintConvInv : The inverse of PrintConv. Necessary for Writable tags
714 when PrintConv is specified (unless WriteAlso is used), but
715 may be used without PrintConv. See ValueConvInv above for
716 more details.
717
718 PrintConvColumns : Number of columns for PrintConv lookup in HTML docs. If not
719 set, the number of columns is determined automatically
720 according to the maximum width of the entries.
721
722 DelValue : Raw value to be used when deleting a permanent tag. (Note all
723 MakerNotes tags are permanent.) If not specified, an attempt
724 is made to convert an empty string for the raw value.
725
726 Validate : Scalar expression used to validate the raw value of a tag when
727 the Validate option is set. The expression may access $val
728 (the Raw tag value), $tag (the tag key) and $self (the current
729 ExifTool object), and should return a warning if any problem
730 is found, or false if OK. The evaluation is performed in the
731 Image::ExifTool::Validate package namespace, so functions of
732 this package need not be prefixed by the package name.
733
734 Relist : [Only if ValueConv or PrintConv is a list ref] Reference to a
735 list of original value indices used to reorganize values. Each
736 entry in the list may be a scalar index, or a reference to a
737 list of indices to join values. (Currently values may be
738 joined, but the order of writable values must not be changed
739 until this ability is added to the writer.)
740
741 Mask : [BinaryData tags only] Bitmask for this value. (Multiple tags
742 may have the same index by using floating point indices. An
743 unknown tag will only be generated for a certain TagID if
744 there is no integral TagID for that tag.) The Mask and
745 BitShift are applied before evaluating RawConv.
746
747 BitShift : [Mask tags only] Bit shift for Mask-ed values. If not
748 specified, set to the number of trailing zero bits in Mask.
749 When reading, the value is shifted right by this number of
750 bits after the Mask is applied.
751
752 Condition : If given, specifies scalar which is evaluated as a Perl
753 expression at extraction time to decide whether the tag is
754 valid. If used in a list of alternate tag definitions, the
755 first list entry with a true condition is taken. If no
756 condition exists, then a 'true' condition is assumed. The
757 expression may use $self to access the ExifTool object. The
758 first 128 bytes of the binary data value are accessible
759 through the reference $valPt for EXIF, Jpeg2000, QuickTime,
760 FLAC and BinaryData tags only. (Note that for BinaryData tags,
761 the binary data of $$valPt is always 'undef' type and consists
762 of the bytes from the start of the value to the end of the
763 BinaryData block. Also, it may not be used when writing
764 except for SubDirectory tags.) EXIF tags (and maybe some
765 other types) may also reference the format string and value
766 count through $format and $count. Note that if the value is
767 writable and $valPt is used, the tag must have a Format
768 (unless 'undef' or 'string'), and a Count (unless 1 or length
769 of the 'undef' or 'string'), so the binary data may be
770 generated for evaluating the Condition. When writing, $valPt,
771 $format and $count refer to the new value, except for
772 MakerNotes tags where $format and $count refer to the old tag
773 if it existed.
774
775 Require : [Composite tags only] A hash reference specifying the tags
776 required to calculate the Composite tag value. The hash
777 values are the names of the required tags, and the keys
778 specify the indices where the tag values are stored in the
779 @val list used in the ValueConv and/or PrintConv expression.
780 The Composite value is only calculated if the values for all
781 Require'd tags are defined. Require, Desire and Inhibit tag
782 names may be prefixed by an optional group family 0 or 1 name
783 followed by a colon. Case IS significant. The keys used by
784 the Require, Desire and Inhibit hashes must not overlap (since
785 they are used as indices into the common @val, @prt and @raw
786 lists), and together the keys must be sequential starting from
787 0. A special feature allows a scalar tag name to be used
788 instead of the hash reference, in which case the next
789 available index will be used (avoiding collisions with Desire
790 and Inhibit hash entries). For example, the following two
791 definitions are equivalent:
792
793 Require => { 0 => 'XMP:Title' },
794 Require => 'XMP:Title',
795
796 Desire : [Composite tags only] This is the same as Require except that
797 the Composite value is calculated even if the specified tags
798 don't exist. Beware that the elements of @val, @prt and @raw
799 may be undefined for Desire'd tags. If no tags are Require'd,
800 at least one of the Desire'd tags must exist for the Composite
801 tag to be generated. If there are no Require'd or Desire'd
802 tags, then the Composite tag is always generated. A scalar
803 Desire tag name is given the next available index (after
804 scalar Require tags are allocated).
805
806 Inhibit : [Composite tags only] Similar to the Require and Desire
807 hashes, except that the Composite tag is NOT built if any of
808 the Inhibit tags exist. A scalar tag name is given the next
809 available index (after scalar Require and Desire tags are
810 allocated).
811
812 Shift : [Writable tags only] Specifies type of shift to apply if this
813 value may be shifted. Set to 'Time' for shifting date/time
814 tags, or '0' to prevent tag from being shifted or
815 conditionally deleted. May not be used for Writable Composite
816 tags.
817
818 Writable : Indicates this tag can be written (or not written if Writable
819 is set to zero), and for EXIF and QuickTime tables gives
820 format for writing. Writable may be set to 1 for MakerNotes
821 information because the existing format is always used,
822 however providing a format is desirable because it is used in
823 validating the value. Set to 2 for tag to show "yes" in the
824 Writable column of the tag name documentation even when there
825 is no WRITE_PROC defined (eg. if it is written via an Extra
826 tag). For EXIF and QuickTime tables, the Writable flag may be
827 different than the Format flag, in which case Format is used
828 for converting the binary value and Writable specifies the
829 format code written to the EXIF IFD. For SubDirectories in
830 EXIF information, this flag is only defined if the
831 SubDirectory is writable as a block, or if the SubDirectory
832 can not be edited (in which case Writable is set to 0). If
833 non-zero, the SubDirectory is also extracted as a block, so
834 the Binary and Protected flags should usually set as well.
835 There is currently no way to specify a write format for a
836 SubDirectory that is not writable as a block (the default is
837 'int32u' for IFD-type SubDirectories, and 'undef' for all
838 others).
839
840 WriteAlso : Used for writable tag to specify other tags to write when this
841 tag is written. The value is a hash reference. The hash keys
842 are the names of the tags to write, and the values are
843 evaluated to obtain the ValueConv values of each tag (or undef
844 to delete the tag). In the eval, $val is the new Raw value of
845 the parent tag (which may be undef if the tag is being
846 deleted, and should not be modified because it will affect
847 subsequent WriteAlso tags), and the %opts hash may be accessed
848 to modify SetNewValue options for each tag. By default, Type
849 is set to "ValueConv" and the Protected option has bit 0x02
850 set to allow writing of Protected tags that aren't directly
851 writable. The AddValue, DelValue, Shift and Replace options
852 from the parent tag are also defined, but no other options are
853 set by default. Previous new values of WriteAlso tags have
854 already been removed prior to the eval if the Replace option
855 was used for the parent tag. If an empty warning is issued
856 ("\n"), the target tag is not written and no error is
857 reported.
858
859 WriteCheck : If given, specifies a scalar which is evaluated as a Perl
860 expression for a one-time validatation the Raw value being
861 written. The expression has access to 3 variables: $val is
862 the value to be written, $self is the ExifTool object, and
863 $tagInfo is the tag information hash reference. It returns an
864 error string, or undef if the value is good. If the error
865 string is empty, the tag is not written and no warnings are
866 issued, but WriteAlso is still evaluated if it exists.
867
868 WriteHook : [QuickTime only] Routine to call with these arguments when tag
869 is encountered during writing: 0) tag value, 1) ExifTool ref.
870
871 WriteOnly : Flag set if tag is write-only. Used for documentation only.
872
873 DelCheck : Similar to WriteCheck, but called when the tag is deleted. The
874 expression may access $self, $tagInfo and $wantGroup. Returns
875 error string, or undef on success, and may set $val to
876 something other than undef. May return empty string ('') to
877 suppress warning messages but not delete tag (eg. when
878 deleting only associated tags).
879
880 WriteCondition: [Writable EXIF tags only] Specifies a condition to be
881 evaluated before the tag can be written to a specific file.
882 The condition may use $self to reference the ExifTool object,
883 and returns true if it is OK for writing. Unlike WriteCheck
884 which is done only once when the new value is set, this
885 condition is evaluated just before the tag is written to the
886 file.
887
888 WriteGroup : [Writable EXIF and Composite tags only] Specifies the IFD
889 where the information gets written by default. Must be
890 defined for writable EXIF tags if WRITE_GROUP is not specified
891 in table. A WriteGroup of 'All' is special: For writable
892 Composite tags this causes any group specified for the
893 Composite tag to be propagated to the WriteAlso tags when
894 writing. For other tags this allows writing to all EXIF IFD's
895 simultaneously (in which case the tag should have a Condition
896 or WriteCondition to restrict the IFD's to which the tag is
897 actually written).
898
899 IsOverwriting : [Writable EXIF tags only] Specifies reference to subroutine
900 which determines if tag should be overwritten. Arguments are:
901 0) ExifTool object ref, 1) new value hash ref, 2) old value,
902 3) new value reference.
903
904 Preferred : This tag is always preferred when writing.
905
906 Override : [User-defined Composite tags only] Flag to specify that the
907 new tag definition should override the definition of existing
908 Composite tags with the same name. Default is 1 unless
909 otherwise specified.
910
911 AllowGroup : [Writable tags only] Regular expression string (case
912 insensitive) to match group names which are allowed when
913 writing this tag. Only needed if tag can be written to
914 groups other than the normal groups for this tag (very rare).
915
916 Deletable : [Writable SubDirectory's only] Overrides internal test for
917 metadata types with permanent directories (currently QuickTime
918 and Jpeg2000), allowing the tag containing these directories
919 to be deleted. Note that either the tag's SubDirectory
920 DirName (which defaults to the TagName if not specified) or
921 the family 0 group name of the SubDirectory TagTable must
922 match a deletable group name.
923
924 OffsetPair : Used in EXIF table to specify the tagID for the corresponding
925 offset or length tag.
926
927 DataTag : Used in EXIF table to specify the tag name of the data
928 associated with offset/length tags.
929
930 FixFormat : [Writable EXIF SubIFD SubDirectory's only] Used to specify a
931 format for writing an IFD pointer other than 'int32u'.
932
933 ChangeBase : [EXIF tags in JPEG images only] Eval used to return new base
934 for the offset for this tag only. Eval may use $dirStart and
935 $dataPos. Note this is geared to the quirky Leica preview
936 image offset, and is only used if the preview is outside the
937 APP1 EXIF segment.
938
939 BitsPerWord : [BITMASK tags only] Number of bits per decoded word. Defaults
940 to 32 if not specified.
941
942 BitsTotal : [Writable BITMASK tags only] Total number of bits in bit mask.
943 Defaults to BitsPerWord if not specified.
944
945 FixedSize : [EXIF only] Hack to ignore value size and use this instead.
946 Only valid if Format is also defined.
947
948 TruncateOK : [EXIF only] Hack to demote a truncated value in an IFD to a
949 minor error.
950
951 Struct : [XMP tags only] Reference to structure hash for structured XMP
952 tags. See "STRUCTURES" section below for more details. (For
953 backward compatibility, this may be a name to an entry in
954 %Image::ExifTool::UserDefined::xmpStruct, but this use is
955 deprecated.) Flattened tags are automatically generated for
956 each field in the structure. Note that Struct tags can NOT
957 have ValueConv/PrintConv entries, because values that are HASH
958 references are are also used by Composite tags, which use the
959 the Conv entries to generate the Composite value.
960
961 NoSubStruct : [XMP tags only] Flag set in flattened tag to break cyclical
962 recursion in nested structures.
963
964 Namespace : [XMP tags only] Gives standard XMP namespace prefix to use for
965 this tag. If not defined, the tag table NAMESPACE is used.
966
967 FlatName : [Struct tags and structure fields only] Name used for
968 automatically-generated flattened tag names, defaults to Name
969 if not specified. In general, this is used to remove the
970 redundant names found in some specifications. May be empty
971 ('') for a Struct tag but not for a structure field.
972
973 Units : [MIE tags only] Reference to a list of valid units strings.
974 The default units are the first item in the list.
975
976 Hook : [BinaryData tags only] Expression to be evaluated when
977 extracting tag to allow dynamic Format, etc for BinaryData
978 tags. May access $self, $size (the full size of the binary
979 data record), $dataPt (reference to the data block), and $pos
980 (position of this tag in the data block), and assign a new
981 value to $format to dynamically set the tag format, and/or
982 increment $varSize to add a byte offset to subsequent tags.
983 $varSize may be set to a large number to effectively abort
984 processing of the directory after this tag. Must have
985 corresponding DATAMEMBER entry in writable tables. Must not
986 have Unknown set.
987
988 LargeTag : [BinaryData tags only] Flag to indicate that the data for this
989 tag is large, and that it shouldn't be stored in the %val
990 hash, even if the tag exists as a DATAMEMBER.
991
992 SetBase : [QuickTime and BinaryData tags only] Sets ExifTool BASE offset
993 for use when ExtractInfo is called with the ReEntry flag from
994 inside the RawConv of a tag.
995
996 ByteOrder : [Non-writable tags extracted with HandleTag and writable EXIF
997 offset-pair tags only] Specifies byte order if tag value is
998 stored with a constant byte order that is different from that
999 of the parent directory.
1000
1001 DontRead : [QuickTime tags with compatible SubDirectory entries only]
1002 Avoid reading subdirectory data from file. Instead, pass RAF
1003 reference (with current position at start of directory) and
1004 DirEnd.
1005
1006 TagID : [reserved] Used internally to save the table key for this tag.
1007 Note: For XMP tables this corresponds to the XMP property
1008 name, but the table key may have a full XMP namespace prefix
1009 added.
1010
1011 NewTagID : [reserved] Used internally to save new ID of tag in Composite
1012 table if it is different that the original TagID (happens if
1013 there was a conflict with an existing entry in the table)
1014
1015 Index : [reserved] Used internally to save the index of tagInfo items
1016 which are in a conditional list.
1017
1018 Table : [reserved] Reference to parent tag table.
1019
1020 PropertyPath : [reserved] Used internally by XMP writer to save property path
1021 name. Also used in structure field information hashes, but
1022 for these the full property path is not stored.
1023
1024 SrcTagInfo : [reserved] Used internally to store reference to default
1025 language tagInfo hash for alternate-language tags.
1026
1027 OtherLang : [reserved] Used internally by QuickTime module to store a list
1028 of tag ID's for alternate-language tags based on this one.
1029
1030 ParentTagInfo : [reserved] Used internally to store a reference to the tag
1031 information hash of the parent structure for flattened
1032 structure tags.
1033
1034 RootTagInfo : [reserved] Used internally to store a reference to the tag
1035 information hash of the top-level structure for flattened
1036 structure tags.
1037
1038 Module : [reserved] Used internally to store module name for writable
1039 Composite tags.
1040
1041 LangCode : [reserved] Used internally to indicate language code for
1042 alternate language tags (eg. 'fr'). Only used with formats
1043 which support alternate languages (eg. XMP, MIE, etc).
1044
1045 AddedUnknown : [reserved] Used internally to mark Unknown tags that were
1046 added to the table at run time.
1047
1048 SubDirectory { If it exists, this specifies the start of a new subdirectory.
1049 It contains a collection of variables which specify the type
1050 and location of the subdirectory. Note that ValueConv and
1051 PrintConv do not apply to SubDirectory tags, but RawConv is
1052 evaluated before the SubDirectory is processed. The following
1053 is a list of SubDirectory variables:
1054
1055 TagTable : Specifies the name of the tag table lookup for the new
1056 subdirectory. If not specified, the parent tag table is used.
1057
1058 Start : The offset to the start of the subdirectory relative to the
1059 current Base. This is a Perl expression which may use
1060 $valuePtr to represent the location of the tag value in the
1061 file, or $val for the value itself. If not specified, a Start
1062 of '$valuePtr' is assumed. Subdirectories in BinaryData may
1063 also use $dirStart to represent the offset of the current
1064 directory start relative to the start of the data block.
1065
1066 OffsetPt : [EXIF directories only] If specified, this is a Perl
1067 expression that gives the position of a 32-bit word in the
1068 current directory that is added to the Start position to get
1069 the position of the new subdirectory. The expression
1070 should use the position of the current tag ($valuePtr).
1071
1072 Base : This expression specifies the base offset for all pointers in
1073 the subdirectory. This need not be specified if the offset is
1074 the same as the current directory, which is normally the case.
1075 May use $start to represent the subdirectory start location
1076 relative to the current base, and $base for the value of the
1077 current base. If this is defined, the automatic validation of
1078 base offsets is disabled for maker notes directories. The IFD
1079 is flagged as using relative offsets when writing if '$start'
1080 is used in this expression.
1081
1082 EntryBased : [EXIF directories only] Flag indicating that the offsets are
1083 based on the individual directory entry position, so offsets
1084 are incremented by 12 times the corresponding entry index.
1085
1086 MaxSubdirs : Maximum number of subdirectories specified by the current tag
1087 (if the tag specifies multiple values). If not specified, the
1088 tag value ($val) is used as-is. If MaxSubdirs is specified,
1089 then one subdirectory is parsed for each value found up to the
1090 maximum number specified. Ignored when writing.
1091
1092 ByteOrder : Specifies byte ordering if different than than the rest of the
1093 file. Must be either BigEndian, LittleEndian or Unknown. If
1094 Unknown is specified, the byte order will be determined from
1095 the directory count for EXIF (however, this can not be done if
1096 OffsetPt is specified).
1097
1098 Validate : If given, specifies Perl expression which is used to validate
1099 the subdirectory data (regardless of Validate option setting).
1100 The following variables may be used in the expression: $val
1101 (value of the tag), $dirData (reference to directory data),
1102 $subdirStart (offset to subdirectory start) and $size (size of
1103 subdirectory). Returns true if subdirectory is valid.
1104
1105 ProcessProc: If given, specifies processing procedure used to decode this
1106 subdirectory data. This overrides the default procedure
1107 specified by PROCESS_PROC in the tag table.
1108
1109 WriteProc : If given, specifies processing procedure used to write this
1110 subdirectory data. This overrides the default procedure
1111 specified by WRITE_PROC in the tag table.
1112
1113 DirName : Name of this subdirectory. If not specified, the name is
1114 taken from the tag name. DirName is important because it is
1115 used when writing to compare against names in the directory
1116 map to determine which directories need to be edited.
1117
1118 FixBase : Flag set if base offsets should be fixed. Used to add a
1119 constant to maker notes offsets to fix damage done by some
1120 image editing utilities. (maker notes only) Set to 2 for
1121 unknown maker notes to be a bit more flexible in adjusting
1122 the base offset.
1123
1124 AutoFix : Flag set to patch GE makernote offset quirks and apply FixBase
1125 without warnings when writing.
1126
1127 FixOffsets : Expression to evaluate for each value pointer to patch
1128 problems with some EXIF maker note offsets. May access the
1129 following variables: $valuePtr, $valEnd, $size, $tagID and
1130 $wFlag. May return undef when writing to ignore the entry.
1131
1132 RelativeBase:[EXIF directories only] Flag to adjust all offsets relative
1133 to the start of the IFD when writing.
1134
1135 Multi : [EXIF directories only] Flag to allow multiple linked IFD's.
1136 1 is assumed if DirName is IFD0 or SubIFD unless otherwise
1137 defined.
1138
1139 Magic : [TiffIFD directories only] Magic number used in TIFF-like
1140 header.
1141 }
1142
1143 STRUCTURES
1144
1145 Structure hashes are very similar to tag tables in that their keys are structure
1146 field ID's and their values are structure field information hashes. The special
1147 keys in structure hashes are:
1148
1149 NAMESPACE : Same as in tag tables, but may be set to undef for a
1150 variable-namespace structure which holds any top-level tag. This
1151 is mandatory for built-in tags, but optional for user-defined
1152 tags (where it defaults to the NAMESPACE of the tag table).
1153
1154 STRUCT_NAME : Name of structure (used in warning messages and documentation).
1155 May contain leading module name separated by a space to avoid
1156 name conflicts with same-named structures in other modules.
1157 Default module is "XMP" unless otherwise specified.
1158
1159 TYPE : rdf:type resource for structure.
1160
1161 NOTES : Notes for documentation.
1162
1163 GROUPS : Same as in tag table, but only the family 2 group name is used,
1164 as the default for the flattened tags.
1165
1166 SORT_ORDER : Order for sorting fields in documentation.
1167
1168 The contained structure field information hashes are similar to tag information
1169 hashes, except that only the following elements are used:
1170
1171 Raw/Value/PrintConv (and their inverses), TagID (optional), Groups, List,
1172 Writable, Struct, Namespace, FlatName, LangCode, PropertyPath, Notes.
1173
1174 But note that for PropertyPath, only the element of the path corresponding to
1175 the specific field is stored (including any necessary list properties). The
1176 full property path is obtained by walking the structure tree.
1177
1178 Flattened tags corresponding to each field in a structure are automatically
1179 generated (using an on-demand approach to reduce startup overhead). Pre-defined
1180 flattened tags are allowed, and are used when it is necessary to change the Name
1181 or Description of a flattened tag. The flattened tag information hash entries
1182 are copied from the corresponding structure field definitions, even for
1183 pre-defined flattened tags. The exception is that the List property is
1184 generated automatically unless explicitly set to 0 in a pre-defined flattened
1185 tag.
1186
1187 --------------------------------------------------------------------------------