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