--------------------------------------------------------------------------------
File: Image/ExifTool/README
Description: ExifTool support modules documentation
The ExifTool support modules are loaded by ExifTool to interpret various formats
of meta information.
The tables in these files are used as lookups based on the EXIF tag 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. The corresponding hash value provides information about
the tag (explained later).
Eleven special keys (PROCESS_PROC, WRITE_PROC, CHECK_PROC, GROUPS, FORMAT,
INCREMENT, FIRST_ENTRY, TAG_PREFIX, PRINT_CONV, DID_TAG_ID and WRITABLE) 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:
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. The process proc returns 1 on success or 0 on failure, and takes
3 arguments: 0) reference to the ExifTool object, 1) reference to the tag
table hash, 2) reference to a directory information hash, with the following
members:
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
Nesting - Nesting depth in directory tree
DirName - Name of this directory
Parent - Name of parent directory
RAF - Reference to File::RandomAccess object if available
Multi - True if we should scan for multiple IFD's
NewDataPos - File position of new data (write proc only)
Fixup - Reference to hash of offset fixups (used in EXIF writing only)
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.
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.
The possible values of FORMAT are:
int8s - Signed 8-bit integer
int8u - Unsigned 8-bit integer
int16s - Signed 16-bit integer
int16u - Unsigned 16-bit integer
int32s - Signed 32-bit integer
int32u - Unsigned 32-bit integer
int64s - Signed 64-bit integer
int64u - Unsigned 64-bit integer
rational16s - Rational consisting of 2 int16s values
rational16u - Rational consisting of 2 int16u values
rational32s - Rational consisting of 2 int32s values
rational32u - Rational consisting of 2 int32u values
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
double - 64-bit IEEE floating point value
string - Series of 8-bit ASCII characters
binary - Binary data
INCREMENT : If specified, overrides the default increment for a BinaryData
table. The default increment is the number of bytes in the FORMAT type.
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 tags where PrintConv isn't specified.
DID_TAG_ID : Used by GetTagID() as a flag to indicate that TagID's have been
defined for all tags in this table. This may be set in the table definition
to prevent GetTagID() from assigning TagID's.
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.
The remaining entries in a tag table are the EXIF tags 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:
Name : [required if tag is numerical] The tag name. Tag names need
not be unique. If they aren't unique, duplicate tags
overwrite values of previous tags unless the Duplicates option
is set. With Duplicates set, the name of the previous tag is
changed to the form "TagName (N)" where N starts at 1 and
increments for subsequent duplicate tags.
Description : [optional] 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.
Groups : [optional] Hash lookup for group names for this tag.
Format : [optional] Only valid for BinaryData, EXIF and IPTC tables.
For a Binary or EXIF table, this gives the format of the data,
and is one of the FORMAT types specified above. 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, or the data size via $size. For example,
'string[$val{3}]' defines a string with length given by the
table entry with tag index '3'. 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).
For IPTC tables, the only valid Format type is binary,
otherwise the data is assumed to be string.
Count : [optional] Count to override count in EXIF IFD entry.
Flags : [optional] 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. The available flag
names are:
'List' - indicates that duplicate entries of this tag should
be accumulated in a list (a comma separated string of
PrintConv values and a reference to an array of ValueConv
values). The value is the list type for XMP lists.
'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.
'Protected' - indicates that even though this tag may be
writable, it can not be set directly by the user. (Instead,
it is set via the Require tags of a composite tag.)
'PrintHex' - specifies that unknown PrintConv values should
be printed in hex (ie. "Unknown (0x0)")
'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.
'IsOffset' - flag set if the tag represents an offset to some
data, and causes value will be adjusted to an absolute file
offset.
'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.
'DataTag' - associated tag name containing data for offset or
byte count tags.
'MakerNotes' - set if this tag is maker note data.
'DataMember' - name of exiftool data member associated with
this tag if it should be stored as a special data member.
'Permanent' - flag indicates that a tag is permanent, and
can't be added or deleted from the file. By default, all
MakerNotes tags are permanent unless otherwise specified.
'Avoid' - avoid creating this tag if possible.
ValueConv : [optional] Used to convert the raw data value to a useable
form. May be either a hash reference to act as a lookup table
or a scalar which is evaluated as a Perl expression. 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. In an expression, $val is the raw
value, $dataPt may be used to access the original EXIF data
block, and $self is a reference to the current ExifTool
object. Composite tags which Require or Desire other tags may
access the ValueConv and PrintConv values of these tags
through the elements of the @val and @valPrint lists. The
result of the ValueConv evaluation may be undefined to
indicate the tag should be ignored. If ValueConv is not
specified, the raw value is not converted.
PrintConv : [optional] 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 or a scalar
Perl expression. In this expression, $val represents the
result of the ValueConv from above. When evaluated, the
expression may return either a scalar representing the a
printable value, or a scalar reference to the value if it is
not printable (as with a binary data block). Note that the
print conversion is only done if the PrintConv option is
enabled (which it is by default).
ValueConvInv : [optional] The inverse of ValueConv. Only necessary if
ValueConv is specified and this tag is Writable.
PrintConvInv : [optional] The inverse of PrintConv. Only necessary if
PrintConv is specified and this tag is Writable.
Condition : [optional] If given, specifies scalar which is evaluated as a
Perl expression to decide whether the tag is valid. If used
in a list, the first list entry with a true condition is
taken. If no condition exists, then a 'true' condition is
assumed. The previous value for this tag is available as
$oldVal for use in the logic expression.
Require : [Composite tables only] Specifies a list of tag names for
values which are required in order to calculate the composite
value. The values are stored in a @val list in the positions
specified by the Require keys, and can be used in a ValueConv
or PrintConv expression. The composite value is only
calculated if the values for all Require'd tags are defined.
Desire : [Composite tables only] This is the same as Require except
that the value is still calculated even if the specified tags
don't exist. Beware that the elements of @val and @valPrint
may be undefined for Desire'd tags. Both Require and Desire
may exist together, however be sure to specify unique keys for
each tag since they are used as indices into the @val and
@valPrint lists.
TagID : [reserved] This entry is used internally by GetTagID() to
cache tag ID numbers for speed.
Writable : [optional] 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 value and Writable specifies the
format code written to the EXIF IFD.
WriteGroup : [optional] Required for writable EXIF tags to specify the IFD
where the information gets written.
WriteCondition: [optional] Only meaningful for writable EXIF tags. Specifies
a condition to be evaluated before the tag can be written.
OffsetPair : [optional] Used in EXIF table to specify the tagID for the
corresponding offset or length tag.
DataTag : [optional] Used in EXIF table to specify the tag name of the
data associated with offset/length tags.
SubDirectory { [optional] 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 : [optional] Specifies the name of the tag table lookup for the
new subdirectory. If not specified, the current tag table is
used.
Start : [optional] 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 : [optional] 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 : [optional] 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.
MaxSubdirs: [optional] 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.
ByteOrder : [optional] 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 : [optional] 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).
ProcessProc : [optional] If given, specifies processing procedure used
to decode this subdirectory data. This overrides the default
procedure specified by PROCESS_PROC in the tag table.
DirName : [optional] Name of this subdirectory. If not specified, the
name is taken from the TagTable default GROUP0 name, or from
the tag Group1 name if no TagTable specified.
}
--------------------------------------------------------------------------------