README 58 KB

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