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