2089 lines
113 KiB
HTML
Executable File
2089 lines
113 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Image::ExifTool</title>
|
|
<link rel=stylesheet type='text/css' href='style.css' title='Style'>
|
|
<style type="text/css">
|
|
<!--
|
|
pre { padding: 0; margin: 0px 2px }
|
|
ul { margin-top: 0 }
|
|
-->
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1 class='up'>The Image::ExifTool Perl Library Module</h1>
|
|
|
|
<h2>Description</h2>
|
|
|
|
<p>The Image::ExifTool library provides a set of Perl modules to read and
|
|
write meta information in a wide variety of image, audio, video and document
|
|
files.</p>
|
|
|
|
<hr><h2><a name="Methods">Methods</a></h2>
|
|
|
|
<p>All ExifTool features are accessed through the methods of the public
|
|
interface listed below. Other Image::ExifTool methods and modules should not be
|
|
accessed directly because their interface may change with future versions.</p>
|
|
|
|
<p>The ExifTool methods should never die or issue a warning to STDERR if called
|
|
with the proper arguments (with the exception of
|
|
<a href="#SetNewValue">SetNewValue</a> which may send an error message to
|
|
STDERR, but only when called in scalar context). Error and warning messages
|
|
that occur during processing are stored in the values of the Error and Warning
|
|
tags, and are accessible via the <a href="#GetValue">GetValue</a> method to
|
|
retrieve a single Error or Warning message, or <a href="#GetInfo">GetInfo</a> to
|
|
retrieve any number of them.</p>
|
|
|
|
<p>The ExifTool methods are not thread safe.</p>
|
|
|
|
<table><tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#ImageInfo">ImageInfo</a></li>
|
|
<li><a href="#new">new</a></li>
|
|
<li><a href="#Options">Options</a></li>
|
|
<li><a href="#ClearOptions">ClearOptions</a></li>
|
|
<li><a href="#ExtractInfo">ExtractInfo</a></li>
|
|
<li><a href="#GetInfo">GetInfo</a></li>
|
|
<li><a href="#WriteInfo">WriteInfo</a></li>
|
|
<li><a href="#GetTagList">GetTagList</a></li>
|
|
<li><a href="#GetFoundTags">GetFoundTags</a></li>
|
|
<li><a href="#GetRequestedTags">GetRequestedTags</a></li>
|
|
<li><a href="#GetValue">GetValue</a></li>
|
|
<li><a href="#SetNewValue">SetNewValue</a></li>
|
|
</ul>
|
|
</td><td valign=top>
|
|
<ul>
|
|
<li><a href="#GetNewValue">GetNewValue</a></li>
|
|
<li><a href="#SetNewValuesFromFile">SetNewValuesFromFile</a></li>
|
|
<li><a href="#CountNewValues">CountNewValues</a></li>
|
|
<li><a href="#SaveNewValues">SaveNewValues</a></li>
|
|
<li><a href="#RestoreNewValues">RestoreNewValues</a></li>
|
|
<li><a href="#SetFileModifyDate">SetFileModifyDate</a></li>
|
|
<li><a href="#SetFileName">SetFileName</a></li>
|
|
<li><a href="#SetNewGroups">SetNewGroups</a></li>
|
|
<li><a href="#GetNewGroups">GetNewGroups</a></li>
|
|
<li><a href="#GetTagID">GetTagID</a></li>
|
|
<li><a href="#GetDescription">GetDescription</a></li>
|
|
<li><a href="#GetGroup">GetGroup</a></li>
|
|
</ul>
|
|
</td><td valign=top>
|
|
<ul>
|
|
<li><a href="#GetGroups">GetGroups</a></li>
|
|
<li><a href="#BuildCompositeTags">BuildCompositeTags</a></li>
|
|
<li><a href="#GetTagName">GetTagName</a></li>
|
|
<li><a href="#GetShortcuts">GetShortcuts</a></li>
|
|
<li><a href="#GetAllTags">GetAllTags</a></li>
|
|
<li><a href="#GetWritableTags">GetWritableTags</a></li>
|
|
<li><a href="#GetAllGroups">GetAllGroups</a></li>
|
|
<li><a href="#GetDeleteGroups">GetDeleteGroups</a></li>
|
|
<li><a href="#GetFileType">GetFileType</a></li>
|
|
<li><a href="#CanWrite">CanWrite</a></li>
|
|
<li><a href="#CanCreate">CanCreate</a></li>
|
|
<li><a href="#AddUserDefinedTags">AddUserDefinedTags</a></li>
|
|
</ul>
|
|
</td></tr></table>
|
|
|
|
<hr><h2><a name="UsingExifTool">Using ExifTool</a></h2>
|
|
|
|
<p>The ExifTool module may be used by simply calling the
|
|
<a href="#ImageInfo">ImageInfo</a> function:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
use Image::ExifTool qw(:Public);
|
|
my $info = <a href="#ImageInfo">ImageInfo</a>('image.jpg');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>or in a more object-oriented fashion, by creating an ExifTool object:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
use Image::ExifTool;
|
|
my $exifTool = <a href="#new">new</a> Image::ExifTool;
|
|
my $info = $exifTool-><a href="#ImageInfo">ImageInfo</a>('image.jpg');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>The object-oriented method allows more flexibility, but is slightly more
|
|
complicated. You choose the method that you prefer.</p>
|
|
|
|
<p>The $info value returned by <a href="#ImageInfo">ImageInfo</a> in the above
|
|
examples is a reference to a hash containing the tag/value pairs. Here is a
|
|
simplified example which prints out this information:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
foreach (keys %$info) {
|
|
print "$_ => $$info{$_}\n";
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>See <a href="#ImageInfo">ImageInfo</a> for a more detailed description of the
|
|
info hash entries.</p>
|
|
|
|
<p>And the technique for writing meta information is equally simple:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
use Image::ExifTool;
|
|
my $exifTool = <a href="#new">new</a> Image::ExifTool;
|
|
$exifTool-><a href="#SetNewValue">SetNewValue</a>(Author => 'Phil Harvey');
|
|
$exifTool-><a href="#WriteInfo">WriteInfo</a>('image.jpg','modified_image.jpg');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="Config">Configuration</a></h2>
|
|
|
|
<p>User-defined tags can be added via the ExifTool configuration file, or by
|
|
defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
|
|
functions. See "<a href="config.html">ExifTool_config</a>" in the ExifTool
|
|
distribution for more details.</p>
|
|
|
|
<p>By default ExifTool looks for a configuration file named ".ExifTool_config"
|
|
first in your home directory, then in the directory of the application script,
|
|
but a different directory may be specified by setting the EXIFTOOL_HOME
|
|
environment variable, or a different file may be specified by setting the
|
|
ExifTool "<code>configFile</code>" variable before using Image::ExifTool. For
|
|
example:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
|
|
use Image::ExifTool;
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>The configuration feature may also be disabled by setting
|
|
"<code>configFile</code>" to an empty string:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
BEGIN { $Image::ExifTool::configFile = '' }
|
|
use Image::ExifTool;
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="ImageInfo">ImageInfo</a></h2>
|
|
|
|
<p>Read image file and return meta information. This is the one-step function for
|
|
retrieving meta information from an image. Internally,
|
|
<a href="#ImageInfo">ImageInfo</a> calls <a href="#ExtractInfo">ExtractInfo</a>
|
|
to extract data from the image, <a href="#GetInfo">GetInfo</a> to generate the
|
|
information hash, and <a href="#GetTagList">GetTagList</a> for the returned tag
|
|
list.</p>
|
|
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>ImageInfo($;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> [<i>optional</i>] ExifTool object reference
|
|
<br><b>1)</b> File name, file reference or scalar reference
|
|
<br><b>2-N)</b> [<i>optional</i>] list of tag names to find (or tag list reference or
|
|
options reference, see below)
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Reference to hash of tag key/value pairs</td></tr>
|
|
</table></blockquote>
|
|
|
|
<p><b>Examples:</b></p>
|
|
|
|
<blockquote>Non object-oriented example showing use of options and returning tag list:
|
|
<table class='box'><tr><td><pre>
|
|
use Image::ExifTool qw(ImageInfo);
|
|
my @ioTagList;
|
|
my $info;
|
|
|
|
$info = <b>ImageInfo</b>('image.jpg', \@ioTagList, {Sort => 'Group0'});
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote>Object-oriented example to read from a file that is already open:
|
|
<table class='box'><tr><td><pre>
|
|
my $exifTool = <a href="#new">new</a> Image::ExifTool;
|
|
|
|
$info = $exifTool-><b>ImageInfo</b>(\*FILE_PT, 'Aperture', 'ShutterSpeed', 'ISO');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote>Extract information from an image in memory:
|
|
<table class='box'><tr><td><pre>
|
|
$info = $exifTool-><b>ImageInfo</b>(\$imageData);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote>Extract information from an embedded thumbnail image:
|
|
<table class='box'><tr><td><pre>
|
|
$info = <b>ImageInfo</b>('image.jpg', 'thumbnailimage');
|
|
my $thumbInfo = <b>ImageInfo</b>($$info{ThumbnailImage});
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote>Using an ExifTool object to set the options before calling
|
|
<a href="#ImageInfo">ImageInfo</a>:
|
|
<table class='box'><tr><td><pre>
|
|
my $filename = shift || die "Please specify filename\n";
|
|
my @ioTagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
|
|
|
|
$exifTool-><a href="#Options">Options</a>(Unknown => 1, DateFormat => '%H:%M:%S %a. %b. %e, %Y');
|
|
$info = $exifTool-><b>ImageInfo</b>($filename, \@ioTagList);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p><b>Function Arguments:</b></p>
|
|
|
|
<p><a href="#ImageInfo">ImageInfo</a> is very flexible about the arguments
|
|
passed to it, and interprets them based on their type. It may be called with
|
|
one or more arguments. The one required argument is either a SCALAR (the image
|
|
file name), a file reference (a reference to the image file) or a SCALAR
|
|
reference (a reference to the image in memory). Other arguments are optional.
|
|
The order of the arguments is not significant, except that the first SCALAR is
|
|
taken to be the file name unless a file reference or scalar reference comes
|
|
earlier in the argument list.</p>
|
|
|
|
<p>Below is a more detailed explanation of how the <a href="#ImageInfo">ImageInfo</a>
|
|
function arguments are interpreted.</p>
|
|
|
|
<blockquote><table class='norm'>
|
|
<tr><td valign=top><b>ExifTool ref</b></td><td>
|
|
<a href="#ImageInfo">ImageInfo</a> may be called with an ExifTool object if
|
|
desired. Advantages of using the object-oriented form are that options may be
|
|
set before calling <a href="#ImageInfo">ImageInfo</a>, and the object may be
|
|
used afterward to access member functions. Must be the first argument if used.
|
|
|
|
</td></tr><tr><td valign=top><b>SCALAR</b></td><td>
|
|
The first scalar argument is taken to be the file name unless an earlier
|
|
argument specified the image data via a file reference (file ref) or data
|
|
reference (SCALAR ref). The remaining scalar arguments are names of tags for
|
|
requested information. All tags are returned if no tags are specified.
|
|
<br> <br>
|
|
Tag names are case-insensitive and may be prefixed by optional group names
|
|
separated by colons. A group name may begin with a family number (eg.
|
|
'<code>1IPTC:Keywords</code>'), to restrict matches to a specific family. In the
|
|
tag name, a '<code>?</code>' matches any single character and a '<code>*</code>'
|
|
matches zero or more characters. Thus '<code>GROUP:*</code>' represents all
|
|
tags in a specific group. Wildcards may not be used in group names, with the
|
|
exception that a group name of '<code>*</code>' may be used to extract all
|
|
available instances of a tag regardless of the
|
|
<a href="#Duplicates">Duplicates</a> setting (eg. '<code>*:WhiteBalance</code>').
|
|
Multiple groups may be specified (eg. '<code>EXIF:Time:*</code>' extracts all
|
|
EXIF Time tags). And finally, a leading '<code>-</code>' indicates a tag to be
|
|
excluded (eg. '<code>-IFD1:*</code>'), or a trailing '<code>#</code>' causes the
|
|
ValueConv value to be returned for this tag.
|
|
<br> <br>
|
|
Note that keys in the returned information hash and elements of the returned tag
|
|
list are not necessarily the same as these tag names because group names are
|
|
removed, the case may be changed, and an instance number may be added. For this
|
|
reason it is best to use either the keys of the returned hash or the elements of
|
|
the returned tag list when accessing the tag values.
|
|
<br> <br>
|
|
See the <a href="TagNames/index.html">TagNames</a> documentation for a
|
|
complete list of ExifTool tag names.
|
|
|
|
</td></tr><tr><td valign=top><b>File ref</b></td><td>
|
|
A reference to an open image file. If you use this method (or a SCALAR
|
|
reference) to access information in an image, the FileName and Directory tags
|
|
will not be returned. (Also, the FileSize, FileModifyDate, FilePermissions and
|
|
FileAttributes tags will not be returned unless it is a plain file.) Image
|
|
processing begins at the current file position, and on return the file position
|
|
is unspecified. May be either a standard filehandle or a reference to a
|
|
File::RandomAccess object.
|
|
<br> <br>
|
|
[Advanced: To allow a non-rewindable stream (eg. a network socket) to be
|
|
re-read after processing with ExifTool, first wrap the file reference in a
|
|
File::RandomAccess object, then pass this object to
|
|
<a href="#ImageInfo">ImageInfo</a>. The File::RandomAccess object will buffer
|
|
the file if necessary, and may be used to re-read the file after
|
|
<a href="#ImageInfo">ImageInfo</a> returns.]
|
|
|
|
</td></tr><tr><td valign=top><b>SCALAR ref</b></td><td>
|
|
A reference to image data in memory.
|
|
|
|
</td></tr><tr><td valign=top><b>ARRAY ref</b></td><td>
|
|
Reference to a list of tag names. On entry, any elements in the list are added
|
|
to the list of requested tags. On return, this list is updated to contain an
|
|
ordered list of tag keys for the returned information.
|
|
<br> <br>
|
|
There will be 1:1 correspondence between the requested tags and the returned
|
|
tag keys only if the <a href="#Duplicates">Duplicates</a> option is 0 and
|
|
<a href="#Sort">Sort</a> is 'Input'. (With
|
|
<a href="#Duplicates">Duplicates</a> enabled, there may be more entries in the
|
|
returned list of tag keys, and with other <a href="#Sort">Sort</a> settings the
|
|
entries may not be in the same order as requested.) If a requested tag doesn't
|
|
exist, a tag key is still generated, but the tag value is undefined.
|
|
|
|
</td></tr><tr><td valign=top><b>HASH ref</b></td><td>
|
|
Reference to a hash containing the options settings. See
|
|
<a href="#Options">Options</a> documentation below for a list of available
|
|
options. Options specified as arguments to <a href="#ImageInfo">ImageInfo</a>
|
|
take precedence over <a href="#Options">Options</a> settings.
|
|
</td></tr></table></blockquote>
|
|
|
|
<p><b>Return Value:</b></p>
|
|
|
|
<p><a href="#ImageInfo">ImageInfo</a> returns a reference to a hash of tag
|
|
key/value pairs. The tag keys are identifiers, which are similar to the tag
|
|
names but may have an appended instance number if multiple tags with the same
|
|
name were extracted from the image. Many of the ExifTool functions require a
|
|
tag key as an argument. Use <a href="#GetTagName">GetTagName</a> to get the tag
|
|
name for a given tag key. Note that the case of the tag names may not be the
|
|
same as requested.</p>
|
|
|
|
<p>Values of the returned hash are usually simple scalars, but a scalar
|
|
reference is used to indicate binary data and an array reference may be used to
|
|
indicate a list. Also, a hash reference may be returned if the
|
|
<a href="#Struct">Struct</a> option is used. Lists of values are joined by
|
|
commas into a single string only if the PrintConv option is enabled and the List
|
|
option is disabled (which are the defaults). Note that binary values are not
|
|
necessarily extracted unless specifically requested, or the Binary option is
|
|
enabled and the tag is not specifically excluded. If not extracted the value is
|
|
a reference to a string of the form "<code>Binary data ##### bytes</code>".</p>
|
|
|
|
<p>Here is a simple example to print out the information returned by
|
|
<a href="#ImageInfo">ImageInfo</a>:</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
foreach (keys %$info) {
|
|
my $val = $$info{$_};
|
|
if (ref $val eq 'ARRAY') {
|
|
$val = join(', ', @$val);
|
|
} elsif (ref $val eq 'SCALAR') {
|
|
$val = '(Binary data)';
|
|
}
|
|
printf("%-24s : %s\n", $_, $val);
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>which gives output like this (PrintConv enabled):</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
WhiteBalance : Auto
|
|
FNumber : 3.5
|
|
InteroperabilityOffset : 936
|
|
XResolution : 72
|
|
ISO : 100
|
|
ThumbnailImage : (Binary data)
|
|
FlashOn : On
|
|
Make : FUJIFILM
|
|
ShutterSpeedValue : 1/64
|
|
ExposureCompensation : 0
|
|
Sharpness : Soft
|
|
ResolutionUnit : inches
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p><b>Notes:</b></p>
|
|
|
|
<p>ExifTool returns all values as byte strings of encoded characters. Perl wide
|
|
characters are not used. See <a href="faq.html#Q10">FAQ number 10</a> for
|
|
details about the encodings. By default, most returned strings are encoded in
|
|
UTF-8. For these, Encode::decode_utf8() may be used to convert to a sequence of
|
|
logical Perl characters.</p>
|
|
|
|
<p>As well as tags representing information extracted from the image, the
|
|
following <a href="TagNames/Extra.html">Extra tags</a> generated by ExifTool may
|
|
be returned:</p>
|
|
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>ExifToolVersion</b></td><td>The ExifTool version number</td></tr>
|
|
<tr><td><b>Error</b></td><td>An error message if the image could not be processed</td></tr>
|
|
<tr><td><b>Warning</b></td><td>A warning message if problems were encountered
|
|
while processing the image</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="new">new</a></h2>
|
|
<p>Create a new ExifTool object.</p>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $exifTool = <b>new</b> Image::ExifTool;
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p>Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
|
|
using Image::ExifTool as a base class must define an AUTOLOAD which calls
|
|
Image::ExifTool::DoAutoLoad(). ie)</p>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
sub AUTOLOAD
|
|
{
|
|
Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><table bgcolor='#aaffaa' width='100%' cellpadding=8><tr><td><center><b>
|
|
The following functions require an ExifTool object as the first argument
|
|
</b></center></td></tr></table>
|
|
|
|
<hr><h2><a name='options'></a><a name="Options">Options</a></h2>
|
|
<p>Get/set ExifTool options. This function can be called to set the default
|
|
options for an ExifTool object. Options set this way are in effect for
|
|
all function calls but may be overridden by options passed as arguments
|
|
to some functions. Option names are not case sensitive.</p>
|
|
<p>The default option values may be changed by defining a
|
|
%Image::ExifTool::UserDefined::Options hash. See the
|
|
<a href="config.html">ExifTool_config file</a> in the full ExifTool
|
|
distribution for examples.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>Options($$;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Parameter name (case-insensitive, see table below)
|
|
<br><b>2)</b> [<i>optional</i>] Option value if specified (may be undef to clear option)
|
|
<br><b>3-N)</b> [<i>optional</i>] Additional parameter/value pairs
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Previous value of last specified parameter</td></tr>
|
|
</table></blockquote>
|
|
|
|
<p><b>Available options:</b></p>
|
|
<blockquote>
|
|
<table class='norm'>
|
|
<tr><th colspan=4 bgcolor='#dddddd'><font size='+1'>ExifTool Options</font></th></tr>
|
|
<tr><th>Option</th><th>Description</th><th>Values</th><th>Default</th></tr>
|
|
<tr><td>Binary</td><td><a name="Binary"></a>Flag to extract the value data for all binary tags.
|
|
Tag values representing large binary data blocks (eg. ThumbnailImage)
|
|
are not necessarily extracted unless this option is set or the tag is
|
|
specifically requested by name.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>ByteOrder</td><td><a name="ByteOrder"></a>The byte order for newly created EXIF segments when
|
|
writing. Note that if EXIF information already exists, the existing order is
|
|
maintained. If ByteOrder is not defined, then the order of the maker notes is
|
|
used (if they are being copied), otherwise big-endian ('MM') order is assumed.
|
|
This can also be set via the <a href="TagNames/Extra.html">ExifByteOrder tag</a>,
|
|
but the ByteOrder option takes precedence if both are set.</td>
|
|
<td align=center>'MM','II' or undef</td><td align=center>undef</td></tr>
|
|
<tr><td>Charset</td><td>Character set for encoding character
|
|
strings passed to/from ExifTool containing code points above U+007F. Note
|
|
that this option affects some types of information when reading/writing the
|
|
file and other types when getting/setting tag values, so it must be defined
|
|
for both types of access. Charset values listed to the right have aliases
|
|
which are given in brackets. Case is not significant. See
|
|
<a href="faq.html#Q10">FAQ #10</a> for more information about character sets.</td>
|
|
<td align=center><a name="Charset"></a><table class=clear>
|
|
<tr><td valign=top align=right>UTF8</td><td>(cp65001, UTF-8)</td></tr>
|
|
<tr><td valign=top align=right>Latin</td><td>(cp1252, Latin1)</td></tr>
|
|
<tr><td valign=top align=right>Latin2</td><td>(cp1250)</td></tr>
|
|
<tr><td valign=top align=right>Cyrillic</td><td>(cp1251, Russian)</td></tr>
|
|
<tr><td valign=top align=right>Greek</td><td>(cp1253)</td></tr>
|
|
<tr><td valign=top align=right>Turkish</td><td>(cp1254)</td></tr>
|
|
<tr><td valign=top align=right>Hebrew</td><td>(cp1255)</td></tr>
|
|
<tr><td valign=top align=right>Arabic</td><td>(cp1256)</td></tr>
|
|
<tr><td valign=top align=right>Baltic</td><td>(cp1257)</td></tr>
|
|
<tr><td valign=top align=right>Vietnam</td><td>(cp1258)</td></tr>
|
|
<tr><td valign=top align=right>Thai</td><td>(cp874)</td></tr>
|
|
<tr><td valign=top align=right>MacRoman</td><td>(cp10000, Mac, Roman)</td></tr>
|
|
<tr><td valign=top align=right>MacLatin2</td><td>(cp10029)</td></tr>
|
|
<tr><td valign=top align=right>MacCyrillic</td><td>(cp10007)</td></tr>
|
|
<tr><td valign=top align=right>MacGreek</td><td>(cp10006)</td></tr>
|
|
<tr><td valign=top align=right>MacTurkish</td><td>(cp10081)</td></tr>
|
|
<tr><td valign=top align=right>MacRomanian</td><td>(cp10010)</td></tr>
|
|
<tr><td valign=top align=right>MacIceland</td><td>(cp10079)</td></tr>
|
|
<tr><td valign=top align=right>MacCroatian</td><td>(cp10082)</td></tr>
|
|
</table></td><td align=center>'UTF8'</td></tr>
|
|
<tr><td>CharsetEXIF</td><td><a name="CharsetEXIF"></a>Internal encoding to use for stored
|
|
EXIF "ASCII" string values. May also be set to undef to pass through EXIF
|
|
"ASCII" values without recoding. Set to "UTF8" to conform with the MWG
|
|
recommendation.</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i><br>or undef</td><td align=center>undef</td></tr>
|
|
<tr><td>CharsetFileName</td><td><a name="CharsetFileName"></a>External character set
|
|
used when specifying file names. When set in Windows, this triggers use of
|
|
Windows Unicode file library routines (requires Win32API::File).</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i><br>or undef</td><td align=center>undef</td></tr>
|
|
<tr><td>CharsetID3</td><td><a name="CharsetID3"></a>Internal encoding to assume for ID3v1 strings. By
|
|
the specification ID3v1 strings should be encoded in ISO 8859-1 (essentially
|
|
'Latin'), but some applications may use local encoding instead. This option
|
|
allows different encodings to be specified.</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr>
|
|
<tr><td>CharsetIPTC</td><td><a name="CharsetIPTC"></a>Fallback internal IPTC character set to assume if IPTC information
|
|
contains no CodedCharacterSet tag.</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr>
|
|
<tr><td>CharsetPhotoshop</td><td><a name="CharsetPhotoshop"></a>Internal encoding to assume for Photoshop IRB resource names.</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr>
|
|
<tr><td>CharsetQuickTime</td><td><a name="CharsetQuickTime"></a>Internal encoding to assume for QuickTime
|
|
strings stored with an unspecified encoding.</td>
|
|
<td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'MacRoman'</td></tr>
|
|
<tr><td>Compact</td><td><a name="Compact"></a>Flag to write compact output. The XMP specification suggests
|
|
that the data be padded with blanks to allow in-place editing. With this
|
|
flag set the 2kB of padding is not written. Note that this only effects
|
|
embedded XMP since padding is never written for stand-alone XMP files.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>Composite</td><td><a name="Composite"></a>Flag to generate Composite tags when extracting information.</td>
|
|
<td align=center>0 or 1</td><td align=center>1</td></tr>
|
|
<tr><td>Compress</td><td><a name="Compress"></a>Flag to write new values in compressed format if possible.
|
|
Has no effect unless Compress::Zlib is installed.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>CoordFormat</td><td><a name="CoordFormat"></a>Specify output format for GPS coordinates.</td>
|
|
<td>A printf-style format string with specifiers for degrees, minutes and
|
|
seconds in that order, however minutes and seconds may be omitted. If the
|
|
hemisphere is known, a reference direction (N, S, E or W) is appended to
|
|
each printed coordinate, but adding a '<code>+</code>' to the first format
|
|
specifier (eg. <code>'%+.6f'</code>) prints a signed coordinate instead.
|
|
The default for reading is equivalent to a format string of
|
|
<code>q{%d deg %d' %.2f"}</code>, but to avoid a loss
|
|
of precision the default for copying tags with
|
|
<a href="#SetNewValuesFromFile">SetNewValuesFromFile</a> is
|
|
<code>q{%d %d %.8f}</code>.
|
|
</td><td align=center>undef</td></tr>
|
|
<tr><td>DateFormat</td><td><a name="DateFormat"></a>Output format for date/time values. If date can not
|
|
be converted, value is left unchanged unless the StrictDate option is set.
|
|
Timezones are ignored.</td> <td>See strftime manpage for details. The default
|
|
is similar to a format string of <code>"%Y:%m:%d %H:%M:%S"</code>.</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>Duplicates</td><td><a name="Duplicates"></a>Flag to return values from
|
|
tags with duplicate names when extracting information.</td>
|
|
<td align=center>0 or 1</td><td align=center>1</td></tr>
|
|
<tr><td>Escape</td>
|
|
<td><a name="Escape"></a>Escape special characters in extracted values for
|
|
HTML or XML. Also unescapes HTML or XML character entities in input values
|
|
passed to <a href="#SetNewValue">SetNewValue</a>.</td> <td
|
|
align=center>HTML, XML or undef</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>Exclude</td>
|
|
<td>Exclude specified tags when extracting information.</td>
|
|
<td><a name="Exclude"></a>Tag name or reference to a list of tag names to
|
|
exclude. Case is not significant. Tags may also be excluded by preceding
|
|
their name with a '-' in the arguments to ImageInfo.</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>ExtendedXMP</td><td><a name="ExtendedXMP"></a>This setting affects the
|
|
reading and editing of extended XMP in JPEG images. According to the XMP
|
|
specification, extended XMP is only valid if it has the GUID specified by
|
|
the <a href="TagNames/XMP.html#xmpNote">HasExtendedXMP tag</a>. ExifTool
|
|
9.95 and earlier would read extended XMP regardless of GUID, but with the
|
|
addition of this option in version 9.96 the default behaviour was changed to
|
|
conform with the XMP specification (to read only extended XMP with the
|
|
proper GUID). This option should be set to 2 to emulate pre-9.96 behaviour
|
|
and read all extended XMP. It may also be set to a GUID to read a specific
|
|
extended XMP, or 0 to ignore extended XMP entirely.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=right><b>0</b> =</td><td>ignore extended XMP</td></tr>
|
|
<tr><td valign=top align=right><b>1</b> =</td><td>valid GUID only</td></tr>
|
|
<tr><td valign=top align=right><b>2</b> =</td><td>any GUID</td></tr>
|
|
<tr><td valign=top align=right><i>guid</i> =</td><td>specific GUID</td></tr>
|
|
</table></td><td align=center>1</td></tr>
|
|
<tr><td>ExtractEmbedded</td>
|
|
<td><a name="Embedded"></a>Flag to extract information from embedded
|
|
documents in EPS files, embedded EPS information and JPEG and Jpeg2000
|
|
images in PDF files, embedded MPF images in JPEG and MPO files, streaming
|
|
metadata in AVCHD videos, and the resource fork of Mac OS files.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>FastScan</td>
|
|
<td><a name="FastScan"></a>Flag to increase speed of extracting information
|
|
from JPEG images. With this option set to 1, ExifTool will not scan to the
|
|
end of a JPEG image to check for an AFCP, CanonVRD, FotoStation,
|
|
PhotoMechanic, MIE or PreviewImage trailer. This also stops the parsing
|
|
after the first comment in GIF images, and at the audio/video data with
|
|
RIFF-format files (AVI, WAV, etc), so any trailing metadata (ie.eg. XMP written
|
|
by some utilities) may be missed. When combined with the ScanForXMP option,
|
|
prevents scanning for XMP in recognized file types. With a value of 2,
|
|
ExifTool will also avoid extracting any EXIF MakerNote information. When set
|
|
to 3, the file is not actually parsed, and only an initial guess at FileType
|
|
and some pseudo tags are returned. </td>
|
|
<td align=center>0, 1, 2 or 3</td><td align=center>undef</td></tr>
|
|
<tr><td>Filter</td>
|
|
<td>Perl expression used to filter all returned tag values. Applies to
|
|
PrintConv values only.</td><td><a name="Filter"></a>Expression to act on the
|
|
value of the Perl default variable ($_), changing the value of this variable
|
|
as required</td> <td align=center>undef</td></tr>
|
|
<tr><td>FixBase</td>
|
|
<td>Fix maker notes base offset. Allows values to be extracted from maker notes
|
|
which have been corrupted by editing with 3rd party software.</td>
|
|
<td><a name="FixBase"></a>An integer specifying a value to be added to the
|
|
maker notes base offset, or the empty string ('') for ExifTool to take its
|
|
best guess at the correct base.</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>GeoMaxIntSecs</td>
|
|
<td><a name="GeoMaxIntSecs"></a>Maximum interpolation time in seconds for
|
|
geotagging. Geotagging is treated as an extrapolation if the Geotime value
|
|
lies between two fixes in the same track which are separated by a number of
|
|
seconds greater than this. Otherwise, the coordinates are calculated as a
|
|
linear interpolation between the nearest fixes on either side of the Geotime
|
|
value. Set to 0 to disable interpolation and use the coordinates of the
|
|
nearest fix instead (provided it is within GeoMaxExtSecs, otherwise
|
|
geotagging fails).</td>
|
|
<td align=center>A floating point number</td>
|
|
<td align=center>1800</td></tr>
|
|
<tr><td>GeoMaxExtSecs</td>
|
|
<td><a name="GeoMaxExtSecs"></a>Maximum extrapolation time in seconds for
|
|
geotagging. Geotagging fails if the Geotime value lies outside a GPS track
|
|
by a number of seconds greater than this. Otherwise, the coordinates of the
|
|
nearest fix are taken.</td>
|
|
<td align=center>A floating point number</td>
|
|
<td align=center>1800</td></tr>
|
|
<tr><td>GeoMaxHDOP</td>
|
|
<td><a name="GeoMaxHDOP"></a>Maximum Horizontal (2D) Dilution Of Precision
|
|
for geotagging. GPS fixes are ignored if the HDOP is greater than this.</td>
|
|
<td align=center>A floating point number, or undef</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>GeoMaxPDOP</td>
|
|
<td><a name="GeoMaxPDOP"></a>Maximum Position (3D) Dilution Of Precision for
|
|
geotagging. GPS fixes are ignored if the PDOP is greater than this.</td>
|
|
<td align=center>A floating point number, or undef</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>GeoMinSats</td>
|
|
<td><a name="GeoMinSats"></a>Minimum number of satellites for geotagging.
|
|
GPS fixes are ignored if the number of acquired satellites is less than this.</td>
|
|
<td align=center>A positive integer, or undef</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>GlobalTimeShift</td>
|
|
<td><a name="GlobalTimeShift"></a>Time shift to apply to all extracted
|
|
date/time PrintConv values. Does not affect ValueConv values.</td>
|
|
<td align=center>Date/time shift string with leading '-' for negative shifts<br>(see <a href="Shift.html">Image::ExifTool::Shift.pl</a>)</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>Group#</td><td>Extract tags only for specified groups in family #
|
|
(Group0 assumed if # not given).</td>
|
|
<td><a name="Group"></a>Group name or reference to list of group names.
|
|
Group name may begin with '-' to exclude a group. Case IS significant.
|
|
See <a href="#GetGroup">GetGroup</a> for a description of group families,
|
|
and <a href="#GetAllGroups">GetAllGroups</a> for a list of available groups.</td>
|
|
<td align=center>undef</td></tr>
|
|
<tr><td>HtmlDump</td><td>Dump information in hex to a dynamic HTML web page.
|
|
Option value sets a limit on the maximum block size. Output file is
|
|
specified by the TextOut option.</td>
|
|
<td><a name="HtmlDump"></a><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>No HTML dump</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>1 KB size limit</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>16 KB size limit</td></tr>
|
|
<tr><td valign=top align=center><b>3</b> =</td><td>Full dump</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>HtmlDumpBase</td><td><a name="HtmlDumpBase"></a>Base for HTML dump
|
|
offsets. If not defined, the EXIF/TIFF base offset is used.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=right><b>0</b> =</td><td>Absolute offsets</td></tr>
|
|
<tr><td valign=top align=right><i>non‑zero</i> =</td><td>Relative offsets</td></tr>
|
|
<tr><td valign=top align=right><b>undef</b> =</td><td>EXIF/TIFF offsets</td></tr>
|
|
</table></td><td align=center>undef</td></tr>
|
|
<tr><td>IgnoreMinorErrors</td><td><a name="IgnoreMinorErrors"></a>Flag to ignore minor errors. Causes minor
|
|
errors to be downgraded to warnings, and minor warnings to be ignored. This
|
|
option is provided mainly to allow writing of files when minor errors occur,
|
|
but by ignoring some minor warnings the behaviour of ExifTool may be changed
|
|
to allow some questionable operations to proceed (such as extracting
|
|
thumbnail and preview images even if they don't have a recognizable header).
|
|
Minor errors/warnings are denoted by "[minor]" at the start of the message,
|
|
or "[Minor]" (with a capital "M") for warnings that affect processing when
|
|
ignored.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>Lang</td><td><a name="Lang"></a>Localized language for exiftool tag descriptions, etc. If the
|
|
specified language isn't available, the option is not changed. May be set to
|
|
undef to select the built-in default language.</td>
|
|
<td align=left>Image::ExifTool::Lang module name (eg. 'fr', 'zh_cn'), or 'en' or undef for the default language.</td>
|
|
<td align=center>'en'</td></tr>
|
|
<tr><td>LargeFileSupport</td><td><a name="LargeFileSupport"></a>Flag to indicate that 64-bit file offsets are supported on this system.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>List</td><td><a name="List"></a>Flag to extract lists of PrintConv values into arrays instead of combining
|
|
them into a string of values.</td><td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>ListItem</td><td><a name="ListItem"></a>Return only a specific item from
|
|
List-type values. A value of 0 returns the first item in each list, 1 returns
|
|
the second item, etc. Negative indices may also be used, with -1 representing the
|
|
last item in the list. Applies only to the top-level list of nested lists.</td>
|
|
<td align=center>An integer, or undef</td><td align=center>undef</td></tr>
|
|
<tr><td>ListSep</td><td><a name="ListSep"></a>Separator string used to join lists of PrintConv values when
|
|
List option is not set.</td><td align=center>Any string</td><td align=center>', '</td></tr>
|
|
<tr><td>ListSplit</td><td><a name="ListSplit"></a>Regular expression used to split values of list-type tags
|
|
into individual items when writing. (eg. use ',\\s*' to split a comma-separated list)</td>
|
|
<td align=center>A regular expression pattern</td><td align=center>undef</td></tr>
|
|
<tr><td>MakerNotes</td><td><a name="MakerNotes"></a>Option to extract MakerNotes and other writable
|
|
subdirectories (such as PrintIM) as a data block. Normally when the MakerNotes
|
|
are extracted they are rebuilt to include data outside the boundaries of the
|
|
original maker note data block, but a value of 2 disables this feature.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>Don't extract writable subdirectories</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>Extract and rebuild makernotes into self-contained block</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>Extract without rebuilding makernotes</td></tr>
|
|
</table></td><td align=center>undef</td></tr>
|
|
<tr><td>MDItemTags</td><td><a name="MDItemTags"></a>Flag to extract the OS X
|
|
metadata item tags (see the "mdls" man page for details).</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>MissingTagValue</td><td><a name="MissingTagValue"></a>Value for missing tags in
|
|
expressions evaluated by <a href="#SetNewValuesFromFile">SetNewValuesFromFile</a>.
|
|
If not set, a minor error is issued for missing values, or the value
|
|
is set to '' if IgnoreMinorErrors is set.</td>
|
|
<td align=center>Any string, or undef</td><td align=center>undef</td></tr>
|
|
<tr><td>NoPDFList</td><td><a name="NoPDFList"></a>Flag to avoid splitting PDF List-type tag
|
|
values into separate items.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>Password</td><td><a name="Password"></a><a name="Passwd"></a>Password for reading/writing
|
|
password-protected PDF documents. Ignored if a password is not required. Character encoding of
|
|
the password is determined by the value of the Charset option at processing time.</td>
|
|
<td align=center>Any string</td><td align=center>undef</td></tr>
|
|
<tr><td>PNGEarlyXMP</td><td><a name="PNGEarlyXMP"></a>Flag to write XMP in PNG
|
|
images before the IDAT (image data) chunk. By default, ExifTool adds new
|
|
XMP to the end of a PNG file (just before IEND). This is allowed by the PNG
|
|
and XMP specifications, but some utilities seem to ignore XMP if it comes
|
|
after the image data. The PNGEarlyXMP option causes ExifTool to instead add
|
|
new XMP before the PNG IDAT chunk. However, since ExifTool uses a
|
|
single-pass writing algorithm, it has no way to tell if XMP already exists
|
|
later in the file before writing the new XMP in this location. If this
|
|
happens, a minor error is issued when the extra XMP is encountered, and the
|
|
file is not written. Adding the <a href="#IgnoreMinorErrors">IgnoreMinorErrors</a>
|
|
option causes the XMP after IDAT to be deleted, thus resolving the conflict
|
|
(at the expense of possible metadata loss), and allowing the file to be
|
|
written. The PNGEarlyXMP option is applied automatically when deleting all
|
|
XMP and writing new XMP back in one step. When reading, this option causes
|
|
a warning to be issued if standard XMP is found after the IDAT chunk.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>PrintConv</td><td><a name="PrintConv"></a>Flag to enable print conversion. Also enables inverse print
|
|
conversion for writing.</td><td align=center>0 or 1</td><td align=center>1</td></tr>
|
|
<tr><td>QuickTimeUTC</td><td><a name="QuickTimeUTC"></a>Flag set to assume that QuickTime
|
|
date/time values are stored as UTC, causing conversion to local time when they are
|
|
extracted. According to the QuickTime specification date/time values should be UTC,
|
|
but many digital cameras store local time instead (presumably because they don't know
|
|
the time zone). This option also disables the autodetection of incorrect time-zero
|
|
offsets in QuickTime date/time values, and enforces a time zero of 1904 as per the
|
|
QuickTime specification.</td><td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>RequestAll</td><td><a name="RequestAll"></a>Flag to request all tags to be extracted.
|
|
This causes some tags to be generated which normally would not be unless specifically
|
|
requested (by passing the tag name to <a href="#ImageInfo">ImageInfo</a> or
|
|
<a href="#ExtractInfo">ExtractInfo</a>). Note that this flag is set automatically
|
|
during a call to <a href="#SetNewValuesFromFile">SetNewValuesFromFile</a> to
|
|
make all tags available for copying.</td><td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>RequestTags</td><td><a name="RequestTags"></a>List of additional tags to request in
|
|
next call to <a href="#ExtractInfo">ExtractInfo</a>. This option is useful only for
|
|
tags which aren't extracted unless specifically requested.</td><td>List reference,
|
|
delimited string of tag names (any delimiter is allowed), or undef to clear the
|
|
previous RequestTags list. Case is not significant.</td><td align=center>undef</td></tr>
|
|
<tr><td>ScanForXMP</td><td><a name="ScanForXMP"></a>Flag to scan all files (even unrecognized
|
|
formats) for XMP information unless XMP was already found in the file. When combined with
|
|
the FastScan option, only unrecognized file types are scanned for XMP.
|
|
</td><td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>Sort</td><td>Specifies order to sort tags in the returned tag list.</td>
|
|
<td><a name="Sort"></a><table class=clear>
|
|
<tr><td valign=top align=right><b>Input</b> =</td><td>Sort in same order as input tag arguments</td></tr>
|
|
<tr><td valign=top align=right><b>File</b> =</td><td>Sort in order that tags were found in the file</td></tr>
|
|
<tr><td valign=top align=right><b>Tag</b> =</td><td>Sort alphabetically by tag name</td></tr>
|
|
<tr><td valign=top align=right><b>Descr</b> =</td><td>Sort by tag description (with current Lang setting)</td></tr>
|
|
<tr valign=top><td valign=top align=right><b>Group#</b> =</td><td>Sort by tag group,
|
|
where # is zero or more family numbers separated by colons. If # is not specified,
|
|
Group0 is assumed. See <a href="#GetGroup">GetGroup</a> for a description of group
|
|
families.</td></tr>
|
|
</table></td><td align=center>'Input'</td></tr>
|
|
<tr><td>Sort2</td><td>Secondary sort order used for tags within each group when Sort is 'Group'.</td>
|
|
<td><a name="Sort2"></a><table class=clear>
|
|
<tr><td valign=top align=right><b>File</b> =</td><td>Sort in order that tags were found in the file</td></tr>
|
|
<tr><td valign=top align=right><b>Tag</b> =</td><td>Sort alphabetically by tag name</td></tr>
|
|
<tr><td valign=top align=right><b>Descr</b> =</td><td>Sort by tag description (with current Lang setting)</td></tr>
|
|
</table></td><td align=center>'File'</td></tr>
|
|
<tr><td>StrictDate</td><td><a name="StrictDate"></a>Flag to return undefined value for any date which can't be
|
|
converted when the DateFormat option is used.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>Struct</td><td>Flag to return XMP structures as HASH references
|
|
instead of flattening into individual tags. This setting has no effect
|
|
when writing since both flattened or structured tags may always be written.
|
|
See the <a href="struct.html">Structured Information documentation</a> for
|
|
more details about structured information.</td>
|
|
<td><a name="Struct"></a><table class=clear>
|
|
<tr><td valign=top align=right><b>undef</b> =</td><td>Same as 0 for reading and 2 for copying</td></tr>
|
|
<tr><td valign=top align=right><b>0</b> =</td><td>Read/copy flattened tags</td></tr>
|
|
<tr><td valign=top align=right><b>1</b> =</td><td>Read/copy structures</td></tr>
|
|
<tr><td valign=top align=right><b>2</b> =</td><td>Read/copy both flattened and structured tags,
|
|
but flag flattened tags as "unsafe" for copying</td></tr>
|
|
</table></td><td align=center>undef</td></tr>
|
|
<tr><td>SystemTags</td><td><a name="SystemTags"></a>Flag to extract the
|
|
following additional File System tags: FileAttributes, FileDeviceNumber,
|
|
FileInodeNumber, FileHardLinks, FileUserID, FileGroupID, FileDeviceID,
|
|
FileBlockSize and FileBlockCount.</td>
|
|
<td align=center>0 or 1</td><td align=center>undef</td></tr>
|
|
<tr><td>TextOut</td><td><a name="TextOut"></a>Output file for Verbose and HtmlDump options.</td>
|
|
<td align=center>File reference</td><td align=center>\*STDOUT</td></tr>
|
|
<tr><td>Unknown</td><td><a name="Unknown"></a>Control extraction of unknown tags.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>Unknown tags not extracted</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>Unknown tags are extracted from EXIF
|
|
(and other tagged-format) directories</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>Unknown tags also extracted from binary data blocks</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>UserParam</td><td><a name="UserParam"></a>Special option to set/get user-defined parameters.
|
|
Useful to allow external input into tag name expressions and ValueConv logic.
|
|
<i>PARAM</i> is the user-defined parameter name (case insensitive). These parameters
|
|
may be accessed in tag name expressions by prefixing the parameter name with a dollar
|
|
sign, just like normal tags. If called without a parameter name,
|
|
<code>Options('UserParam')</code> returns a reference to the hash of all user
|
|
parameters (with lower-case names).
|
|
</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top><i>PARAM</i></td><td>- Get parameter</td></tr>
|
|
<tr><td valign=top><i>PARAM=</i></td><td>- Clear parameter</td></tr></table>
|
|
<table class=clear>
|
|
<tr><td valign=top><i>PARAM=VALUE</i></td><td>- Set parameter</td></tr>
|
|
</table></td><td align=center>{ }</td></tr>
|
|
<tr><td>Verbose</td><td>Print verbose messages to file specified by TextOut option.
|
|
<a href="verbose.html">Click here</a> for example outputs.</td>
|
|
<td><a name="Verbose"></a><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>No verbose messages</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>Print tag names and raw values</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>Add additional tag details</td></tr>
|
|
<tr><td valign=top align=center><b>3</b> =</td><td>Add hex dump of tag data (with length limits)</td></tr>
|
|
<tr><td valign=top align=center><b>4</b> =</td><td>Remove length limit on dump of tag values</td></tr>
|
|
<tr><td valign=top align=center><b>5</b> =</td><td>Remove length limit on dump of JPEG segments</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>WriteMode</td><td>Set tag write/create mode.</td>
|
|
<td><a name="WriteMode"></a>A string with one or more of these characters:<table class=clear>
|
|
<tr><td valign=top align=center><b>w</b> =</td><td><b>W</b>rite existing tags</td></tr>
|
|
<tr><td valign=top align=center><b>c</b> =</td><td><b>C</b>reate new tags</td></tr>
|
|
<tr><td valign=top align=center><b>g</b> =</td><td>Create new <b>g</b>roups <sup>†</sup></td></tr>
|
|
</table></td><td align=center>'wcg'</td></tr>
|
|
<tr><td>XMPAutoConv</td><td><a name="XMPAutoConv"></a>Flag to enable automatic conversion
|
|
for unknown XMP tags with values that look like rational numbers or dates.</td>
|
|
<td align=center>0 or 1</td>
|
|
<td align=center>1</td></tr>
|
|
</table></blockquote>
|
|
|
|
<blockquote><table><tr><td valign=top><sup>†</sup></td><td>The level of
|
|
the group differs for different types of metadata. For XMP or IPTC this is the
|
|
full XMP/IPTC block (the family 0 group), but for EXIF this is the individual
|
|
IFD (the family 1 group).</td></tr></table></blockquote>
|
|
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># exclude the 'OwnerName' tag from returned information</span>
|
|
$exifTool-><b>Options</b>(Exclude => 'OwnerName');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># only get information in EXIF or MakerNotes groups</span>
|
|
$exifTool-><b>Options</b>(Group0 => ['EXIF', 'MakerNotes']);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># ignore information from IFD1</span>
|
|
$exifTool-><b>Options</b>(Group1 => '-IFD1');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># sort by groups in family 2, and extract unknown tags</span>
|
|
$exifTool-><b>Options</b>(Sort => 'Group2', Unknown => 1);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># reset DateFormat option</span>
|
|
$exifTool-><b>Options</b>(DateFormat => undef);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># do not extract duplicate tag names</span>
|
|
$oldSetting = $exifTool-><b>Options</b>(Duplicates => 0);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># get current Verbose setting</span>
|
|
$isVerbose = $exifTool-><b>Options</b>('Verbose');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set a user parameter</span>
|
|
$exifTool-><b>Options</b>(UserParam => 'MyParam=some value');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="ClearOptions">ClearOptions</a></h2>
|
|
<p>Reset all options to their default values. Loads user-defined default
|
|
option values from the %Image::ExifTool::UserDefined::Options hash in
|
|
the .ExifTool_config file if it exists.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>ClearOptions()</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="ExtractInfo">ExtractInfo</a></h2>
|
|
<p>Extract all meta information from an image.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>ExtractInfo($;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1-N)</b> Same as <a href="#ImageInfo">ImageInfo</a> except that a list of tag
|
|
keys is not returned if an ARRAY reference is given.
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>1 if this was a recognized file format, 0 otherwise</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
$success = $exifTool-><b>ExtractInfo</b>('image.jpg', \%options);
|
|
</pre></td></tr></table></blockquote>
|
|
<p>The following options are effective in the call to <a href="#ExtractInfo">ExtractInfo</a>:</p>
|
|
<blockquote>
|
|
Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3, CharsetIPTC,
|
|
CharsetQuickTime, Composite, ExtendedXMP, ExtractEmbedded, FastScan,
|
|
FixBase, HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang, LargeFileSupport,
|
|
MakerNotes, NoPDFList, PNGEarlyXMP, ScanForXMP, Struct, SystemTags, TextOut,
|
|
Unknown and Verbose.
|
|
</blockquote>
|
|
|
|
<hr><h2><a name="GetInfo">GetInfo</a></h2>
|
|
<p><a href="#GetInfo">GetInfo</a> is called to return meta information
|
|
after it has been extracted from the image by a previous call to
|
|
<a href="#ExtractInfo">ExtractInfo</a> or <a href="#ImageInfo">ImageInfo</a>.
|
|
This function may be called repeatedly after a single call to
|
|
<a href="#ExtractInfo">ExtractInfo</a> or <a href="#ImageInfo">ImageInfo</a>.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetInfo($;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1-N)</b> Same as <a href="#ImageInfo">ImageInfo</a> except that an image
|
|
can not be specified
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Reference to information hash, the same as with
|
|
<a href="#ImageInfo">ImageInfo</a></td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># get image width and height only</span>
|
|
$info = $exifTool-><b>GetInfo</b>('ImageWidth', 'ImageHeight');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># get all Error and Warning messages</span>
|
|
$info = $exifTool-><b>GetInfo</b>('Error', 'Warning');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># get information for all tags in list (list updated with tags found)</span>
|
|
$info = $exifTool-><b>GetInfo</b>(\@ioTagList);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># get all information in Author or Location groups</span>
|
|
$info = $exifTool-><b>GetInfo</b>({Group2 => ['Author', 'Location']});
|
|
</pre></td></tr></table></blockquote>
|
|
<p>The following options are effective in the call to <a href="#GetInfo">GetInfo</a>:</p>
|
|
<blockquote>
|
|
Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter, Group#,
|
|
GlobalTimeShift, Lang, List, ListItem, ListSep, PrintConv, Sort (if a tag
|
|
list reference is given) and StrictDate.
|
|
</blockquote>
|
|
|
|
<hr><h2><a name="WriteInfo">WriteInfo</a></h2>
|
|
<p>Write meta information to a file. The specified source file is rewritten to
|
|
the same-type destination file with new information as specified by previous
|
|
calls to <a href="#SetNewValue">SetNewValue</a>. The necessary segments and/or
|
|
directories are created in the destination file as required to store the
|
|
specified information. May be called repeatedly to write the same information
|
|
to additional files without the need to call <a href="#SetNewValue">SetNewValue</a>
|
|
again.</p>
|
|
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>WriteInfo($$;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Source file name, file reference, scalar reference, or undef to
|
|
create a file from scratch. A reference to a File::RandomAccess object is
|
|
also allowed as a source, but in this case the destination is not optional.
|
|
<br><b>2)</b> [<i>optional</i>] Destination file name, file reference, scalar
|
|
reference, or undef to overwrite the original file. May be '-' to write to
|
|
stdout.
|
|
<br><b>3)</b> [<i>optional</i>] Destination file type. Ignored if a source
|
|
is defined.
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>1 if file was written OK, 2 if file was written
|
|
but no changes made, 0 on file write error.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p>The source file name may be undefined to create a file from scratch
|
|
(currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be created
|
|
in this way -- see <a href="#CanCreate">CanCreate</a> for details).
|
|
If undefined, the destination file type is required unless the type can be
|
|
determined from the extension of the destination file name.</p>
|
|
<p>If a destination file name is given, the specified file must not exist
|
|
because an existing destination file will not be overwritten. Any new
|
|
values for FileName, Directory or HardLink are ignored when a destination
|
|
file name is specified.</p>
|
|
<p>The destination file name may be undefined to overwrite the original file
|
|
(make sure you have backups!). In this case, if a source file name is
|
|
provided, a temporary file is created and renamed to replace the source file
|
|
if no errors occurred while writing. Otherwise, if a source file reference
|
|
or scalar reference is used, the image is first written to memory then
|
|
copied back to replace the original if there were no errors.</p>
|
|
<p>On Mac OS systems, the file resource fork is preserved if this routine
|
|
is called with a source file name.</p>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># add information to a source file, writing output to new file</span>
|
|
my $result = $exifTool-><b>WriteInfo</b>($srcfile, $dstfile);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># create XMP data file from scratch</span>
|
|
$exifTool-><b>WriteInfo</b>(undef, $dstfile, 'XMP');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># overwrite file (you do have backups, right?)</span>
|
|
$exifTool-><b>WriteInfo</b>($srcfile);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># retrieve error and warning messages</span>
|
|
$errorMessage = $exifTool-><a href="#GetValue">GetValue</a>('Error');
|
|
$warningMessage = $exifTool-><a href="#GetValue">GetValue</a>('Warning');
|
|
</pre></td></tr></table></blockquote>
|
|
<p>If an error code is returned, an Error tag is set and GetValue('Error') can
|
|
be called to obtain the error description. A Warning tag may be set even if
|
|
this routine is successful. Calling WriteInfo clears any pre-existing Error
|
|
and Warning tags.</p>
|
|
<p>The following ExifTool options are effective in the call to
|
|
<a href="#WriteInfo">WriteInfo</a>:</p>
|
|
<blockquote>
|
|
ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
|
|
Compress, FixBase, IgnoreMinorErrors, PNGEarlyXMP and Verbose.
|
|
</blockquote>
|
|
|
|
<hr><h2><a name="GetTagList">GetTagList</a></h2>
|
|
<p>Get a sorted list of tags from the specified information hash or tag list.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetTagList($;$$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> [<i>optional</i>] Reference to info hash or tag list
|
|
<br><b>2)</b> [<i>optional</i>] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
|
|
<br><b>3)</b> [<i>optional</i>] Secondary sort order ('File', 'Tag' or 'Descr')
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of tag keys in specified order</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
@tags = $exifTool-><b>GetTagList</b>($info, 'Group0');
|
|
</pre></td></tr></table></blockquote>
|
|
<p>If the information hash or tag list reference is not provided, then the list
|
|
of found tags from the last call to <a href="#ImageInfo">ImageInfo</a>,
|
|
<a href="#ExtractInfo">ExtractInfo</a> or <a href="#GetInfo">GetInfo</a>
|
|
is used instead, and the result is the same as if
|
|
<a href="#GetFoundTags">GetFoundTags</a> was called. If sort order is not
|
|
specified, the sort order is taken from the current options settings.</p>
|
|
|
|
<hr><h2><a name="GetFoundTags">GetFoundTags</a></h2>
|
|
<p>Get list of found tags in specified sort order. The found tags are the
|
|
tags for the information obtained from the most recent call to
|
|
<a href="#ImageInfo">ImageInfo</a>, <a href="#ExtractInfo">ExtractInfo</a>
|
|
or <a href="#GetInfo">GetInfo</a> for this object.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetFoundTags($;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> [<i>optional</i>] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
|
|
<br><b>2)</b> [<i>optional</i>] Secondary sort order ('File', 'Tag' or 'Descr')
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of tag keys in the specified order</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my @tags = $exifTool-><b>GetFoundTags</b>('File');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetRequestedTags">GetRequestedTags</a></h2>
|
|
<p>Get list of requested tags. These are the tags that were specified
|
|
in the arguments of the most recent call to <a href="#ImageInfo">ImageInfo</a>,
|
|
<a href="#ExtractInfo">ExtractInfo</a> or <a href="#GetInfo">GetInfo</a>,
|
|
including tags specified via a tag list reference. They are returned
|
|
in the same order that they were specified. Shortcut tags are expanded
|
|
in the list.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetRequestedTags($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of tag keys for requested tags
|
|
(empty if no tags specifically requested)</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my @requestedTags = $exifTool-><b>GetRequestedTags</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetValue">GetValue</a></h2>
|
|
<p>Get the value of a specified tag. The returned value is either the
|
|
human-readable (PrintConv) value, the converted machine-readable (ValueConv)
|
|
value, or the original raw (Raw) value. If the value type is not specified,
|
|
the PrintConv value is returned if the PrintConv option is set, otherwise the
|
|
ValueConv value is returned. The PrintConv values are the same as the values
|
|
returned by <a href="#ImageInfo">ImageInfo</a> and <a href="#GetInfo">GetInfo</a>
|
|
in the tag/value hash unless the PrintConv option is disabled.</p>
|
|
<p>Tags which represent lists of multiple values (as may happen with
|
|
'<code>Keywords</code>' for example) are handled specially. In scalar context,
|
|
the returned PrintConv value for these tags is either a string of values or
|
|
a list reference (depending on the List option setting), and the ValueConv
|
|
value is always a list reference. But in list context,
|
|
<a href="#GetValue">GetValue</a> always returns the list itself.</p>
|
|
<p>Note that <a href="#GetInfo">GetValue</a> requires a case-sensitive tag key
|
|
as an argument. To retrieve tag information based on a case-insensitive tag name
|
|
(with an optional group specifier), use <a href="#GetInfo">GetInfo</a>
|
|
instead.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetValue($$;$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Tag key
|
|
<br><b>2)</b> [<i>optional</i>] Value type, 'PrintConv', 'ValueConv', 'Both',
|
|
'Raw' or 'Rational'
|
|
<br> <br>The default value type is 'PrintConv' if the PrintConv option
|
|
is set, otherwise the default is 'ValueConv'. A value type of 'Both'
|
|
returns both ValueConv and PrintConv values as a list. 'Rational' returns
|
|
the raw rational value as a string fraction for rational types, or undef for
|
|
other types.
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>
|
|
The value of the specified tag. If the tag represents a list of multiple values
|
|
and the List option is disabled then PrintConv returns a string of values,
|
|
otherwise a reference to the list is returned in scalar context. The list
|
|
itself is returned in list context. (Unless 'Both' values are requested, in
|
|
which case two list references are returned, regardless of context.) Values may
|
|
also be scalar references to binary data, or hash references if the
|
|
<a href="#Struct">Struct</a> option is set.<br> <br> Note: It is possible
|
|
for <a href="#GetValue">GetValue</a> to return an undefined ValueConv or
|
|
PrintConv value (or an empty list in list context) even if the tag exists, since
|
|
it is possible for these conversions to yield undefined values. And the
|
|
Rational value will be undefined for any non-rational tag. The Raw value should
|
|
always exist if the tag exists.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># PrintConv example</span>
|
|
my $val = $exifTool-><b>GetValue</b>($tag);
|
|
if (ref $val eq 'SCALAR') {
|
|
print "$tag = (unprintable value)\n";
|
|
} else {
|
|
print "$tag = $val\n";
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># ValueConv example</span>
|
|
my $val = $exifTool-><b>GetValue</b>($tag, 'ValueConv');
|
|
if (ref $val eq 'ARRAY') {
|
|
print "$tag is a list of values\n";
|
|
} elsif (ref $val eq 'SCALAR') {
|
|
print "$tag represents binary data\n";
|
|
} else {
|
|
print "$tag is a simple scalar\n";
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># list example</span>
|
|
my @keywords = $exifTool-><b>GetValue</b>('Keywords', 'ValueConv');
|
|
</pre></td></tr></table></blockquote>
|
|
<p>The following options are in effect when <a href="#GetValue">GetValue</a> is
|
|
called:</p>
|
|
<blockquote>
|
|
Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift, Lang, List,
|
|
ListItem, ListSep, PrintConv and StrictDate.
|
|
</blockquote>
|
|
|
|
<hr><h2><a name="SetNewValue">SetNewValue</a></h2>
|
|
<p>Set the new value for a tag. The routine may be called multiple times to set
|
|
the values of many tags before using <a href="#WriteInfo">WriteInfo</a> to write
|
|
the new values to an image.</p>
|
|
<p>For list-type tags (like <code>Keywords</code>), either call repeatedly with
|
|
the same tag name for each value, or call with a reference to the list of values.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SetNewValue($;$$%)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> [<i>optional</i>] Tag key or tag name, or undef to clear all new
|
|
values. The tag name may be prefixed one or more family 0, 1 or 2 group
|
|
names with optional leading family numbers, separated by colons (eg.
|
|
'<code>EXIF:Artist</code>', '<code>XMP:Time:*</code>'), which is equivalent
|
|
to using a Group option argument. Also, a '<code>#</code>' may be appended
|
|
to the tag name (eg. '<code>EXIF:Orientation#</code>'), with the same effect
|
|
as setting Type to 'ValueConv'. Wildcards ('<code>*</code>' and
|
|
'<code>?</code>') may be used in the tag name to assign multiple tags
|
|
simultaneously A tag name of '<code>*</code>' is special when deleting
|
|
information, and will delete an entire group even if some individual tags in
|
|
the group are not writable, but only if a single family 0 or 1 group name is
|
|
specified (otherwise, the tags are deleted individually). Use
|
|
<a href="#GetDeleteGroups">GetDeleteGroups</a> to get a list of deletable group
|
|
names, and see the <a href="TagNames/index.html">TagNames documentation</a>
|
|
for a complete list of ExifTool tag names.
|
|
<br><b>2)</b> [<i>optional</i>] New value for tag. Undefined to delete tag
|
|
from file. May be a scalar, scalar reference, list reference to set a list
|
|
of values, or hash reference for a structure. Integer values may be
|
|
specified as a hexadecimal string (with a leading '0x'), and simple
|
|
rational values may be specified in fractional form (eg. '4/10'). Structure
|
|
tags may be specified either as a hash reference or a serialized string
|
|
(see the last two examples below).
|
|
<br><b>3-N)</b> [<i>optional</i>] SetNewValue option/value pairs (see below).
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Scalar context: The number of tags set, and
|
|
errors are printed to STDERR.
|
|
<br>List context: The number of tags set, and the error string (undefined if no error).
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<blockquote><table class='norm'>
|
|
<tr><th colspan=4 bgcolor='#dddddd'>SetNewValue Options</th></tr>
|
|
<tr><th>Option</th><th>Description</th><th width='30%'>Values</th><th>Default</th></tr>
|
|
<tr><td>AddValue</td><td>Add value to existing list in a file rather than overwriting</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>Overwrite existing value(s)</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>Add to existing list, or warn for non-list tags</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>Add to existing list, or overwrite non-list tags</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>DelValue</td><td>Delete existing tag from a file if it has the specified value</td>
|
|
<td align=center>0 or 1</td><td align=center>0</td></tr>
|
|
<tr><td>EditGroup</td><td>Create tags in existing groups only. Don't create new group.
|
|
Effectively removes the 'g' from the ExifTool WriteMode option for this tag only.</td>
|
|
<td align=center>0 or 1</td><td align=center>0</td></tr>
|
|
<tr><td>EditOnly</td><td>Edit tag only if it already exists. Don't create new tag.
|
|
Effectively removes the 'c' from the ExifTool WriteMode option for this tag only.</td>
|
|
<td align=center>0 or 1</td><td align=center>0</td></tr>
|
|
<tr><td>Group</td><td>Specifies group name where tag should be written.
|
|
If not specified, tag is written to highest priority group as specified
|
|
by <a href="#SetNewGroups">SetNewGroups</a>. Case is not significant</td>
|
|
<td align=center>One or more family 0, 1 or 2 groups with optional leading
|
|
family number, separated by colons</td><td align=center>undef</td></tr>
|
|
<tr><td>NoFlat</td><td>Treat flattened tags as 'unsafe'</td><td align=center>0 or 1</td><td align=center>0</td></tr>
|
|
<tr><td>NoShortcut</td><td>Disables default behaviour of looking up tag in
|
|
shortcuts if not found otherwise.</td><td align=center>0 or 1</td><td align=center>0</td></tr>
|
|
<tr><td>Protected</td><td>Allow protected tags to be written</td>
|
|
<td>Bitmask of tag protection levels to write:
|
|
<table class=clear>
|
|
<tr><td valign=top align=center><b>0x01</b> =</td>
|
|
<td>Write '<a href="TagNames/index.html">unsafe</a>' tags (ie. tags not copied
|
|
automatically via <a href="#SetNewValuesFromFile">SetNewValuesFromFile</a>)</td></tr>
|
|
<tr><td valign=top align=center><b>0x02</b> =</td>
|
|
<td>Write '<a href="TagNames/index.html">protected</a>' tags (internal use only)</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>ProtectSaved</td><td>Avoid setting new values which were saved after the Nth
|
|
call to <a href="#SaveNewValues">SaveNewValues</a>. Has no effect on unsaved values,
|
|
or values saved before the Nth call.</td><td align=center>N</td><td align=center>undef</td></tr>
|
|
<tr><td>Replace</td><td>Replace previous new values for this tag (ie. replace the values
|
|
set in previous calls to <a href="#SetNewValue">SetNewValue</a>). This option
|
|
is most commonly used to replace previously-set new values for list-type tags.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=center><b>0</b> =</td><td>Set new value normally</td></tr>
|
|
<tr><td valign=top align=center><b>1</b> =</td><td>Reset previous new values and replace with the specifed new value</td></tr>
|
|
<tr><td valign=top align=center><b>2</b> =</td><td>Reset previous new values only</td></tr>
|
|
</table></td><td align=center>0</td></tr>
|
|
<tr><td>Shift</td><td>Shift the tag by the specified value. Currently only date/time tags
|
|
and tags with numerical values may be shifted. Value is added if Shift is 1, or subtracted
|
|
if Shift is -1. See <a href="Shift.html">Image::ExifTool::Shift.pl</a> for details time shift formats.</td>
|
|
<td><table class=clear>
|
|
<tr><td valign=top align=left colspan=2><b>undef</b> = No shift</td></tr>
|
|
<tr><td valign=top align=right><b>0</b> =</td><td>Shift if shiftable:<br>
|
|
Positive if AddValue set, or<br>
|
|
Negative if DelValue set and<br>
|
|
tag is date/time</td></tr>
|
|
<tr><td valign=top align=right><b>1</b> =</td><td>Positive shift</td></tr>
|
|
<tr><td valign=top align=right><b>-1</b> =</td><td>Negative shift</td></tr>
|
|
</table></td><td align=center>undef</td></tr>
|
|
<tr><td>Type</td><td>The type of value being set</td>
|
|
<td>PrintConv, ValueConv or Raw (default depends on <a href="#PrintConv">PrintConv</a> Option)</td>
|
|
<td align=center>PrintConv or ValueConv</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set a new value for a tag (errors go to STDERR)</span>
|
|
$success = $exifTool-><b>SetNewValue</b>($tag, $value);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set a new value and capture any error message</span>
|
|
($success, $errStr) = $exifTool-><b>SetNewValue</b>($tag, $value);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># delete information for specified tag if it exists in image
|
|
# (also resets AddValue and DelValue options for this tag)</span>
|
|
$exifTool-><b>SetNewValue</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># reset all values from previous calls to SetNewValue()</span>
|
|
$exifTool-><b>SetNewValue</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># delete a specific keyword</span>
|
|
$exifTool-><b>SetNewValue</b>('Keywords', $word, DelValue => 1);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set keywords (a list-type tag) with two new values</span>
|
|
$exifTool-><b>SetNewValue</b>(Keywords => 'word1');
|
|
$exifTool-><b>SetNewValue</b>(Keywords => 'word2');
|
|
<span class=com># equivalent, but set both in one call using an array reference</span>
|
|
$exifTool-><b>SetNewValue</b>(Keywords => ['word1','word2']);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># add a keyword without replacing existing keywords in the file</span>
|
|
$exifTool-><b>SetNewValue</b>(Keywords => $word, AddValue => 1);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set a tag in a specific group</span>
|
|
$exifTool-><b>SetNewValue</b>(Headline => $val, Group => 'XMP');
|
|
$exifTool-><b>SetNewValue</b>('XMP:Headline' => $val); <span class=com># (equivalent)</span>
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># shift original date/time back by 2.5 hours</span>
|
|
$exifTool-><b>SetNewValue</b>(DateTimeOriginal => '2:30', Shift => -1);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># write a tag only if it had a specific value
|
|
# (the order of the following calls is not significant)</span>
|
|
$exifTool-><b>SetNewValue</b>(Title => $oldVal, DelValue => 1);
|
|
$exifTool-><b>SetNewValue</b>(Title => $newVal);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># write tag by numerical value</span>
|
|
$exifTool-><b>SetNewValue</b>(Orientation => 6, Type => 'ValueConv');
|
|
$exifTool-><b>SetNewValue</b>('Orientation#' => 6); <span class=com># (equivalent)</span>
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># delete all but EXIF tags</span>
|
|
$exifTool-><b>SetNewValue</b>('*'); <span class=com># delete all...</span>
|
|
$exifTool-><b>SetNewValue</b>('EXIF:*', undef, Replace => 2); <span class=com># ...but EXIF</span>
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td>
|
|
<pre><span class=com># write structured information as a HASH reference</span>
|
|
$exifTool-><b>SetNewValue</b>('XMP:Flash' => { mode=>'on', fired=>'true', return=>'not' });</pre>
|
|
</td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td>
|
|
<pre><span class=com># write structured information as a serialized string</span>
|
|
$exifTool-><b>SetNewValue</b>('XMP:Flash' => '{mode=on,fired=true,return=not}');</pre>
|
|
</td></tr></table>(see <a href="struct.html#Serialize">struct.html</a> for a
|
|
description of the structure serialization technique)</blockquote>
|
|
|
|
<p><b>Notes:</b></p>
|
|
<p>When deleting groups of tags, the Replace option may be used to exclude
|
|
specific groups from a mass delete. However, this technique may not be used to
|
|
exclude individual tags from a group delete (unless a family 2 group was
|
|
specified in the delete). Instead, use
|
|
<a href="#SetNewValuesFromFile">SetNewValuesFromFile</a> to recover the values
|
|
of individual tags after deleting a group.</p>
|
|
<p>When deleting all tags from a JPEG image, the APP14 "Adobe" information is
|
|
not deleted by default because doing so may affect the appearance of the image.
|
|
However, this information may be deleted by specifying it explicitly, either by
|
|
group (with '<code>Adobe:*</code>') or as a block (with '<code>Adobe</code>').</p>
|
|
<p>The following ExifTool options are effective in the call to
|
|
<a href="#SetNewValue">SetNewValue</a>:</p>
|
|
<blockquote>
|
|
Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv, Verbose
|
|
and WriteMode.
|
|
</blockquote>
|
|
|
|
<hr><h2><a name="GetNewValue">GetNewValue</a><a name="GetNewValues"></a></h2>
|
|
<p>Get the new Raw value for a tag. This is the value set by
|
|
<a href="#SetNewValue">SetNewValue</a> that is queued to be written to
|
|
file. List-type tags may return multiple values in list context.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetNewValue($$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Tag name (case sensitive, may be prefixed by family 0 or 1 group name)
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of new Raw tag values, or first value in
|
|
list when called in scalar context. The list may be empty either if the tag
|
|
isn't being written, or if it is being deleted (ie. if
|
|
<a href="#SetNewValue">SetNewValue</a> was called without a value).
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $rawVal = $exifTool-><b>GetNewValue</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my @rawVals = $exifTool-><b>GetNewValue</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="SetNewValuesFromFile">SetNewValuesFromFile</a></h2>
|
|
<p>A very powerful routine that sets new values for tags from information found
|
|
in a specified file.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SetNewValuesFromFile($$;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> File name, file reference, or scalar reference
|
|
<br><b>2-N)</b> [<i>optional</i>] List of tag names to set or options hash
|
|
references. All writable tags are set if none are specified. The tag names
|
|
are not case sensitive, and may be prefixed by one or more family 0, 1 or 2
|
|
group names with optional leading family numbers, separated by colons (eg.
|
|
'<code>exif:iso</code>'). A leading '<code>-</code>' indicates tags to be
|
|
excluded (eg. '<code>-comment</code>'), or a trailing '<code>#</code>' causes
|
|
the ValueConv value to be copied (same as setting the Type option to
|
|
'ValueConv' for this tag only). Wildcards ('<code>*</code>' and
|
|
'<code>?</code>') may be used in the tag name. A tag name of '<code>*</code>'
|
|
is commonly used when a group is specified to copy all tags in the group (eg.
|
|
'<code>XMP:*</code>').<br> <br> A special feature allows tag names of the
|
|
form '<code>DSTTAG<SRCTAG</code>' (or '<code>SRCTAG>DSTTAG</code>') to be
|
|
specified to copy information to a tag with a different name or a specified
|
|
group. Both '<code>SRCTAG</code>' and '<code>DSTTAG</code>' may contain
|
|
wildcards and/or be prefixed by a group name (eg.
|
|
'<code>fileModifyDate<modifyDate</code>' or '<code>xmp:*<*</code>'),
|
|
and/or suffixed by a '<code>#</code>' to disable print conversion. Copied tags
|
|
may also be added or deleted from a list with arguments of the form
|
|
'<code>DSTTAG+<SRCTAG</code>' or '<code>DSTTAG-<SRCTAG</code>'. Tags are
|
|
evaluated in order, so exclusions apply only to tags included earlier in the
|
|
list. An extension of this feature allows the tag value to be set from an
|
|
expression containing tag names with leading '<code>$</code>' symbols (eg.
|
|
'<code>Comment<the file is $filename</code>'). Braces '<code>{}</code>' may
|
|
be used around the tag name to separate it from subsequent text, and a
|
|
'<code>$$</code>' is used to to represent a '<code>$</code>' symbol. The
|
|
behaviour for missing tags in expressions is defined by the <a
|
|
href="#MissingTagValue">MissingTagValue</a> option. The tag value may be
|
|
modified via changes to the default input variable (<code>$_</code>) in Perl
|
|
expressions placed inside the braces and after a semicolon following the tag
|
|
name. Braces within the expression must be balanced.
|
|
<br> <br>
|
|
Multiple options hash references may be passed to set different options for
|
|
different tags. Options apply to subsequent tags in the argument list.
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>A hash of information that was set
|
|
successfully. May include Warning or Error entries if there were problems
|
|
reading the input file.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p>By default, this routine will commute information between same-named tags in
|
|
different groups, allowing information to be translated between images with
|
|
different formats. This behaviour may be modified by specifying a group name
|
|
for extracted tags (even if '<code>*</code>' is used as a group name), in which
|
|
case the information is written to the original group, unless redirected to a
|
|
different group. When '<code>*</code>' is used for a group name, by default the
|
|
family 1 group of the original tag is preserved, but a different family may be
|
|
specified with a leading family number. (For example, specifying
|
|
'<code>*:*</code>' copies all information while preserving the original family 1
|
|
groups, while '<code>0*:*</code>' preserves the family 0 group.)</p>
|
|
<p><b>SetNewValuesFromFile Options:</b></p>
|
|
<p>The options are the same was for <a href="#SetNewValue">SetNewValue</a>, and
|
|
are passed directly to <a href="#SetNewValue">SetNewValue</a> internally,
|
|
with a few exceptions:</p>
|
|
<ul>
|
|
<li>The Replace option defaults to 1 instead of 0 as with
|
|
<a href="#SetNewValue">SetNewValue</a>.</li>
|
|
<li>The AddValue or DelValue option is set for individual tags if '+>' or
|
|
'->' (or '+<' or '-<') are used.</li>
|
|
<li>The Group option is set for tags where a group name is given.</li>
|
|
<li>The Protected flag is set to 1 for individually specified tags.</li>
|
|
<li>The Type option also applies to extracted tags.</li>
|
|
</ul>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set new values from all information in a file...</span>
|
|
my $info = $exifTool-><b>SetNewValuesFromFile</b>($srcFile);
|
|
<span class=com># ...then write these values to another image</span>
|
|
my $result = $exifTool-><a href="#WriteInfo">WriteInfo</a>($file2, $outFile);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set all new values, preserving original groups</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($srcFile, '*:*');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set specific information</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($srcFile, $tag1, $tag2...);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set new value from a different tag in specific group</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($src, 'IPTC:Keywords>XMP-dc:Subject');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># add all IPTC keywords to XMP subject list</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($src, 'IPTC:Keywords+>XMP-dc:Subject');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set new value from an expression involving other tags</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($file,
|
|
'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set keywords list from the values of multiple tags</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($file, { Replace => 0 },
|
|
'keywords<xmp:subject', 'keywords<filename');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># copy all EXIF information, preserving the original IFD
|
|
# (without '>*.*' tags would be copied to the preferred EXIF IFD)</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($file, 'EXIF:*>*:*');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># copy all tags with names starting with "gps" (note: this is
|
|
# different than "gps:*" because it will also copy XMP GPS tags)</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($file, 'gps*');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># set FileName from Model, translating questionable characters to underlines</span>
|
|
$exifTool-><b>SetNewValuesFromFile</b>($file, 'filename<${model;tr(/\\\\?*:|"<>)(_)}.jpg');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<p><b>Notes:</b></p>
|
|
<p>The PrintConv option applies to this routine, but it normally should be left
|
|
on to provide more reliable transfer of information between groups.</p>
|
|
<p>If a preview image exists, it is not copied. The preview image must be
|
|
transferred separately if desired, in a separate call to
|
|
<a href="#WriteInfo">WriteInfo</a></p>
|
|
<p>When simply copying all information between files of the same type, it is
|
|
usually desirable to preserve the original groups by specifying
|
|
'<code>*:*</code>' for the tags to set.</p>
|
|
<p>The <a href="#Duplicates">Duplicates</a> option is always in effect for tags
|
|
extracted from the source file using this routine.</p>
|
|
<p>The <a href="#Struct">Struct</a> option is enabled by default for tags
|
|
extracted by this routine. This allows the hierarchy of complex structures to
|
|
be preserved when copying, but the Struct option may be set to 0 to override
|
|
this behaviour and copy as flattened tags instead.</p>
|
|
|
|
<hr><h2><a name="CountNewValues">CountNewValues</a></h2>
|
|
<p>Return the total number of new values set.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>CountNewValues($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>In scalar context, returns the total number
|
|
of tags with new values set. In list context, also returns the number of
|
|
"pseudo" tag values which have been set. "Pseudo" tags are tags like FileName
|
|
and FileModifyDate which are not contained within the file and can be changed
|
|
without rewriting the file.</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $numSet = $exifTool-><b>CountNewValues</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my ($numSet, $numPseudo) = $exifTool-><b>CountNewValues</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="SaveNewValues">SaveNewValues</a></h2>
|
|
<p>Save state of new values to be later restored by <a href="#RestoreNewValues">RestoreNewValues</a>.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SaveNewValues($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Count of the number of times this routine has
|
|
been called (N) since the last time the new values were reset.</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
$exifTool-><b>SaveNewValues</b>(); <span class=com># save state of new values</span>
|
|
$exifTool-><a href="#SetNewValue">SetNewValue</a>(ISO => 100); <span class=com># set new value for ISO</span>
|
|
$exifTool-><a href="#WriteInfo">WriteInfo</a>($src, $dst1); <span class=com># write ISO plus any previous new values</span>
|
|
$exifTool-><b>RestoreNewValues</b>(); <span class=com># restore previous new values</span>
|
|
$exifTool-><a href="#WriteInfo">WriteInfo</a>($src, $dst2); <span class=com># write previous new values only</span>
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="RestoreNewValues">RestoreNewValues</a></h2>
|
|
<p>Restore new values to the settings that existed when
|
|
<a href="#SaveNewValues">SaveNewValues</a> was last called. May be called
|
|
repeatedly after a single call to <a href="#SaveNewValues">SaveNewValues</a>.
|
|
See <a href="#SaveNewValues">SaveNewValues</a> above for an example.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>RestoreNewValues($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="SetFileModifyDate">SetFileModifyDate</a></h2>
|
|
<p>Write the filesystem modification or creation time from the new value of the
|
|
FileModifyDate or FileCreateDate tag.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SetFileModifyDate($$;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> File name
|
|
<br><b>2)</b> [<i>optional</i>] Base time if applying shift (in days before $^T)
|
|
<br><b>3)</b> [<i>optional</i>] Tag to write: 'FileModifyDate' (default), or 'FileCreateDate'
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>1 if the time was changed, 0 if nothing was
|
|
done, or -1 if there was an error setting the time.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
$exifTool-><a href="#SetNewValue">SetNewValue</a>(FileModifyDate => '2000:01:02 03:04:05', Protected => 1);
|
|
my $result = $exifTool-><b>SetFileModifyDate</b>($file);
|
|
</pre></td></tr></table></blockquote>
|
|
<p><b>Notes:</b></p>
|
|
<p>Equivalent to, but more efficient than calling <a href="#WriteInfo">WriteInfo</a>
|
|
when only the FileModifyDate or FileCreateDate tag has been set. If a timezone is not
|
|
specified, local time is assumed. When shifting, the time of the original
|
|
file is used unless the optional base time is specified.</p>
|
|
<p>The ability to write FileCreateDate is currently restricted to Windows systems only.</p>
|
|
|
|
<hr><h2><a name="SetFileName">SetFileName</a></h2>
|
|
<p>Set the file name and directory, or create a hard link to the file. If not
|
|
specified, the new file name is derived from the new values of the FileName and
|
|
Directory tags, or from the HardLink tag if creating a link. If the FileName
|
|
tag contains a '<code>/</code>', then the file is renamed into a new directory.
|
|
If FileName ends with '<code>/</code>', then it is taken as a directory name and
|
|
the file is moved into the new directory. The new value for the Directory tag
|
|
takes precedence over any directory specified in FileName.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SetFileName($$;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Current file name
|
|
<br><b>2)</b> [<i>optional</i>] New file name
|
|
<br><b>3)</b> [<i>optional</i>] 'Link' to create a hard link instead of renaming the file,
|
|
or 'Test' to test renaming feature by printing the old and new names instead of
|
|
changing anything.
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>1 if the file name or directory was changed,
|
|
0 if nothing was done, or -1 if there was an error renaming the file.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $result = $exifTool-><b>SetFileName</b>($file);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $result = $exifTool-><b>SetFileName</b>($file, $newName);
|
|
</pre></td></tr></table></blockquote>
|
|
<p><b>Notes:</b></p>
|
|
<p>Will not overwrite existing files. New directories are created as
|
|
necessary.</p>
|
|
|
|
<hr><h2><a name="SetNewGroups">SetNewGroups</a></h2>
|
|
<p>Set the order of the preferred groups when adding new information. In
|
|
subsequent calls to <a href="#SetNewValue">SetNewValue</a>, new information
|
|
will be created in the first valid group of this list. This has an impact
|
|
only if the group is not specified when calling
|
|
<a href="#SetNewValue">SetNewValue</a>, and if the tag name exists in more
|
|
than one group. The default order is EXIF, IPTC then XMP. Any family 0
|
|
group name may be used. Case is not significant.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>SetNewGroups($;@)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1-N)</b> Groups in order of priority. If no groups are specified, the
|
|
priorities are reset to the defaults.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
$exifTool-><b>SetNewGroups</b>('XMP','EXIF','IPTC');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetNewGroups">GetNewGroups</a></h2>
|
|
<p>Get current group priority list.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetNewGroups($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of group names in order of write
|
|
priority. Highest priority first.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
@groups = $exifTool-><b>GetNewGroups</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetTagID">GetTagID</a></h2>
|
|
<p>Get the ID for the specified tag. The ID is the IFD tag number in EXIF
|
|
information, the property name in XMP information, or the data offset in a
|
|
binary data block. For some tags, such as Composite tags where there is no ID,
|
|
an empty string is returned. In list context, also returns a language code for
|
|
the tag if available and different from the default language (eg. with
|
|
alternate language entries for XMP "lang-alt" tags).</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetTagID($$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Tag key
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>In scalar context, returns the tag ID or '' if
|
|
there is no ID for this tag.<br>In list context, returns the tag ID (or '') and the
|
|
language code (or undef).</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $id = $exifTool-><b>GetTagID</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my ($id, $lang) = $exifTool-><b>GetTagID</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetDescription">GetDescription</a></h2>
|
|
<p>Get description for specified tag. This function will always return a defined
|
|
value. In the case where the description doesn't exist, one is generated from
|
|
the tag name.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetDescription($$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Tag key
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Tag description</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="GetGroup">GetGroup</a></h2>
|
|
<p>Get group name(s) for a specified tag.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetGroup($$;$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> Tag key
|
|
<br><b>2)</b> [<i>optional</i>] Group family number, or string of numbers
|
|
separated by colons
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Group name (or '' if tag has no
|
|
group). If no group family is specified, returns the name of group in family 0
|
|
when called in scalar context, or the names of groups for all families in list
|
|
context. Returns a string of group names separated by colons if the input group
|
|
family contains a colon. The string is simplified to remove a leading 'Main:'
|
|
and adjacent identical group names unless the family string begins with a colon.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p>The following families of groups are available:</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><th>Family</th><th>Description</th><th>Examples</th></tr>
|
|
<tr><td align=center>0</td><td>Information Type</td> <td>EXIF, XMP, IPTC</td></tr>
|
|
<tr><td align=center>1</td><td>Specific Location</td><td>IFD0, XMP-dc</td></tr>
|
|
<tr><td align=center>2</td><td>Category</td> <td>Author, Time</td></tr>
|
|
<tr><td align=center>3</td><td>Document Number</td> <td>Main, Doc1, Doc3-2</td></tr>
|
|
<tr><td align=center>4</td><td>Instance Number</td> <td>Copy1, Copy2, Copy3...</td></tr>
|
|
</table></blockquote>
|
|
|
|
<p>Families 0 and 1 are based on the file structure, and are similar except that
|
|
family 1 is more specific and sub-divides some groups to give more detail about
|
|
the specific location where the information was found. For example, the EXIF
|
|
group is split up based on the specific IFD (Image File Directory), the
|
|
MakerNotes group is divided into groups for each manufacturer, and the XMP group
|
|
is separated based on the XMP namespace prefix. Note that only common XMP
|
|
namespaces are listed in the <a href="#GetAllGroups">GetAllGroups</a>
|
|
documentation, but additional namespaces may be present in some XMP data. Also
|
|
note that the '<code>XMP-xmp</code>...' group names may appear in the older form
|
|
'<code>XMP-xap</code>...' since these names evolved as the XMP standard was
|
|
developed. The ICC_Profile group is broken down to give information about the
|
|
specific ICC_Profile tag from which multiple values were extracted. As well,
|
|
information extracted from the ICC_Profile header is separated into the
|
|
ICC-header group.</p>
|
|
<p>Family 2 classifies information based on the logical category to which the
|
|
information refers.</p>
|
|
<p>Family 3 gives the document number for tags extracted from embedded documents,
|
|
or 'Main' for tags from the main document. (See the
|
|
<a href="#Embedded">ExtractEmbedded</a> option for extracting tags from embedded
|
|
documents.) Nested sub-documents (if they exist) are indicated by numbers
|
|
separated with dashes in the group name, to an arbitrary depth. (eg.
|
|
'<code>Doc2-3-1</code>' is the 1<sup>st</sup> sub-sub-document of the
|
|
3<sup>rd</sup> sub-document of the 2<sup>nd</sup> embedded document of the main
|
|
file.)</p>
|
|
<p>Family 4 provides a method for differentiating tags when multiple tags exist
|
|
with the same name in the same location. The primary instance of a tag (the tag
|
|
extracted when the Duplicates option is disabled and no group is specified) has
|
|
no family 4 group name, but additional instances have have family 4 group names
|
|
of '<code>Copy1</code>', '<code>Copy2</code>', '<code>Copy3</code>', etc.</p>
|
|
<p>See <a href="#GetAllGroups">GetAllGroups</a> for lists of group names.</p>
|
|
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># return family 0 group name (eg. 'EXIF')</span>
|
|
$group = $exifTool-><b>GetGroup</b>($tag, 0);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># return all groups (eg. qw{EXIF IFD0 Author Main})</span>
|
|
@groups = $exifTool-><b>GetGroup</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># return groups as a string (eg. 'Main:IFD0:Author')</span>
|
|
$group = $exifTool-><b>GetGroup</b>($tag, ':3:1:2');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
<span class=com># return groups as a simplified string (eg. 'IFD0:Author')</span>
|
|
$group = $exifTool-><b>GetGroup</b>($tag, '3:1:2');
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetGroups">GetGroups</a></h2>
|
|
<p>Get list of group names for all tags in specified information hash.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetGroups($;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
<br><b>1)</b> [<i>optional</i>] Information hash reference (default is all extracted info)
|
|
<br><b>2)</b> [<i>optional</i>] Group family number (default 0)
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>
|
|
List of group names in alphabetical order.
|
|
If information hash is not specified, the group names are returned for
|
|
all extracted information. See <a href="#GetAllGroups">GetAllGroups</a> for
|
|
a list of groups in each family.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my @groups = $exifTool-><b>GetGroups</b>($info, $family);
|
|
</pre></td></tr></table></blockquote>
|
|
<blockquote>Example of one way to print information organized by group
|
|
<table class='box'><tr><td><pre>
|
|
my $exifTool = <a href="#new">new</a> Image::ExifTool;
|
|
$exifTool-><a href="#ExtractInfo">ExtractInfo</a>('t/images/ExifTool.jpg');
|
|
|
|
my $family = 1;
|
|
my @groups = $exifTool-><b>GetGroups</b>($family);
|
|
my $group;
|
|
foreach $group (@groups) {
|
|
print "---- $group ----\n";
|
|
my $info = $exifTool-><a href="#GetInfo">GetInfo</a>({"Group$family" => $group});
|
|
foreach ($exifTool-><a href="#GetTagList">GetTagList</a>($info)) {
|
|
print "$_ : $$info{$_}\n";
|
|
}
|
|
}
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="BuildCompositeTags">BuildCompositeTags</a></h2>
|
|
<p>Builds composite tags from required tags. The composite tags are convenience
|
|
tags which are derived from the values of other tags. This routine is called
|
|
automatically by <a href="#ImageInfo">ImageInfo</a> if the Composite option is set.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>BuildCompositeTags($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>(none)</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Notes:</b></p>
|
|
<ol>
|
|
<li>Tag values are calculated in alphabetical order unless a tag Require's
|
|
or Desire's another composite tag, in which case the calculation is
|
|
deferred until after the other tag is calculated.</li>
|
|
<li>Composite tags may need to read data from the image for their value to be
|
|
determined, and for these <a href="#BuildCompositeTags">BuildCompositeTags</a>
|
|
must be called while the image is available. This is only a problem if
|
|
<a href="#ImageInfo">ImageInfo</a> is called with a filename (as opposed to a
|
|
file reference or scalar reference) since in this case the file is closed before
|
|
<a href="#ImageInfo">ImageInfo</a> returns. Here the Composite option may be
|
|
used so that <a href="#BuildCompositeTags">BuildCompositeTags</a> is called from
|
|
within <a href="#ImageInfo">ImageInfo</a>, before the file is closed.</li>
|
|
</ol>
|
|
<hr><table bgcolor='#ffaaaa' width='100%' cellpadding=8><tr><td><center><b>
|
|
The following functions access only static data and are not called with an
|
|
ExifTool object
|
|
</b></center></td></tr></table>
|
|
|
|
<p>The names of all the following functions, plus
|
|
<a href="#ImageInfo">ImageInfo</a>, may be imported into the current namespace
|
|
with the "Public" tag. When this is done, the functions can be accessed without
|
|
the need to prefix the function name with "<code>Image::ExifTool::</code>". For
|
|
example:</p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
use Image::ExifTool ':Public';
|
|
$tagName = <a href="#GetTagName">GetTagName</a>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetTagName">GetTagName</a></h2>
|
|
<p>Get name of tag from tag identifier. This is a convenience function that
|
|
strips the embedded instance number, if it exists, from the tag key.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetTagName($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> Tag key
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>Tag name</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
$tagName = Image::ExifTool::<b>GetTagName</b>($tag);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetShortcuts">GetShortcuts</a></h2>
|
|
<p>Get list of tag shortcut names.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetShortcuts()</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td>(none)
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>List of shortcuts</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="GetAllTags">GetAllTags</a></h2>
|
|
<p>Get list of all available tag names.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetAllTags(;$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> [<i>optional</i>] Group name,
|
|
or string of group names separated by colons
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>A list of all available tags in alphabetical
|
|
order, or all tags in a specified group or intersection of groups. The
|
|
group name is case insensitive, and any group in families 0-2 may be used
|
|
except for EXIF family 1 groups (ie. the specific IFD).
|
|
</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="GetWritableTags">GetWritableTags</a></h2>
|
|
<p>Get list of all writable tag names.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetWritableTags(;$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> [<i>optional</i>] Group name,
|
|
or string of group names separated by colons
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>A list of all writable tags in alphabetical
|
|
order. These are the tags for which values may be set through
|
|
<a href="#SetNewValue">SetNewValue</a>. If a group name is given, returns
|
|
only writable tags in specified group(s). The group name is case insensitive,
|
|
and any group in families 0-2 may be used except for EXIF family 1 groups (ie.
|
|
the specific IFD).
|
|
</td></tr>
|
|
</table></blockquote>
|
|
|
|
<hr><h2><a name="GetAllGroups">GetAllGroups</a></h2>
|
|
<p>Get list of all group names in specified family.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetAllGroups($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> Group family number (0-4)
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td>
|
|
<td>A list of all groups in the specified family in alphabetical order</td></tr>
|
|
</table></blockquote>
|
|
<p>Here is a complete list of groups for each family:</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><th>Family</th><th>Group Names</th></tr>
|
|
<tr><td><b>0 (Information Type)</b></td>
|
|
<td>AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15, APP4, APP5,
|
|
APP6, APP8, ASF, Audible, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky,
|
|
EXE, EXIF, ExifTool, FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation,
|
|
GIF, GIMP, GeoTiff, H264, HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG,
|
|
Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, MNG, MOI, MPC, MPEG, MPF, MXF,
|
|
MakerNotes, Matroska, Meta, Ogg, OpenEXR, PDF, PICT, PLIST, PNG, PSP, Palm,
|
|
PanasonicRaw, PhotoCD, PhotoMechanic, Photoshop, PostScript, PrintIM,
|
|
QuickTime, RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real, SVG, SigmaRaw,
|
|
Stim, Theora, Torrent, VCard, Vorbis, XML, XMP, ZIP
|
|
</td></tr>
|
|
<tr><td><b>1 (Specific Location)</b></td>
|
|
<td>AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple, Audible,
|
|
CIFF, Canon, CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#, Composite,
|
|
DICOM, DNG, DV, DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool,
|
|
FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation, FujiFilm, FujiIFD, GE,
|
|
GIF, GIMP, GPS, GeoTiff, GlobParamIFD, GraphConv, H264, HP, HTC, HTML,
|
|
HTML-dc, HTML-ncc, HTML-office, HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm,
|
|
ICC-clrt, ICC-header, ICC-meas, ICC-meta, ICC-view, ICC_Profile,
|
|
ICC_Profile#, ID3, ID3v1, ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1,
|
|
IPTC, IPTC#, ITC, InteropIFD, JFIF, JPEG, JPEG-HDR, JVC, Jpeg2000, KDC_IFD,
|
|
Kodak, KodakBordersIFD, KodakEffectsIFD, KodakIFD, KyoceraRaw, LNK, Leaf,
|
|
LeafSubIFD, Leica, Lytro, M2TS, MAC, MIE-Audio, MIE-Camera, MIE-Canon,
|
|
MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-Geo, MIE-Image, MIE-Lens,
|
|
MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-Orient, MIE-Preview, MIE-Thumbnail,
|
|
MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MNG, MOBI, MOI, MPC, MPEG, MPF0,
|
|
MPImage, MXF, MakerNotes, MakerUnknown, Matroska, MediaJukebox, MetaIFD,
|
|
Microsoft, Minolta, MinoltaRaw, Motorola, NITF, Nikon, NikonCapture,
|
|
NikonCustom, NikonScan, Nintendo, Ocad, Ogg, Olympus, OpenEXR, PDF, PICT,
|
|
PNG, PNG-pHYs, PSP, Palm, Panasonic, PanasonicRaw, Pentax, PhaseOne,
|
|
PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript, PreviewIFD,
|
|
PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF,
|
|
Radiance, Rawzor, Real, Real-CONT, Real-MDPR, Real-PROP, Real-RA3, Real-RA4,
|
|
Real-RA5, Real-RJMD, Reconyx, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD,
|
|
SRF#, SVG, Samsung, Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim,
|
|
SubIFD, System, Theora, Torrent, Track#, VCalendar, VCard, Version0, Vorbis,
|
|
XML, XMP, XMP-DICOM, XMP-GPano, XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas,
|
|
XMP-acdsee, XMP-album, XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell, XMP-crs,
|
|
XMP-dc, XMP-dex, XMP-digiKam, XMP-dwc, XMP-exif, XMP-exifEX,
|
|
XMP-expressionmedia, XMP-extensis, XMP-fpv, XMP-getty, XMP-ics,
|
|
XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro, XMP-microsoft,
|
|
XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech,
|
|
XMP-photoshop, XMP-plus, XMP-prism, XMP-prl, XMP-pur, XMP-rdf, XMP-swf,
|
|
XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, XMP-xmpNote,
|
|
XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP
|
|
</td></tr>
|
|
<tr><td><b>2 (Category)</b></td>
|
|
<td>Audio, Author, Camera, Document, ExifTool, Image, Location, Other,
|
|
Preview, Printing, Time, Unknown, Video
|
|
</td></tr>
|
|
<tr><td><b>3 (Document Number)</b></td>
|
|
<td>Doc#, Main
|
|
</td></tr>
|
|
<tr><td><b>4 (Instance Number)</b></td>
|
|
<td>Copy#
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
@groupList = Image::ExifTool::<b>GetAllGroups</b>($family);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetDeleteGroups">GetDeleteGroups</a></h2>
|
|
<p>Get list of all deletable group names.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetDelGroups()</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td>
|
|
<td>None
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>A list of deletable group names in
|
|
alphabetical order.
|
|
</td></tr>
|
|
</table></blockquote>
|
|
<p>Below is a current list of deletable group names. All names in this list
|
|
are either family 0 or family 1 group names, with the exception of
|
|
'<code>Trailer</code>' which allows all trailers in JPEG and TIFF-format images
|
|
to be deleted at once, including unknown trailers. To schedule a group for
|
|
deletion, call <a href="#SetNewValue">SetNewValue</a> with an undefined value
|
|
and a tag name like '<code>Trailer:*</code>'.</p>
|
|
<blockquote>AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15, APP2, APP3,
|
|
APP4, APP5, APP6, APP7, APP8, APP9, Adobe, Audio, Author, CIFF, Camera,
|
|
CanonVRD, Copyright, Document, Ducky, EXIF, ExifIFD, ExifTool, File,
|
|
FlashPix, FotoStation, GPS, GlobParamIFD, ICC_Profile, IFD0, IFD1, IPTC,
|
|
Image, InteropIFD, JFIF, Jpeg2000, Location, MIE, MPF, MakerNotes, Meta,
|
|
MetaIFD, NikonCapture, Other, PDF, PDF-update, PNG, PNG-pHYs, PhotoMechanic,
|
|
Photoshop, PrintIM, Printing, RMETA, RSRC, SubIFD, Time, Trailer, Video,
|
|
XML, XML-*, XMP, XMP-*</blockquote>
|
|
<p>Note that the JPEG "APP" groups are special, and are used only to delete
|
|
application segments which are not associated with another deletable group. For
|
|
example, deleting '<code>APP14:*</code>' will delete other APP14 segments, but
|
|
not the APP14 "Adobe" segment. Also note that deleting a family 0 or 1 group
|
|
will delete the entire corresponding block of metadata, but deleting a family 2
|
|
group (eg. Audio, Author, Camera, etc.) deletes the individual tags belonging
|
|
to that category.</p>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my @delGroups = Image::ExifTool::<b>GetDelGroups</b>();
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="GetFileType">GetFileType</a></h2>
|
|
<p>Get type of file given file name.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>GetFileType(;$$)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td>
|
|
<td><b>0)</b> [<i>optional</i>] File name or extension
|
|
<br><b>1)</b> [<i>optional</i>] Flag to return a description instead of a type.
|
|
Set to 0 to return type for recognized but unsupported files (otherwise the
|
|
return value for unsupported files is undef).
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>A string, based on the file extension, which
|
|
indicates the basic format of the file. Note that some files may be based on
|
|
other formats (like many RAW image formats are based on TIFF). In array
|
|
context, may return more than one file type if the file may be based on
|
|
different formats. Returns undef if files with this extension are not yet
|
|
supported by ExifTool. Returns a list of extensions for all supported file
|
|
types if no input extension is specified (or all recognized file types if the
|
|
description flag is set to 0). Returns a more detailed description of the
|
|
specific file format when the description flag is set.</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Examples:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $type = Image::ExifTool::<b>GetFileType</b>($filename);
|
|
my $desc = Image::ExifTool::<b>GetFileType</b>($filename, 1);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="CanWrite">CanWrite</a></h2>
|
|
<p>Can the specified file be written?</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>CanWrite($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td>
|
|
<td><b>0)</b> File name or extension</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>True if ExifTool supports writing files of
|
|
this type (based on the file extension).</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $writable = Image::ExifTool::<b>CanWrite</b>($filename);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="CanCreate">CanCreate</a></h2>
|
|
<p>Can the specified file be created?</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>CanCreate($)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td>
|
|
<td><b>0)</b> File name or extension</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>True if ExifTool can create files with this
|
|
extension from scratch.<br>Currently, this can only be done with XMP, MIE, ICC,
|
|
VRD, DR4, EXV and EXIF files.</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
my $creatable = Image::ExifTool::<b>CanCreate</b>($filename);
|
|
</pre></td></tr></table></blockquote>
|
|
|
|
<hr><h2><a name="AddUserDefinedTags">AddUserDefinedTags</a></h2>
|
|
<p>Add user-defined tags to an existing tag table at run time. This differs from
|
|
the usual technique of creating user-defined tags via the
|
|
%Image::ExifTool::UserDefined hash (see the
|
|
<a href="config.html">sample config file</a>), because it allows tags to be added
|
|
after the tag table has been initialized.</p>
|
|
<blockquote><table class='norm'>
|
|
<tr><td><b>Prototype</b></td><td>AddUserDefinedTags($%)</td></tr>
|
|
<tr><td valign=top><b>Inputs</b></td><td><b>0)</b> Destination tag table name
|
|
<br><b>1-N)</b> Pairs of tag ID / tag information hash references for the new tags
|
|
</td></tr>
|
|
<tr><td valign=top><b>Returns</b></td><td>The number of tags added</td></tr>
|
|
</table></blockquote>
|
|
<p><b>Example:</b></p>
|
|
<blockquote><table class='box'><tr><td><pre>
|
|
use Image::ExifTool ':Public';
|
|
my %tags = (
|
|
TestTagID1 => { Name => 'TestTagName1' },
|
|
TestTagID2 => { Name => 'TestTagName2' },
|
|
);
|
|
my $num = <b>AddUserDefinedTags</b>('Image::ExifTool::PDF::Info', %tags);
|
|
</pre></td></tr></table></blockquote>
|
|
<p><b>Notes:</b></p>
|
|
<p>Pre-existing tags with the same ID will be replaced in the destination table.
|
|
See lib/Image/ExifTool/README in the full distribution for full details on the
|
|
elements of the tag information hash.</p>
|
|
|
|
<hr>
|
|
<p class='lf'><a href="index.html"><-- Back to ExifTool home page</a></p>
|
|
</body>
|
|
</html>
|