source: gs2-extensions/parallel-building/trunk/src/perllib/cpan/Image/ExifTool/README@ 24626

Last change on this file since 24626 was 24626, checked in by jmt12, 13 years ago

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