123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088 |
- <!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>
|